v2: publish @azure/documentdb-mcp-server to npm

v2: publish @azure/documentdb-mcp-server to npm

Why

v1 unblocks customers by having every plugin (Claude / Codex / Cursor / Gemini / Copilot / VS Code) fetch the MCP server directly from the public GitHub repo via npx github:microsoft/documentdb-mcp#v1.0.0. That works but has three drawbacks:

1. Cold start is slow — npx clones the repo and (if dist/ isn't shipped) runs prepare before launching. Users see 30–60 s of nothing on first install.
2. No semver — customers can pin to a tag, but the registry-level "latest" / "^1.0.0" experience customers expect from npm packages doesn't exist.
3. Corp networks — some enterprise environments block direct GitHub fetches from npx but allow registry.npmjs.org. These users can't install v1.

What v2 does

Publish the MCP server as a proper scoped npm package and swap every plugin config from github:... to the registry name.

Naming

Recommend @azure/documentdb-mcp-server. The unscoped documentdb-mcp-server was published then unpublished — npm blocks republishing the same name for 72 hours after unpublish, and even after, the squat-risk on an unscoped name argues for the scope. @azure/... matches Azure's existing npm scope (@azure/identity, @azure/cosmos, etc.) and reads correctly to customers.

If @azure/ isn't available to this repo's publisher identity, fall back to @microsoft/documentdb-mcp-server.

Tasks

• Reserve @azure/documentdb-mcp-server on the npm registry (npmjs.com Azure scope)
• Add a GitHub Actions release workflow that publishes on tag push:

  on:
    push:
      tags: ['v*']
  jobs:
    publish:
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
          with: { node-version: '20', registry-url: 'https://registry.npmjs.org' }
        - run: npm ci
        - run: npm run build
        - run: npm publish --access public --provenance
          env:
            NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
  

• Wire NPM_TOKEN as an actions secret (granular automation token, publish-only)
• Enable npm provenance so customers can verify the package was built from this repo
• Tag v2.0.0 and confirm the workflow publishes successfully
• Smoke-test: npx -y @azure/documentdb-mcp-server on a fresh machine
• Open a PR against Azure/documentdb-agent-kit to swap the four plugin configs from github:... to @azure/documentdb-mcp-server
• Tag agent-kit v2.0.0 to align
• Update pinned discussion: "v2 is live. Existing v1 installs continue to work; new installs use the npm package automatically."

Versioning

v1 lives on the github:... path forever (don't break it — old plugin installs reference it). v2+ is npm-first. The agent-kit's mcp.json will reference v2 going forward.

Done when

• @azure/documentdb-mcp-server resolves on npm
• Provenance is attached
• Release workflow is green
• Agent-kit's plugin configs point at the npm package
• Both paths (github: and npm:) are documented in README, with npm as the recommended default

Start with the requested GitHub Actions release workflow and review the agent-kit's mcp.json and four plugin configs. Confirm the npm package resolves with provenance, the release workflow is green, both GitHub and npm installation paths are documented in README, and the agent-kit references the npm package.