Skip to content

Add cross-client installer bundling skills + DocumentDB MCP server#23

Merged
khelanmodi merged 9 commits into
mainfrom
bundle-installer
May 29, 2026
Merged

Add cross-client installer bundling skills + DocumentDB MCP server#23
khelanmodi merged 9 commits into
mainfrom
bundle-installer

Conversation

@xgerman
Copy link
Copy Markdown
Collaborator

@xgerman xgerman commented May 21, 2026

What

Replaces the broken npx skills add Azure/documentdb-agent-kit placeholder
with real one-line installers that, in a single command, wire both this
kit's skills and the microsoft/documentdb-mcp
server into every detected MCP client.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.sh | bash -s -- --uri "<conn>"

# Windows
$env:DOCUMENTDB_URI = "<conn>"
irm https://raw.githubusercontent.com/Azure/documentdb-agent-kit/main/install.ps1 | iex

Why

The kit was just announced with the line
npx skills add Azure/documentdb-agent-kit, but that command does not exist:
there's no skills package on npm, and the repo had no installer of its own.
Customers clicking the link in the announcement would have hit an error.

This PR makes the announcement true and goes further — the same install
command now also wires up the upstream DocumentDB MCP server, so customers get
both tooling and guidance in one step.

What's in the box

File Change
install.sh New — Bash installer (macOS / Linux). 388 lines, no runtime deps beyond git + Node 20+.
install.ps1 New — PowerShell installer (Windows + cross-platform pwsh 7+).
skills/mcp-setup/SKILL.md Rewritten — the previous version walked users through setting $DOCUMENTDB_URI in a shell profile, which is not how the current upstream MCP server is actually configured. New version is built around the actual upstream contract: per-client MCP config file with CONNECTION_PROFILES JSON, TRANSPORT=stdio, ALLOW_UNAUTHENTICATED_STDIO=true. Includes a per-client config-file table for Claude Code / Desktop / Cursor / Copilot CLI / Gemini CLI / VS Code.
README.md Install section rewritten: real one-liner, install matrix (what gets written where, per client), requirements, all flags, verify steps, uninstall command, manual fallback.
AGENTS.md 1-line edit — mcp-setup row description updated to match.
CHANGELOG.md New top entry.

Client coverage

Client MCP entry written to Skills installed at
Claude Code ~/.claude.json ~/.claude/skills/ (symlinks)
Claude Desktop claude_desktop_config.json (per-OS) Claude/skills/ (symlinks, if dir exists)
Cursor ~/.cursor/mcp.json — (Cursor Rules are project-local)
GitHub Copilot CLI ~/.copilot/mcp-config.json — (copy AGENTS.md per-project)
Gemini CLI ~/.gemini/settings.json — (use GEMINI.md per-project)

Safety properties

  • Existing entries preserved. Both installers add (or update) a single
    DocumentDB entry; other servers and unrelated top-level keys are kept.
  • .bak timestamped backups before every JSON edit. Atomic writes
    (tmp+rename), so a crash mid-write can't corrupt a config file.
  • Idempotent. Re-running the installer does not duplicate entries.
  • Selective uninstall. --uninstall removes only the kit's symlinks +
    DocumentDB MCP entries. Foreign symlinks and other servers are untouched.
  • Single-element array preservation. Both python3's json module and the
    PowerShell pipeline (with the explicit ,@(...) wrapping helper) keep
    one-element args arrays as arrays — so installing alongside an MCP server
    whose args is ["one-thing"] doesn't corrupt it into a string.

Flags

--uri <conn>        DocumentDB / MongoDB connection string
--yes               Non-interactive
--dry-run           Print planned changes; write nothing
--uninstall         Remove MCP entries + skill symlinks + ~/.documentdb-agent-kit
--clients <list>    Comma-separated subset of supported clients
--skills-only       Skip MCP server install
--mcp-only          Skip skill linking
--mcp-ref <ref>     Git ref of microsoft/documentdb-mcp (default: main)
--kit-ref <ref>     Git ref of Azure/documentdb-agent-kit (default: main)
--profile <name>    CONNECTION_PROFILES key name (default: default)

(PowerShell uses -Uri, -Yes, etc.)

Testing performed

