|
| 1 | +package registries |
| 2 | + |
| 3 | +import ( |
| 4 | + "context" |
| 5 | + "encoding/json" |
| 6 | + "errors" |
| 7 | + "fmt" |
| 8 | + "io" |
| 9 | + "net/http" |
| 10 | + "net/url" |
| 11 | + "strings" |
| 12 | + "time" |
| 13 | + |
| 14 | + "github.com/modelcontextprotocol/registry/pkg/model" |
| 15 | +) |
| 16 | + |
| 17 | +var ( |
| 18 | + ErrMissingIdentifierForCargo = errors.New("package identifier is required for Cargo packages") |
| 19 | + ErrMissingVersionForCargo = errors.New("package version is required for Cargo packages") |
| 20 | +) |
| 21 | + |
| 22 | +// CargoReadmeMetaResponse is the structure returned by the crates.io readme metadata endpoint. |
| 23 | +// |
| 24 | +// With `Accept: application/json`, crates.io's /api/v1/crates/{name}/{version}/readme |
| 25 | +// endpoint returns 200 OK with a JSON body containing a `url` field that points to the |
| 26 | +// rendered README on the static CDN. (Without the Accept header, or via HEAD, the same |
| 27 | +// endpoint emits a 302 redirect to the CDN URL — the validator uses the JSON path so |
| 28 | +// that crates.io controls where the README lives.) Validators must follow the pointer |
| 29 | +// to retrieve the actual README content. |
| 30 | +type CargoReadmeMetaResponse struct { |
| 31 | + URL string `json:"url"` |
| 32 | +} |
| 33 | + |
| 34 | +// ValidateCargo validates that a Cargo (crates.io) package contains the correct MCP server name. |
| 35 | +// |
| 36 | +// Verification mechanism: the `mcp-name: <server-name>` token is searched for in the package's |
| 37 | +// rendered README. This mirrors the PyPI validator's README-token approach (see ValidatePyPI), |
| 38 | +// requiring no Cargo.toml parsing on the registry side. Crate authors add a single line |
| 39 | +// `mcp-name: io.github.OWNER/REPO` to their README before publishing. |
| 40 | +// |
| 41 | +// Two-call retrieval pattern: |
| 42 | +// 1. GET https://crates.io/api/v1/crates/{name}/{version}/readme |
| 43 | +// → 200 OK with JSON: {"url": "https://static.crates.io/readmes/.../...html"} |
| 44 | +// 2. GET <url from step 1> |
| 45 | +// → 200 OK with rendered README HTML, or 403 if the crate/version is missing |
| 46 | +// |
| 47 | +// The two-call pattern stays on the documented crates.io API surface rather than relying |
| 48 | +// on the CDN URL layout being stable. |
| 49 | +func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) error { |
| 50 | + // Set default registry base URL if empty |
| 51 | + if pkg.RegistryBaseURL == "" { |
| 52 | + pkg.RegistryBaseURL = model.RegistryURLCrates |
| 53 | + } |
| 54 | + |
| 55 | + if pkg.Identifier == "" { |
| 56 | + return ErrMissingIdentifierForCargo |
| 57 | + } |
| 58 | + |
| 59 | + if pkg.Version == "" { |
| 60 | + return ErrMissingVersionForCargo |
| 61 | + } |
| 62 | + |
| 63 | + // Validate that MCPB-specific fields are not present |
| 64 | + if pkg.FileSHA256 != "" { |
| 65 | + return fmt.Errorf("cargo packages must not have 'fileSha256' field - this is only for MCPB packages") |
| 66 | + } |
| 67 | + |
| 68 | + // Validate that the registry base URL matches crates.io exactly |
| 69 | + if pkg.RegistryBaseURL != model.RegistryURLCrates { |
| 70 | + return fmt.Errorf("registry type and base URL do not match: '%s' is not valid for registry type '%s'. Expected: %s", |
| 71 | + pkg.RegistryBaseURL, model.RegistryTypeCargo, model.RegistryURLCrates) |
| 72 | + } |
| 73 | + |
| 74 | + return validateCargoREADME(ctx, pkg, serverName) |
| 75 | +} |
| 76 | + |
| 77 | +// validateCargoREADME performs the two-call README fetch and the mcp-name token |
| 78 | +// check. It is split out from ValidateCargo so that httptest-based tests can |
| 79 | +// drive the HTTP pipeline against a mock server (exposed via export_test.go), |
| 80 | +// bypassing the exact-baseURL guard that ValidateCargo enforces for callers. |
| 81 | +func validateCargoREADME(ctx context.Context, pkg model.Package, serverName string) error { |
| 82 | + client := &http.Client{Timeout: 10 * time.Second} |
| 83 | + // crates.io's crawler policy expects a non-generic User-Agent identifying the source. |
| 84 | + userAgent := "MCP-Registry-Validator/1.0 (https://registry.modelcontextprotocol.io)" |
| 85 | + |
| 86 | + // Step 1: fetch the README pointer from the documented API endpoint. |
| 87 | + metaURL := fmt.Sprintf("%s/api/v1/crates/%s/%s/readme", |
| 88 | + pkg.RegistryBaseURL, |
| 89 | + url.PathEscape(pkg.Identifier), |
| 90 | + url.PathEscape(pkg.Version)) |
| 91 | + |
| 92 | + metaReq, err := http.NewRequestWithContext(ctx, http.MethodGet, metaURL, nil) |
| 93 | + if err != nil { |
| 94 | + return fmt.Errorf("failed to create crates.io metadata request: %w", err) |
| 95 | + } |
| 96 | + metaReq.Header.Set("User-Agent", userAgent) |
| 97 | + metaReq.Header.Set("Accept", "application/json") |
| 98 | + |
| 99 | + metaResp, err := client.Do(metaReq) |
| 100 | + if err != nil { |
| 101 | + return fmt.Errorf("failed to fetch package metadata from crates.io: %w", err) |
| 102 | + } |
| 103 | + defer metaResp.Body.Close() |
| 104 | + |
| 105 | + if metaResp.StatusCode != http.StatusOK { |
| 106 | + // 5xx from the metadata endpoint is upstream availability, not a missing crate. |
| 107 | + if metaResp.StatusCode >= 500 && metaResp.StatusCode < 600 { |
| 108 | + return fmt.Errorf("crates.io upstream error fetching metadata for cargo package '%s' (status: %d) — likely transient, retry later", pkg.Identifier, metaResp.StatusCode) |
| 109 | + } |
| 110 | + return fmt.Errorf("cargo package '%s' metadata fetch failed (status: %d)", pkg.Identifier, metaResp.StatusCode) |
| 111 | + } |
| 112 | + |
| 113 | + var meta CargoReadmeMetaResponse |
| 114 | + if err := json.NewDecoder(metaResp.Body).Decode(&meta); err != nil { |
| 115 | + return fmt.Errorf("failed to parse crates.io readme metadata: %w", err) |
| 116 | + } |
| 117 | + if meta.URL == "" { |
| 118 | + return fmt.Errorf("cargo package '%s' metadata response missing 'url' field", pkg.Identifier) |
| 119 | + } |
| 120 | + |
| 121 | + // Step 2: fetch the rendered README from the URL the API gave us. |
| 122 | + readmeReq, err := http.NewRequestWithContext(ctx, http.MethodGet, meta.URL, nil) |
| 123 | + if err != nil { |
| 124 | + return fmt.Errorf("failed to create crates.io readme request: %w", err) |
| 125 | + } |
| 126 | + readmeReq.Header.Set("User-Agent", userAgent) |
| 127 | + readmeReq.Header.Set("Accept", "text/html") |
| 128 | + |
| 129 | + readmeResp, err := client.Do(readmeReq) |
| 130 | + if err != nil { |
| 131 | + return fmt.Errorf("failed to fetch rendered README from crates.io: %w", err) |
| 132 | + } |
| 133 | + defer readmeResp.Body.Close() |
| 134 | + |
| 135 | + // Missing crates and missing versions surface as 403 from static.crates.io |
| 136 | + // (S3's default for missing keys), not 404. 5xx from the CDN is upstream |
| 137 | + // availability — surface it as transient so callers can distinguish retryable |
| 138 | + // failures from genuinely missing crates. |
| 139 | + if readmeResp.StatusCode != http.StatusOK { |
| 140 | + if readmeResp.StatusCode >= 500 && readmeResp.StatusCode < 600 { |
| 141 | + 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) |
| 142 | + } |
| 143 | + return fmt.Errorf("cargo package '%s' version '%s' not found on crates.io (status: %d)", pkg.Identifier, pkg.Version, readmeResp.StatusCode) |
| 144 | + } |
| 145 | + |
| 146 | + body, err := io.ReadAll(readmeResp.Body) |
| 147 | + if err != nil { |
| 148 | + return fmt.Errorf("failed to read rendered README: %w", err) |
| 149 | + } |
| 150 | + |
| 151 | + // Search for the mcp-name: <server-name> token. The token contains no characters |
| 152 | + // that get HTML-escaped during README rendering (no <, >, &, ", '), so a direct |
| 153 | + // substring match against the rendered HTML is reliable. |
| 154 | + mcpNamePattern := "mcp-name: " + serverName |
| 155 | + if strings.Contains(string(body), mcpNamePattern) { |
| 156 | + return nil |
| 157 | + } |
| 158 | + |
| 159 | + 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) |
| 160 | +} |
0 commit comments