Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
150 changes: 148 additions & 2 deletions .github/workflows/mcp-registry.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,33 @@ on:
- server.json
- packages/mcp/package.json
- .github/workflows/mcp-registry.yml
# Run before publishing: the hosted deployment must already serve this version.
# Release calls this after npm has the version; dispatch it by hand to recover a missed one.
workflow_call:
inputs:
version:
description: Released @pascal-app/mcp version; checks out its release tag
required: true
type: string
publish:
required: true
type: boolean
secrets:
MCP_REGISTRY_PRIVATE_KEY:
required: false
workflow_dispatch:
inputs:
version:
description: Released @pascal-app/mcp version; checks out its release tag
required: true
type: string
publish:
description: Publish server.json to the MCP Registry
type: boolean
default: false
check-hosted:
description: Check that the hosted API catalog and server card report this version
type: boolean
default: true

env:
MCP_PUBLISHER_VERSION: 1.8.1
Expand All @@ -27,6 +52,7 @@ jobs:
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
ref: ${{ inputs.version && format('refs/tags/@pascal-app/mcp@{0}', inputs.version) || '' }}
persist-credentials: false

- name: Install MCP Registry publisher
Expand Down Expand Up @@ -81,16 +107,136 @@ jobs:
'resource_metadata="https://editor.pascal.app/.well-known/oauth-protected-resource"' \
"$RUNNER_TEMP/mcp-response.headers"

# The registry reads mcpName from the npm tarball, so this waits until npm serves the
# version, and it fails unless the registry lists the version afterwards.
publish:
if: inputs.publish
needs: validate
runs-on: ubuntu-latest
# The environment's deployment rule allows only main; it holds MCP_REGISTRY_PRIVATE_KEY.
environment: mcp-registry
concurrency:
group: mcp-registry-publish
cancel-in-progress: false
permissions:
contents: read
env:
NAME: app.pascal/editor
PACKAGE: "@pascal-app/mcp"
VERSIONS_URL: https://registry.modelcontextprotocol.io/v0/servers/app.pascal%2Feditor/versions
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
ref: refs/tags/@pascal-app/mcp@${{ inputs.version }}
persist-credentials: false

# Later steps take the version only from this step's output.
- name: Validate release manifest
id: manifest
env:
INPUT_VERSION: ${{ inputs.version }}
run: |
case "$INPUT_VERSION" in
*$'\r'* | *$'\n'*)
echo "::error::version contains a line break"
exit 1
;;
esac
if ! [[ "$INPUT_VERSION" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
echo "::error::version must be a stable semver release such as 1.2.3"
exit 1
fi
jq --exit-status --arg name "$NAME" --arg package "$PACKAGE" --arg version "$INPUT_VERSION" '
.name == $name
and .version == $version
and (.packages | length) == 1
and .packages[0].identifier == $package
and .packages[0].version == $version
' server.json >/dev/null || {
echo "::error::server.json must name $NAME with the single package $PACKAGE, both at $INPUT_VERSION"
exit 1
}
jq --exit-status --arg name "$NAME" --arg package "$PACKAGE" --arg version "$INPUT_VERSION" '
.name == $package and .mcpName == $name and .version == $version
' packages/mcp/package.json >/dev/null || {
echo "::error::packages/mcp/package.json must be $PACKAGE@$INPUT_VERSION with mcpName $NAME"
exit 1
}
echo "version=$INPUT_VERSION" >> "$GITHUB_OUTPUT"

# A fresh publish can take a few minutes to show up in `npm view`.
- name: Wait for npm to serve the version
env:
VERSION: ${{ steps.manifest.outputs.version }}
run: |
for attempt in $(seq 1 30); do
if [ "$(npm view "$PACKAGE@$VERSION" mcpName 2>/dev/null)" = "$NAME" ]; then
echo "$PACKAGE@$VERSION is on npm with mcpName $NAME"
exit 0
fi
sleep 20
done
echo "::error::$PACKAGE@$VERSION with mcpName $NAME is not on npm after 10 minutes"
exit 1

- name: Install MCP Registry publisher
run: |
curl --fail --location \
"https://github.com/modelcontextprotocol/registry/releases/download/v${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz" \
--output "$RUNNER_TEMP/mcp-publisher.tar.gz"
echo "${MCP_PUBLISHER_LINUX_AMD64_SHA256} $RUNNER_TEMP/mcp-publisher.tar.gz" | sha256sum --check
tar -xzf "$RUNNER_TEMP/mcp-publisher.tar.gz" -C "$RUNNER_TEMP" mcp-publisher

