feat(mcp): add the MCP reference page, browse, and submit tools

[harlan-zw]

🔗 Linked issue

Related to #517

❓ Type of change

• 📖 Documentation
• 🐞 Bug fix
• 👌 Enhancement
• ✨ New feature
• 🧹 Chore
• ⚠️ Breaking change

📚 Description

The Claude directory listing needs public docs that an IT admin can review. The only docs were the setup steps on /developers, which say nothing about what each tool does or what data it sees. The MCP server could also only search: an Agent had no way to browse, or to add a repository the registry lacks.

New /developers/mcp page, owned by the MCP layer

• It renders every tool from mcpTools, so the page lists exactly what the directories scan. Each tool now carries an examplePrompt.
• Sections: overview, tools, connect, limits and data, troubleshooting, and support (#support, by email or Discord).
• It renders noindex,follow. FREEZE_AUDIT_PATHS lists it, which keeps it out of the pages sitemap until a measured query admits it.
• /developers moved to developers/index.vue so the new route is a sibling, not a child. It links the new page from its MCP steps.
• claudeConnectorUrl moved to shared/agent-setup.ts, so both layers build the Add to Claude link without a cross-layer import.

Four browse tools

• list_tracks and get_track read tracks, each a page of Skills for one kind of work. list_trending reads the trending board, and each row says whether developers talked about it on X or Bluesky or its GitHub stars rose. get_repository lists every Skill in one Repository.
• Each description leads with the user's goal. Every tool is read only and bounds its output under the MCP limit: tracks 25 Skills, trending 20 rows, repositories 30 Skills.
• The rows already carry pageUrl and runCommand from the API, so provenance stays one click away.
• GLOSSARY.md freezes list_tracks and get_track as identifiers for "track".

Submit a repository

• submit_repository asks skilld.dev to index a public GitHub repository through the public index request. It returns the indexed Skills, or a queued id with a status URL that later reports progress or the failure reason, such as a private repository.
• It is the only tool that is not read only. The API dedupes a repeat request, so it is idempotent and not destructive, and it changes nothing in the repository. A person still reviews which Skills the registry admits.
• Every page and listing that called all tools read only now names the exception: /developers, /developers/mcp, privacy, terms, the OpenAI package, the runbook, and the skilld-registry Skill. WebMCP now passes each tool's own read-only hint.
• The OpenAI review cases stay at five read-focused cases. A submission against a real repository either changes nothing or queues a job, which makes a weak review case.

The MCP server stays on Skill discovery and provenance; curator features are under review

• get_collection leaves the server and the WebMCP tools.
• install_command accepts only owner/repo and owner/repo/skill-name. A curator or collection ref now returns the accepted forms. The CLI and the site's collection pages are untouched.
• The privacy tool list, the OpenAI package, the runbook, and the skilld-registry Skill drop the collection tool.

Safety claims

• In the opencode evals, 4 of 4 answers called a Skill "safe", and once "verified". The get_skill description now states that skilld does not check whether a Skill is safe. The server instructions say skilld.dev shows provenance, does not review safety, and never calls a Skill safe or verified.
• feat(mcp): tell chat agents to follow a Skill without a shell #520 put chat-app instructions into the get_skill description. The Claude compliance step rejects behaviour instructions in a tool description, so that wording moved into the server instructions with the same meaning.

ChatGPT setup steps

• The ChatGPT tab described a Developer mode toggle that no longer exists, and its guide link answered 404. The steps now follow the Plugins flow verified today in ChatGPT on the web: Add custom MCP server, No authentication, Create as a plugin, Connect. The plan sentence now links OpenAI's custom MCP server guide instead of naming plans.

Support and listings

• Help now goes to harlan@harlanzw.com or the Harlan's Open Source Discord. This covers the terms page, supportURL in the OpenAI package (/developers/mcp#support), and the runbook's Claude fields.
• The OpenAI package's five review cases now cover search, provenance, a track, trending, and the run command.
• The runbook now adds the OpenAI domain token to wrangler.jsonc vars through a pull request, because the deploy workflow is the only path to production.

⚠️ Breaking Changes

MCP clients that call get_collection, or pass a curator or collection ref to install_command, now get an error. ChatGPT and Claude drop the tool on their next scan.

🤖 AI disclosure: Harlan Agent Kit modified this description. My AI open-source policy.

[harlan-zw]

Agent note (Harlan Agent Kit). Checked by hand on a local production build served by wrangler dev, since CI cannot cover it:

• tools/list returns search_skills, get_skill, and install_command, each with annotations.title.
• install_command with anthropics/skills returns npx skilld add anthropics/skills. With @harlan-zw it returns the accepted forms.
• /developers/mcp renders noindex,follow, has #support, and is absent from sitemap/pages.xml.
• At 390px the page has no horizontal scroll.

[harlan-zw]

Agent note (Harlan Agent Kit), for head b2b9b0b. Checked by hand, since CI cannot cover it:

• A local production build lists 7 tools, each with annotations.title: search_skills, get_skill, install_command, list_tracks, get_track, list_trending, get_repository. list_trending rejects window "year".
• Against the live API, list_tracks returns 14 tracks. get_track testing returns 10 of 98. list_trending month at 20 rows is 37,412 characters, under the 48,000 limit. get_repository anthropics/skills returns 20 of 20. A missing slug returns "Track not found: nothing-here".
• /developers/mcp renders all 7 tools. The ChatGPT tab shows the Plugins flow, with no Developer mode step. At 390px there is no horizontal scroll.
• The opencode MCP evals were not run: the local D1 holds no registry data, and production does not serve the new tools yet.

[harlan-zw]

Agent note (Harlan Agent Kit), for head fed3532. Checked by hand, since CI cannot cover it: a local production build lists 8 tools, each with annotations.title. submit_repository is the only one with readOnlyHint false, and idempotentHint is true. /developers/mcp shows 7 Read only badges and 1 Queues a request. Against the live API, submit_repository with vercel-labs/agent-skills answers indexed with 9 Skills and the Repository page. That repository was already indexed, so no job was queued. With https://gitlab.com/a/b it answers "Cannot index https://gitlab.com/a/b. Send owner/repo or the URL of a public GitHub repository."