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/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) + }) + } +} 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"),