# The app.pascal namespace is verified through CI's own pascal.app DNS TXT record,
# whose Ed25519 private key is the MCP_REGISTRY_PRIVATE_KEY environment secret.
- name: Publish to the MCP Registry
env:
VERSION: ${{ steps.manifest.outputs.version }}
MCP_REGISTRY_PRIVATE_KEY: ${{ secrets.MCP_REGISTRY_PRIVATE_KEY }}
run: |
if curl --silent --fail "$VERSIONS_URL" \
| jq --exit-status --arg v "$VERSION" 'any(.servers[]; .server.version == $v)' >/dev/null; then
echo "$NAME@$VERSION is already in the MCP Registry"
exit 0
fi
if [ -z "$MCP_REGISTRY_PRIVATE_KEY" ]; then
echo "::error::MCP_REGISTRY_PRIVATE_KEY is not set, so $NAME@$VERSION cannot be published. See wiki/npm-release.md#mcp-registry."
exit 1
fi
"$RUNNER_TEMP/mcp-publisher" login dns --domain pascal.app --private-key "$MCP_REGISTRY_PRIVATE_KEY"
"$RUNNER_TEMP/mcp-publisher" publish

- name: Remove the registry token
if: always()
run: rm -f ~/.mcpregistry_registry_token

- name: Registry lists the version
env:
VERSION: ${{ steps.manifest.outputs.version }}
run: |
for attempt in $(seq 1 10); do
if curl --silent --fail "$VERSIONS_URL" \
| jq --exit-status --arg v "$VERSION" 'any(.servers[]; .server.version == $v)' >/dev/null; then
echo "$NAME@$VERSION is in the MCP Registry"
exit 0
fi
sleep 15
done
echo "::error::$NAME@$VERSION is not in the MCP Registry: $VERSIONS_URL"
exit 1

# The hosted API catalog and server card are served by the hosted deployment, not
# this repository, so they only match after that deployment picks up this version.
# It does not gate the registry publish.
hosted-matches-manifest:
if: github.event_name == 'workflow_dispatch'
if: inputs.check-hosted
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
with:
ref: ${{ inputs.version && format('refs/tags/@pascal-app/mcp@{0}', inputs.version) || '' }}
persist-credentials: false

- name: Verify live API catalog matches manifest
Expand Down
16 changes: 14 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -219,8 +219,7 @@ jobs:
# leaves them on the last stable release.
bun scripts/sync-agent-versions.ts

# Publishing server.json to the MCP Registry stays a manual owner step after
# this release lands; see wiki/npm-release.md.
# The mcp-registry job publishes server.json once this job has pushed the tag.
- name: Validate MCP Registry manifest
env:
MCP_PUBLISHER_VERSION: 1.8.1
Expand Down Expand Up @@ -441,6 +440,19 @@ jobs:
gh release upload "$TAG" "$ARCHIVE" "$ARCHIVE.sha256" --clobber
echo "🌐 Uploaded $(basename "$ARCHIVE") to $TAG"

# A beta leaves server.json on the last stable version, which is already listed.
mcp-registry:
needs: release
if: inputs.dry-run == false && needs.release.outputs.channel == 'latest'

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Exclude prerelease recovery runs from registry publishing

When a partial beta release is recovered with the documented bump=none, the release keeps its *-beta.* version but NPM_TAG/the channel output is set to latest because only the literal beta input selects the beta channel. This condition therefore invokes the registry workflow with the prerelease version, while sync-agent-versions.ts intentionally leaves server.json on the previous stable version; the called workflow then fails its VERSION != EXPECTED_VERSION check. A recovery that otherwise successfully publishes or tags the beta is consequently reported failed. Gate this job on the released version containing no prerelease suffix, or expose an explicit stable-release output instead of inferring stability from channel.

Useful? React with 👍 / 👎.

Comment thread
cursor[bot] marked this conversation as resolved.
Resolved
permissions:
contents: read
uses: ./.github/workflows/mcp-registry.yml
with:
version: ${{ needs.release.outputs.version }}
publish: true
secrets:
MCP_REGISTRY_PRIVATE_KEY: ${{ secrets.MCP_REGISTRY_PRIVATE_KEY }}

