Watch

Jonathan Hefner 43d41a242e

Prepare docs for modelcontextprotocol.io (#728 )

This PR reorganizes and extends the existing documentation in
preparation for publishing on https://modelcontextprotocol.io/.

The current plan is for docs to remain in this repo, and be synced to
the `modelcontextprotocol/modelcontextprotocol` whenever necessary
(e.g., accompanying a release of the registry). I have included a script
in
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1725
(`bin/pull-registry-docs.sh`) that can be run manually to perform the
sync.

If we later decide to permanently move the docs to the
`modelcontextprotocol/modelcontextprotocol` repo, that also works.

This PR puts all https://modelcontextprotocol.io/ docs into
`docs/modelcontextprotocol-io/`. Docs outside that subdirectory, such as
`docs/administration/admin-operations.md`, are intended to be accessible
solely via this repo. One major exception is the
`docs/reference/server-json/` subdirectory, which will depend on the
resolution of
https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1649.
However, I think we could address that in a follow-up PR.

---------

Co-authored-by: Adam Jones <adamj+git@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>

2025-11-18 17:22:31 +00:00

2.7 KiB

Raw Blame History

Release Guide

Creating a Release

Go to GitHub: Navigate to https://github.com/modelcontextprotocol/registry/releases
Click "Draft a new release"
Choose a tag: Click "Choose a tag" and type a new semantic version that follows the last one available (e.g., v1.0.0)
Generate notes: Click "Generate release notes" to auto-populate the name and description
Publish: Click "Publish release"

The release workflow will automatically:

Build binaries for 6 platforms (Linux, macOS, Windows × amd64, arm64)
Create and push Docker images with :latest and :X.Y.Z tags (note: no 'v' prefix)
Attach all artifacts to the GitHub release
Generate checksums and signatures

After Release

Docker images will be available at:
- ghcr.io/modelcontextprotocol/registry:latest - Latest stable release
- ghcr.io/modelcontextprotocol/registry:X.Y.Z - Specific release version (note: no 'v' prefix)
Binaries can be downloaded from the GitHub release page

Deploying to Production

Releases do not automatically deploy to production. To deploy a release:

Update mcp-registry:imageTag in deploy/Pulumi.gcpProd.yaml to the desired version (e.g., 1.2.3 - note: no 'v' prefix)
Commit and push the change to the main branch (either through a PR or by pushing directly to main)
The deploy-production.yml workflow will automatically trigger and deploy the specified version

See the deployment documentation for more details.

Staging

Staging auto-deploys from main via deploy-staging.yml. It always runs the latest main branch code.

Rollback

To rollback production, update deploy/Pulumi.gcpProd.yaml to the previous version and push.

Note: Rollbacks may not work as expected if the release included database migrations, since migrations are not automatically reversed.

Docker Image Tags

The registry publishes different Docker image tags for different use cases:

:latest - Latest stable release (updated only on releases)
:X.Y.Z - Specific release versions (e.g., :1.0.0 - note: no 'v' prefix)
:main - Rolling tag updated on every push to main branch (continuous deployment)
:main-YYYYMMDD-sha - Specific development builds from main branch

Note: Git release tags include the 'v' prefix (e.g., v1.0.0), but Docker image tags follow the standard Docker convention and do not include the 'v' prefix (e.g., 1.0.0).

Versioning

We use semantic versioning (SemVer):

v1.0.0 - Major release with breaking changes
v1.1.0 - Minor release with new features
v1.0.1 - Patch release with bug fixes

2.7 KiB Raw Blame History Unescape Escape