Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
#20 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
github, node.js
Domain
release, tooling

Research direction

First confirm that microsoft/documentdb-mcp is public and has the v1.0.0 tag, then inspect mcp.json, the .claude-plugin/, .codex-plugin/, and .cursor-plugin/ configs, gemini-extension.json, README.md, and any listed agent instructions for hardcoded commands. Validate installation and list_databases across the clients in the matrix, then confirm the discussion and agent-kit v1.0.0 tag are in place.

Written by the indexing model from the issue text.

Description

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
Dominant language
Shell
Stars
6
Forks
10
Avg merge
11d 20h
Merged PRs (30d)
2

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Azure/documentdb-agent-kit

All issues in Azure/documentdb-agent-kit

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.