Skip to content

Commit 0659ed7

Browse files
committed
ci: list releases in the MCP registry from a workflow, by OIDC
`mcp-publisher login github` cannot publish under an organisation namespace today: the registry's GitHub App is not installed on the org, so only io.github.<user>/* is granted and io.github.creatoan/* answers 403 whatever the role or membership visibility. Open upstream as modelcontextprotocol/registry#1468, #1537 and #1649. The registry also supports logging in with a workflow's OIDC token, which proves the namespace through the repository. This adds .github/workflows/registry.yml, runnable by hand for an existing tag and callable from release.yml behind the opt-in variable MCP_REGISTRY_PUBLISH. - the credential is minted by one job only; mcp-publisher is pinned to a version and a SHA-256; server.json and PyPI are checked first - uses `validate`, not a dry run: `publish` has no such flag, so one is ignored and the publish happens - tests/test_workflows.py holds these properties, and that every action is pinned to a commit Corrects the release guide, which advised `publish --dry-run`. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_013cXTLmKd7xHDn7su4zav3Y
1 parent 0402bb3 commit 0659ed7

5 files changed

Lines changed: 297 additions & 8 deletions

File tree

‎.github/workflows/registry.yml‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
name: MCP Registry
2+
3+
# Lists a release in the official MCP registry (https://registry.modelcontextprotocol.io),
4+
# which holds metadata only: server.json, pointing at the package on PyPI.
5+
#
6+
# Why this is a workflow and not `mcp-publisher login github` on somebody's machine: the
7+
# interactive login asks a GitHub App for the user's organisations, and for an
8+
# organisation namespace that comes back without them -- the registry then offers only
9+
# `io.github.<user>/*` and answers 403 for `io.github.creatoan/*`, whatever the role or
10+
# the membership visibility. Open upstream, reported by several people with the same
11+
# symptoms: modelcontextprotocol/registry#1468, #1537, #1649. The registry supports a
12+
# second route made for exactly this -- the workflow proves the namespace through the
13+
# repository it runs in, with GitHub's OIDC token, and no organisation lookup is involved.
14+
# That is the route used here.
15+
#
16+
# Two ways in:
17+
#
18+
# - by hand, for a release that already exists (Actions -> MCP Registry -> Run
19+
# workflow, giving the tag). The first listing, and any retry, goes this way.
20+
# - from release.yml, after the release is out, once the repository variable
21+
# MCP_REGISTRY_PUBLISH is "true". Opt-in, like PYPI_TRUSTED_PUBLISHER, because the
22+
# login route is unproven for this namespace until it has worked once.
23+
on:
24+
workflow_dispatch:
25+
inputs:
26+
tag:
27+
description: "Release tag to list, such as v0.8.0"
28+
required: true
29+
type: string
30+
workflow_call:
31+
inputs:
32+
tag:
33+
description: "Release tag to list, such as v0.8.0"
34+
required: true
35+
type: string
36+
37+
permissions:
38+
contents: read
39+
40+
jobs:
41+
publish:
42+
name: List ${{ inputs.tag }} in the registry
43+
runs-on: ubuntu-latest
44+
permissions:
45+
contents: read
46+
# The credential. Set on this job only: every other job in this repository would
47+
# otherwise be able to mint a token that speaks for the namespace, and the registry
48+
# lets a token for an organisation namespace publish -- and overwrite -- anything
49+
# under it.
50+
id-token: write
51+
env:
52+
TAG: ${{ inputs.tag }}
53+
steps:
54+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
55+
with:
56+
ref: refs/tags/${{ inputs.tag }}
57+
persist-credentials: false
58+
59+
# server.json names a version, and the registry verifies the package at that
60+
# version. Catching a mismatch here gives a message about this repository rather
61+
# than a registry error about a package.
62+
- name: server.json must describe this tag
63+
run: |
64+
VERSION="${TAG#v}"
65+
python3 - "$VERSION" <<'PY'
66+
import json, sys
67+
version = sys.argv[1]
68+
manifest = json.load(open("server.json", encoding="utf-8"))
69+
found = {manifest["version"], *(p["version"] for p in manifest["packages"])}
70+
assert found == {version}, f"server.json says {sorted(found)}, the tag is {version}"
71+
print(f"server.json: {manifest['name']} {version}")
72+
PY
73+
74+
# The registry reads the PyPI description for the `mcp-name` marker, so the release
75+
# has to be there. A tag push uploads to PyPI first, but the index can lag behind
76+
# the upload by a little; this waits rather than failing a run that would pass a
77+
# minute later.
78+
- name: The version must be on PyPI
79+
run: |
80+
VERSION="${TAG#v}"
81+
for attempt in 1 2 3 4 5 6 7 8 9 10; do
82+
if curl -fsS "https://pypi.org/pypi/scenet/${VERSION}/json" >/dev/null; then
83+
echo "scenet ${VERSION} is on PyPI"
84+
exit 0
85+
fi
86+
echo "attempt ${attempt}: not on PyPI yet"
87+
sleep 30
88+
done
89+
echo "::error::scenet ${VERSION} is not on PyPI, so the registry cannot verify it"
90+
exit 1
91+
92+
# Pinned and checksummed. This binary runs with the OIDC credential in reach, so it
93+
# is not `latest`, and not whatever a mutable URL serves on the day. To move to a
94+
# newer release: download its linux_amd64 tarball, check it, and replace both lines.
95+
- name: Install mcp-publisher
96+
env:
97+
VERSION: v1.8.1
98+
SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
99+
run: |
100+
curl -fsSL -o mcp-publisher.tar.gz \
101+
"https://github.com/modelcontextprotocol/registry/releases/download/${VERSION}/mcp-publisher_linux_amd64.tar.gz"
102+
echo "${SHA256} mcp-publisher.tar.gz" | sha256sum --check
103+
tar xzf mcp-publisher.tar.gz mcp-publisher
104+
./mcp-publisher --version
105+
106+
# `validate` and not a dry run: publish has no such flag, so a flag that looks like
107+
# one would simply publish.
108+
- name: Validate server.json
109+
run: ./mcp-publisher validate
110+
111+
- name: Authenticate with the repository's identity
112+
run: ./mcp-publisher login github-oidc
113+
114+
- name: Publish
115+
run: ./mcp-publisher publish

