Add cross-client installer bundling skills + DocumentDB MCP server#23
Merged
Conversation
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
approved these changes
May 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Replaces the broken
npx skills add Azure/documentdb-agent-kitplaceholderwith real one-line installers that, in a single command, wire both this
kit's skills and the
microsoft/documentdb-mcpserver into every detected MCP client.
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
skillspackage 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
install.shgit+ Node 20+.install.ps1skills/mcp-setup/SKILL.md$DOCUMENTDB_URIin 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 withCONNECTION_PROFILESJSON,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.mdAGENTS.mdCHANGELOG.mdClient coverage
~/.claude.json~/.claude/skills/(symlinks)claude_desktop_config.json(per-OS)Claude/skills/(symlinks, if dir exists)~/.cursor/mcp.json~/.copilot/mcp-config.jsonAGENTS.mdper-project)~/.gemini/settings.jsonGEMINI.mdper-project)Safety properties
DocumentDBentry; other servers and unrelated top-level keys are kept..baktimestamped backups before every JSON edit. Atomic writes(tmp+rename), so a crash mid-write can't corrupt a config file.
--uninstallremoves only the kit's symlinks +DocumentDBMCP entries. Foreign symlinks and other servers are untouched.python3'sjsonmodule and thePowerShell pipeline (with the explicit
,@(...)wrapping helper) keepone-element
argsarrays as arrays — so installing alongside an MCP serverwhose
argsis["one-thing"]doesn't corrupt it into a string.Flags
(PowerShell uses
-Uri,-Yes, etc.)Testing performed
End-to-end against fake client configs in sandboxed
$HOMEon macOS, forboth Bash and PowerShell installers, verifying:
mcpServerskeys preservedargsarrays preservedargsarrays preserved (regression-tested — was a realPowerShell bug, fixed before this PR)
DocumentDBentryskills/<name>/directories--uninstallremoves only kit entries; foreign symlinks left in place--uninstallremoves~/.documentdb-agent-kit/ExistingServerandkeep: metop-level keys survive bothinstall and uninstall
scripts/validate-skills.ps1Known limitations / follow-ups (not in this PR)
microsoft/documentdb-mcpis a privaterepo at the time of writing. The installer assumes upstream goes public
before customers run it. Once upstream is public, no installer change is
needed.
mainby default. Once upstream cuts release tags, we shouldbump the default
--mcp-refto a pinned tag for stability.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
After install, fully quit and reopen each configured client, then ask the
agent: "list databases using the DocumentDB MCP server with connection_profile 'default'".