Unblock plugin installs in Claude / Codex / Gemini / Copilot / Cursor / VS Code

[khelanmodi]

Unblock plugin installs in Claude / Codex / Gemini / Copilot / Cursor / VS Code

Problem

The plugin scaffolding in this repo (.claude-plugin/, .codex-plugin/, .cursor-plugin/, gemini-extension.json, mcp.json) all reference an npm package that doesn't exist:

"command": "npx",
"args": ["-y", "documentdb-mcp-server"]

$ npm view documentdb-mcp-server
npm error 404  Unpublished on 2025-04-17T14:13:45.796Z

So the plugin installs are broken in every client today. v2 will publish to npm under a scoped name; this issue tracks the interim fix so customers can use the plugins now.

Approach

Switch every plugin config from the dead npm name to the public-GitHub spec that npx understands natively:

"args": ["-y", "github:microsoft/documentdb-mcp#v1.0.0"]

This requires microsoft/documentdb-mcp to be public first — tracked in microsoft/documentdb-mcp#TBD.

Tasks (in order)

• Wait for microsoft/documentdb-mcp to be made public and tagged v1.0.0
• Open PR swapping the MCP command in all of these files in lockstep:
  • mcp.json
  • .claude-plugin/plugin.json (if it duplicates the command — currently inherits from mcp.json)
  • .codex-plugin/ configs
  • .cursor-plugin/ configs
  • gemini-extension.json
  • README.md install snippets
  • AGENTS.md / GEMINI.md / CLAUDE.md if any hardcode a command
• Tag agent-kit v1.0.0 after merge so marketplaces have a stable ref
• Pin a discussion explaining v1 ships from GitHub and v2 will move to npm (no breaking change for customers)

Validation matrix — gate before announcing

Install the plugin end-to-end in each client at least once and confirm list_databases works:

Client	Pass?	Notes
Claude Code (/plugin install)	☐	Most likely to choke on cold-start TS compile under npx
Claude Desktop (claude_desktop_config.json)	☐
Codex CLI	☐
Cursor (deep-link install badge)	☐
GitHub Copilot CLI	☐
VS Code (deep-link install badge)	☐
Gemini CLI	☐

If cold-start under npx is too slow (> 60 s) in any client, escalate v2 npm publish — see microsoft/documentdb-mcp#TBD.

Pinning: tag vs branch

Pin to #v1.0.0 (the tag), not #main. Tag pinning prevents customers from breaking when main moves; hotfixes can ship as v1.0.1 etc.

Out of scope

• npm publish (tracked separately as v2)
• Org transfer to Azure/ (tracked separately)

Done when

• All four+ plugin configs reference the tagged public GitHub spec
• All six clients in the validation matrix install + work
• Pinned discussion is up
• agent-kit v1.0.0 tag exists

[khelanmodi]

Related tracking issues:

• Make repo public + tag v1.0.0 to unblock plugin distribution microsoft/documentdb-mcp#48 — make MCP repo public (prereq)
• v2: publish @azure/documentdb-mcp-server to npm microsoft/documentdb-mcp#49 — v2 npm publish (replaces the github: spec later)
• Transfer ownership: microsoft/documentdb-mcp -> Azure/documentdb-mcp microsoft/documentdb-mcp#50 — org transfer to Azure/