End-to-end against fake client configs in sandboxed $HOME on macOS, for
both Bash and PowerShell installers, verifying:

  • ✅ Detects all 5 clients when their config dirs exist
  • ✅ Existing MCP servers preserved across install
  • ✅ Top-level non-mcpServers keys preserved
  • ✅ Multi-element args arrays preserved
  • ✅ Single-element args arrays preserved (regression-tested — was a real
    PowerShell bug, fixed before this PR)
  • ✅ Re-running install does not create a duplicate DocumentDB entry
  • ✅ Skill symlinks point at the kit's skills/<name>/ directories
  • --uninstall removes only kit entries; foreign symlinks left in place
  • --uninstall removes ~/.documentdb-agent-kit/
  • ✅ Pre-existing ExistingServer and keep: me top-level keys survive both
    install and uninstall
  • ✅ All 16 skills still pass scripts/validate-skills.ps1

Known limitations / follow-ups (not in this PR)

  • Upstream is currently private. microsoft/documentdb-mcp is a private
    repo at the time of writing. The installer assumes upstream goes public
    before customers run it. Once upstream is public, no installer change is
    needed.
  • MCP ref is main by default. Once upstream cuts release tags, we should
    bump the default --mcp-ref to a pinned tag for stability.
  • DXT bundle / Claude Code plugin / skill-serving wrapper MCP server are
    better long-term shapes for some clients; they remain out of scope for this
    PR. The installer is the cross-client lowest-common-denominator that works
    today.

How to verify

# Show what the installer plans to do (writes nothing)
./install.sh --dry-run --uri "mongodb://localhost:27017" --yes

# Full install with local MongoDB / DocumentDB
./install.sh --uri "mongodb://localhost:27017" --yes

# Uninstall
./install.sh --uninstall --yes

After install, fully quit and reopen each configured client, then ask the
agent: "list databases using the DocumentDB MCP server with connection_profile 'default'".

German and others added 9 commits May 21, 2026 14:27
Replaces the broken `npx skills add Azure/documentdb-agent-kit` placeholder
with real one-line installers (install.sh / install.ps1) that, in a single
command, wire both this kit's skills and the microsoft/documentdb-mcp server
into every detected client (Claude Code, Claude Desktop, Cursor, GitHub
Copilot CLI, Gemini CLI).

- install.sh: POSIX bash; uses python3 (fallback jq) for safe JSON merges
- install.ps1: PS 5.1+/pwsh 7+; uses ConvertFrom/ConvertTo-Json; falls back
  to copy when symlinks need Developer Mode on Windows
- Idempotent re-runs, .bak backups before every JSON edit, --dry-run,
  --uninstall, --skills-only, --mcp-only, --clients, --mcp-ref, --uri, --yes
- Clones repos into ~/.documentdb-agent-kit/{agent-kit,mcp-server}
- Pre-existing MCP entries and unrelated top-level keys are preserved
- Single- and multi-element `args` arrays preserved across JSON round-trips
- Verified end-to-end against fake client configs in sandboxed $HOME

Also fixed two stale claims:

- skills/mcp-setup/SKILL.md previously walked users through setting
  $DOCUMENTDB_URI in a shell profile. The current upstream MCP server is
  configured per-client via a CONNECTION_PROFILES JSON map in the client's
  MCP config file. Rewrote the skill around the actual upstream contract
  with per-client config-file paths for Claude Code / Desktop / Cursor /
  Copilot CLI / Gemini CLI / VS Code.
- README's "npx skills add Azure/documentdb-agent-kit" one-liner was not a
  real command; replaced with the curl|bash and irm|iex installers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The upstream MCP server defaults AUTH_REQUIRED=true and exits at startup
(validateConfig in main.ts) when ENTRA_TENANT_ID / ENTRA_AUDIENCE are
unset — even for TRANSPORT=stdio. Add AUTH_REQUIRED=false to the env
emitted by both installers so a fresh install actually launches.

Document the scope so users know cluster auth is unaffected:
AUTH_REQUIRED gates only the Entra-JWT bearer check on the HTTP/SSE
transport between client and server. MongoDB cluster auth (SCRAM from
the URI, or authMode=entra), TLS, and capability gates (ENABLE_*_TOOLS)
flow through CONNECTION_PROFILES and stay enforced regardless. Safe
only with TRANSPORT=stdio; flipped on streamable-http it would expose
/mcp unauthenticated.

