feat: add cargo (crates.io) as a package registry type (#1207)
> **Update — 2026-06-01 (commit 1f3be53)** > > - **All @P4ST4S review feedback addressed** — positive-path hermetic mock + live anchor against `rust-faf-mcp v0.3.1`; 5xx routed as transient; doc comment qualified. See the [close-out comment](https://github.com/modelcontextprotocol/registry/pull/1207#issuecomment-4589711057) for the per-item breakdown. > - **Runtime-model question RESOLVED** — `package-types.mdx` documents cargo and MCPB as both first-class Rust MCP distribution paths (cargo for source-distributed, MCPB for prebuilt-binary). The "Open question" section below was the original draft framing; the doc now ships the resolution. > - **Cargo-specific gotcha discovered and documented** — crates.io strips HTML comments during README rendering, unlike PyPI/NuGet. `package-types.mdx` now spells this out so cargo authors don't ship invisible mcp-name tokens (which is exactly what happened to `rust-faf-mcp v0.3.0`; fixed in v0.3.1). > - **Stale reference removed in this update** — the "Out of scope" line mentioning `docs/guides/publishing/publish-cargo.md` pointed at a path that doesn't exist. The canonical per-type doc is `docs/modelcontextprotocol-io/package-types.mdx`; the Cargo section has been added there directly. > - **Two real-world Rust MCP servers queued for day-one register**: `rust-faf-mcp v0.3.1` (live, end-to-end validated by the new live test) and `perfetto-mcp-rs` ([@0xZOne](https://github.com/0xZOne) in #1055). > - **Tests:** 19/19 cargo tests pass (16 existing + 2 hermetic + 1 live anchor). `make validate` clean. `golangci-lint` 0 issues. --- Adds support for `registryType: cargo` so Rust MCP servers published to crates.io can be registered through the documented validation flow rather than the MCPB binary-packaging workaround. Closes #1055. ## Motivation and Context #1055 noted that crates.io has ~1,800 MCP-related packages with no direct path into the registry — only the MCPB binary-packaging workaround. This PR adds first-class support for cargo as a package registry type: schema + API surface, validator, integration tests, and a documented example. The publishing guide (`docs/guides/publishing/publish-cargo.md`) follows on this branch once the runtime-model direction in **Additional context** is settled. ## How Has This Been Tested? - **`make validate`** — clean. Schema-vs-openapi sync verified; 17/17 examples in `generic-server-json.md` validate against the schema; `expectedServerJSONCount` bumped 16 → 17 to match the new Cargo example. - **`go test ./internal/validators/...`** — passes. 16 cargo validator sub-cases across 4 test functions, run against real crates.io (~2.5s wall): - Input validation rejection paths - Registry-baseURL rejection (4 variants: different host, trailing slash, http-not-https, subdomain typo) - Ownership validation against real crates (`serde`, `tokio`, `rand`) — all correctly rejected for missing `mcp-name` token - Server-name format variations (canonical `io.github.OWNER/REPO`, multi-hyphen, underscore, numeric suffix) - **Positive-path test** — gated on `rust-faf-mcp` v0.2.3+ being published with `mcp-name: io.github.Wolfe-Jam/rust-faf-mcp` in its README. Reserved as a TODO in `cargo_test.go`; uncomments to become the live anchor once that publish lands. - **Local `make test-unit`** — not run due to a Go toolchain version quirk on my workstation (project auto-downloads 1.26.0; my local `go` is 1.25.6, causing compile mismatch). CI will exercise the full PostgreSQL-backed suite. ## Breaking Changes None. This is an additive change — `cargo` joins the supported `registryType` enum alongside `npm`/`pypi`/`nuget`/`oci`/`mcpb`. Existing publishes continue to work unchanged. ## Types of changes - [x] New feature (non-breaking change which adds functionality) - [x] Documentation update (new Cargo example in `generic-server-json.md`) ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [x] I have added appropriate error handling - [x] I have added or updated documentation as needed ## Additional context ### Validator design — two-call retrieval on the documented API `internal/validators/registries/cargo.go` mirrors the PyPI validator's README-token approach (substring-match `mcp-name: <serverName>`), with a two-call retrieval pattern to stay on the documented public crates.io API: 1. `GET /api/v1/crates/{name}/{version}/readme` returns 200 OK with a JSON pointer (`{"url": "https://static.crates.io/readmes/.../...html"}`) — crates.io hands us the URL rather than emitting a 302. 2. Follow the pointer to the rendered HTML; substring-match for the token. The two-call pattern stays on the documented public surface. The CDN URL layout is observed-stable, but treating it as the entry point would mean depending on an undocumented path. With two calls, crates.io controls where the README lives — if they move it, the metadata endpoint hands us the new URL. Missing crates and missing versions surface as **403** from the CDN (S3's default for missing keys), not 404. The validator treats any non-200 as "not found" and surfaces the actual status code in the error message. ### Open question — runtime model Cargo's runtime model is genuinely different from npm/PyPI/NuGet. `cargo install` is one-time (binary lands on PATH at `~/.cargo/bin`), not per-invocation like `npx`, `uvx`, or `dnx` (the new one in .NET 10 SDK Preview 6+). The new Cargo example in `generic-server-json.md` annotates this honestly and omits `runtimeHint`. If a different framing is preferred — e.g. recommending **MCPB** (prebuilt binary distribution via GitHub Releases) as the primary path for Rust MCP servers instead of cargo — happy to adjust the documentation accordingly. The schema + validator code in this PR is **additive** and doesn't force a recommendation either way; a Rust author who chooses cargo can use it, and one who prefers MCPB still can. ### Out of scope (deferred) - **`docs/guides/publishing/publish-cargo.md`** — follows on this branch once the runtime-model direction above is settled. - **Publisher CLI `Cargo.toml` autodetect** in `cmd/publisher/commands/init.go` — separate concern, separate PR. - **Positive-path validator test** — gated on `rust-faf-mcp` v0.2.3+ publishing as noted in *How Has This Been Tested?*. --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Radoslav Dimitrov <radoslav@stacklok.com>
This commit is contained in:
Wolfe-James
GitHub
parent
5d91ce7c2e
commit
685e354b2f
4 changed files with 671 additions and 3 deletions
|
|
@ -125,6 +125,57 @@ This MCP server manages Azure DevOps work items and pipelines.
|
|||
<!-- mcp-name: io.github.username/azure-devops-mcp -->
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
|
|
|||
|
|
@ -659,10 +659,11 @@ components:
|
|||
properties:
|
||||
registryType:
|
||||
type: string
|
||||
description: Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb')
|
||||
description: Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'cargo', 'oci', 'nuget', 'mcpb')
|
||||
examples:
|
||||
- "npm"
|
||||
- "pypi"
|
||||
- "cargo"
|
||||
- "oci"
|
||||
- "nuget"
|
||||
- "mcpb"
|
||||
|
|
@ -673,6 +674,7 @@ components:
|
|||
examples:
|
||||
- "https://registry.npmjs.org"
|
||||
- "https://pypi.org"
|
||||
- "https://crates.io"
|
||||
- "https://docker.io"
|
||||
- "https://api.nuget.org/v3/index.json"
|
||||
- "https://github.com"
|
||||
|
|
|
|||
|
|
@ -239,6 +239,7 @@
|
|||
"examples": [
|
||||
"https://registry.npmjs.org",
|
||||
"https://pypi.org",
|
||||
"https://crates.io",
|
||||
"https://docker.io",
|
||||
"https://api.nuget.org/v3/index.json",
|
||||
"https://github.com",
|
||||
|
|
@ -248,10 +249,11 @@
|
|||
"type": "string"
|
||||
},
|
||||
"registryType": {
|
||||
"description": "Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'oci', 'nuget', 'mcpb')",
|
||||
"description": "Registry type indicating how to download packages (e.g., 'npm', 'pypi', 'cargo', 'oci', 'nuget', 'mcpb')",
|
||||
"examples": [
|
||||
"npm",
|
||||
"pypi",
|
||||
"cargo",
|
||||
"oci",
|
||||
"nuget",
|
||||
"mcpb"
|
||||
|
|
|
|||
|
|
@ -372,6 +372,35 @@ The same `registryType` / `identifier` pattern works for other supported OCI hos
|
|||
}
|
||||
```
|
||||
|
||||
### Cargo (Rust) Package Example
|
||||
|
||||
`cargo install <crate>` places the binary on PATH (via `~/.cargo/bin`); MCP clients invoke it directly by name. There is no single-shot equivalent of `npx` (npm), `uvx` (PyPI), or `dnx` (NuGet, .NET 10 SDK) for cargo — install once, run by name.
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
||||
"name": "io.github.example/widget-mcp",
|
||||
"description": "Rust-native MCP server",
|
||||
"title": "Widget",
|
||||
"repository": {
|
||||
"url": "https://github.com/example/widget-mcp",
|
||||
"source": "github"
|
||||
},
|
||||
"version": "0.3.0",
|
||||
"packages": [
|
||||
{
|
||||
"registryType": "cargo",
|
||||
"registryBaseUrl": "https://crates.io",
|
||||
"identifier": "widget-mcp",
|
||||
"version": "0.3.0",
|
||||
"transport": {
|
||||
"type": "stdio"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### NuGet (.NET) Package Example
|
||||
|
||||
The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
|
||||
|
|
|
|||
Loading…
Reference in a new issue