# The self-host image, built from the release tag on native runners (a Next
# build under QEMU takes most of an hour) and stitched into one multi-arch
# manifest. Tagged with the npm version so the container and the CLI runtime
Expand Down
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,8 +133,10 @@ These workflows require a connected Pascal MCP server for their tool-backed acti
`app.pascal/editor`. It lists the `@pascal-app/mcp` npm package and the hosted Streamable HTTP
endpoint, which signs in with OAuth. Its version is the `@pascal-app/mcp` package version:
`bun scripts/sync-agent-versions.ts` rewrites it, and the Cursor plugin's CLI pin, from the
package versions, and CI fails when they drift. A Pascal owner publishes from `main` after a
release; see [wiki/npm-release.md](wiki/npm-release.md#mcp-registry).
package versions, and CI fails when they drift. Each stable release publishes it to the registry
after npm has the package. The signing key is CI's own `pascal.app` DNS key, held only in the
`mcp-registry` environment, which a repository admin sets up first; see
[wiki/npm-release.md](wiki/npm-release.md#mcp-registry).

## Using Published Packages

Expand Down
37 changes: 32 additions & 5 deletions wiki/npm-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,38 @@ The same `release.yml` run publishes `ghcr.io/pascalorg/pascal-editor` after the

## MCP Registry

[`server.json`](../server.json) publishes as `app.pascal/editor` with the `@pascal-app/mcp` npm package and the hosted remote. Nothing publishes it automatically. After a release lands on `main`:
[`server.json`](../server.json) publishes as `app.pascal/editor` with the `@pascal-app/mcp` npm package and the hosted remote. Its version is never edited by hand: `bun scripts/sync-agent-versions.ts` rewrites it from `packages/mcp/package.json`.

1. The registry checks npm ownership by reading `mcpName` from the published `@pascal-app/mcp@<version>`, so publish only versions whose npm tarball carries `"mcpName": "app.pascal/editor"`.
2. Deploy the hosted editor at the same version, then run the **MCP Registry** workflow by hand (`gh workflow run mcp-registry.yml`). Its `hosted-matches-manifest` job checks that the live API catalog and `/.well-known/mcp/server-card.json` report this version and registry name.
3. Authenticate for the `app.pascal` namespace once per session: `mcp-publisher login dns --domain pascal.app --private-key <hex Ed25519 key>`, which needs the `pascal.app` TXT record `v=MCPv1; k=ed25519; p=<public key>`. HTTP verification (`mcp-publisher login http`, serving `https://pascal.app/.well-known/mcp-registry-auth`) is the alternative.
4. From the repository root, `mcp-publisher publish`, then confirm with `curl "https://registry.modelcontextprotocol.io/v0/servers?search=app.pascal/editor"`.
A stable `release.yml` run ends with the `mcp-registry` job, which calls [`mcp-registry.yml`](../.github/workflows/mcp-registry.yml) with the released version and passes it only the `MCP_REGISTRY_PRIVATE_KEY` secret. The `publish` job checks out the `@pascal-app/mcp@<version>` tag and fails unless the version is a stable `X.Y.Z` and `server.json` and `packages/mcp/package.json` name `app.pascal/editor` and `@pascal-app/mcp` at that version. It then waits until `npm view @pascal-app/mcp@<version> mcpName` reports `app.pascal/editor` (the registry verifies npm ownership through that field), publishes, deletes the registry token, and fails unless `https://registry.modelcontextprotocol.io/v0/servers/app.pascal%2Feditor/versions` then lists the version. A version that is already listed is skipped, so reruns are safe, and publish runs never overlap. Betas are not published: server.json stays on the last stable version.

### The CI signing key

The `app.pascal` namespace is verified by DNS: a `pascal.app` TXT record `v=MCPv1; k=ed25519; p=<public key>` whose private key signs the login. `pascal.app` already carries two such records; neither is CI's. CI uses its own keypair, generated only for CI, with its own TXT record, so it can be revoked without touching anyone else's key. When the record is added, write its `p=` value here so the record CI owns is on file (the public key only):

- CI public key: _not set up yet_

Setting it up is a repository admin's job, done in this order:

1. Create the GitHub environment `mcp-registry`. Its deployment branch rule allows only `main`; add a required reviewer as well where possible.
2. Generate the keypair: `openssl genpkey -algorithm Ed25519 -out ci-key.pem`. The public key for the TXT record is `openssl pkey -in ci-key.pem -pubout -outform DER | tail -c 32 | base64`, and the hex private key for the secret is `openssl pkey -in ci-key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'`.
3. Add the TXT record `v=MCPv1; k=ed25519; p=<public key>` to `pascal.app`, and record the public key above.
4. Store the hex private key as the `MCP_REGISTRY_PRIVATE_KEY` secret of the `mcp-registry` environment, then delete `ci-key.pem`.

`MCP_REGISTRY_PRIVATE_KEY` lives only in that environment. It is never a repository secret or a secret of any other environment. Until it exists the `publish` job fails and says so.

### Rotating the CI key

1. Remove CI's TXT record from `pascal.app` (the one whose `p=` value is listed above).
2. Generate a new keypair and publish its TXT record, as in the setup steps above, and update the public key listed here.
3. Replace `MCP_REGISTRY_PRIVATE_KEY` in the `mcp-registry` environment with the new private key.
4. Check what the registry lists: `https://registry.modelcontextprotocol.io/v0/servers?search=app.pascal` and `https://registry.modelcontextprotocol.io/v0/servers/app.pascal%2Feditor/versions`. Every entry should match a release in this repository.
5. Mark any entry that does not with `mcp-publisher status --status deleted app.pascal/editor <version>`, logged in with a `pascal.app` key.
6. If the workflow itself is in doubt, revert the change or disable `mcp-registry.yml` in the Actions settings until it is sorted out.

### Recovering a missed version

Dispatch the workflow from `main` with the version, which is required: `gh workflow run mcp-registry.yml -f version=<version> -f publish=true`. With `check-hosted` (on by default) the `hosted-matches-manifest` job also checks that the live API catalog and `/.well-known/mcp/server-card.json` report this version; those are served by the hosted deployment, so that job only passes once it runs the same `@pascal-app/mcp`, and it does not gate the publish.

By hand, from the release tag: `mcp-publisher login dns --domain pascal.app --private-key <hex key>`, then `mcp-publisher publish`.

GitHub release notes follow the house style: emoji sections, every line linked to its PR, a 📦 package table, individual contributor attributions, and the compare link last. Verify the table against npm before publishing — an earlier release claimed versions that were never published.
Loading