Skip to content

Package the local MCP server as a Claude plugin bundle for the Anthropic directory (MCPB listings deprecated) #895

Closed

Description

@jeffreyaven

Summary

Sibling of #893 (ChatGPT plugin directory ZIP). Depends on stackql/stackql.io#305 for the support and terms URLs. The current Anthropic listing is a Desktop Extension (.mcpb) entry submitted through the Anthropic Google form on 2026-06-13, per packaging/mcpb/docs/anthropic-submission.md.

Anthropic has moved directory submissions to a developer portal (claude.ai/directory/manage) with two submission kinds, and the local server no longer fits the one we used:

  • MCP connector: one remote MCP server, submitted by https:// URL. The connector checklist states: "A local server can't be submitted on its own; include it in a plugin instead."
  • Plugin bundle: a folder in a public GitHub repository holding .claude-plugin/plugin.json, a README, a license, and any combination of skills, commands, agents, hooks and MCP server references. A local stdio server is declared with command and args.
  • "Desktop extension listings in the directory are deprecated, and the directory no longer accepts local MCP servers packaged as desktop extensions (MCPB). To distribute a local MCP server through the directory, include it in a plugin bundle."

In Anthropic's terms StackQL is therefore a local MCP server distributed inside a plugin bundle, not a connector. The connector review criteria still describe what a reviewer checks on the server behind the plugin, and main already meets them: read and write tools are separate, every tool carries title, readOnlyHint, destructiveHint and openWorldHint (#892, on main at 821cd3d but not yet in a release; v0.12.824 predates it), tool names are under 64 characters, there is no catch-all request tool, and stackql.io/privacy covers collection, use, sharing, retention and contact.

Where a plugin's local server runs, per Anthropic's component support table: Claude Code loads it; Cowork loads it when the session runs on the user's computer; claude.ai chat and the desktop app's chat ignore it. Skills load on every surface. Manual .mcpb install in Claude Desktop (double-click, drag and drop, or Settings > Extensions > Advanced settings > Install Extension) is still supported and stays the Claude Desktop chat path, so the MCPB bundle keeps shipping; it just no longer has a directory listing.

Sources, all read 2026-11-05: claude.com/docs/connectors/building/submission, claude.com/docs/connectors/building/review-criteria, claude.com/docs/plugins/pre-submission-checklist, claude.com/docs/plugins/submit, claude.com/docs/plugins/build, claude.com/docs/plugins/platform-support, claude.com/docs/directory/publish, claude.com/docs/connectors/building/mcpb, code.claude.com/docs/en/plugins/manifest-reference.

Gaps against the plugin pre-submission checklist

Audited on main at 821cd3d. "Blocks" means the portal refuses the submission; "Held" means an Anthropic reviewer must clear the version, and the same hold can recur on every new version; "Validation stops" means no report at all.

Check Result if unmet State on main
.claude-plugin/plugin.json in the plugin folder Blocks None. Only .codex-plugin/plugin.json (OpenAI shape) exists
README of at least 40 words in the plugin folder; it is shown as the listing description Blocks packaging/openai-plugin/plugins/stackql/ has no README; the README is one level up
LICENSE file in the plugin folder or license in plugin.json Blocks license: MIT is in the Codex manifest; carry it over
Local server started as node ${CLAUDE_PLUGIN_ROOT}/<file> with plain arguments, no shell, no inline program, no npm run Held .mcp.json uses ./bin/stackql-mcp.js with cwd: ".", the Codex form
Package launcher (npx, uvx) pinned to an exact version Blocks if unpinned; still held when pinned ("Runs a pinned npx or uvx package") The launcher runs npx -y @stackql/mcp-server@0.12.778, through a shell on Windows
package.json beside a lockfile at the plugin root Held ("Dependencies install from a lockfile") None today; the vendoring in #893 change 4 must not add one
Every non-image file under 256 KiB, at most 512 files, only text, images and fonts Held Fine today; the vendored launcher and adm-zip must stay within this
Non-shell file run by an MCP server command when the plugin folder is a subfolder of the repository Held on every version ("Scripts the validator couldn't follow") Applies to any plugin folder under packaging/ in this repository
Executables in a top-level bin/ directory claude.ai and Cowork refuse to install the plugin The launcher lives in bin/
Credential read from the user's machine and sent to a server Held ("Uses a credential from the user's machine") The server reads ~/.stackql/.env and sends provider credentials to the provider APIs; must be stated in the README
Listing fields icon, documentationUrl, supportUrl, privacyPolicyUrl, termsOfServiceUrl, all https:// Listing incomplete stackql.io/privacy and /docs return 200; /terms and /support return 404 (stackql/stackql.io#305)
Security scan: README states everything the plugin runs, sends and fetches; readable source, not minified or packed First submission rejected if it fails The launcher downloads and executes the pinned stackql binary on first run; nothing states this yet
Repository under 50 MiB archived and 256 MiB unpacked, under 10,000 files, cross-platform file names, no export-ignore or filter attributes, no symlinks, submodules or LFS Validation stops Passes: 11.5 MiB gzip, 135.7 MiB unpacked, 1,555 files, no case clashes, the one .gitattributes sets only eol
Plugin name lowercase, distinctive, not reserved, not taken by another organization Blocks or held stackql passes the pattern; the portal checks uniqueness
Skill front matter with name and a single-string description Blocks No skill exists yet; #893 change 3 adds one

