Skip to content

chore(release): list each server in the MCP Registry at release time - #5629

Open
cliffhall wants to merge 2 commits into
v2/mainfrom
v2/chore/3047-mcp-registry-entries
Open

cliffhall wants to merge 2 commits into
v2/mainfrom
v2/chore/3047-mcp-registry-entries

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #3047

Description

Adds what this repository needs to list its seven servers in the official MCP Registry. Merging this registers nothing. The first entries are published by the next GitHub Release a maintainer publishes and approves.

  • src/<server>/server.json (seven files): each server's registry entry, named io.github.modelcontextprotocol/server-<name>, the name every published package already claims (mcpName in package.json, the mcp-name: marker in the Python READMEs). The committed file carries no version.
  • scripts/mcp-registry-entries.mjs: checks each entry against the package it points at (name equals the package's marker, identifier equals the manifest's name, description within the registry's 100 characters, one stdio package, no committed version) and stamps the version from package.json / pyproject.toml. A version still lives only in the manifests, so the Version Packages and Prepare Python Release PRs are unchanged. The check also runs in the script tests (validate:guards), so a bad entry fails CI on the PR that introduces it, not at release time.
  • release.yml:
    • detect-packages runs the script and hands the stamped entries on as a job output (mcp_registry), the way it already hands on each package's expected name and version.
    • A new job, publish-mcp-registry, runs after publish-npm and publish-pypi (the registry accepts an entry only for a package version that is already on npm or PyPI). For each entry it asks the registry's public API whether that version is listed: 200 skips it, 404 queues it, anything else fails that entry. If anything is queued it runs mcp-publisher login github-oidc once and publishes each.
  • Docs: RELEASING.md (a new The MCP Registry section, the job table, the release steps), AGENTS.md (the tree, and a rule under Versions), and the release and project-structure skills.

How the new job meets the credentialed-job rules

Rule Here
Every action in a credentialed job is SHA-pinned The job runs no action at all. verify:action-pins passes, and detect-packages, whose output it reads, was already pinned
A job with a publish credential does not install dependencies or build No checkout, no install. It downloads one binary, mcp-publisher, pinned to release v1.8.9 and to the SHA-256 of that release's Linux archive, checked before it is unpacked
Publishing is a deliberate maintainer action It only runs in a release: published run, and it takes the release environment, so it waits for a required reviewer like the other publish jobs
What is published comes from reviewed source The entries arrive as a detect-packages job output, computed on the released commit before any dependency code runs. The job re-checks each directory, name and version before using them in a path or URL

There is no secret and no account: the registry grants io.github.modelcontextprotocol/* to an OIDC token whose repository_owner is this organization.

Server Details

None (repository-wide). No server's code, tools, resources or prompts change. Each server gains a server.json beside its manifest; the npm packages do not ship it (files is ["dist"]), and the Python sdists gain one small metadata file.

Motivation and Context

#3047 asks for the reference servers to be listed in the registry. The package-side markers shipped long ago, and nothing else existed: no server.json, no publish step. None of the seven is listed today (see the probes).

The issue's own plan, mcp-publisher login github from a maintainer's machine, no longer works for this namespace. The registry's authentication docs now say the interactive login cannot publish to an organization namespace at all, and name two ways that can: GitHub Actions OIDC, or an organization Owner's personal access token. This PR takes the first, which needs no token.

Not in this PR

  • The docs server (https://modelcontextprotocol.io/mcp), the eighth item in the issue. This repository has none of it: it is served by the documentation site, whose source is modelcontextprotocol/modelcontextprotocol (docs/). Its entry is a remotes entry with no package to verify, and it belongs with that repository.
  • Docker images (mcp/<server>), which the issue mentions as a possibility. The registry verifies an image by a label inside it, and these images are not built by this repository's workflows.

How Has This Been Tested?

No client-observable surface, so targeted probes. Nothing below authenticated to the registry or published to it.

1. None of the seven is registered today (the registry's public API, by name):

server-everything -> 404        server-fetch -> 404
server-filesystem -> 404        server-git -> 404
server-memory -> 404            server-time -> 404
server-sequential-thinking -> 404
control (io.github.x402node/x402-mcp, a server known to be listed) -> 200

2. Every current package version carries the marker the registry verifies:

@modelcontextprotocol/server-everything 2.3.1            mcpName= io.github.modelcontextprotocol/server-everything
@modelcontextprotocol/server-filesystem 2.4.0            mcpName= io.github.modelcontextprotocol/server-filesystem
@modelcontextprotocol/server-memory 2.2.1                mcpName= io.github.modelcontextprotocol/server-memory
@modelcontextprotocol/server-sequential-thinking 2.2.0   mcpName= io.github.modelcontextprotocol/server-sequential-thinking
mcp-server-fetch 2026.11.18   mcp-name: io.github.modelcontextprotocol/server-fetch
mcp-server-git 2026.11.18     mcp-name: io.github.modelcontextprotocol/server-git
mcp-server-time 2026.11.18    mcp-name: io.github.modelcontextprotocol/server-time

3. The stamped entries validate against the registry's published schema (https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json, with Ajv), and the committed, version-less file does not, which is why the stamp exists:

everything  io.github.modelcontextprotocol/server-everything  2.3.1       VALID
fetch       io.github.modelcontextprotocol/server-fetch       2026.11.18  VALID
filesystem  io.github.modelcontextprotocol/server-filesystem  2.4.0       VALID
git         io.github.modelcontextprotocol/server-git         2026.11.18  VALID
memory      io.github.modelcontextprotocol/server-memory      2.2.1       VALID
sequentialthinking  io.github.modelcontextprotocol/server-sequential-thinking  2.2.0  VALID
time        io.github.modelcontextprotocol/server-time        2026.11.18  VALID
committed src/time/server.json (no version): must have required property 'version'

4. The guard fires on a planted defect, then passes. With src/git/server.json given a different name and identifier and a committed version:

mcp-registry-entries: 3 problem(s) with the MCP Registry entries:
  src/git/server.json: `name` is "io.github.modelcontextprotocol/server-gitt" but the package claims "io.github.modelcontextprotocol/server-git" (the `mcp-name:` marker in README.md); the registry refuses an entry whose package names another server
  src/git/server.json: `packages[0].identifier` must be the published package, `mcp-server-git`
  src/git/server.json: `packages[0].version` must not be committed: it is stamped from the package manifest at release time
exit 1

Restored: exit 0.

5. The job's own shell, run from the workflow file with curl and mcp-publisher stubbed (scripts/release-mcp-registry.test.mjs, 25 tests): every missing entry is published after one login; a listed version is skipped; with nothing missing no token is requested; a 500, 429, 302 or no answer fails that entry without publishing it and without stopping the others; one refused entry does not stop the rest and fails the job; an empty, malformed or out-of-namespace job output registers nothing. scripts/mcp-registry-entries.test.mjs (40 tests) covers the entry rules, the stamp, the README marker, and the repository's own entries.

6. npm run local:gate: exit 0.

Not exercised, and cannot be before a Release: the live login github-oidc and publish calls. The job is written so a failure there cannot affect the packages, which are already published when it starts. mcp-publisher validate was not run locally either; probe 3 is the schema check it would have made.

Breaking Changes

None. No client configuration changes.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation (not applicable to the protocol: the registry's publishing docs were read instead, at modelcontextprotocol/registry docs/)
  • My changes follow MCP security best practices (the credentialed-job table above)
  • I have updated the server's README accordingly (not applicable: no server's tools, configuration or environment variables change; RELEASING.md and AGENTS.md are updated)
  • I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes (not applicable: server.json is outside each package's files, so no published TypeScript package changes)
  • I have tested this with an LLM client (not applicable: no client-observable surface; targeted probes above)
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have documented all environment variables and configuration options (the two MCP_PUBLISHER_* pins, in the workflow and RELEASING.md)

Additional context

What a maintainer does after merging

  1. Nothing until the next release. At that release, after approving the package deployments, approve one more: Publish to the MCP Registry. It starts only once the package publish jobs finish.
  2. Check the result with the loop the release skill gains (step 6), or by searching the registry for io.github.modelcontextprotocol.

Choices a maintainer may want to revisit

  • The release environment on the new job. The registry does not bind to it; it is there so registering waits for a person. The cost is a second approval moment per release. Dropping environment: release from the job would let it follow the approved package publishes on its own.
  • The first registration lists the versions current at that release, not earlier ones. Older versions can never be backfilled by this workflow, and need not be: clients resolve the latest.
  • The registry is in preview, and its docs warn of breaking changes. The job is last in the run and touches nothing else, so a registry-side break costs a red job, not a release.

🤖 Generated with Claude Code

Each server gets a `server.json`, its entry for the official MCP Registry.
The committed file carries no version: `scripts/mcp-registry-entries.mjs`
stamps it from the package manifest on the released commit, after checking
the entry against the package it points at (`mcpName`, or the README's
`mcp-name:` marker), so a version still lives only in the manifests.

`release.yml` gains `publish-mcp-registry`, which runs after the package
publish jobs, in the `release` environment, and registers each entry the
registry does not already list with `mcp-publisher login github-oidc`. The
publisher binary is pinned by release and SHA-256. The job has no checkout
and runs no action; what it registers reaches it as a `detect-packages`
output.

Nothing is registered by this change: the first entries are published by
the next Release a maintainer publishes and approves.

Closes #3047

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall cliffhall added the v2 label Nov 18, 2026
@changeset-bot

changeset-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 3c42f9f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

filesystem: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 16 0 0 1
Head 16 0 0 1

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

sequentialthinking: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 1 0 0 0
Head 1 0 0 0

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

everything: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 22 4 8 5
Head 22 4 8 5

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

fetch: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 1 1 0 0
Head 1 1 0 0

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

git: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 14 2 0 0
Head 14 2 0 0

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

memory: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 9 0 1 0
Head 9 0 1 0

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

time: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 525feb526db0 (Merge 3c42f9f into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 3 0 0 0
Head 3 0 0 0

Updated by this run for 3c42f9fe3b146fe2fd8879bae203176ff18d9866.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The filesystem registry entry lacks a required, repeatable allowed-directory argument, causing generated launches to use an empty allow-list that breaks tool calls and prevents legacy clients without Roots from initializing.

1 open issue
What changed in this PR

Adds release-time registration of the seven reference servers in the official MCP Registry, addressing the repository-owned portion of #3047. Merging alone registers nothing; registration follows package publication during a maintainer-approved release.

Changes:

  • Adds versionless registry entries, validated against package metadata and stamped from manifest versions.
  • Adds an OIDC-authenticated publishing job that skips existing entries and reports individual failures.
  • Adds validation and workflow regression tests, plus release and maintenance documentation.
File Description
src/​time/​server.json Declares the Time registry entry.
src/​sequentialthinking/​server.json Declares the Sequential Thinking registry entry.
src/​memory/​server.json Declares the Memory registry entry.
src/​git/​server.json Declares the Git registry entry.
src/​filesystem/​server.json Declares the Filesystem registry entry.
src/​fetch/​server.json Declares the Fetch registry entry.
src/​everything/​server.json Declares the Everything registry entry.
scripts/​release-mcp-registry.test.mjs Tests publishing decisions and workflow safeguards.
scripts/​mcp-registry-entries.test.mjs Tests entry validation and version stamping.
scripts/​mcp-registry-entries.mjs Validates and stamps entries for release.
RELEASING.md Documents registration, approvals, and recovery.
AGENTS.md Records registry metadata maintenance rules.
.github/​workflows/​release.yml Passes stamped entries to the registry publishing job.
.claude/​skills/​release/​SKILL.md Adds approval and registration verification steps.
.claude/​skills/​project-structure/​SKILL.md Documents registry files in server layouts.

Review effort: Balanced

Comment thread src/filesystem/server.json Resolved
…try entry

A client that builds its launch command from the entry had no directory
input to collect, so the server would start with an empty allow-list.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: one finding, fixed.

  • src/filesystem/server.json declared no allowed-directory argument (high): fixed in 3c42f9f. The entry now carries a required, repeatable positional packageArguments input (format: filepath), so a client that builds its launch command from the entry collects the directories first. A script test pins it. No suppressed comments in the round.

npm run local:gate exit 0 on 3c42f9f. Requesting another round for the fix.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the release-time MCP Registry registration changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 2: clean (no findings; the round 1 finding is marked resolved). The review loop ends here on the first clean round. Not merged: merging is the maintainer's.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Register MCP reference and docs servers in the official server registry

2 participants