From 7da087da667f6403a85c670ff13d83fda39606d6 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 13:02:16 -0500 Subject: [PATCH 1/2] chore(release): list each server in the MCP Registry at release time 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 Signed-off-by: cliffhall --- .claude/skills/project-structure/SKILL.md | 4 +- .claude/skills/release/SKILL.md | 16 + .github/workflows/release.yml | 125 +++++- AGENTS.md | 13 +- RELEASING.md | 21 +- scripts/mcp-registry-entries.mjs | 306 ++++++++++++++ scripts/mcp-registry-entries.test.mjs | 469 ++++++++++++++++++++++ scripts/release-mcp-registry.test.mjs | 385 ++++++++++++++++++ src/everything/server.json | 20 + src/fetch/server.json | 20 + src/filesystem/server.json | 20 + src/git/server.json | 20 + src/memory/server.json | 20 + src/sequentialthinking/server.json | 20 + src/time/server.json | 20 + 15 files changed, 1472 insertions(+), 7 deletions(-) create mode 100644 scripts/mcp-registry-entries.mjs create mode 100644 scripts/mcp-registry-entries.test.mjs create mode 100644 scripts/release-mcp-registry.test.mjs create mode 100644 src/everything/server.json create mode 100644 src/fetch/server.json create mode 100644 src/filesystem/server.json create mode 100644 src/git/server.json create mode 100644 src/memory/server.json create mode 100644 src/sequentialthinking/server.json create mode 100644 src/time/server.json diff --git a/.claude/skills/project-structure/SKILL.md b/.claude/skills/project-structure/SKILL.md index 78e9bf9a3a..2937c0d955 100644 --- a/.claude/skills/project-structure/SKILL.md +++ b/.claude/skills/project-structure/SKILL.md @@ -24,7 +24,8 @@ entry point is `index.ts`, sources sit at the workspace root (there is no `src/` inside a server), tests are in `__tests__/`, and `tsc` writes `dist/`. Each has the same four config files: `package.json`, `tsconfig.json` (the build), `tsconfig.test.json` (the no-emit typecheck program, which also -includes the tests) and `vitest.config.ts`. +includes the tests) and `vitest.config.ts`. Each also has a `server.json`, its +MCP Registry entry, which carries no version: `release.yml` stamps it. | Server | Layout | Where its features are registered | | --- | --- | --- | @@ -66,6 +67,7 @@ in-process harness. src// ├── pyproject.toml dependencies, the console script, pytest and coverage config ├── uv.lock, .python-version +├── server.json the server's MCP Registry entry (no version: release.yml stamps it) ├── src/mcp_server_/ │ ├── __init__.py main(): the command-line flags, then asyncio.run(serve(...)) │ ├── __main__.py python -m mcp_server_ diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index e939551079..7f9265fcf5 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -721,6 +721,12 @@ skip. Approve the packages whose build leg passed. One failed build leg does not hold the others back; that package is handled as a failed publish (`RELEASING.md` **When a publish fails**). +**One more approval arrives after the packages publish**: `Publish to the MCP +Registry`, which lists each published version in the MCP Registry. It cannot +be approved with the others, because it only starts once they finish, so come +back for it. Its failure does not touch the packages (`RELEASING.md` **The MCP +Registry**). + ## 6. After it publishes ```sh @@ -738,6 +744,16 @@ done A freshly published npm version can take a few minutes to appear. Query the exact version, as above, never `dist-tags`. +Then each server's MCP Registry entry at that version: 200 means listed. + +```sh +node scripts/mcp-registry-entries.mjs | jq -r '.[] | "\(.name) \(.version)"' | + while read -r name version; do + echo "$name $version $(curl -s -o /dev/null -w '%{http_code}' \ + "https://registry.modelcontextprotocol.io/v0/servers/${name/\//%2F}/versions/$version")" + done +``` + ### The first semver release only: deprecate the date-stamped versions The TypeScript packages were published with date-stamped versions (`2025.x`, diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 55d108f780..6242ca489c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,6 +19,16 @@ # `id-token: write` and the `release` environment. No checkout, # no dependency install, no build. # +# AFTER THE PACKAGES, THE MCP REGISTRY (#3047). `publish-mcp-registry` lists +# each server in the official MCP Registry (registry.modelcontextprotocol.io) +# at the version just published. A registry entry is a `server.json` that +# points at a package, and the registry accepts one only for a package version +# that already exists on npm or PyPI and names the server itself (`mcpName`, +# or the README's `mcp-name:` marker), so the job runs after both sets of +# publish legs. What it registers comes from `detect-packages` +# (`scripts/mcp-registry-entries.mjs`), as a job output, and it is one more +# `release` environment deployment for a maintainer to approve. +# # The split is about what runs next to the OIDC token. Installing dependencies # runs their lifecycle scripts, and a build runs the toolchain; in a job that # can mint a publish credential, any of that code can publish. Here the only @@ -34,7 +44,8 @@ # the next release with no special handling, and one that did not change costs # a skipped leg. For npm the build leg decides (`npm-publish-guard.mjs`) and # uploads a `SKIP` marker instead of a tarball; for PyPI the registry decides -# at upload (`skip-existing`). +# at upload (`skip-existing`). The MCP Registry job asks the registry for each +# entry's version and publishes only the ones it does not have. # # The trigger is `release: published` and nothing else, so editing a # published Release's notes never re-runs publishing. A release event runs the @@ -44,7 +55,11 @@ # Authentication is OIDC trusted publishing on both registries: there are no # registry tokens. Each trusted publisher is bound to this workflow's filename # (`release.yml`) and the `release` environment, so the publish jobs must stay -# in this file and keep that environment. +# in this file and keep that environment. The MCP Registry takes the same kind +# of token (`mcp-publisher login github-oidc`) and grants the +# `io.github.modelcontextprotocol/*` namespace to any workflow in this +# organization: it is bound to neither the file nor the environment, so there +# the environment is the maintainer's approval and nothing else. # # Only a commit that is on `main` is published. A Release can be created for # any tag on any commit, and the environment approval shows a reviewer a tag @@ -73,7 +88,7 @@ concurrency: group: release queue: max -# Nothing in this workflow needs more than read access by default; the two +# Nothing in this workflow needs more than read access by default; the three # publish jobs add `id-token: write` for themselves. permissions: contents: read @@ -88,6 +103,7 @@ jobs: pypi_packages: ${{ steps.find-packages.outputs.pypi_packages }} npm_expected: ${{ steps.expected.outputs.npm_expected }} pypi_expected: ${{ steps.expected.outputs.pypi_expected }} + mcp_registry: ${{ steps.registry.outputs.mcp_registry }} steps: # On a release event the default ref is the release's tag: the exact # commit the maintainer released. Full history, for the check below. @@ -124,6 +140,14 @@ jobs: id: expected run: node scripts/release-manifest.mjs + # Each server's MCP Registry entry: its committed `server.json`, checked + # against the package it points at and stamped with that package's + # version. Read here for the same reason as the step above, and a + # problem with any entry stops the release before anything is built. + - name: Record each server's MCP Registry entry + id: registry + run: node scripts/mcp-registry-entries.mjs + build-npm: timeout-minutes: 15 needs: [detect-packages] @@ -476,3 +500,98 @@ jobs: with: packages-dir: dist skip-existing: true + + publish-mcp-registry: + timeout-minutes: 10 + needs: [detect-packages, publish-npm, publish-pypi] + # After the package publish legs, whatever their results: an entry is only + # accepted for a package version that is on npm or PyPI, so one package's + # failed leg fails that entry alone and the rest are still registered. + if: ${{ !cancelled() && needs.detect-packages.result == 'success' }} + name: Publish to the MCP Registry + # The registry does not look at the environment (see the header). It is + # here so that registering, like publishing, waits for a maintainer. + environment: release + permissions: + # Required for `mcp-publisher login github-oidc`. Like the other publish + # jobs, this one has no checkout and installs no dependency. + id-token: write + runs-on: ubuntu-latest + env: + # The registry's publisher CLI, pinned to one release and to the SHA-256 + # of that release's archive: a release asset can be replaced, and this + # binary runs next to the OIDC token. Bump both together, taking the + # digest from the release's asset list (RELEASING.md has the command). + MCP_PUBLISHER_VERSION: v1.8.9 + MCP_PUBLISHER_SHA256: 4d527ca8f1ced0394c962dc925c2a4a4addef441cbefd62501c875e9481823a8 + steps: + - name: Download the pinned mcp-publisher + run: | + ARCHIVE=mcp-publisher_linux_amd64.tar.gz + curl --fail --location --silent --show-error --output "$ARCHIVE" \ + "https://github.com/modelcontextprotocol/registry/releases/download/$MCP_PUBLISHER_VERSION/$ARCHIVE" + echo "$MCP_PUBLISHER_SHA256 $ARCHIVE" | sha256sum --check --strict - + tar -xzf "$ARCHIVE" mcp-publisher + + # One `entries//server.json` per server, and `plan.tsv` naming + # each for the shell below. An empty or unreadable output fails here: + # nothing is registered from a release that recorded no entries. + - name: Write the entries the released commit declares + env: + ENTRIES: ${{ needs.detect-packages.outputs.mcp_registry }} + run: | + node -e ' + const fs = require("fs"); + const entries = Object.entries(JSON.parse(process.env.ENTRIES)); + if (entries.length === 0) throw new Error("no MCP Registry entries were recorded"); + const plan = []; + for (const [dir, entry] of entries) { + const { name, version } = entry; + // These three reach a URL and a path in the next step. + if (!/^[a-z0-9-]+$/.test(dir)) throw new Error("unexpected server directory " + JSON.stringify(dir)); + if (typeof name !== "string" || !/^io\.github\.modelcontextprotocol\/[a-zA-Z0-9._-]+$/.test(name)) throw new Error("unexpected server name " + JSON.stringify(name)); + if (typeof version !== "string" || !/^[0-9A-Za-z.-]+$/.test(version)) throw new Error("unexpected version " + JSON.stringify(version)); + fs.mkdirSync("entries/" + dir, { recursive: true }); + fs.writeFileSync("entries/" + dir + "/server.json", JSON.stringify(entry, null, 2) + "\n"); + plan.push([dir, name, version].join("\t")); + } + fs.writeFileSync("plan.tsv", plan.join("\n") + "\n"); + ' + cat plan.tsv + + # The registry-diff guard for the MCP Registry: a version it already + # lists is skipped, not failed, and a published entry cannot be changed, + # so a re-run or a later release registers only what is missing. An + # answer that is neither "there" nor "not there" fails that entry rather + # than guessing. The token is asked for only when there is something to + # publish. One entry's failure does not stop the others; it fails the + # job at the end, and the next release (or a re-run) picks it up. + - name: Publish each entry the registry does not have + run: | + pending="" + failed=0 + while IFS="$(printf '\t')" read -r dir name version; do + url="https://registry.modelcontextprotocol.io/v0/servers/$(printf '%s' "$name" | sed 's|/|%2F|')/versions/$version" + code="$(curl -sS -o /dev/null -w '%{http_code}' "$url")" || code="no answer" + case "$code" in + 200) echo "$name@$version is already in the MCP Registry; nothing to publish." ;; + 404) pending="$pending $dir" ;; + *) + echo "::error::Could not tell whether $name@$version is in the MCP Registry ($code from $url)" + failed=1 + ;; + esac + done < plan.tsv + if [ -z "$pending" ]; then + exit "$failed" + fi + ./mcp-publisher login github-oidc + for dir in $pending; do + if ./mcp-publisher publish "entries/$dir/server.json"; then + echo "Registered src/$dir." + else + echo "::error::The MCP Registry refused the entry for src/$dir (see the output above). If its package failed to publish in this run, fix that first." + failed=1 + fi + done + exit "$failed" diff --git a/AGENTS.md b/AGENTS.md index c090e1a5d0..5ca356ae0a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,13 +55,13 @@ servers/ ├── .changeset/ Pending changesets for the TypeScript servers, and the changesets config ├── scripts/ The pre-push gate (gate-lease, smoke-servers, validate-py, coverage-py, interface-diff), its guards (verify-*), │ the skills tooling, release tooling (npm-publish-guard, prepare-python-release, -│ pack-and-verify, release-manifest, release-notes), and the issue-filing sweeps +│ pack-and-verify, release-manifest, mcp-registry-entries, release-notes), and the issue-filing sweeps │ (dependency-refresh, dependabot-alerts, sdk-watch), and the session-start │ instructions check (session-instructions-check) ├── docs/ Design documents; quality-gate.md is the gate's reference (stages, CI vs local, the lease); │ contribution-model.md holds the outside-PR backlog plan; ai-software-factory.md is the │ overview of how the rules, skills, gates and sweeps fit together -├── .github/workflows/ typescript.yml, python.yml (per-package CI), release.yml (publishes on a GitHub Release), +├── .github/workflows/ typescript.yml, python.yml (per-package CI), release.yml (publishes on a GitHub Release, then lists each server in the MCP Registry), │ version-packages.yml (the changesets PR), prepare-python-release.yml (the CalVer PR), │ everything-mcp-diff.yml (each changed server's interface diff on PRs), │ mcp-interface-diff.yml (a dispatch-only placeholder for that file's new name, #5463), @@ -314,6 +314,15 @@ maintainer publishes a GitHub Release), never a side effect of a merge. - **A TypeScript server reports its version from its `package.json`** (the `SERVER_VERSION` its `version.ts` exports), never from a literal in the source: the version PR edits `package.json` only. +- **A server's `server.json` is its MCP Registry entry, and carries no + version.** `release.yml` stamps it from the manifest and registers it after + the package publishes (`scripts/mcp-registry-entries.mjs`). Its `name` is the + `mcpName` in the server's `package.json`, or the `mcp-name:` marker in a + Python server's `README.md`: the registry verifies the entry against the + published package, so the two change together, and the script tests fail + when they differ. **Never rename a registered server**: a published + entry cannot be edited, so the old name would stay behind as a separate + entry that nothing updates. ## Contributing diff --git a/RELEASING.md b/RELEASING.md index c4d16eff93..61234e3fd7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -51,6 +51,7 @@ Publishing is triggered by a maintainer **publishing a GitHub Release** whose ta | --- | --- | --- | | **Build** (`build-npm`, `build-pypi`) | No `id-token`, no environment | Installs dependencies, **runs the package's tests** (for Python, the whole `validate:py` chain: ruff, pyright, pytest), then runs **`pack:verify`**: it builds the tarball or wheel, installs it into an empty directory and boots the installed server. Uploads that verified artifact | | **Publish** (`publish-npm`, `publish-pypi`) | `id-token: write` and the `release` environment (a required reviewer must approve each deployment) | Downloads the artifact, checks that its name and version are the ones the released commit declares for that package, and hands it to the registry. No checkout, no dependency install, no build | +| **Register** (`publish-mcp-registry`, one job for all seven servers) | `id-token: write` and the `release` environment | After the publish jobs: lists each server in the [MCP Registry](https://registry.modelcontextprotocol.io/) at the version just published. No checkout, no dependency install, no action. See [The MCP Registry](#the-mcp-registry) | The split is about what runs next to the publish credential. Installing dependencies runs their lifecycle scripts, and a build runs a toolchain; in a job that can mint an OIDC token, any of that code could publish. Here the token only ever sits beside the registry client and SHA-pinned actions. Every action in the build and publish jobs is pinned to a commit SHA, enforced by `npm run verify:action-pins`. @@ -70,6 +71,24 @@ So a release publishes exactly the packages whose version moved, and a package w Because of those bindings, the publish jobs must stay in `release.yml` and keep the `release` environment. +### The MCP Registry + +Each server is also listed in the official [MCP Registry](https://registry.modelcontextprotocol.io/), where clients look servers up, under the name `io.github.modelcontextprotocol/server-`. A listing is not a package: it is a `server.json` that points at the npm or PyPI package, and the registry stores one per version. + +- **The entry is `src//server.json`, and it carries no version.** [`scripts/mcp-registry-entries.mjs`](scripts/mcp-registry-entries.mjs) stamps the version from `package.json` or `pyproject.toml` on the released commit, so the manifests stay the only place a version lives. It runs in `detect-packages`, and it fails the release before anything is built if an entry is malformed or disagrees with its package. The same check runs in the script tests, so a bad entry fails CI on the PR that introduces it. +- **The registry verifies the package, not this repository.** It accepts an entry only when the published package names the server: `mcpName` in `package.json` for npm, and an `mcp-name: ` marker in the README for PyPI. The current version of every package carries one. That is also why `publish-mcp-registry` runs after the publish jobs: the version it registers must already be on npm or PyPI. +- **Authentication is GitHub OIDC, with no token and no account.** `mcp-publisher login github-oidc` exchanges the job's OIDC token for the `io.github.modelcontextprotocol/*` namespace, which the registry grants to any workflow in this organization. The interactive `mcp-publisher login github` cannot publish to an organization namespace at all, so this job is the way these entries are published; do not register one from a laptop. +- **It is one more `release` environment approval**, and it arrives after the package publish jobs finish, so it is approved separately from them. The registry does not look at the environment; it is there so that registering, like publishing, waits for a maintainer. +- **A version the registry already lists is skipped, not failed**, so a re-run or a later release registers only what is missing. A published entry cannot be edited: a change to a title or description reaches the registry with the server's next version. +- **`mcp-publisher` is pinned** in the job's `env`, by release tag and by the SHA-256 of that release's Linux archive, which the job checks before unpacking it. To move to a newer release, change both together: + + ```bash + gh api repos/modelcontextprotocol/registry/releases/tags/ \ + --jq '.assets[] | select(.name == "mcp-publisher_linux_amd64.tar.gz") | .digest' + ``` + +When the job fails, the packages are already published and are unaffected. An entry the registry refused because its package's own publish leg failed is registered by re-running the job once that package is out (or by the next release). A registry outage is a re-run. The registry is in preview, so a change on its side that the pinned `mcp-publisher` cannot speak (an `invalid audience` error, say) is fixed by bumping the pin on `v2/main`; the entries it missed can only be registered from a later release, since a release runs the workflow as it is at its tag. + ## Cutting a release A release ships one **milestone**. The step-by-step procedure, with its commands, is the [`release` skill](.claude/skills/release/SKILL.md) (`/release`); this is its shape. @@ -84,7 +103,7 @@ A release ships one **milestone**. The step-by-step procedure, with its commands 3. **The merge PR** takes `v2/main` into `main`. It is a pure merge: its branch is `origin/v2/main` with no commits of its own, and the merged tree equals `origin/v2/main`'s. Its body starts with `Part of #`, not `Closes`, because `main` is the default branch and a closing keyword there would close the issue before anything is published. It is merged with a merge commit, never squashed. 4. **The release ledger** is linked from the merge PR. It records, for the merge branch's tree: `npm run local:gate`; `npm run pack:verify` for each package; each server-facing issue in the milestone exercised through a client; and a targeted probe for each issue with no client surface. The maintainers approve the merge on it. A finding is fixed on `v2/main` and merged in again, never committed to the merge branch. 5. **A maintainer publishes a GitHub Release** targeting the merge commit on `main` (the commit the ledger verified, chosen by SHA rather than by the branch name, which may have moved). [`scripts/release-notes.mjs`](scripts/release-notes.mjs) (`npm run release:notes`) writes the notes, one section per published package with its PRs and a Thanks section for the community members whose issues and advisories (`--advisory`) the release addresses and whose prototypes ship in it (`--thank`), and with `--draft` creates the draft Release under a tag named for the milestone (`vX.Y.Z`). The maintainer reads the draft and publishes it. The tag is a label, not a version. -6. **The build jobs run, then the maintainer approves the `release` environment deployments.** Each package publishes if its version is not on the registry yet; the rest skip cleanly. +6. **The build jobs run, then the maintainer approves the `release` environment deployments.** Each package publishes if its version is not on the registry yet; the rest skip cleanly. Once they finish, one more deployment asks for approval: `publish-mcp-registry`, which lists the published versions in the MCP Registry. 7. **The release issue is closed by hand**, and its card moves to Done. ## When a publish fails diff --git a/scripts/mcp-registry-entries.mjs b/scripts/mcp-registry-entries.mjs new file mode 100644 index 0000000000..71d07be141 --- /dev/null +++ b/scripts/mcp-registry-entries.mjs @@ -0,0 +1,306 @@ +#!/usr/bin/env node +// Each server's entry for the official MCP Registry +// (registry.modelcontextprotocol.io), for `release.yml` (#3047). +// +// A registry entry is a `server.json`: the server's registry name, a title and +// description, and the package a client installs to run it. Each server keeps +// its own at `src//server.json`. +// +// THE COMMITTED FILE CARRIES NO VERSION, and this script adds it. The registry +// requires one, and it must be the version of a package that is already on npm +// or PyPI. But a version in this repository changes only in a version PR, +// which edits `package.json` or `pyproject.toml` and nothing else +// (`AGENTS.md`, **Versions**). A version written into `server.json` as well +// would be a second copy for those PRs to keep in step, and a stale one would +// register an entry pointing at the wrong package. So the manifest stays the +// only place a version lives, and the entry is stamped from it at release +// time, on the released commit. +// +// The registry accepts an entry only when the package itself names the server: +// `mcpName` in a published `package.json`, or an `mcp-name: ` marker in +// the README a PyPI project publishes as its description. Those were added +// when the issue was filed and are in every published package. A committed +// entry that disagreed with them would be refused at release time, long after +// the change that broke it merged, so `entryProblems` checks each entry against +// its package here, and the script tests run it against the repository as it +// stands (`npm run test:scripts`, part of `validate:guards`). +// +// Like `release-manifest.mjs`, this runs in `detect-packages`, with nothing +// installed and no third-party import, and its result reaches the publish job +// as a job output: the job that holds the OIDC credential takes what to +// register from the released source, not from a file a build job wrote. +// +// Under GitHub Actions it writes one step output, `mcp_registry`: a JSON +// object keyed by the server's directory under `src/`, each value the complete +// `server.json` to publish. It always prints the same JSON to stdout. Any +// problem with any entry fails the run and writes nothing. + +import { appendFileSync, existsSync, readFileSync } from "node:fs"; +import path from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { expectedPackages } from "./release-manifest.mjs"; + +const repoRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", +); + +/** The `server.json` schema the entries are written against. */ +export const SCHEMA_URL = + "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json"; + +/** + * The registry grants a namespace to whoever proves they own it. A workflow in + * this organization proves `io.github.modelcontextprotocol/*` with its OIDC + * token, and no other, so an entry outside it could never be published. + */ +export const NAMESPACE = "io.github.modelcontextprotocol/"; + +const REPOSITORY_URL = "https://github.com/modelcontextprotocol/servers"; + +// The registry's own limits (the schema's `maxLength`s). An over-long +// description is its most common rejection. +const MAX_DESCRIPTION = 100; +const MAX_TITLE = 100; +const NAME_PATTERN = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/; + +/** + * The server name a README claims with an `mcp-name:` marker, as the registry + * reads it: the token after the marker, ended by whitespace, an HTML tag or a + * comment close. + * + * @param {string} readme + * @returns {string | undefined} + */ +export function readmeMarker(readme) { + const match = /mcp-name:[ \t]*([^\s<]+?)(?=\s|<|-->|$)/.exec(readme); + return match?.[1]; +} + +/** + * Pure: what is wrong with one server's committed entry. + * + * @param {object} server + * @param {string} server.dir the server's directory under `src/` + * @param {"npm" | "pypi"} server.registryType + * @param {string} server.packageName the name its manifest publishes under + * @param {string | undefined} server.marker the server name its package claims + * @param {unknown} server.entry the parsed `server.json` + * @returns {string[]} one message per problem; empty when the entry is sound + */ +export function entryProblems({ + dir, + registryType, + packageName, + marker, + entry, +}) { + if (entry === null || typeof entry !== "object" || Array.isArray(entry)) + return ["is not a JSON object"]; + const problems = []; + const { name, title, description, repository, packages } = entry; + + if (entry.$schema !== SCHEMA_URL) + problems.push(`\`$schema\` must be ${SCHEMA_URL}`); + + if (typeof name !== "string" || !NAME_PATTERN.test(name)) + problems.push("`name` must be `/`"); + else if (!name.startsWith(NAMESPACE)) + problems.push( + `\`name\` must start with \`${NAMESPACE}\`, the only namespace this repository's workflows can publish to`, + ); + if (marker === undefined) + problems.push( + registryType === "npm" + ? "its package.json has no `mcpName`, which the registry reads to verify the package" + : "its README has no `mcp-name:` marker, which the registry reads to verify the package", + ); + else if (name !== marker) + problems.push( + `\`name\` is ${JSON.stringify(name)} but the package claims ${JSON.stringify(marker)} (${registryType === "npm" ? "`mcpName` in package.json" : "the `mcp-name:` marker in README.md"}); the registry refuses an entry whose package names another server`, + ); + + if (typeof title !== "string" || title === "" || title.length > MAX_TITLE) + problems.push(`\`title\` must be 1 to ${MAX_TITLE} characters`); + if ( + typeof description !== "string" || + description === "" || + description.length > MAX_DESCRIPTION + ) + problems.push( + `\`description\` must be 1 to ${MAX_DESCRIPTION} characters${typeof description === "string" ? ` (it is ${description.length})` : ""}`, + ); + + if ("version" in entry) + problems.push( + "`version` must not be committed: it is stamped from the package manifest at release time", + ); + + if ( + repository?.url !== REPOSITORY_URL || + repository?.source !== "github" || + repository?.subfolder !== `src/${dir}` + ) + problems.push( + `\`repository\` must be { url: ${REPOSITORY_URL}, source: github, subfolder: src/${dir} }`, + ); + + if ("remotes" in entry) + problems.push( + "`remotes` is not supported: these servers are installed as packages", + ); + + if (!Array.isArray(packages) || packages.length !== 1) { + problems.push("`packages` must hold exactly one package"); + return problems; + } + const [pkg] = packages; + if (pkg === null || typeof pkg !== "object") { + problems.push("`packages[0]` is not an object"); + return problems; + } + if (pkg.registryType !== registryType) + problems.push(`\`packages[0].registryType\` must be \`${registryType}\``); + if (pkg.identifier !== packageName) + problems.push( + `\`packages[0].identifier\` must be the published package, \`${packageName}\``, + ); + if ("version" in pkg) + problems.push( + "`packages[0].version` must not be committed: it is stamped from the package manifest at release time", + ); + if ("registryBaseUrl" in pkg) + problems.push( + "`packages[0].registryBaseUrl` must be left out: the registry accepts only the public npm and PyPI registries, which are the defaults", + ); + if (pkg.transport?.type !== "stdio") + problems.push( + "`packages[0].transport.type` must be `stdio`, the transport every server starts in by default", + ); + return problems; +} + +/** + * Pure: the entry to publish, with the package's version in both places the + * registry reads it. `version` goes after `description`, where the registry's + * own examples put it; nothing else moves. + * + * @param {Record} entry a committed entry `entryProblems` passed + * @param {string} version + * @returns {Record} + */ +export function stampEntry(entry, version) { + const stamped = {}; + for (const [key, value] of Object.entries(entry)) { + if (key === "packages") + stamped.packages = value.map((pkg) => ({ + registryType: pkg.registryType, + identifier: pkg.identifier, + version, + ...pkg, + })); + else stamped[key] = value; + if (key === "description") stamped.version = version; + } + return stamped; +} + +/** + * Every server's entry, stamped, or the problems that stop any from being + * published. + * + * @param {string} [root] the repository root + * @returns {{ entries: Record>, problems: string[] }} + */ +export function registryEntries(root = repoRoot) { + const { npm, pypi } = expectedPackages(root); + const servers = [ + ...Object.entries(npm).map(([dir, pkg]) => ({ + dir, + registryType: "npm", + pkg, + })), + ...Object.entries(pypi).map(([dir, pkg]) => ({ + dir, + registryType: "pypi", + pkg, + })), + ].sort((a, b) => a.dir.localeCompare(b.dir)); + + const entries = {}; + const problems = []; + for (const { dir, registryType, pkg } of servers) { + const serverDir = path.join(root, "src", dir); + const file = path.join(serverDir, "server.json"); + const label = `src/${dir}/server.json`; + if (!existsSync(file)) { + problems.push( + `${label} is missing: every published server has a registry entry`, + ); + continue; + } + let entry; + try { + entry = JSON.parse(readFileSync(file, "utf8")); + } catch (err) { + problems.push(`${label} does not parse: ${err.message}`); + continue; + } + const found = entryProblems({ + dir, + registryType, + packageName: pkg.name, + marker: packageMarker(serverDir, registryType), + entry, + }); + if (found.length > 0) { + for (const problem of found) problems.push(`${label}: ${problem}`); + continue; + } + entries[dir] = stampEntry(entry, pkg.version); + } + return { entries, problems }; +} + +/** The server name a package claims, read the way the registry will read it. */ +function packageMarker(serverDir, registryType) { + if (registryType === "npm") { + const { mcpName } = JSON.parse( + readFileSync(path.join(serverDir, "package.json"), "utf8"), + ); + return typeof mcpName === "string" ? mcpName : undefined; + } + // Every Python server's `pyproject.toml` declares `readme = "README.md"`, + // which is what PyPI serves as the project description. + const readme = path.join(serverDir, "README.md"); + return existsSync(readme) + ? readmeMarker(readFileSync(readme, "utf8")) + : undefined; +} + +/** + * @param {object} [options] + * @param {string} [options.root] + * @param {NodeJS.ProcessEnv} [options.env] + * @returns {number} the exit code + */ +export function main({ root = repoRoot, env = process.env } = {}) { + const { entries, problems } = registryEntries(root); + if (problems.length > 0) { + console.error( + `mcp-registry-entries: ${problems.length} problem(s) with the MCP Registry entries:\n`, + ); + for (const problem of problems) console.error(` ${problem}`); + return 1; + } + console.log(JSON.stringify(entries, null, 2)); + if (env.GITHUB_OUTPUT) + appendFileSync( + env.GITHUB_OUTPUT, + `mcp_registry=${JSON.stringify(entries)}\n`, + ); + return 0; +} + +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) + process.exit(main()); diff --git a/scripts/mcp-registry-entries.test.mjs b/scripts/mcp-registry-entries.test.mjs new file mode 100644 index 0000000000..aaa1b7cce3 --- /dev/null +++ b/scripts/mcp-registry-entries.test.mjs @@ -0,0 +1,469 @@ +// Tests for `mcp-registry-entries.mjs` (#3047): the rule each committed +// `server.json` must meet, the version stamp, the README marker as the +// registry reads it, and the entries of the repository as it stands. The last +// is the guard: an entry that disagrees with its package fails here, in +// `validate:guards`, instead of at release time. Run via +// `npm run test:scripts`. + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { + NAMESPACE, + SCHEMA_URL, + entryProblems, + main, + readmeMarker, + registryEntries, + stampEntry, +} from "./mcp-registry-entries.mjs"; +import { expectedPackages } from "./release-manifest.mjs"; + +const NAME = `${NAMESPACE}server-demo`; + +/** A committed entry that meets every rule, for an npm server in `src/demo`. */ +function soundEntry() { + return { + $schema: SCHEMA_URL, + name: NAME, + title: "Demo", + description: "A demonstration server", + repository: { + url: "https://github.com/modelcontextprotocol/servers", + source: "github", + subfolder: "src/demo", + }, + packages: [ + { + registryType: "npm", + identifier: "@modelcontextprotocol/server-demo", + transport: { type: "stdio" }, + }, + ], + }; +} + +/** The problems with `entry` as the npm server in `src/demo`. */ +function problemsWith(entry, overrides = {}) { + return entryProblems({ + dir: "demo", + registryType: "npm", + packageName: "@modelcontextprotocol/server-demo", + marker: NAME, + entry, + ...overrides, + }); +} + +test("entry: a sound entry has no problems", () => { + assert.deepEqual(problemsWith(soundEntry()), []); +}); + +test("entry: something that is not an object is refused outright", () => { + for (const entry of [null, [], "server", 3]) + assert.deepEqual(problemsWith(entry), ["is not a JSON object"]); +}); + +const defects = [ + { + name: "another schema", + edit: (e) => (e.$schema = "https://example.com/server.schema.json"), + expect: /`\$schema` must be/, + }, + { + name: "a name that is not namespace/server", + edit: (e) => (e.name = "server-demo"), + marker: "server-demo", + expect: /`name` must be `\/`/, + }, + { + name: "a name outside the namespace the workflow can prove", + edit: (e) => (e.name = "io.modelcontextprotocol/demo"), + marker: "io.modelcontextprotocol/demo", + expect: /must start with `io\.github\.modelcontextprotocol\/`/, + }, + { + name: "a name the package does not claim", + edit: (e) => (e.name = `${NAMESPACE}server-other`), + expect: + /the package claims "io\.github\.modelcontextprotocol\/server-demo"/, + }, + { + name: "no title", + edit: (e) => delete e.title, + expect: /`title` must be 1 to 100 characters/, + }, + { + name: "a description over the registry's limit", + edit: (e) => (e.description = "x".repeat(101)), + expect: /`description` must be 1 to 100 characters \(it is 101\)/, + }, + { + name: "an empty description", + edit: (e) => (e.description = ""), + expect: /`description` must be 1 to 100 characters \(it is 0\)/, + }, + { + name: "no description", + edit: (e) => delete e.description, + expect: /`description` must be 1 to 100 characters$/, + }, + { + name: "a committed version", + edit: (e) => (e.version = "1.0.0"), + expect: /`version` must not be committed/, + }, + { + name: "a repository pointing at another folder", + edit: (e) => (e.repository.subfolder = "src/other"), + expect: /`repository` must be .*subfolder: src\/demo/, + }, + { + name: "no repository", + edit: (e) => delete e.repository, + expect: /`repository` must be/, + }, + { + name: "a remote", + edit: (e) => + (e.remotes = [{ type: "streamable-http", url: "https://example.com" }]), + expect: /`remotes` is not supported/, + }, + { + name: "no packages", + edit: (e) => delete e.packages, + expect: /`packages` must hold exactly one package/, + }, + { + name: "two packages", + edit: (e) => e.packages.push({ ...e.packages[0] }), + expect: /`packages` must hold exactly one package/, + }, + { + name: "a package that is not an object", + edit: (e) => (e.packages = [null]), + expect: /`packages\[0\]` is not an object/, + }, + { + name: "the wrong package registry", + edit: (e) => (e.packages[0].registryType = "pypi"), + expect: /`packages\[0\]\.registryType` must be `npm`/, + }, + { + name: "another package's identifier", + edit: (e) => (e.packages[0].identifier = "left-pad"), + expect: + /must be the published package, `@modelcontextprotocol\/server-demo`/, + }, + { + name: "a committed package version", + edit: (e) => (e.packages[0].version = "1.0.0"), + expect: /`packages\[0\]\.version` must not be committed/, + }, + { + name: "a registry base URL", + edit: (e) => (e.packages[0].registryBaseUrl = "https://npm.example.com"), + expect: /`packages\[0\]\.registryBaseUrl` must be left out/, + }, + { + name: "a transport other than stdio", + edit: (e) => (e.packages[0].transport = { type: "sse" }), + expect: /`packages\[0\]\.transport\.type` must be `stdio`/, + }, + { + name: "no transport", + edit: (e) => delete e.packages[0].transport, + expect: /`packages\[0\]\.transport\.type` must be `stdio`/, + }, +]; + +// `marker` is what the package claims: by default the sound name, so a case +// that edits the name says what the package claims alongside it. +for (const { name, edit, expect, marker = NAME } of defects) + test(`entry: ${name} is a problem`, () => { + const entry = soundEntry(); + edit(entry); + const problems = problemsWith(entry, { marker }); + assert.equal(problems.length, 1, problems.join("\n")); + assert.match(problems[0], expect); + }); + +test("entry: a package with no marker is a problem, named per registry", () => { + assert.match( + problemsWith(soundEntry(), { marker: undefined })[0], + /its package\.json has no `mcpName`/, + ); + const entry = soundEntry(); + entry.packages[0].registryType = "pypi"; + assert.match( + problemsWith(entry, { registryType: "pypi", marker: undefined })[0], + /its README has no `mcp-name:` marker/, + ); +}); + +test("entry: a PyPI mismatch names the README marker", () => { + const entry = soundEntry(); + entry.packages[0].registryType = "pypi"; + assert.match( + problemsWith(entry, { + registryType: "pypi", + marker: `${NAMESPACE}server-other`, + })[0], + /the `mcp-name:` marker in README\.md/, + ); +}); + +test("entry: every problem is reported, not only the first", () => { + const entry = soundEntry(); + entry.version = "1.0.0"; + entry.description = ""; + entry.packages[0].identifier = "left-pad"; + assert.equal(problemsWith(entry).length, 3); +}); + +test("marker: read from a comment, plain text, or ahead of a tag", () => { + assert.equal(readmeMarker(`# T\n\n\n`), NAME); + assert.equal(readmeMarker(``), NAME); + assert.equal(readmeMarker(`mcp-name: ${NAME}\n`), NAME); + assert.equal(readmeMarker(`mcp-name: ${NAME}`), NAME); + assert.equal(readmeMarker(`