Changes

  1. Plugin folder packaging/claude-plugin/, rendered by scripts/render-platforms.sh --vector claude-plugin from the same npm wrapper source as the OpenAI vector. Contents: .claude-plugin/plugin.json with name, displayName, version, description, author, homepage, repository, license, keywords, the five listing fields, and mcpServers inline as {"stackql": {"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/server/stackql-mcp.js"]}}; README.md stating what the plugin runs (the launcher, then the pinned stackql binary), fetches (the binary from GitHub releases with SHA-256 verification, provider definitions from the registry) and sends (provider API calls with the user's own credentials; nothing to StackQL Studios); LICENSE; icon.png; skills/stackql-setup/SKILL.md shared with Package and ship the ChatGPT plugin directory ZIP for the local stdio MCP server #893 change 3; and the vendored launcher from Package and ship the ChatGPT plugin directory ZIP for the local stdio MCP server #893 change 4 under server/, not bin/, with no package.json or lockfile at the plugin root and every file under 256 KiB.
  2. Decide the repository the directory reads from, before the first submission, because the first organization to submit a repository folder holds that listing permanently. Option (a): submit stackql/stackql with plugin path packaging/claude-plugin and a tag as the tracked ref; every version is then held for a reviewer because the launcher is a non-shell file in a subfolder plugin. Option (b), recommended: a mirror repository stackql/stackql-claude-plugin with the plugin at its root, pushed by mcp-packaging.yml on each release from the rendered folder, the same pattern as stackql/setup-stackql-mcp and stackql/stackql-mcp-go. It avoids the subfolder hold, keeps the tracked branch free of monorepo churn, and the GitHub push webhook triggers each scan. Source of truth stays in this repository either way.
  3. Credentials: keep the env-file model. Optional userConfig.config_dir (type directory) passed as STACKQL_PLUGIN_CONFIG_DIR in the server env; it must carry a default, because Cowork drops a server whose referenced option has no default. Never reference ${user_config.*} in a url or a shell-form field.
  4. CI: a claude plugin validate ./packaging/claude-plugin --strict step and a STACKQL_MCP_BIN smoke run of the Claude layout in .github/workflows/openai-plugin.yml (or a renamed stdio-plugins.yml if the matrix is shared); validate.py parity check extended so the Claude manifest version equals packaging/mcpb/npm/package.json.
  5. Docs: rewrite packaging/mcpb/docs/anthropic-submission.md for the portal (the Google form path is dead, MCPB listings are deprecated, and the per-release email to the review thread is obsolete because the directory tracks the branch or tag and publishes per the auto-publish setting); update the Anthropic row in packaging/mcpb/listings.md, the two "Anthropic Desktop Extensions directory" lines in packaging/mcpb/README.md, and the install section of docs/mcp.md (plugin for Claude Code and Cowork, .mcpb for Claude Desktop chat). The stackql.io install page gets the Claude plugin path alongside the ChatGPT one from Terms, support and OpenAI domain challenge pages for the ChatGPT plugin directory listing stackql.io#305 item 5.
  6. Release flow: make claude-plugin-manifest in the npm-manifest chain next to openai-plugin-manifest; pin bump once the release carrying Explicit MCP tool annotations and titles for the ChatGPT plugin directory submission #892 is on npm (same gate as Package and ship the ChatGPT plugin directory ZIP for the local stdio MCP server #893 change 9).

Must not break

  • The MCPB bundle and manifest.template.json (manual install in Claude Desktop, Team and Enterprise admin deployment), make combined, and the asset immutability rule in mcp-packaging.yml.
  • The Codex marketplace route, .agents/plugins/marketplace.json, and the OpenAI ZIP in Package and ship the ChatGPT plugin directory ZIP for the local stdio MCP server #893.
  • The npm and PyPI wrappers, the OCI, cargo, go and dotnet vectors, and the tools/list shape, which every surface shares.

Verification

  • claude plugin validate clean with --strict, then the portal Validate report with no Blocks.
  • claude --plugin-dir ./packaging/claude-plugin: /mcp shows the server connected and the eight test cases from Package and ship the ChatGPT plugin directory ZIP for the local stdio MCP server #893 pass.
  • Zip upload to claude.ai (Customize > Plugins > Add > Upload plugin): the skill loads in chat and the local server is ignored there without an error.
  • A Cowork task on the same machine: the server loads and a credential-free query succeeds.

Submission checklist (outside the repo)

  • Find the June 2026 Desktop Extension listing in claude.ai/directory/manage and platform.claude.com/plugins/submissions. If it shows Withdraw, withdraw it; if it is there without Withdraw, or not there at all, email directory@anthropic.com asking what happens to the MCPB listing and to attach the plugin submission to the same organization.
  • Submit from the organization that should own the listing long term, on a paid plan (Team or Enterprise: an Owner, or a member granted the Directory permission), with a GitHub account connected on claude.ai that has push access to the submitted repository.
  • Choose the tracked ref (tag recommended) and the auto-publish setting; set up the GitHub push webhook (needs repository admin).
  • Data handling answers: the plugin stores no personal data; data goes to the cloud providers the user queries and to GitHub releases for the binary download; no retention; not intended for people under 18.
  • Four compliance acknowledgements and a monitored contact email.
  • stackql.io /terms and /support live (Terms, support and OpenAI domain challenge pages for the ChatGPT plugin directory listing stackql.io#305) before the listing fields point at them.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestgithub_actionsPull requests that update GitHub Actions code

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions