From 145c2ec7c424d503a553a50c0efac6c48db407db Mon Sep 17 00:00:00 2001 From: Wolfe-Jam Date: Sat, 25 Apr 2026 23:01:37 -0400 Subject: [PATCH 1/2] feat: add cargo (crates.io) as a package registry type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #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 commit adds the schema-side wiring for `registryType: cargo`: - `pkg/model/constants.go`: `RegistryTypeCargo` + `RegistryURLCrates` - `server.json` schema and `openapi.yaml`: `cargo` in the example enum for `registryType`; `https://crates.io` in `registryBaseUrl` - `generic-server-json.md`: new minimal Cargo example, with a runtime-model note. `cargo install` puts the binary on PATH at `~/.cargo/bin` and the MCP client invokes it by name. `npx` (npm), `uvx` (PyPI), and `dnx` (NuGet, .NET 10 SDK) were the cross-ecosystem precedents considered; cargo has no single-shot analog, so `runtimeHint` is omitted. - `tools/validate-examples/main.go`: `expectedServerJSONCount` bumped 16 → 17 to match the new example (caught by `make validate`). Validator and `publish-cargo.md` follow on this branch once the schema-side direction is settled. Refs #1055 --- docs/reference/api/openapi.yaml | 4 ++- .../server-json/draft/server.schema.json | 4 ++- .../server-json/generic-server-json.md | 29 +++++++++++++++++++ pkg/model/constants.go | 2 ++ tools/validate-examples/main.go | 2 +- 5 files changed, 38 insertions(+), 3 deletions(-) diff --git a/docs/reference/api/openapi.yaml b/docs/reference/api/openapi.yaml index faf88950f..25ec5ce1b 100644 --- a/docs/reference/api/openapi.yaml +++ b/docs/reference/api/openapi.yaml @@ -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" diff --git a/docs/reference/server-json/draft/server.schema.json b/docs/reference/server-json/draft/server.schema.json index 5c59335fc..0b9597a70 100644 --- a/docs/reference/server-json/draft/server.schema.json +++ b/docs/reference/server-json/draft/server.schema.json @@ -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" diff --git a/docs/reference/server-json/generic-server-json.md b/docs/reference/server-json/generic-server-json.md index bb5cc44c6..7415988ae 100644 --- a/docs/reference/server-json/generic-server-json.md +++ b/docs/reference/server-json/generic-server-json.md @@ -372,6 +372,35 @@ The same `registryType` / `identifier` pattern works for other supported OCI hos } ``` +### Cargo (Rust) Package Example + +`cargo install ` 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. diff --git a/pkg/model/constants.go b/pkg/model/constants.go index ead176d7f..98a3ba189 100644 --- a/pkg/model/constants.go +++ b/pkg/model/constants.go @@ -7,10 +7,12 @@ const ( RegistryTypeOCI = "oci" RegistryTypeNuGet = "nuget" RegistryTypeMCPB = "mcpb" + RegistryTypeCargo = "cargo" ) // Registry Base URLs - supported package registry base URLs const ( + RegistryURLCrates = "https://crates.io" RegistryURLGitHub = "https://github.com" RegistryURLGitLab = "https://gitlab.com" RegistryURLNPM = "https://registry.npmjs.org" diff --git a/tools/validate-examples/main.go b/tools/validate-examples/main.go index 2f8be56ff..4c48ae649 100644 --- a/tools/validate-examples/main.go +++ b/tools/validate-examples/main.go @@ -33,7 +33,7 @@ func main() { func runValidation() error { // Define what we validate and how - expectedServerJSONCount := 16 + expectedServerJSONCount := 17 targets := []validationTarget{ { path: filepath.Join("docs", "reference", "server-json", "generic-server-json.md"), From 6b2b006275f7bbff7fb0f502e54d2e6fb15cf7bb Mon Sep 17 00:00:00 2001 From: Wolfe-Jam Date: Sat, 25 Apr 2026 23:01:37 -0400 Subject: [PATCH 2/2] feat(validators): add cargo registry validator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #1055. Verification mirrors the PyPI validator: substring-match `mcp-name: ` against the package's rendered README. The publisher adds a single line to their README before publishing. Two-call retrieval pattern: 1. `GET /api/v1/crates/{name}/{version}/readme` returns 200 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. The two-call pattern stays on the documented public crates.io API 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. 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. Tests are integration-only (matching the npm/pypi pattern). 16 sub-cases across input validation, registry-baseURL rejection (four variants), ownership against real crates (serde, tokio, rand), and server-name format variations. The positive-path case is gated on `rust-faf-mcp` v0.2.3+ being published with `mcp-name: io.github.Wolfe-Jam/rust-faf-mcp` in its README — the commented-out test in `cargo_test.go` will uncomment to become the live anchor once that publish happens. Refs #1055 --- internal/validators/package.go | 2 + internal/validators/registries/cargo.go | 142 +++++++++++++++ internal/validators/registries/cargo_test.go | 177 +++++++++++++++++++ 3 files changed, 321 insertions(+) create mode 100644 internal/validators/registries/cargo.go create mode 100644 internal/validators/registries/cargo_test.go diff --git a/internal/validators/package.go b/internal/validators/package.go index 7104f730b..b458244b1 100644 --- a/internal/validators/package.go +++ b/internal/validators/package.go @@ -23,6 +23,8 @@ func ValidatePackage(ctx context.Context, pkg model.Package, serverName string) return registries.ValidateOCI(ctx, pkg, serverName) case model.RegistryTypeMCPB: return registries.ValidateMCPB(ctx, pkg, serverName) + case model.RegistryTypeCargo: + return registries.ValidateCargo(ctx, pkg, serverName) default: return fmt.Errorf("unsupported registry type: %s", pkg.RegistryType) } diff --git a/internal/validators/registries/cargo.go b/internal/validators/registries/cargo.go new file mode 100644 index 000000000..4342db9ce --- /dev/null +++ b/internal/validators/registries/cargo.go @@ -0,0 +1,142 @@ +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. +// +// 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 — +// rather than emitting a 302 redirect. 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: ` 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 +// → 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) + } + + 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 { + 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 (S3 default for missing keys), + // not 404. Treat any non-200 as "not found" — matches the shape of the npm/PyPI + // validators and surfaces the actual status code for debugging. + if readmeResp.StatusCode != http.StatusOK { + 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: 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) +} diff --git a/internal/validators/registries/cargo_test.go b/internal/validators/registries/cargo_test.go new file mode 100644 index 000000000..6bed586a6 --- /dev/null +++ b/internal/validators/registries/cargo_test.go @@ -0,0 +1,177 @@ +package registries_test + +import ( + "context" + "testing" + + "github.com/modelcontextprotocol/registry/internal/validators/registries" + "github.com/modelcontextprotocol/registry/pkg/model" + "github.com/stretchr/testify/assert" +) + +func TestValidateCargo_RealPackages(t *testing.T) { + ctx := context.Background() + + tests := []struct { + name string + packageName string + version string + serverName string + expectError bool + errorMessage string + }{ + { + name: "empty package identifier should fail", + packageName: "", + version: "0.1.0", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "package identifier is required for Cargo packages", + }, + { + name: "empty package version should fail", + packageName: "rust-faf-mcp", + version: "", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "package version is required for Cargo packages", + }, + { + name: "non-existent crate should fail", + packageName: generateRandomPackageName(), + version: "0.1.0", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "not found", + }, + { + name: "non-existent version of real crate should fail", + packageName: "serde", + version: "99.99.99-not-real", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "not found", + }, + { + name: "real crate without mcp-name token should fail", + packageName: "serde", // most-downloaded crate; no MCP server claim + version: "1.0.219", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "ownership validation failed", + }, + { + name: "real crate with mismatched mcp-name should fail", + packageName: "tokio", + version: "1.40.0", + serverName: "io.github.example/completely-different-name", + expectError: true, + errorMessage: "ownership validation failed", + }, + { + name: "additional real crate without mcp-name (rand)", + packageName: "rand", + version: "0.9.0", + serverName: "io.github.example/test", + expectError: true, + errorMessage: "ownership validation failed", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pkg := model.Package{ + RegistryType: model.RegistryTypeCargo, + Identifier: tt.packageName, + Version: tt.version, + } + + err := registries.ValidateCargo(ctx, pkg, tt.serverName) + + if tt.expectError { + assert.Error(t, err) + assert.Contains(t, err.Error(), tt.errorMessage) + } else { + assert.NoError(t, err) + } + }) + } +} + +func TestValidateCargo_RegistryBaseURLMismatch(t *testing.T) { + ctx := context.Background() + + tests := []struct { + name string + baseURL string + }{ + {name: "different host", baseURL: "https://example.com"}, + {name: "trailing slash", baseURL: "https://crates.io/"}, + {name: "http (not https)", baseURL: "http://crates.io"}, + {name: "subdomain", baseURL: "https://www.crates.io"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pkg := model.Package{ + RegistryType: model.RegistryTypeCargo, + RegistryBaseURL: tt.baseURL, + Identifier: "rust-faf-mcp", + Version: "0.2.2", + } + + err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp") + assert.Error(t, err) + assert.Contains(t, err.Error(), "registry type and base URL do not match") + }) + } +} + +func TestValidateCargo_RejectsMCPBOnlyFields(t *testing.T) { + ctx := context.Background() + + pkg := model.Package{ + RegistryType: model.RegistryTypeCargo, + Identifier: "rust-faf-mcp", + Version: "0.2.2", + FileSHA256: "0000000000000000000000000000000000000000000000000000000000000000", + } + + err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp") + assert.Error(t, err) + assert.Contains(t, err.Error(), "cargo packages must not have 'fileSha256' field") +} + +// Server names follow io.github.OWNER/REPO and may contain dots, slashes, +// hyphens, underscores, and digits. None of these get HTML-escaped during +// README rendering, so substring match against the rendered HTML is reliable. +// These tests exercise format variations against a real crate that doesn't +// declare any mcp-name (serde) — every case fails ownership, but we verify +// the failure error preserves the exact server name unchanged. +func TestValidateCargo_ServerNameFormats(t *testing.T) { + ctx := context.Background() + + tests := []struct { + name string + serverName string + }{ + {name: "canonical io.github format", serverName: "io.github.Wolfe-Jam/rust-faf-mcp"}, + {name: "multiple hyphens", serverName: "io.github.example/multi-hyphen-test-name"}, + {name: "underscore", serverName: "io.github.example/snake_case_name"}, + {name: "numeric suffix", serverName: "io.github.example/server-v2"}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pkg := model.Package{ + RegistryType: model.RegistryTypeCargo, + Identifier: "serde", + Version: "1.0.219", + } + + err := registries.ValidateCargo(ctx, pkg, tt.serverName) + assert.Error(t, err) + assert.Contains(t, err.Error(), tt.serverName) + }) + } +}