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>

internal/validators/registries/cargo.go

@@ -0,0 +1,160 @@
+package registries
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/modelcontextprotocol/registry/pkg/model"
+)
+
+var (
+	ErrMissingIdentifierForCargo = errors.New("package identifier is required for Cargo packages")
+	ErrMissingVersionForCargo    = errors.New("package version is required for Cargo packages")
+)
+
+// CargoReadmeMetaResponse is the structure returned by the crates.io readme metadata endpoint.
+//
+// With `Accept: application/json`, crates.io's /api/v1/crates/{name}/{version}/readme
+// endpoint returns 200 OK with a JSON body containing a `url` field that points to the
+// rendered README on the static CDN. (Without the Accept header, or via HEAD, the same
+// endpoint emits a 302 redirect to the CDN URL — the validator uses the JSON path so
+// that crates.io controls where the README lives.) Validators must follow the pointer
+// to retrieve the actual README content.
+type CargoReadmeMetaResponse struct {
+	URL string `json:"url"`
+}
+
+// ValidateCargo validates that a Cargo (crates.io) package contains the correct MCP server name.
+//
+// Verification mechanism: the `mcp-name: <server-name>` token is searched for in the package's
+// rendered README. This mirrors the PyPI validator's README-token approach (see ValidatePyPI),
+// requiring no Cargo.toml parsing on the registry side. Crate authors add a single line
+// `mcp-name: io.github.OWNER/REPO` to their README before publishing.
+//
+// Two-call retrieval pattern:
+//  1. GET https://crates.io/api/v1/crates/{name}/{version}/readme
+//     → 200 OK with JSON: {"url": "https://static.crates.io/readmes/.../...html"}
+//  2. GET <url from step 1>
+//     → 200 OK with rendered README HTML, or 403 if the crate/version is missing
+//
+// The two-call pattern stays on the documented crates.io API surface rather than relying
+// on the CDN URL layout being stable.
+func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) error {
+	// Set default registry base URL if empty
+	if pkg.RegistryBaseURL == "" {
+		pkg.RegistryBaseURL = model.RegistryURLCrates
+	}
+
+	if pkg.Identifier == "" {
+		return ErrMissingIdentifierForCargo
+	}
+
+	if pkg.Version == "" {
+		return ErrMissingVersionForCargo
+	}
+
+	// Validate that MCPB-specific fields are not present
+	if pkg.FileSHA256 != "" {
+		return fmt.Errorf("cargo packages must not have 'fileSha256' field - this is only for MCPB packages")
+	}
+
+	// Validate that the registry base URL matches crates.io exactly
+	if pkg.RegistryBaseURL != model.RegistryURLCrates {
+		return fmt.Errorf("registry type and base URL do not match: '%s' is not valid for registry type '%s'. Expected: %s",
+			pkg.RegistryBaseURL, model.RegistryTypeCargo, model.RegistryURLCrates)
+	}
+
+	return validateCargoREADME(ctx, pkg, serverName)
+}
+
+// validateCargoREADME performs the two-call README fetch and the mcp-name token
+// check. It is split out from ValidateCargo so that httptest-based tests can
+// drive the HTTP pipeline against a mock server (exposed via export_test.go),
+// bypassing the exact-baseURL guard that ValidateCargo enforces for callers.
+func validateCargoREADME(ctx context.Context, pkg model.Package, serverName string) error {
+	client := &http.Client{Timeout: 10 * time.Second}
+	// crates.io's crawler policy expects a non-generic User-Agent identifying the source.
+	userAgent := "MCP-Registry-Validator/1.0 (https://registry.modelcontextprotocol.io)"
+
+	// Step 1: fetch the README pointer from the documented API endpoint.
+	metaURL := fmt.Sprintf("%s/api/v1/crates/%s/%s/readme",
+		pkg.RegistryBaseURL,
+		url.PathEscape(pkg.Identifier),
+		url.PathEscape(pkg.Version))
+
+	metaReq, err := http.NewRequestWithContext(ctx, http.MethodGet, metaURL, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create crates.io metadata request: %w", err)
+	}
+	metaReq.Header.Set("User-Agent", userAgent)
+	metaReq.Header.Set("Accept", "application/json")
+
+	metaResp, err := client.Do(metaReq)
+	if err != nil {
+		return fmt.Errorf("failed to fetch package metadata from crates.io: %w", err)
+	}
+	defer metaResp.Body.Close()
+
+	if metaResp.StatusCode != http.StatusOK {
+		// 5xx from the metadata endpoint is upstream availability, not a missing crate.
+		if metaResp.StatusCode >= 500 && metaResp.StatusCode < 600 {
+			return fmt.Errorf("crates.io upstream error fetching metadata for cargo package '%s' (status: %d) — likely transient, retry later", pkg.Identifier, metaResp.StatusCode)
+		}
+		return fmt.Errorf("cargo package '%s' metadata fetch failed (status: %d)", pkg.Identifier, metaResp.StatusCode)
+	}
+
+	var meta CargoReadmeMetaResponse
+	if err := json.NewDecoder(metaResp.Body).Decode(&meta); err != nil {
+		return fmt.Errorf("failed to parse crates.io readme metadata: %w", err)
+	}
+	if meta.URL == "" {
+		return fmt.Errorf("cargo package '%s' metadata response missing 'url' field", pkg.Identifier)
+	}
+
+	// Step 2: fetch the rendered README from the URL the API gave us.
+	readmeReq, err := http.NewRequestWithContext(ctx, http.MethodGet, meta.URL, nil)
+	if err != nil {
+		return fmt.Errorf("failed to create crates.io readme request: %w", err)
+	}
+	readmeReq.Header.Set("User-Agent", userAgent)
+	readmeReq.Header.Set("Accept", "text/html")
+
+	readmeResp, err := client.Do(readmeReq)
+	if err != nil {
+		return fmt.Errorf("failed to fetch rendered README from crates.io: %w", err)
+	}
+	defer readmeResp.Body.Close()
+
+	// Missing crates and missing versions surface as 403 from static.crates.io
+	// (S3's default for missing keys), not 404. 5xx from the CDN is upstream
+	// availability — surface it as transient so callers can distinguish retryable
+	// failures from genuinely missing crates.
+	if readmeResp.StatusCode != http.StatusOK {
+		if readmeResp.StatusCode >= 500 && readmeResp.StatusCode < 600 {
+			return fmt.Errorf("crates.io upstream error fetching README for cargo package '%s' version '%s' (status: %d) — likely transient, retry later", pkg.Identifier, pkg.Version, readmeResp.StatusCode)
+		}
+		return fmt.Errorf("cargo package '%s' version '%s' not found on crates.io (status: %d)", pkg.Identifier, pkg.Version, readmeResp.StatusCode)
+	}
+
+	body, err := io.ReadAll(readmeResp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read rendered README: %w", err)
+	}
+
+	// Search for the mcp-name: <server-name> token. The token contains no characters
+	// that get HTML-escaped during README rendering (no <, >, &, ", '), so a direct
+	// substring match against the rendered HTML is reliable.
+	mcpNamePattern := "mcp-name: " + serverName
+	if strings.Contains(string(body), mcpNamePattern) {
+		return nil
+	}
+
+	return fmt.Errorf("cargo package '%s' ownership validation failed. The server name '%s' must appear as 'mcp-name: %s' in the package README", pkg.Identifier, serverName, serverName)
+}