- install.sh / install.ps1: emit AUTH_REQUIRED=false; expand comment to
  spell out the constraint and the stdio-only caveat.
- skills/mcp-setup/SKILL.md: explain in Step 3 what the flag does and
  doesn't affect; update the env example; expand troubleshooting; note
  the same in the manual-setup overview.
- CHANGELOG.md: fold the AUTH_REQUIRED change into the existing
  2026-05-21 installer entry.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
# Conflicts:
#	CHANGELOG.md
#	README.md
#	skills/mcp-setup/SKILL.md
On Windows, npm is npm.cmd (a batch shim). PowerShell's `&` call operator
mangles arguments when piping them into .cmd files under the default
PSNativeCommandArgumentPassing setting on pwsh 7.3+, eating characters off
the first arg. Symptom:

    > & npm install --silent --no-audit --no-fund --no-progress
    Unknown command: "pm"

(npm received argv = ['pm', 'install', ...] instead of ['install', ...].)

Route Windows npm calls through cmd.exe via cmd /c, which bypasses
PowerShell's native-command argument parser entirely. macOS / Linux path
is unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
`Invoke-Expression` accepts only `-Command`; it has no `-ArgumentList`
parameter. The old snippet errored with:

    Invoke-Expression: A parameter cannot be found that matches parameter name 'ArgumentList'.

Replace with the download-then-invoke pattern, which is the standard
PowerShell idiom for passing flags to a script fetched over HTTP.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Expand the README install section with explicit step-by-step subsections
for macOS, Linux, and Windows. Each covers prerequisites (with concrete
package-manager commands), the run command, and the restart step.

Also add a Troubleshooting table consolidating the rough edges users have
hit (bash -s -- omission, ExecutionPolicy, irm | iex no flags, the
Windows npm 'Unknown command pm' bug, nvm PATH refresh, etc.) and
collapse the old standalone Requirements section into a one-line
summary since the per-OS sections now cover it in detail.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
When install.sh is invoked via `curl ... | bash -s -- ...`, $0 is
"bash", so "Uninstall: $0 --uninstall" rendered as the literally
invalid command `bash --uninstall`. Detect that case (and the
stdin / non-file cases) and emit the curl one-liner instead; only show
the script-path form when $0 actually points at a file on disk.

install.ps1 had a similar bug: the farewell hint suggested
`irm ... | iex -ArgumentList '-Uninstall'`, but Invoke-Expression has
no -ArgumentList parameter. Replace with the download-then-invoke form
that actually works on Windows PowerShell.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Upstream microsoft/documentdb-mcp#83 renamed ALLOW_UNAUTHENTICATED_STDIO
to TRUST_LOCAL_STDIO. The old name is no longer recognized by the server
at main; it has been silently ignored on every install since that PR
landed. Our installer kept working only because it also sets
AUTH_REQUIRED=false, which short-circuits the server's Entra startup
validator before TRUST_LOCAL_STDIO is ever consulted in the transport
switch. Rename everywhere so future readers don't see a dead env var:

- install.sh build_env_json (python + jq paths)
- install.ps1 Get-EnvJsonHashtable
- mcp.json
- gemini-extension.json (Gemini extension manifest)
- skills/mcp-setup/SKILL.md (Step 3, config template, troubleshooting)
- README.md (troubleshooting table)
- CHANGELOG.md (new entry + footnote on the 2026-05-21 entry)

Comments in install.sh / install.ps1 / SKILL.md keep an explicit
'previously ALLOW_UNAUTHENTICATED_STDIO' note pointing at the upstream
PR so users on older server builds know what to use instead.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a Public Preview status badge to README.md and a top-of-document
IMPORTANT admonition pointing at the Azure Preview Supplemental Terms.
Add a matching status note to AGENTS.md so agents reading the kit
relay the preview status to users before committing kit-installed
configs into production-shaped surfaces.

No functional changes; this clarifies that the kit (like the upstream
microsoft/documentdb-mcp server it depends on) is pre-GA, has no SLA,
is provided 'as-is', and may change in breaking ways before GA.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@khelanmodi khelanmodi merged commit 6131139 into main May 29, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants