From 86bdbc52f6273725fdb415cfca7845af89f20b8d Mon Sep 17 00:00:00 2001 From: Rayhan Hossain Date: Wed, 3 Jun 2026 14:27:09 -0700 Subject: [PATCH] Extract installation guide to a separate folder Signed-off-by: Rayhan Hossain --- README.md | 333 +------------------- docs/installation/README.md | 29 ++ docs/installation/linux.md | 43 +++ docs/installation/macos.md | 42 +++ docs/installation/manual-install.md | 21 ++ docs/installation/plugin-marketplaces.md | 44 +++ docs/installation/requirements-and-flags.md | 27 ++ docs/installation/skills-only.md | 11 + docs/installation/troubleshooting.md | 16 + docs/installation/uninstall.md | 16 + docs/installation/updating.md | 26 ++ docs/installation/verify.md | 5 + docs/installation/what-gets-installed.md | 20 ++ docs/installation/windows.md | 46 +++ 14 files changed, 352 insertions(+), 327 deletions(-) create mode 100644 docs/installation/README.md create mode 100644 docs/installation/linux.md create mode 100644 docs/installation/macos.md create mode 100644 docs/installation/manual-install.md create mode 100644 docs/installation/plugin-marketplaces.md create mode 100644 docs/installation/requirements-and-flags.md create mode 100644 docs/installation/skills-only.md create mode 100644 docs/installation/troubleshooting.md create mode 100644 docs/installation/uninstall.md create mode 100644 docs/installation/updating.md create mode 100644 docs/installation/verify.md create mode 100644 docs/installation/what-gets-installed.md create mode 100644 docs/installation/windows.md diff --git a/README.md b/README.md index 6d306e2..1e41bf6 100644 --- a/README.md +++ b/README.md @@ -31,336 +31,15 @@ skills/ The kit ships with a one-command installer that wires both the **skills** and the [`microsoft/documentdb-mcp`](https://github.com/microsoft/documentdb-mcp) -server into every detected MCP client. This is the recommended path today — -the per-agent plugin/extension marketplaces below are still being published. +server into every detected MCP client. Pick your platform: -### Step-by-step: macOS - -**1. Prerequisites** - -```bash -# git -xcode-select --install # if not already installed -# Node.js 20+ (Homebrew) -brew install node@20 && brew link --overwrite --force node@20 - -# Verify -git --version -node --version # must be v20.x or higher -``` - -**2. Get your DocumentDB connection string** - -- **Azure DocumentDB:** Azure portal → cluster → *Settings → Connection strings*. Shape: - `mongodb+srv://:@.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256`. - URL-encode special characters in the password. -- **Local DocumentDB / MongoDB:** `mongodb://localhost:27017` -- **Atlas / self-hosted:** your standard MongoDB URI. - -> ⚠️ Keep the connection string in your shell only — don't paste it into any AI agent chat. - -**3. Run the installer** - -```bash -curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh \ - | bash -s -- --uri "" --yes -``` - -Or with the URI in an env var: - -```bash -export DOCUMENTDB_URI="" -curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash -s -- --yes -``` - -**4. Fully quit and reopen each configured client.** Closing the window isn't enough — MCP config is read only at process start. - -**5. Verify** (see [Verify it worked](#verify-it-worked) below). - -### Step-by-step: Linux - -**1. Prerequisites** - -```bash -# git -sudo apt install -y git # Debian/Ubuntu -# sudo dnf install -y git # Fedora/RHEL -# sudo pacman -S git # Arch - -# Node.js 20+ — distro packages are usually too old. Pick one: - -# Option A: NodeSource (Debian/Ubuntu/Fedora/RHEL) -curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - -sudo apt install -y nodejs - -# Option B: nvm (any distro, recommended for dev machines) -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash -exec $SHELL -nvm install 20 && nvm use 20 - -# Verify -git --version -node --version # must be v20.x or higher -npm --version -``` - -**2. Get your DocumentDB connection string** — same as macOS above. - -**3. Run the installer** - -```bash -curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh \ - | bash -s -- --uri "" --yes -``` - -> The `bash -s --` part is **required** when piping through `curl` — it tells bash that everything after is an argument to the script, not to bash itself. - -**4. Fully quit and reopen each configured client.** For terminal clients (Copilot CLI, Gemini CLI), exit and reopen the shell. - -**5. Verify** (see [Verify it worked](#verify-it-worked) below). - -> Don't `sudo` the installer — it only writes user-scoped configs. Running as root will create files owned by root in your home directory. - -### Step-by-step: Windows - -**1. Prerequisites** - -Open **PowerShell** (Windows PowerShell 5.1 or pwsh 7+) — as your normal user, not admin: - -```powershell -# git -winget install --id Git.Git - -# Node.js 20+ -winget install OpenJS.NodeJS.LTS - -# Verify (open a new PowerShell window first to refresh PATH) -git --version -node --version # must be v20.x or higher -$PSVersionTable.PSVersion # 5.1+ or 7+ -``` - -*(Optional but recommended)* Enable **Developer Mode** so the installer can use symlinks instead of copying files: *Settings → Privacy & security → For developers → Developer Mode = On*. Without it the installer falls back to copying — that still works, just less elegant for skill updates. - -**2. Get your DocumentDB connection string** — same as macOS above. - -**3. Run the installer** - -```powershell -$env:DOCUMENTDB_URI = "" -irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 | iex -``` - -If you get `running scripts is disabled on this system`, run this once in the same window and re-run: - -```powershell -Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -``` - -**To pass flags** (`-Yes`, `-DryRun`, `-Uninstall`, etc.), `irm | iex` won't work — download then invoke: - -```powershell -irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 -OutFile $env:TEMP\install.ps1 -& $env:TEMP\install.ps1 -Uri "" -Yes -``` - -**4. Fully quit and reopen each configured client.** Use the system tray / Task Manager — closing the window isn't enough. - -**5. Verify** (see [Verify it worked](#verify-it-worked) below). - -### What gets installed - -| Path | What | +| OS | Guide | |---|---| -| `~/.documentdb-agent-kit/agent-kit/` | Clone of this repo (skills + AGENTS.md) | -| `~/.documentdb-agent-kit/mcp-server/` | Clone + build of `microsoft/documentdb-mcp` | - -Then, per detected client: - -| Client | MCP entry → | Skills → | -|---|---|---| -| Claude Code | `~/.claude.json` | `~/.claude/skills/` (symlinks) | -| Claude Desktop | `claude_desktop_config.json` (per-OS path) | `Claude/skills/` (symlinks, if dir exists) | -| Cursor | `~/.cursor/mcp.json` | — (use Cursor Rules per-project) | -| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | — (copy `AGENTS.md` per-project) | -| Gemini CLI | `~/.gemini/settings.json` | — (use `GEMINI.md` per-project) | - -Existing entries in each client's config are preserved — the installer only -adds (or updates) a single `DocumentDB` entry. A timestamped `.bak` backup is -written before every JSON edit. - -### Requirements summary - -- `git` -- Node.js 20+ and `npm` (the MCP server is a Node app, built from source on - install). `--skills-only` mode skips Node requirements. - -See the per-OS step-by-step sections above for install commands. - -### Common flags - -```text ---uri DocumentDB / MongoDB connection string ---yes Non-interactive (don't prompt) ---dry-run Print planned changes; write nothing ---uninstall Remove MCP entries, skill symlinks, and ~/.documentdb-agent-kit ---clients Comma-separated: claude-code,claude-desktop,cursor,copilot-cli,gemini-cli ---skills-only Skip MCP server install ---mcp-only Skip skill linking ---mcp-ref Git ref of microsoft/documentdb-mcp (default: main) ---profile CONNECTION_PROFILES key name (default: default) -``` - -Connection string can also be supplied via `$DOCUMENTDB_URI` (or -`$env:DOCUMENTDB_URI` on PowerShell). When neither flag nor env var is set and -a TTY is attached, the installer prompts. - -### Verify it worked - -1. Fully **quit** and reopen each configured client (not just close the window). -2. Ask the agent: *"list databases using the DocumentDB MCP server with connection_profile 'default'"*. -3. You should get back the database list. - -### Uninstall - -```bash -# macOS / Linux -curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash -s -- --uninstall --yes -``` - -```powershell -# Windows -irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 -OutFile $env:TEMP\install.ps1 -& $env:TEMP\install.ps1 -Uninstall -Yes -``` - -Removes the kit's `DocumentDB` MCP entry from every client, removes skill -symlinks, and deletes `~/.documentdb-agent-kit/`. Other MCP servers and your -non-kit skills are left untouched. - -### Troubleshooting - -| Symptom | Platform | Fix | -|---|---|---| -| `bash: line N: --uri: command not found` | macOS / Linux | Missing `bash -s --` between `curl ... \|` and the flags. | -| `running scripts is disabled on this system` | Windows | `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass` in the same PowerShell session, then re-run. | -| `Invoke-Expression: A parameter cannot be found that matches parameter name 'ArgumentList'` | Windows | `irm \| iex` doesn't accept flags. Use the `irm -OutFile … ; & $env:TEMP\install.ps1 -Yes` pattern. | -| `npm: Unknown command: "pm"` during MCP build | Windows | Old installer bug — re-fetch the latest `install.ps1` (fixed in this kit). | -| `node: command not found` after install | all | Open a new terminal to refresh `PATH`. With nvm, also run `nvm use 20`. | -| `npm: not found` but Node.js is installed | Linux (Debian/Ubuntu) | The distro `nodejs` package sometimes omits npm — `sudo apt install -y npm`, or use nvm. | -| `symlink failed for ; copying instead` warnings | Windows | Harmless. Enable Developer Mode if you want real symlinks. | -| Agent: `connection_profile "default" not found` | all | Tell the agent to use profile `default` explicitly, or pass `--profile ` / `-Profile ` to the installer. | -| Agent: `AUTH_REQUIRED is true ...` or server exits at launch | all | Re-run the installer — it sets `AUTH_REQUIRED=false` + `TRUST_LOCAL_STDIO=true`, required for local stdio. This only disables the MCP-server's Entra-JWT *transport* gate; your cluster's SCRAM/Entra auth is unaffected. | -| TLS error against Azure | all | Confirm `tls=true` is in the URI and the password is URL-encoded. | -| Connection timeout to Azure | all | Azure portal → cluster → *Networking* → add your client IP to the firewall allowlist. | -| `Permission denied` writing into `~/.claude.json` | Linux / macOS | Don't `sudo` the installer — it writes user-scoped configs. Run as your normal user. | - -### Manual install (no script) - -If you don't want to run the installer, every step is documented in the -[`documentdb-mcp-setup` skill](skills/mcp-setup/SKILL.md) (per-client config -file paths, MCP server config template, `CONNECTION_PROFILES` JSON, etc.). -For skills-only manual install: - -```bash -# Claude Code (project-scoped) -mkdir -p .claude && ln -s "$(pwd)/skills" .claude/skills - -# Claude Code (user-scoped) -mkdir -p ~/.claude/skills && for d in skills/*/; do ln -s "$(pwd)/$d" ~/.claude/skills/; done - -# Gemini CLI (project-scoped) -ln -s AGENTS.md GEMINI.md - -# GitHub Copilot / other AGENTS.md-aware clients: drop AGENTS.md + skills/ at repo root -``` - -On Windows, use `New-Item -ItemType SymbolicLink` or copy folders. - -### Coming soon: per-agent plugin / extension marketplaces - -The kit ships plugin manifests for Claude Code, Cursor, Codex, and Gemini CLI -(under `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, -`gemini-extension.json`). The native marketplace install commands below are -**not yet published** — use the one-liner installer above in the meantime. - - - -### Universal one-liner — skills only (no MCP server) - -To install just the skill catalog into whichever agent you're using, via the [skills.sh](https://skills.sh/) CLI: - -```bash -npx skills add Azure/documentdb-agent-kit -``` - -This drops the rule docs into your agent's skill directory but **does not** install the MCP server. Use the [one-liner installer above](#one-liner-recommended) if you want the DB tools too. - -> 💡 **Accept the optional `find-skills` helper when prompted.** During `npx skills add` the installer will ask whether to install [`find-skills`](https://github.com/skills-sh/find-skills) — say **yes**. It's a tiny meta-skill that lets agents auto-discover the right DocumentDB skill for a task (e.g. *"how do I create a BM25 index?"* → auto-loads `documentdb-full-text-search`) instead of relying on you to invoke skills by name. It's especially useful here because the kit ships 17 skills, more than agents reliably route on their own from `AGENTS.md` alone. If you skipped it, re-run `npx skills add find-skills` to add it later. - -## Updating the kit - -New skills, rule fixes, and MCP-server updates are released on `main`. Installs do **not** auto-update — each install path has its own refresh command. Run these when you want to pull in new features or fixes: - -| Install path | Update command | -|---|---| -| One-liner installer (recommended) | re-run the `install.sh` / `install.ps1` curl one-liner with the same connection string (idempotent: refreshes the kit clone, rebuilds the MCP server, and re-merges the `DocumentDB` entry into every detected client config). Pin a specific ref with `--kit-ref ` and/or `--mcp-ref `. | -| Skills only (skills.sh CLI) | re-run `npx skills add Azure/documentdb-agent-kit` | - - - - -> **Skills CLI note:** `npx skills update` exists but is unreliable for GitHub-sourced skills on the current `skills` CLI release. **Re-running `npx skills add Azure/documentdb-agent-kit` is the recommended refresh path** — it re-fetches the latest `main` and overlays the updated rule files. Add `--all` if you originally installed with `--all`. - -The MCP server is fetched via `npx -y documentdb-mcp-server` each time the agent launches the server, so MCP-server updates land automatically on the next agent restart (subject to npm cache). Skill files are snapshotted at install time and only refresh when you run one of the commands above. +| macOS | [`docs/installation/macos.md`](docs/installation/macos.md) | +| Linux | [`docs/installation/linux.md`](docs/installation/linux.md) | +| Windows | [`docs/installation/windows.md`](docs/installation/windows.md) | -To see what's changed between releases, check [`CHANGELOG.md`](CHANGELOG.md). +For uninstall, troubleshooting, manual install, skills-only install, updating, and per-agent plugin marketplaces, see [`docs/installation/`](docs/installation/README.md). ## Configuration diff --git a/docs/installation/README.md b/docs/installation/README.md new file mode 100644 index 0000000..3492bab --- /dev/null +++ b/docs/installation/README.md @@ -0,0 +1,29 @@ +# Installation + +The DocumentDB Agent Kit installer wires both the **skills** and the +[`microsoft/documentdb-mcp`](https://github.com/microsoft/documentdb-mcp) server +into every detected MCP client (Claude Code, Claude Desktop, Cursor, GitHub +Copilot CLI, Gemini CLI). It is the recommended install path today — the +per-agent plugin / extension marketplaces are still being published. + +## Choose your platform + +| OS | Guide | +|---|---| +| macOS | [macos.md](macos.md) | +| Linux | [linux.md](linux.md) | +| Windows | [windows.md](windows.md) | + +## Reference + +| Topic | Doc | +|---|---| +| What gets installed (paths, per-client config) | [what-gets-installed.md](what-gets-installed.md) | +| Requirements & common flags | [requirements-and-flags.md](requirements-and-flags.md) | +| Verify it worked | [verify.md](verify.md) | +| Uninstall | [uninstall.md](uninstall.md) | +| Troubleshooting | [troubleshooting.md](troubleshooting.md) | +| Manual install (no script) | [manual-install.md](manual-install.md) | +| Skills-only install (`npx skills add`) | [skills-only.md](skills-only.md) | +| Per-agent plugin marketplaces (coming soon) | [plugin-marketplaces.md](plugin-marketplaces.md) | +| Updating the kit | [updating.md](updating.md) | diff --git a/docs/installation/linux.md b/docs/installation/linux.md new file mode 100644 index 0000000..2fe8c8a --- /dev/null +++ b/docs/installation/linux.md @@ -0,0 +1,43 @@ +# Installation — Linux + +**1. Prerequisites** + +```bash +# git +sudo apt install -y git # Debian/Ubuntu +# sudo dnf install -y git # Fedora/RHEL +# sudo pacman -S git # Arch + +# Node.js 20+ — distro packages are usually too old. Pick one: + +# Option A: NodeSource (Debian/Ubuntu/Fedora/RHEL) +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt install -y nodejs + +# Option B: nvm (any distro, recommended for dev machines) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash +exec $SHELL +nvm install 20 && nvm use 20 + +# Verify +git --version +node --version # must be v20.x or higher +npm --version +``` + +**2. Get your DocumentDB connection string** — same as [macOS](macos.md#2-get-your-documentdb-connection-string). + +**3. Run the installer** + +```bash +curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh \ + | bash -s -- --uri "" --yes +``` + +> The `bash -s --` part is **required** when piping through `curl` — it tells bash that everything after is an argument to the script, not to bash itself. + +**4. Fully quit and reopen each configured client.** For terminal clients (Copilot CLI, Gemini CLI), exit and reopen the shell. + +**5. Verify** — see [Verify it worked](verify.md). + +> Don't `sudo` the installer — it only writes user-scoped configs. Running as root will create files owned by root in your home directory. diff --git a/docs/installation/macos.md b/docs/installation/macos.md new file mode 100644 index 0000000..a41fe1c --- /dev/null +++ b/docs/installation/macos.md @@ -0,0 +1,42 @@ +# Installation — macOS + +**1. Prerequisites** + +```bash +# git +xcode-select --install # if not already installed +# Node.js 20+ (Homebrew) +brew install node@20 && brew link --overwrite --force node@20 + +# Verify +git --version +node --version # must be v20.x or higher +``` + +**2. Get your DocumentDB connection string** + +- **Azure DocumentDB:** Azure portal → cluster → *Settings → Connection strings*. Shape: + `mongodb+srv://:@.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256`. + URL-encode special characters in the password. +- **Local DocumentDB / MongoDB:** `mongodb://localhost:27017` +- **Atlas / self-hosted:** your standard MongoDB URI. + +> ⚠️ Keep the connection string in your shell only — don't paste it into any AI agent chat. + +**3. Run the installer** + +```bash +curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh \ + | bash -s -- --uri "" --yes +``` + +Or with the URI in an env var: + +```bash +export DOCUMENTDB_URI="" +curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash -s -- --yes +``` + +**4. Fully quit and reopen each configured client.** Closing the window isn't enough — MCP config is read only at process start. + +**5. Verify** — see [Verify it worked](verify.md). diff --git a/docs/installation/manual-install.md b/docs/installation/manual-install.md new file mode 100644 index 0000000..f2b8a3a --- /dev/null +++ b/docs/installation/manual-install.md @@ -0,0 +1,21 @@ +# Manual install (no script) + +If you don't want to run the installer, every step is documented in the +[`documentdb-mcp-setup` skill](../../skills/mcp-setup/SKILL.md) (per-client config +file paths, MCP server config template, `CONNECTION_PROFILES` JSON, etc.). +For skills-only manual install: + +```bash +# Claude Code (project-scoped) +mkdir -p .claude && ln -s "$(pwd)/skills" .claude/skills + +# Claude Code (user-scoped) +mkdir -p ~/.claude/skills && for d in skills/*/; do ln -s "$(pwd)/$d" ~/.claude/skills/; done + +# Gemini CLI (project-scoped) +ln -s AGENTS.md GEMINI.md + +# GitHub Copilot / other AGENTS.md-aware clients: drop AGENTS.md + skills/ at repo root +``` + +On Windows, use `New-Item -ItemType SymbolicLink` or copy folders. diff --git a/docs/installation/plugin-marketplaces.md b/docs/installation/plugin-marketplaces.md new file mode 100644 index 0000000..658e811 --- /dev/null +++ b/docs/installation/plugin-marketplaces.md @@ -0,0 +1,44 @@ +# Coming soon: per-agent plugin / extension marketplaces + +The kit ships plugin manifests for Claude Code, Cursor, Codex, and Gemini CLI +(under `.claude-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, +`gemini-extension.json`). The native marketplace install commands below are +**not yet published** — use the [one-liner installer](../../README.md#installation) in the meantime. + + diff --git a/docs/installation/requirements-and-flags.md b/docs/installation/requirements-and-flags.md new file mode 100644 index 0000000..7dba9d9 --- /dev/null +++ b/docs/installation/requirements-and-flags.md @@ -0,0 +1,27 @@ +# Requirements & common flags + +## Requirements summary + +- `git` +- Node.js 20+ and `npm` (the MCP server is a Node app, built from source on + install). `--skills-only` mode skips Node requirements. + +See the per-OS step-by-step guides ([macOS](macos.md), [Linux](linux.md), [Windows](windows.md)) for install commands. + +## Common flags + +```text +--uri DocumentDB / MongoDB connection string +--yes Non-interactive (don't prompt) +--dry-run Print planned changes; write nothing +--uninstall Remove MCP entries, skill symlinks, and ~/.documentdb-agent-kit +--clients Comma-separated: claude-code,claude-desktop,cursor,copilot-cli,gemini-cli +--skills-only Skip MCP server install +--mcp-only Skip skill linking +--mcp-ref Git ref of microsoft/documentdb-mcp (default: main) +--profile CONNECTION_PROFILES key name (default: default) +``` + +Connection string can also be supplied via `$DOCUMENTDB_URI` (or +`$env:DOCUMENTDB_URI` on PowerShell). When neither flag nor env var is set and +a TTY is attached, the installer prompts. diff --git a/docs/installation/skills-only.md b/docs/installation/skills-only.md new file mode 100644 index 0000000..34ce2ab --- /dev/null +++ b/docs/installation/skills-only.md @@ -0,0 +1,11 @@ +# Skills-only install (no MCP server) + +To install just the skill catalog into whichever agent you're using, via the [skills.sh](https://skills.sh/) CLI: + +```bash +npx skills add Azure/documentdb-agent-kit +``` + +This drops the rule docs into your agent's skill directory but **does not** install the MCP server. Use the [one-liner installer](../../README.md#installation) if you want the DB tools too. + +> 💡 **Accept the optional `find-skills` helper when prompted.** During `npx skills add` the installer will ask whether to install [`find-skills`](https://github.com/skills-sh/find-skills) — say **yes**. It's a tiny meta-skill that lets agents auto-discover the right DocumentDB skill for a task (e.g. *"how do I create a BM25 index?"* → auto-loads `documentdb-full-text-search`) instead of relying on you to invoke skills by name. It's especially useful here because the kit ships 17 skills, more than agents reliably route on their own from `AGENTS.md` alone. If you skipped it, re-run `npx skills add find-skills` to add it later. diff --git a/docs/installation/troubleshooting.md b/docs/installation/troubleshooting.md new file mode 100644 index 0000000..6c73ef0 --- /dev/null +++ b/docs/installation/troubleshooting.md @@ -0,0 +1,16 @@ +# Troubleshooting + +| Symptom | Platform | Fix | +|---|---|---| +| `bash: line N: --uri: command not found` | macOS / Linux | Missing `bash -s --` between `curl ... \|` and the flags. | +| `running scripts is disabled on this system` | Windows | `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass` in the same PowerShell session, then re-run. | +| `Invoke-Expression: A parameter cannot be found that matches parameter name 'ArgumentList'` | Windows | `irm \| iex` doesn't accept flags. Use the `irm -OutFile … ; & $env:TEMP\install.ps1 -Yes` pattern. | +| `npm: Unknown command: "pm"` during MCP build | Windows | Old installer bug — re-fetch the latest `install.ps1` (fixed in this kit). | +| `node: command not found` after install | all | Open a new terminal to refresh `PATH`. With nvm, also run `nvm use 20`. | +| `npm: not found` but Node.js is installed | Linux (Debian/Ubuntu) | The distro `nodejs` package sometimes omits npm — `sudo apt install -y npm`, or use nvm. | +| `symlink failed for ; copying instead` warnings | Windows | Harmless. Enable Developer Mode if you want real symlinks. | +| Agent: `connection_profile "default" not found` | all | Tell the agent to use profile `default` explicitly, or pass `--profile ` / `-Profile ` to the installer. | +| Agent: `AUTH_REQUIRED is true ...` or server exits at launch | all | Re-run the installer — it sets `AUTH_REQUIRED=false` + `TRUST_LOCAL_STDIO=true`, required for local stdio. This only disables the MCP-server's Entra-JWT *transport* gate; your cluster's SCRAM/Entra auth is unaffected. | +| TLS error against Azure | all | Confirm `tls=true` is in the URI and the password is URL-encoded. | +| Connection timeout to Azure | all | Azure portal → cluster → *Networking* → add your client IP to the firewall allowlist. | +| `Permission denied` writing into `~/.claude.json` | Linux / macOS | Don't `sudo` the installer — it writes user-scoped configs. Run as your normal user. | diff --git a/docs/installation/uninstall.md b/docs/installation/uninstall.md new file mode 100644 index 0000000..b4ef9a8 --- /dev/null +++ b/docs/installation/uninstall.md @@ -0,0 +1,16 @@ +# Uninstall + +```bash +# macOS / Linux +curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash -s -- --uninstall --yes +``` + +```powershell +# Windows +irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 -OutFile $env:TEMP\install.ps1 +& $env:TEMP\install.ps1 -Uninstall -Yes +``` + +Removes the kit's `DocumentDB` MCP entry from every client, removes skill +symlinks, and deletes `~/.documentdb-agent-kit/`. Other MCP servers and your +non-kit skills are left untouched. diff --git a/docs/installation/updating.md b/docs/installation/updating.md new file mode 100644 index 0000000..6dc0f67 --- /dev/null +++ b/docs/installation/updating.md @@ -0,0 +1,26 @@ +# Updating the kit + +New skills, rule fixes, and MCP-server updates are released on `main`. Installs do **not** auto-update — each install path has its own refresh command. Run these when you want to pull in new features or fixes: + +| Install path | Update command | +|---|---| +| One-liner installer (recommended) | re-run the `install.sh` / `install.ps1` curl one-liner with the same connection string (idempotent: refreshes the kit clone, rebuilds the MCP server, and re-merges the `DocumentDB` entry into every detected client config). Pin a specific ref with `--kit-ref ` and/or `--mcp-ref `. | +| Skills only (skills.sh CLI) | re-run `npx skills add Azure/documentdb-agent-kit` | + + + +> **Skills CLI note:** `npx skills update` exists but is unreliable for GitHub-sourced skills on the current `skills` CLI release. **Re-running `npx skills add Azure/documentdb-agent-kit` is the recommended refresh path** — it re-fetches the latest `main` and overlays the updated rule files. Add `--all` if you originally installed with `--all`. + +The MCP server is fetched via `npx -y documentdb-mcp-server` each time the agent launches the server, so MCP-server updates land automatically on the next agent restart (subject to npm cache). Skill files are snapshotted at install time and only refresh when you run one of the commands above. + +To see what's changed between releases, check [`CHANGELOG.md`](../../CHANGELOG.md). diff --git a/docs/installation/verify.md b/docs/installation/verify.md new file mode 100644 index 0000000..691eeaf --- /dev/null +++ b/docs/installation/verify.md @@ -0,0 +1,5 @@ +# Verify it worked + +1. Fully **quit** and reopen each configured client (not just close the window). +2. Ask the agent: *"list databases using the DocumentDB MCP server with connection_profile 'default'"*. +3. You should get back the database list. diff --git a/docs/installation/what-gets-installed.md b/docs/installation/what-gets-installed.md new file mode 100644 index 0000000..f64594e --- /dev/null +++ b/docs/installation/what-gets-installed.md @@ -0,0 +1,20 @@ +# What gets installed + +| Path | What | +|---|---| +| `~/.documentdb-agent-kit/agent-kit/` | Clone of this repo (skills + AGENTS.md) | +| `~/.documentdb-agent-kit/mcp-server/` | Clone + build of `microsoft/documentdb-mcp` | + +Then, per detected client: + +| Client | MCP entry → | Skills → | +|---|---|---| +| Claude Code | `~/.claude.json` | `~/.claude/skills/` (symlinks) | +| Claude Desktop | `claude_desktop_config.json` (per-OS path) | `Claude/skills/` (symlinks, if dir exists) | +| Cursor | `~/.cursor/mcp.json` | — (use Cursor Rules per-project) | +| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | — (copy `AGENTS.md` per-project) | +| Gemini CLI | `~/.gemini/settings.json` | — (use `GEMINI.md` per-project) | + +Existing entries in each client's config are preserved — the installer only +adds (or updates) a single `DocumentDB` entry. A timestamped `.bak` backup is +written before every JSON edit. diff --git a/docs/installation/windows.md b/docs/installation/windows.md new file mode 100644 index 0000000..c41b519 --- /dev/null +++ b/docs/installation/windows.md @@ -0,0 +1,46 @@ +# Installation — Windows + +**1. Prerequisites** + +Open **PowerShell** (Windows PowerShell 5.1 or pwsh 7+) — as your normal user, not admin: + +```powershell +# git +winget install --id Git.Git + +# Node.js 20+ +winget install OpenJS.NodeJS.LTS + +# Verify (open a new PowerShell window first to refresh PATH) +git --version +node --version # must be v20.x or higher +$PSVersionTable.PSVersion # 5.1+ or 7+ +``` + +*(Optional but recommended)* Enable **Developer Mode** so the installer can use symlinks instead of copying files: *Settings → Privacy & security → For developers → Developer Mode = On*. Without it the installer falls back to copying — that still works, just less elegant for skill updates. + +**2. Get your DocumentDB connection string** — same as [macOS](macos.md#2-get-your-documentdb-connection-string). + +**3. Run the installer** + +```powershell +$env:DOCUMENTDB_URI = "" +irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 | iex +``` + +If you get `running scripts is disabled on this system`, run this once in the same window and re-run: + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +``` + +**To pass flags** (`-Yes`, `-DryRun`, `-Uninstall`, etc.), `irm | iex` won't work — download then invoke: + +```powershell +irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 -OutFile $env:TEMP\install.ps1 +& $env:TEMP\install.ps1 -Uri "" -Yes +``` + +**4. Fully quit and reopen each configured client.** Use the system tray / Task Manager — closing the window isn't enough. + +**5. Verify** — see [Verify it worked](verify.md).