04623ed925Registry-wide hardening of the `mcp-name:` ownership-token match, plus the cargo follow-up fixes from the #1330 review — consolidated here per maintainer request. Rebased onto current `main` (the merged #1330 cargo commit drops out), so the diff is just the net-new work. ### Changes - **PyPI/NuGet: boundary-anchored token match.** Replace `strings.Contains(readme, "mcp-name: "+name)` with the shared `containsMCPNameToken`, so a README declaring a longer name (`…/widget-pro`) no longer satisfies an ownership claim for a shorter prefix (`…/widget`). (Cargo already got this in #1330; NPM is unaffected — it compares an exact metadata field.) - **Matcher: treat the HTML comment close as a boundary.** `<!-- mcp-name: NAME-->` / `<!--mcp-name: NAME-->` (any spacing) validate again — the documented hidden-comment form for PyPI/NuGet — while a genuine longer name (`…/widget--pro`) still does not. - **Cargo hardening (review of #1330):** pin scheme+port (not just host) on the README fetch and redirects; a rate-limited/failed crate-version existence probe now reports *transient* instead of "not found"; a 403 with the crate present no longer flatly asserts "no README". - **Docs:** note the token must be followed by a boundary. ### ⚠️ Behavior change for PyPI/NuGet — read before merging The match is **strictly stricter** (verified by fuzz, 2.3M execs: it can only flip pass→fail, never fail→pass). After the comment-close fix, the **only** forms that newly fail are unusual *inline* ones: the token ending a sentence (`…/my-mcp.`) or glued to a trailing `/`. The documented forms (own line, in `<!-- … -->`) are unaffected. **Correcting an earlier claim:** this re-validates on **edits too**, not just new versions — `edit.go → UpdateServer → ValidateUpdateRequest → validateRegistryOwnership` runs the token check on any edit of a live server (only delete-transitions skip it). So an existing PyPI/NuGet server whose README uses one of the breaking inline forms would fail on its next publish *or* edit. Given the v0.1 API-freeze posture, this should land as a deliberate, noted change. ### Testing `go build`, `vet`, `gofmt`, `golangci-lint` (prod files), `check-schema`, `validate-examples` all clean. Hermetic + **live** PyPI/NuGet/cargo suite passes. New: `TestCargoURLAllowed`, a combined-fixture probe-429→transient case, comment-form matcher cases, and `FuzzContainsMCPNameToken` (the strictly-stricter property, 2.3M execs). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
261 lines
10 KiB
Text
261 lines
10 KiB
Text
---
|
|
title: MCP Registry Supported Package Types
|
|
sidebarTitle: Package Types
|
|
---
|
|
|
|
<Note>
|
|
The MCP Registry is currently in preview. Breaking changes or data resets may occur before general availability. If you encounter any issues, please report them on [GitHub](https://github.com/modelcontextprotocol/registry/issues).
|
|
</Note>
|
|
|
|
# Package Types
|
|
|
|
The MCP Registry supports several different package types, and each package type has its own verification method.
|
|
|
|
## npm Packages
|
|
|
|
For npm packages, the MCP Registry currently supports the npm public registry (`https://registry.npmjs.org`) only.
|
|
|
|
npm packages use `"registryType": "npm"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/email-integration-mcp",
|
|
"title": "Email Integration",
|
|
"description": "Send emails and manage email accounts",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "npm",
|
|
"identifier": "@username/email-integration-mcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of npm packages by checking `mcpName` in `package.json`. The `mcpName` property **MUST** match the server name from `server.json`. For example:
|
|
|
|
```json package.json
|
|
{
|
|
"name": "@username/email-integration-mcp",
|
|
"version": "1.0.0",
|
|
"mcpName": "io.github.username/email-integration-mcp"
|
|
}
|
|
```
|
|
|
|
## PyPI Packages
|
|
|
|
For PyPI packages, the MCP Registry currently supports the official PyPI registry (`https://pypi.org`) only.
|
|
|
|
PyPI packages use `"registryType": "pypi"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/database-query-mcp",
|
|
"title": "Database Query",
|
|
"description": "Execute SQL queries and manage database connections",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "pypi",
|
|
"identifier": "database-query-mcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of PyPI packages by checking for the existence of an `mcp-name: $SERVER_NAME` string in the package README (which becomes the package description on PyPI). The string may be hidden in a comment, but the `$SERVER_NAME` portion **MUST** match the server name from `server.json`. For example:
|
|
|
|
```markdown README.md highlight={5}
|
|
# Database Query MCP Server
|
|
|
|
This MCP server executes SQL queries and manages database connections.
|
|
|
|
<!-- mcp-name: io.github.username/database-query-mcp -->
|
|
```
|
|
|
|
The `mcp-name:` token must be followed by a boundary — a newline, whitespace, an HTML tag, or the comment close `-->`. Keep it on its own line or inside `<!-- … -->`; do not glue it directly to trailing characters such as a sentence-ending period (`…/database-query-mcp.`), which prevents the match.
|
|
|
|
## NuGet Packages
|
|
|
|
For NuGet packages, the MCP Registry currently supports the official NuGet registry (`https://api.nuget.org/v3/index.json`) only.
|
|
|
|
NuGet packages use `"registryType": "nuget"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/azure-devops-mcp",
|
|
"title": "Azure DevOps",
|
|
"description": "Manage Azure DevOps work items and pipelines",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "nuget",
|
|
"identifier": "Username.AzureDevOpsMcp",
|
|
"version": "1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of NuGet packages by checking for the existence of an `mcp-name: $SERVER_NAME` string in the package README. The string may be hidden in a comment, but the `$SERVER_NAME` portion **MUST** match the server name from `server.json`. For example:
|
|
|
|
```markdown README.md highlight={5}
|
|
# Azure DevOps MCP Server
|
|
|
|
This MCP server manages Azure DevOps work items and pipelines.
|
|
|
|
<!-- mcp-name: io.github.username/azure-devops-mcp -->
|
|
```
|
|
|
|
The `mcp-name:` token must be followed by a boundary — a newline, whitespace, an HTML tag, or the comment close `-->`. Keep it on its own line or inside `<!-- … -->`; do not glue it directly to trailing characters such as a sentence-ending period (`…/azure-devops-mcp.`), which prevents the match.
|
|
|
|
## Cargo (Rust) Packages
|
|
|
|
For Cargo packages, the MCP Registry currently supports the official crates.io registry (`https://crates.io`) only.
|
|
|
|
Cargo packages use `"registryType": "cargo"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/widget-mcp",
|
|
"title": "Widget",
|
|
"description": "Rust-native MCP server",
|
|
"version": "0.3.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "cargo",
|
|
"identifier": "widget-mcp",
|
|
"version": "0.3.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Runtime Model
|
|
|
|
Cargo's runtime model differs from npm/PyPI/NuGet. `cargo install <crate>` places the compiled binary on PATH at `~/.cargo/bin`, after which MCP clients invoke it directly by name. There is no per-invocation runner equivalent to `npx` (npm), `uvx` (PyPI), or `dnx` (NuGet, .NET 10 SDK Preview 6+) — install is one-time, execution is by binary name. The Cargo example above intentionally omits `runtimeHint` for this reason.
|
|
|
|
Rust MCP authors have two first-class distribution paths:
|
|
|
|
- **Cargo (`registryType: cargo`)** — source-distributed via crates.io. End users need the Rust toolchain (`rustup`) to run `cargo install`. Idiomatic for the Rust ecosystem and consistent with how Rust CLIs are typically published.
|
|
- **MCPB (`registryType: mcpb`)** — prebuilt binary distributed via GitHub or GitLab Releases. End users need no toolchain. Right choice if the priority is "no Rust toolchain required."
|
|
|
|
Both paths are supported; the choice is the author's. Cargo native support exists so Rust authors who prefer source distribution are not forced into the MCPB binary-packaging workaround.
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of Cargo packages by checking for the existence of an `mcp-name: $SERVER_NAME` string in the package README (which is rendered to HTML and served by crates.io's static CDN). The `$SERVER_NAME` portion **MUST** match the server name from `server.json`. For example:
|
|
|
|
```markdown README.md highlight={5}
|
|
# Widget MCP Server
|
|
|
|
A Rust-native MCP server for widget operations.
|
|
|
|
- MCP Registry name: `mcp-name: io.github.username/widget-mcp`
|
|
```
|
|
|
|
**Cargo-specific gotcha:** Unlike PyPI and NuGet (which preserve HTML comments in their README rendering), **crates.io strips HTML comments during markdown→HTML conversion**. The `<!-- mcp-name: ... -->` hidden-comment form that works for PyPI/NuGet **does not work for cargo** — the token will not appear in the rendered HTML the validator inspects. Cargo authors must include the `mcp-name:` token as visible markdown text. A simple bullet in the Links section is the recommended pattern.
|
|
|
|
## Docker/OCI Images
|
|
|
|
For Docker/OCI images, the MCP Registry currently supports:
|
|
|
|
- Docker Hub (`docker.io`)
|
|
- GitHub Container Registry (`ghcr.io`)
|
|
- Quay.io (`quay.io`)
|
|
- Google Artifact Registry (any `*.pkg.dev` domain)
|
|
- Azure Container Registry (`*.azurecr.io`)
|
|
- Microsoft Container Registry (`mcr.microsoft.com`)
|
|
|
|
Docker/OCI images use `"registryType": "oci"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/kubernetes-manager-mcp",
|
|
"title": "Kubernetes Manager",
|
|
"description": "Deploy and manage Kubernetes resources",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "oci",
|
|
"identifier": "docker.io/yourusername/kubernetes-manager-mcp:1.0.0",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The format of `identifier` is `registry/namespace/repository:tag`. For example, `docker.io/user/app:1.0.0`, `ghcr.io/user/app:1.0.0`, or `quay.io/myorg/my-mcp-server:1.0.0`. The tag can also be specified as a digest.
|
|
|
|
### Ownership Verification
|
|
|
|
The MCP Registry verifies ownership of Docker/OCI images by checking for an `io.modelcontextprotocol.server.name` annotation. The value of the `io.modelcontextprotocol.server.name` annotation **MUST** match the server name from `server.json`. For example:
|
|
|
|
```dockerfile Dockerfile
|
|
LABEL io.modelcontextprotocol.server.name="io.github.username/kubernetes-manager-mcp"
|
|
```
|
|
|
|
## MCPB Packages
|
|
|
|
For MCPB packages, the MCP Registry currently supports MCPB artifacts hosted via GitHub or GitLab releases.
|
|
|
|
MCPB packages use `"registryType": "mcpb"` in `server.json`. For example:
|
|
|
|
```json server.json highlight={9}
|
|
{
|
|
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
"name": "io.github.username/image-processor-mcp",
|
|
"title": "Image Processor",
|
|
"description": "Process and transform images with various filters",
|
|
"version": "1.0.0",
|
|
"packages": [
|
|
{
|
|
"registryType": "mcpb",
|
|
"identifier": "https://github.com/username/image-processor-mcp/releases/download/v1.0.0/image-processor.mcpb",
|
|
"fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
|
|
"transport": {
|
|
"type": "stdio"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Verification
|
|
|
|
The MCPB package URL (`identifier` in `server.json`) **MUST** contain the string "mcp". That can be as part of the `.mcpb` file extension or in the name of the repository.
|
|
|
|
The package metadata in `server.json` **MUST** include a `fileSha256` property with a SHA-256 hash of the MCPB artifact, which can be computed using the `openssl` command:
|
|
|
|
```bash
|
|
openssl dgst -sha256 image-processor.mcpb
|
|
```
|
|
|
|
The MCP Registry does not validate this hash; however, MCP clients **do** validate the hash before installation to ensure file integrity. Downstream registries may also implement their own validation.
|