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>

docs/contributing/add-package-registry.md

@@ -0,0 +1,56 @@
+# Adding a new package registry
+
+The MCP Registry project is a **metaregistry**, meaning that it hosts metadata for MCP servers but does not host the code for the servers directly.
+
+For local MCP servers, the MCP Registry has pointers in the `packages` node of the [`server.json`](../../reference/server-json/generic-server-json.md) schema that refer to packages in supported package managers.
+
+The list of supported package managers for hosting MCP servers is defined by the `properties.packages[N].properties.registryType` string enum in the [`server.json` schema](../../reference/server-json/server.schema.json). For example, this could be "npm" (for npmjs.com packages) or "pypi" (for PyPI packages).
+
+For remote MCP servers, the package registry is not relevant. The MCP client consumes the server via a URL instead of by downloading and running a package. In other words, this document only applies to local MCP servers.
+
+For the sake of illustration, this document will use npm (the Node.js package manager) as an example at each step.
+
+## Prerequisites
+
+The package registry must meet the following requirements:
+
+1. The package registry supports packaging and executing CLI apps. Local MCP servers use the [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio).
+   - npm CLI tools typically express their CLI commands in the [`bin` property of the package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json#bin)
+1. The package registry (or associated client tooling) has a widely accepted **single-shot** CLI command.
+   - npm's `npx` tool executes CLI commands using a [documented execution heuristic](https://docs.npmjs.com/cli/v11/commands/npx#description)
+   - For example, the MCP client can map the `server.json` metadata to an `npx` CLI execution, with args and environment variables populated via user input.
+1. The package registry supports anonymous package downloads. This allows the MCP client software to use the metadata found in the MCP registry to discover, download, and execute package-based local MCP servers with minimal user intervention.
+   - `npx` by default connects to the public npmjs.com registry, allowing simple consumption of public npm packages.
+1. The package registry should support a validation mechanism to verify ownership of the server name. This prevents misattribution and ensures that only the actual package owner can reference their packages in server registrations. For example:
+   - npm requires an `mcpName` field in `package.json` that matches the server name being registered
+   - PyPI requires a `mcp-name:` line in the package README/description
+   - Each registry type must implement a validation mechanism accessible via public API
+
+## Steps
+
+These steps may evolve as additional validations or details are discovered and mandated.
+
+1. [Create a feature request issue](https://github.com/modelcontextprotocol/registry/issues/new?template=feature_request.md) on the MCP Registry repository to begin the discussion about adding the package registry.
+   - Example for NuGet: https://github.com/modelcontextprotocol/registry/issues/126
+1. Open a PR with the following changes:
+   - Update the [`server.json` schema](../../reference/server-json/server.schema.json)
+     - Add your package registry name to the `registryType` example array.
+     - Add your package registry base url to the `registryBaseUrl` example array.
+     - Add the single-shot CLI command name to the `runtimeHint` example value array.
+   - Update the [`openapi.yaml`](../../reference/api/openapi.yaml)
+     - Add your package registry name to the `registryType` enum value array.
+     - Add your package registry base url to the `registryBaseUrl` enum value array.
+     - Add the single-shot CLI command name to the `runtimeHint` example value array.
+   - Add a sample, minimal `server.json` to the [`server.json` examples](../../reference/server-json/generic-server-json.md).
+   - Implement a registry validator:
+      - Create a new validator file: `internal/validators/registries/yourregistry.go`, following the pattern of existing validators. Examples:
+         - **npm**: Checks for an `mcpName` field in `package.json` that matches the server name
+         - **PyPI**: Searches for `mcp-name: server-name` format in the package README content
+         - **NuGet**: Looks for `mcp-name: server-name` format in the package README file
+         - **Docker/OCI**: Validates a Docker image label `io.modelcontextprotocol.server.name` in the image manifest
+      - Add corresponding unit tests: `internal/validators/registries/yourregistry_test.go`
+      - Register your validator in `internal/validators/validators.go`
+   - Update the publishing documentation:
+      - Add a new publishing guide: `docs/guides/publishing/publish-[yourregistry].md`, following the pattern of existing publishing guides (e.g., `publish-npm.md`, `publish-pypi.md`)
+      - Include instructions on how to prepare packages for your registry, including any specific validation requirements
+      - Update `docs/guides/publishing/README.md` to reference your new publishing guide

docs/contributing/releasing.md

@@ -0,0 +1,60 @@
+# Release Guide
+
+## Creating a Release
+
+1. **Go to GitHub**: Navigate to https://github.com/modelcontextprotocol/registry/releases
+2. **Click "Draft a new release"**
+3. **Choose a tag**: Click "Choose a tag" and type a new semantic version that follows the last one available (e.g., `v1.0.0`)
+5. **Generate notes**: Click "Generate release notes" to auto-populate the name and description
+6. **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:
+
+1. Update `mcp-registry:imageTag` in `deploy/Pulumi.gcpProd.yaml` to the desired version (e.g., `1.2.3` - note: no 'v' prefix)
+2. Commit and push the change to the `main` branch (either through a PR or by pushing directly to main)
+3. The [deploy-production.yml](../../../.github/workflows/deploy-production.yml) workflow will automatically trigger and deploy the specified version
+
+See the [deployment documentation](../../../deploy/README.md) for more details.
+
+## Staging
+
+Staging auto-deploys from `main` via [deploy-staging.yml](../../../.github/workflows/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