‎.github/workflows/release.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -243,3 +243,23 @@ jobs:
243243
else
244244
gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file release-notes.md dist/*
245245
fi
246+
247+
# Last, and nothing waits on it: a listing that fails leaves a complete release behind,
248+
# and can be re-run from the Actions tab (MCP Registry -> Run workflow) without touching
249+
# the tag. Skipped until the repository variable MCP_REGISTRY_PUBLISH is "true"; see
250+
# registry.yml for why this is a workflow identity and not a person's login.
251+
#
252+
# gh variable set MCP_REGISTRY_PUBLISH --body true
253+
registry:
254+
name: List in the MCP registry
255+
needs: [publish, github-release]
256+
if: >-
257+
vars.MCP_REGISTRY_PUBLISH == 'true'
258+
&& needs.publish.result == 'success'
259+
&& needs.github-release.result == 'success'
260+
permissions:
261+
contents: read
262+
id-token: write # the OIDC credential, for this job only
263+
uses: ./.github/workflows/registry.yml
264+
with:
265+
tag: ${{ github.ref_name }}

‎docs/maintainer/releasing.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -102,21 +102,49 @@ It is a real trade. Releases stop being synchronous, which matters when the pers
102102
tagged is not around to approve; and the gate protects against a mistake that cannot be
103103
undone. Decide once, deliberately, rather than discovering it mid-release.
104104

105-
## Publishing to the MCP registry
105+
## Listing in the MCP registry
106106

107107
Optional, and after PyPI has the release. The
108108
[official MCP registry](https://github.com/modelcontextprotocol/registry) stores metadata only:
109109
`server.json` describes how to launch `scenet mcp` from the PyPI package, and the registry checks
110110
that the package's description — the README — carries the `mcp-name` marker for the
111-
`io.github.creatoan/scenet` namespace. Ownership of that namespace is proved by signing in as the
112-
GitHub organisation that owns the repository:
111+
`io.github.creatoan/scenet` namespace.
112+
113+
**This is done by a workflow, not from a laptop.** `mcp-publisher login github` — the interactive
114+
login — fails for an organisation namespace: the registry's GitHub App is not installed on the
115+
organisation, so the registry sees only `io.github.<your-user>/*` and answers 403 for
116+
`io.github.creatoan/*`, whatever the role and whatever the membership visibility. That is an open
117+
upstream bug reported by several people
118+
([#1468](https://github.com/modelcontextprotocol/registry/issues/1468),
119+
[#1537](https://github.com/modelcontextprotocol/registry/issues/1537),
120+
[#1649](https://github.com/modelcontextprotocol/registry/issues/1649)). The workflow,
121+
`.github/workflows/registry.yml`, logs in the other way the registry supports — GitHub's OIDC token,
122+
which proves the namespace through the repository it runs in — and needs no secret.
123+
124+
To list a release that already exists, once: **Actions → MCP Registry → Run workflow**, giving the
125+
tag (`v0.8.0`). To list every future release automatically, set the opt-in variable, which makes
126+
`release.yml` call the same workflow after the release is out:
113127

114128
```bash
115-
mcp-publisher login github
116-
mcp-publisher publish --dry-run # validate first
117-
mcp-publisher publish
129+
gh variable set MCP_REGISTRY_PUBLISH --body true
118130
```
119131

132+
Nothing waits on it: a failed listing leaves a complete release and can be re-run from the Actions
133+
tab. Leave the variable unset until a hand-run has succeeded once — that login route is unproven
134+
for this namespace until it has.
135+
136+
The workflow checks that `server.json` names the tag's version and that the version is on PyPI,
137+
then runs `mcp-publisher validate`, `login github-oidc` and `publish`. **`publish` has no dry-run
138+
flag**: an unknown flag is ignored, so `publish --dry-run` publishes. Use `validate`, which checks
139+
the manifest against the live registry and changes nothing.
140+
141+
`mcp-publisher` is pinned to a version and a SHA-256 in the workflow, because it runs with the
142+
credential in reach. To update it, download the new `linux_amd64` tarball, check it, and replace
143+
both values.
144+
145+
A listing can be withdrawn. `mcp-publisher status --status deprecated|deleted <name> <version>`
146+
(or `--all-versions`) changes a version's status, with an optional `--message`.
147+
120148
## PyPI is opt-in
121149

122150
The `publish` job is skipped unless the repository variable `PYPI_TRUSTED_PUBLISHER`

‎docs/reference/mcp.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,5 +126,5 @@ connect in process or mount it inside a server of its own.
126126
describes the server for the [official MCP registry](https://github.com/modelcontextprotocol/registry),
127127
which holds metadata only and points at the package on PyPI. Ownership of the
128128
`io.github.creatoan/scenet` namespace is proved by the `mcp-name` marker in the README, which
129-
becomes the PyPI project description. Publishing is a maintainer step; see
130-
[releasing](../maintainer/releasing.md).
129+
becomes the PyPI project description. Listing a release is done by a workflow; see
130+
[releasing](../maintainer/releasing.md#listing-in-the-mcp-registry).

‎tests/test_workflows.py‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
"""The release workflows hold credentials, so their shape is tested.
2+
3+
A workflow is the one place in this repository that can publish to something other
4+
people read. Nothing here runs it -- that needs GitHub -- but the properties that keep
5+
it safe are properties of the file, and a file can be checked: the credential is minted
6+
by one job and no other, nothing installs an unverified binary, and every action is
7+
pinned to a commit rather than to a tag somebody can move.
8+
"""
9+
10+
import re
11+
from pathlib import Path
12+
from typing import Any
13+
14+
import pytest
15+
import yaml
16+
17+
WORKFLOWS = Path(__file__).resolve().parents[1] / ".github" / "workflows"
18+
19+
20+
def _load(name: str) -> dict[Any, Any]:
21+
return yaml.safe_load((WORKFLOWS / name).read_text(encoding="utf-8"))
22+
23+
24+
def _triggers(workflow: dict[Any, Any]) -> dict[str, Any]:
25+
# YAML 1.1 reads a bare `on` as the boolean True, which is how PyYAML sees it.
26+
return workflow.get("on") or workflow[True]
27+
28+
29+
@pytest.mark.parametrize("path", sorted(WORKFLOWS.glob("*.yml")), ids=lambda p: p.name)
30+
def test_every_action_is_pinned_to_a_commit(path: Path):
31+
"""A tag can be re-pointed at different code by whoever controls the repository."""
32+
text = path.read_text(encoding="utf-8")
33+
for use in re.findall(r"^\s*-?\s*uses:\s*(\S+)", text, re.MULTILINE):
34+
if use.startswith("./"):
35+
continue
36+
assert re.search(r"@[0-9a-f]{40}$", use), f"{path.name}: {use} is not pinned to a SHA"
37+
38+
39+
class TestRegistryWorkflow:
40+
"""Publishing to the MCP registry, by OIDC, from the repository's own identity."""
41+
42+
@pytest.fixture(scope="class")
43+
@classmethod
44+
def registry(cls) -> dict[Any, Any]:
45+
return _load("registry.yml")
46+
47+
def test_it_can_be_run_by_hand_and_called_by_the_release(self, registry: dict[Any, Any]):
48+
"""By hand because the first release needs listing without re-tagging it."""
49+
triggers = _triggers(registry)
50+
assert set(triggers) == {"workflow_dispatch", "workflow_call"}
51+
assert "tag" in triggers["workflow_dispatch"]["inputs"]
52+
assert "tag" in triggers["workflow_call"]["inputs"]
53+
54+
def test_nothing_is_granted_workflow_wide(self, registry: dict[Any, Any]):
55+
assert registry["permissions"] == {"contents": "read"}
56+
57+
def test_the_credential_is_minted_by_one_job_only(self, registry: dict[Any, Any]):
58+
minting = [
59+
name
60+
for name, job in registry["jobs"].items()
61+
if (job.get("permissions") or {}).get("id-token") == "write"
62+
]
63+
assert minting == ["publish"]
64+
65+
def test_the_tool_is_pinned_and_checksummed(self, registry: dict[Any, Any]):
66+
"""The binary runs with the OIDC credential in reach, so it is not `latest`."""
67+
(step,) = [
68+
s
69+
for s in registry["jobs"]["publish"]["steps"]
70+
if "mcp-publisher" in s.get("name", "") and "Install" in s["name"]
71+
]
72+
assert re.fullmatch(r"v\d+\.\d+\.\d+", step["env"]["VERSION"])
73+
assert re.fullmatch(r"[0-9a-f]{64}", step["env"]["SHA256"])
74+
assert "releases/download/${VERSION}/" in step["run"]
75+
assert "/releases/latest/" not in step["run"]
76+
assert "sha256sum --check" in step["run"]
77+
assert step["run"].index("sha256sum --check") < step["run"].index("tar ")
78+
79+
def test_it_checks_before_it_publishes(self, registry: dict[Any, Any]):
80+
script = "\n".join(step.get("run", "") for step in registry["jobs"]["publish"]["steps"])
81+
order = [
82+
script.index(command)
83+
for command in (
84+
"./mcp-publisher validate",
85+
"./mcp-publisher login github-oidc",
86+
"./mcp-publisher publish",
87+
)
88+
]
89+
assert order == sorted(order)
90+
91+
def test_it_never_relies_on_a_dry_run_flag(self, registry: dict[Any, Any]):
92+
"""`publish` has no such flag, so one would be ignored and the publish would happen."""
93+
script = "\n".join(step.get("run", "") for step in registry["jobs"]["publish"]["steps"])
94+
assert "--dry-run" not in script
95+
96+
def test_it_waits_for_the_package_it_points_at(self, registry: dict[Any, Any]):
97+
"""The registry checks the PyPI description, so the version has to be there."""
98+
script = "\n".join(step.get("run", "") for step in registry["jobs"]["publish"]["steps"])
99+
assert "pypi.org/pypi/scenet/" in script
100+
101+
102+
class TestReleaseWorkflowCallsIt:
103+
@pytest.fixture(scope="class")
104+
@classmethod
105+
def release(cls) -> dict[Any, Any]:
106+
return _load("release.yml")
107+
108+
def test_it_is_opt_in(self, release: dict[Any, Any]):
109+
"""OIDC login for an org namespace is unproven until it has worked once."""
110+
assert "vars.MCP_REGISTRY_PUBLISH == 'true'" in release["jobs"]["registry"]["if"]
111+
112+
def test_it_runs_after_everything_else_and_blocks_nothing(self, release: dict[Any, Any]):
113+
job = release["jobs"]["registry"]
114+
assert set(job["needs"]) == {"publish", "github-release"}
115+
for name, other in release["jobs"].items():
116+
assert "registry" not in (other.get("needs") or []), name
117+
118+
def test_it_calls_the_reusable_workflow_with_the_tag(self, release: dict[Any, Any]):
119+
job = release["jobs"]["registry"]
120+
assert job["uses"] == "./.github/workflows/registry.yml"
121+
assert job["with"]["tag"] == "${{ github.ref_name }}"
122+
123+
def test_the_credential_is_granted_to_that_job_only(self, release: dict[Any, Any]):
124+
assert release["permissions"] == {"contents": "read"}
125+
job = release["jobs"]["registry"]
126+
assert job["permissions"]["id-token"] == "write"

0 commit comments

Comments
 (0)