mcp-name: ${NAME}

`), NAME); +}); + +test("marker: a README without one has none", () => { + assert.equal(readmeMarker("# A server\n\nNo marker here.\n"), undefined); +}); + +test("stamp: the version lands after the description and in the package", () => { + const stamped = stampEntry(soundEntry(), "1.2.3"); + assert.deepEqual(Object.keys(stamped), [ + "$schema", + "name", + "title", + "description", + "version", + "repository", + "packages", + ]); + assert.equal(stamped.version, "1.2.3"); + assert.deepEqual(stamped.packages, [ + { + registryType: "npm", + identifier: "@modelcontextprotocol/server-demo", + version: "1.2.3", + transport: { type: "stdio" }, + }, + ]); +}); + +test("stamp: the committed entry is left as it was", () => { + const entry = soundEntry(); + stampEntry(entry, "1.2.3"); + assert.deepEqual(entry, soundEntry()); +}); + +test("repository: every published server has a sound entry at its manifest's version", () => { + const { entries, problems } = registryEntries(); + assert.deepEqual(problems, []); + const { npm, pypi } = expectedPackages(); + const packages = { ...npm, ...pypi }; + assert.deepEqual(Object.keys(entries).sort(), Object.keys(packages).sort()); + for (const [dir, entry] of Object.entries(entries)) { + assert.equal(entry.version, packages[dir].version, dir); + assert.equal(entry.packages[0].version, packages[dir].version, dir); + assert.equal(entry.packages[0].identifier, packages[dir].name, dir); + } +}); + +test("repository: no two servers share a registry name", () => { + const names = Object.values(registryEntries().entries).map((e) => e.name); + assert.equal(new Set(names).size, names.length); +}); + +/** + * A repository root holding one npm server and one PyPI server, each with a + * sound entry, for the tests to break. + * + * @returns {string} the root; the caller removes it + */ +function fixture() { + const root = mkdtempSync(path.join(tmpdir(), "mcp-registry-")); + const npmDir = path.join(root, "src", "demo"); + mkdirSync(npmDir, { recursive: true }); + writeFileSync( + path.join(npmDir, "package.json"), + JSON.stringify({ + name: "@modelcontextprotocol/server-demo", + version: "1.2.3", + mcpName: NAME, + }), + ); + writeFileSync(path.join(npmDir, "server.json"), JSON.stringify(soundEntry())); + const pyDir = path.join(root, "src", "pydemo"); + mkdirSync(pyDir, { recursive: true }); + writeFileSync( + path.join(pyDir, "pyproject.toml"), + '[project]\nname = "mcp-server-pydemo"\nversion = "2026.1.2"\n', + ); + writeFileSync( + path.join(pyDir, "README.md"), + `# Demo\n\n\n`, + ); + const pyEntry = soundEntry(); + pyEntry.name = `${NAMESPACE}server-pydemo`; + pyEntry.repository.subfolder = "src/pydemo"; + pyEntry.packages[0] = { + registryType: "pypi", + identifier: "mcp-server-pydemo", + transport: { type: "stdio" }, + }; + writeFileSync(path.join(pyDir, "server.json"), JSON.stringify(pyEntry)); + return root; +} + +/** Run `main` with the console captured, so expected errors stay off it. */ +function runMain(options) { + const lines = { out: [], err: [] }; + const { log, error } = console; + console.log = (line) => lines.out.push(line); + console.error = (line) => lines.err.push(line); + try { + return { code: main(options), ...lines }; + } finally { + console.log = log; + console.error = error; + } +} + +test("fixture: both registries' entries are stamped from their manifests", () => { + const root = fixture(); + try { + const { entries, problems } = registryEntries(root); + assert.deepEqual(problems, []); + assert.equal(entries.demo.version, "1.2.3"); + assert.equal(entries.pydemo.version, "2026.1.2"); + assert.equal(entries.pydemo.packages[0].version, "2026.1.2"); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("fixture: a server with no entry is a problem", () => { + const root = fixture(); + try { + rmSync(path.join(root, "src", "demo", "server.json")); + const { entries, problems } = registryEntries(root); + assert.deepEqual(Object.keys(entries), ["pydemo"]); + assert.match(problems[0], /^src\/demo\/server\.json is missing/); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("fixture: an entry that is not JSON is a problem", () => { + const root = fixture(); + try { + writeFileSync(path.join(root, "src", "demo", "server.json"), "{ nope"); + const { problems } = registryEntries(root); + assert.match(problems[0], /^src\/demo\/server\.json does not parse/); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("fixture: a package.json whose mcpName is gone is a problem", () => { + const root = fixture(); + try { + writeFileSync( + path.join(root, "src", "demo", "package.json"), + JSON.stringify({ + name: "@modelcontextprotocol/server-demo", + version: "1.2.3", + mcpName: 7, + }), + ); + const { problems } = registryEntries(root); + assert.match(problems[0], /package\.json has no `mcpName`/); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("fixture: a Python server whose README is gone, or lost its marker, is a problem", () => { + const root = fixture(); + try { + const readme = path.join(root, "src", "pydemo", "README.md"); + writeFileSync(readme, "# Demo\n"); + assert.match( + registryEntries(root).problems[0], + /README has no `mcp-name:` marker/, + ); + rmSync(readme); + assert.match( + registryEntries(root).problems[0], + /README has no `mcp-name:` marker/, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("main: prints the entries and writes the step output", () => { + const root = fixture(); + try { + const output = path.join(root, "github-output"); + writeFileSync(output, ""); + const { code, out } = runMain({ root, env: { GITHUB_OUTPUT: output } }); + assert.equal(code, 0); + const printed = JSON.parse(out.join("\n")); + assert.deepEqual(Object.keys(printed), ["demo", "pydemo"]); + const written = readFileSync(output, "utf8"); + assert.match(written, /^mcp_registry=\{.*\}\n$/); + assert.deepEqual( + JSON.parse(written.slice("mcp_registry=".length)), + printed, + ); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("main: outside GitHub Actions it only prints", () => { + const root = fixture(); + try { + const { code, out } = runMain({ root, env: {} }); + assert.equal(code, 0); + assert.equal(out.length, 1); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + +test("main: a problem fails the run and writes no output", () => { + const root = fixture(); + try { + const output = path.join(root, "github-output"); + writeFileSync(output, ""); + const file = path.join(root, "src", "demo", "server.json"); + const entry = soundEntry(); + entry.version = "9.9.9"; + writeFileSync(file, JSON.stringify(entry)); + const { code, out, err } = runMain({ + root, + env: { GITHUB_OUTPUT: output }, + }); + assert.equal(code, 1); + assert.deepEqual(out, []); + assert.match(err.join("\n"), /src\/demo\/server\.json: `version` must not/); + assert.equal(readFileSync(output, "utf8"), ""); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); diff --git a/scripts/release-mcp-registry.test.mjs b/scripts/release-mcp-registry.test.mjs new file mode 100644 index 0000000000..637dabe43d --- /dev/null +++ b/scripts/release-mcp-registry.test.mjs @@ -0,0 +1,385 @@ +// Regression tests for `release.yml`'s `publish-mcp-registry` job (#3047). +// +// The job lists each server in the official MCP Registry after its package is +// published. It holds an OIDC credential and has no checkout, so, as with the +// dist-tag choice (release-dist-tag.test.mjs), what decides which entries are +// published is shell inside the workflow file, and it runs only when a Release +// is published. These tests read the steps out of the workflow and run THAT +// text, with `curl` and `mcp-publisher` replaced by stubs: nothing here +// reaches the registry or authenticates to it. +// +// They pin what must not regress silently: +// - an entry the registry already lists is skipped, and no token is asked +// for when nothing is missing; +// - an answer that is neither 200 nor 404 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 or malformed job output registers nothing; +// - the job's shape: the credential, the environment, its place after the +// package publish legs, no action and no checkout, and a publisher binary +// pinned by version and checksum, verified before it is unpacked. +// +// The steps' shell is bash, so those tests are skipped where there is none. +// Run via `npm run test:scripts`. + +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; +import { + chmodSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { parse } from "yaml"; +import { registryEntries } from "./mcp-registry-entries.mjs"; + +const repoRoot = path.resolve( + path.dirname(fileURLToPath(import.meta.url)), + "..", +); + +const WRITE_STEP = "Write the entries the released commit declares"; +const PUBLISH_STEP = "Publish each entry the registry does not have"; +const DOWNLOAD_STEP = "Download the pinned mcp-publisher"; + +function workflow() { + return parse( + readFileSync( + path.join(repoRoot, ".github", "workflows", "release.yml"), + "utf8", + ), + ); +} + +/** The `publish-mcp-registry` job, as the workflow file declares it. */ +function registryJob() { + const job = workflow().jobs["publish-mcp-registry"]; + assert.ok(job, "release.yml has no publish-mcp-registry job"); + return job; +} + +function step(name) { + const found = registryJob().steps.find((s) => s.name === name); + assert.ok(found, `publish-mcp-registry has no \`${name}\` step`); + return found; +} + +const hasBash = + process.platform !== "win32" && + spawnSync("bash", ["-c", "exit 0"]).status === 0; + +const A = "io.github.modelcontextprotocol/server-a"; +const B = "io.github.modelcontextprotocol/server-b"; +const C = "io.github.modelcontextprotocol/server-c"; + +/** Three entries, in the shape `detect-packages` hands over. */ +function threeEntries() { + return { + a: { name: A, version: "1.0.0", packages: [] }, + b: { name: B, version: "2026.1.2", packages: [] }, + c: { name: C, version: "3.0.0", packages: [] }, + }; +} + +/** + * Run the write step and then the publish step in a scratch directory. + * + * `curl` is a stub that answers each registry lookup from `answers`, keyed by + * the server's name: an HTTP status to print, or `"fail"` to exit non-zero the + * way curl does when it cannot connect. `mcp-publisher` is a stub that logs + * each call and fails a `publish` of any directory in `refuse`. + * + * @param {object} options + * @param {string} [options.entries] the `mcp_registry` output, as text + * @param {Record} [options.answers] + * @param {string[]} [options.refuse] + * @returns {{ write: number | null, publish: number | null, calls: string[], lookups: string[], stdout: string, stderr: string, dir: (file: string) => string | undefined }} + */ +function run({ + entries = JSON.stringify(threeEntries()), + answers = {}, + refuse = [], +} = {}) { + const dir = mkdtempSync(path.join(tmpdir(), "mcp-registry-job-")); + try { + const bin = path.join(dir, "bin"); + mkdirSync(bin); + const lookups = path.join(dir, "lookups.log"); + const calls = path.join(dir, "calls.log"); + // The URL is curl's last argument. The name in it is `%2F`-encoded. + const cases = Object.entries(answers) + .map(([name, answer]) => { + const pattern = `*/v0/servers/${name.replace("/", "%2F")}/versions/*`; + return answer === "fail" + ? ` ${pattern}) printf '000'; exit 7 ;;` + : ` ${pattern}) printf '${answer}' ;;`; + }) + .join("\n"); + writeFileSync( + path.join(bin, "curl"), + `#!/bin/sh\nfor url; do :; done\necho "$url" >> "${lookups}"\ncase "$url" in\n${cases}\n *) printf '404' ;;\nesac\n`, + ); + chmodSync(path.join(bin, "curl"), 0o755); + const refused = refuse + .map((d) => ` "publish entries/${d}/server.json") exit 1 ;;`) + .join("\n"); + writeFileSync( + path.join(dir, "mcp-publisher"), + `#!/bin/sh\necho "$*" >> "${calls}"\ncase "$*" in\n${refused}\n *) exit 0 ;;\nesac\n`, + ); + chmodSync(path.join(dir, "mcp-publisher"), 0o755); + + const env = { + ...process.env, + PATH: `${bin}${path.delimiter}${process.env.PATH}`, + ENTRIES: entries, + }; + const options = { cwd: dir, encoding: "utf8", env }; + const write = spawnSync( + "bash", + ["-e", "-c", step(WRITE_STEP).run], + options, + ); + const publish = + write.status === 0 + ? spawnSync("bash", ["-e", "-c", step(PUBLISH_STEP).run], options) + : { status: null, stdout: "", stderr: "" }; + const lines = (file) => + existsSync(file) + ? readFileSync(file, "utf8").split("\n").filter(Boolean) + : []; + const files = new Map( + ["plan.tsv", "entries/a/server.json"].map((f) => [ + f, + existsSync(path.join(dir, f)) + ? readFileSync(path.join(dir, f), "utf8") + : undefined, + ]), + ); + return { + write: write.status, + publish: publish.status, + calls: lines(calls), + lookups: lines(lookups), + stdout: write.stdout + publish.stdout, + stderr: write.stderr + publish.stderr, + dir: (file) => files.get(file), + }; + } finally { + rmSync(dir, { recursive: true, force: true }); + } +} + +const bashTest = (name, fn) => test(name, { skip: !hasBash }, fn); + +bashTest("write: one server.json per entry, and a plan naming each", () => { + const result = run(); + assert.equal(result.write, 0, result.stderr); + assert.equal( + result.dir("plan.tsv"), + `a\t${A}\t1.0.0\nb\t${B}\t2026.1.2\nc\t${C}\t3.0.0\n`, + ); + assert.deepEqual( + JSON.parse(result.dir("entries/a/server.json")), + threeEntries().a, + ); +}); + +bashTest("write: the entries the repository records pass its checks", () => { + const { entries, problems } = registryEntries(); + assert.deepEqual(problems, []); + const result = run({ entries: JSON.stringify(entries) }); + assert.equal(result.write, 0, result.stderr); + assert.equal( + result.dir("plan.tsv").trim().split("\n").length, + Object.keys(entries).length, + ); +}); + +for (const [name, entries] of [ + ["an empty output", ""], + ["an output with no entries", "{}"], + ["an output that is not JSON", "{ nope"], + [ + "a directory that would leave entries/", + JSON.stringify({ "../x": { name: A, version: "1.0.0" } }), + ], + [ + "a name outside this organization's namespace", + JSON.stringify({ a: { name: "io.github.someone/else", version: "1.0.0" } }), + ], + ["an entry with no name", JSON.stringify({ a: { version: "1.0.0" } })], + ["an entry with no version", JSON.stringify({ a: { name: A } })], + [ + "a version that would change the lookup URL", + JSON.stringify({ a: { name: A, version: "1.0.0/../../x" } }), + ], +]) + bashTest(`write: ${name} registers nothing`, () => { + const result = run({ entries }); + assert.notEqual(result.write, 0); + assert.equal(result.publish, null); + assert.deepEqual(result.calls, []); + assert.deepEqual(result.lookups, []); + }); + +bashTest("publish: every missing entry is published, after one login", () => { + const result = run(); + assert.equal(result.publish, 0, result.stderr); + assert.deepEqual(result.calls, [ + "login github-oidc", + "publish entries/a/server.json", + "publish entries/b/server.json", + "publish entries/c/server.json", + ]); + assert.deepEqual(result.lookups, [ + "https://registry.modelcontextprotocol.io/v0/servers/io.github.modelcontextprotocol%2Fserver-a/versions/1.0.0", + "https://registry.modelcontextprotocol.io/v0/servers/io.github.modelcontextprotocol%2Fserver-b/versions/2026.1.2", + "https://registry.modelcontextprotocol.io/v0/servers/io.github.modelcontextprotocol%2Fserver-c/versions/3.0.0", + ]); +}); + +bashTest("publish: an entry the registry already lists is skipped", () => { + const result = run({ answers: { [B]: "200" } }); + assert.equal(result.publish, 0, result.stderr); + assert.deepEqual(result.calls, [ + "login github-oidc", + "publish entries/a/server.json", + "publish entries/c/server.json", + ]); + assert.match( + result.stdout, + /server-b@2026\.1\.2 is already in the MCP Registry/, + ); +}); + +bashTest("publish: with nothing missing, no token is asked for", () => { + const result = run({ answers: { [A]: "200", [B]: "200", [C]: "200" } }); + assert.equal(result.publish, 0, result.stderr); + assert.deepEqual(result.calls, []); +}); + +for (const [name, answer] of [ + ["a server error", "500"], + ["a rate limit", "429"], + ["a redirect", "302"], + ["no answer at all", "fail"], +]) + bashTest(`publish: ${name} fails that entry without publishing it`, () => { + const result = run({ answers: { [B]: answer } }); + assert.equal(result.publish, 1); + assert.deepEqual(result.calls, [ + "login github-oidc", + "publish entries/a/server.json", + "publish entries/c/server.json", + ]); + assert.match( + result.stdout, + /::error::Could not tell whether .*server-b@2026\.1\.2 is in the MCP Registry/, + ); + }); + +bashTest( + "publish: unreadable answers and nothing missing still fail, with no login", + () => { + const result = run({ answers: { [A]: "200", [B]: "503", [C]: "200" } }); + assert.equal(result.publish, 1); + assert.deepEqual(result.calls, []); + }, +); + +bashTest( + "publish: one refused entry does not stop the rest, and fails the job", + () => { + const result = run({ refuse: ["a"] }); + assert.equal(result.publish, 1); + assert.deepEqual(result.calls, [ + "login github-oidc", + "publish entries/a/server.json", + "publish entries/b/server.json", + "publish entries/c/server.json", + ]); + assert.match( + result.stdout, + /::error::The MCP Registry refused the entry for src\/a/, + ); + assert.match(result.stdout, /Registered src\/b\./); + }, +); + +test("shape: the job holds the credential and waits for the release environment", () => { + const job = registryJob(); + assert.deepEqual(job.permissions, { "id-token": "write" }); + assert.equal(job.environment, "release"); + assert.equal(typeof job["timeout-minutes"], "number"); +}); + +test("shape: it runs after both sets of package publish legs, whatever their result", () => { + const job = registryJob(); + assert.deepEqual([...job.needs].sort(), [ + "detect-packages", + "publish-npm", + "publish-pypi", + ]); + assert.match(job.if, /!cancelled\(\)/); + assert.match(job.if, /needs\.detect-packages\.result == 'success'/); +}); + +test("shape: it runs no action, so no checkout and no dependency install", () => { + for (const s of registryJob().steps) { + assert.equal(s.uses, undefined, `step \`${s.name}\` uses an action`); + assert.doesNotMatch(s.run, /\bnpm (ci|install|i)\b|\bnpx\b|\bpip\b|\buv\b/); + } +}); + +test("shape: the entries come from detect-packages, as a job output", () => { + const detect = workflow().jobs["detect-packages"]; + assert.equal( + detect.outputs.mcp_registry, + "${{ steps.registry.outputs.mcp_registry }}", + ); + const record = detect.steps.find((s) => s.id === "registry"); + assert.ok(record, "detect-packages has no step with id `registry`"); + assert.equal(record.run, "node scripts/mcp-registry-entries.mjs"); + assert.equal( + step(WRITE_STEP).env.ENTRIES, + "${{ needs.detect-packages.outputs.mcp_registry }}", + ); +}); + +test("shape: the publisher is pinned by release and checksum, verified before it is unpacked", () => { + const job = registryJob(); + assert.match(job.env.MCP_PUBLISHER_VERSION, /^v\d+\.\d+\.\d+$/); + assert.match(job.env.MCP_PUBLISHER_SHA256, /^[a-f0-9]{64}$/); + const { run: script } = step(DOWNLOAD_STEP); + assert.match( + script, + /github\.com\/modelcontextprotocol\/registry\/releases\/download\/\$MCP_PUBLISHER_VERSION\//, + ); + assert.doesNotMatch(script, /releases\/latest/); + const check = script.indexOf("sha256sum --check --strict"); + const unpack = script.indexOf("tar -xzf"); + assert.ok(check !== -1, "the download step no longer checks the archive"); + assert.ok( + check < unpack, + "the archive must be checked before it is unpacked", + ); + assert.match(script, /\$MCP_PUBLISHER_SHA256 {2}\$ARCHIVE/); +}); + +test("shape: the download comes first, and the only login is github-oidc", () => { + const steps = registryJob().steps; + assert.equal(steps[0].name, DOWNLOAD_STEP); + const logins = steps.flatMap( + (s) => s.run.match(/mcp-publisher login \S+/g) ?? [], + ); + assert.deepEqual(logins, ["mcp-publisher login github-oidc"]); + for (const s of steps) assert.doesNotMatch(s.run, /secrets\./); +}); diff --git a/src/everything/server.json b/src/everything/server.json new file mode 100644 index 0000000000..fb4fc8e123 --- /dev/null +++ b/src/everything/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-everything", + "title": "Everything", + "description": "Reference server that exercises every MCP feature: tools, resources, prompts, sampling and more", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/everything" + }, + "packages": [ + { + "registryType": "npm", + "identifier": "@modelcontextprotocol/server-everything", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/fetch/server.json b/src/fetch/server.json new file mode 100644 index 0000000000..931d14a9d2 --- /dev/null +++ b/src/fetch/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-fetch", + "title": "Fetch", + "description": "Fetches web content and converts it to Markdown for an LLM to read", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/fetch" + }, + "packages": [ + { + "registryType": "pypi", + "identifier": "mcp-server-fetch", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/filesystem/server.json b/src/filesystem/server.json new file mode 100644 index 0000000000..0768a84f90 --- /dev/null +++ b/src/filesystem/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-filesystem", + "title": "Filesystem", + "description": "Read, write, search and edit files, with access limited to allowed directories or client Roots", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/filesystem" + }, + "packages": [ + { + "registryType": "npm", + "identifier": "@modelcontextprotocol/server-filesystem", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/git/server.json b/src/git/server.json new file mode 100644 index 0000000000..8056b60a39 --- /dev/null +++ b/src/git/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-git", + "title": "Git", + "description": "Read, search and manipulate Git repositories: status, diff, log, commit, branch and more", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/git" + }, + "packages": [ + { + "registryType": "pypi", + "identifier": "mcp-server-git", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/memory/server.json b/src/memory/server.json new file mode 100644 index 0000000000..400b34e3fa --- /dev/null +++ b/src/memory/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-memory", + "title": "Memory", + "description": "Persistent memory for an assistant, stored as a knowledge graph of entities and relations", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/memory" + }, + "packages": [ + { + "registryType": "npm", + "identifier": "@modelcontextprotocol/server-memory", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/sequentialthinking/server.json b/src/sequentialthinking/server.json new file mode 100644 index 0000000000..961f0f9676 --- /dev/null +++ b/src/sequentialthinking/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-sequential-thinking", + "title": "Sequential Thinking", + "description": "Step-by-step problem solving through a sequence of thoughts that can be revised and branched", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/sequentialthinking" + }, + "packages": [ + { + "registryType": "npm", + "identifier": "@modelcontextprotocol/server-sequential-thinking", + "transport": { + "type": "stdio" + } + } + ] +} diff --git a/src/time/server.json b/src/time/server.json new file mode 100644 index 0000000000..878d020b36 --- /dev/null +++ b/src/time/server.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.modelcontextprotocol/server-time", + "title": "Time", + "description": "Current time lookup and conversion between IANA timezones", + "repository": { + "url": "https://github.com/modelcontextprotocol/servers", + "source": "github", + "subfolder": "src/time" + }, + "packages": [ + { + "registryType": "pypi", + "identifier": "mcp-server-time", + "transport": { + "type": "stdio" + } + } + ] +} From 3c42f9fe3b146fe2fd8879bae203176ff18d9866 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Wed, 18 Nov 2026 14:34:37 -0500 Subject: [PATCH 2/2] chore(release): declare filesystem's allowed directories in its registry 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 Signed-off-by: cliffhall --- scripts/mcp-registry-entries.test.mjs | 14 ++++++++++++++ src/filesystem/server.json | 12 +++++++++++- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/scripts/mcp-registry-entries.test.mjs b/scripts/mcp-registry-entries.test.mjs index aaa1b7cce3..66f2a3e657 100644 --- a/scripts/mcp-registry-entries.test.mjs +++ b/scripts/mcp-registry-entries.test.mjs @@ -282,6 +282,20 @@ test("repository: every published server has a sound entry at its manifest's ver } }); +test("repository: filesystem's entry asks for its allowed directories", () => { + // Without them a 2026-07-28 client starts the server with an empty + // allow-list, so an entry a client builds its launch command from must say + // they are needed, and that there can be several. + const [pkg] = registryEntries().entries.filesystem.packages; + assert.equal(pkg.version, expectedPackages().npm.filesystem.version); + assert.equal(pkg.packageArguments.length, 1); + const [argument] = pkg.packageArguments; + assert.equal(argument.type, "positional"); + assert.equal(argument.format, "filepath"); + assert.equal(argument.isRequired, true); + assert.equal(argument.isRepeated, true); +}); + test("repository: no two servers share a registry name", () => { const names = Object.values(registryEntries().entries).map((e) => e.name); assert.equal(new Set(names).size, names.length); diff --git a/src/filesystem/server.json b/src/filesystem/server.json index 0768a84f90..32574b8908 100644 --- a/src/filesystem/server.json +++ b/src/filesystem/server.json @@ -14,7 +14,17 @@ "identifier": "@modelcontextprotocol/server-filesystem", "transport": { "type": "stdio" - } + }, + "packageArguments": [ + { + "type": "positional", + "valueHint": "allowed_directory", + "description": "A directory the server may read and write. Repeat for each directory to allow.", + "format": "filepath", + "isRequired": true, + "isRepeated": true + } + ] } ] }