Skip to content

Commit 1f3be53

Browse files
committed
review: address PR feedback + add cargo registry-type docs + live test
Addresses @P4ST4S's PR #1207 review (all 3 items): - Positive-path test coverage (mildly blocking) — added two complementary tests in cargo_test.go: TestValidateCargo_PositivePathMock (hermetic, httptest.Server stand-in for crates.io) and TestValidateCargo_LivePositivePath (live anchor against rust-faf-mcp v0.3.1 on real crates.io). The HTTP pipeline is split into a package-private validateCargoREADME, exposed to tests via export_test.go without weakening the exact-baseURL guard in the public ValidateCargo. - 5xx as transient (defer-able, done anyway) — 403 from static.crates.io (S3 default for missing keys) stays 'not found'; 5xx now reports as 'likely transient, retry later' with the actual status code. Applied symmetrically to both the metadata endpoint and the README endpoint. - CargoReadmeMetaResponse doc comment (minor) — clarified that the 200+JSON shape requires Accept: application/json; without it, the endpoint emits a 302. Also lands docs/modelcontextprotocol-io/package-types.mdx 'Cargo (Rust) Packages' section, including: - Runtime-model resolution: cargo (source-distributed) and MCPB (prebuilt-binary) both documented as first-class paths for Rust MCP authors; the schema is additive and doesn't force a recommendation. - Cargo-specific 'gotcha' caveat in the Ownership Verification section: crates.io strips HTML comments during markdown→HTML rendering (unlike PyPI/NuGet which preserve them), so cargo authors MUST include the mcp-name token as visible markdown text — the <!-- ... --> hidden form documented elsewhere does not work for cargo. Caught live by shipping rust-faf-mcp v0.3.0 with the hidden form (validator rejected), then v0.3.1 with the visible form (validator accepts — see live test). Tests: 19/19 cargo tests pass (16 existing + 2 hermetic + 1 live anchor). make validate: clean. golangci-lint: 0 issues. Closes #1055 (once merged + the two queued real-world Rust MCP servers register: rust-faf-mcp v0.3.1 and perfetto-mcp-rs).
1 parent 6b2b006 commit 1f3be53

4 files changed

Lines changed: 187 additions & 7 deletions

File tree

‎docs/modelcontextprotocol-io/package-types.mdx‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,57 @@ This MCP server manages Azure DevOps work items and pipelines.
125125
<!-- mcp-name: io.github.username/azure-devops-mcp -->
126126
```
127127

128+
## Cargo (Rust) Packages
129+
130+
For Cargo packages, the MCP Registry currently supports the official crates.io registry (`https://crates.io`) only.
131+
132+
Cargo packages use `"registryType": "cargo"` in `server.json`. For example:
133+
134+
```json server.json highlight={9}
135+
{
136+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
137+
"name": "io.github.username/widget-mcp",
138+
"title": "Widget",
139+
"description": "Rust-native MCP server",
140+
"version": "0.3.0",
141+
"packages": [
142+
{
143+
"registryType": "cargo",
144+
"identifier": "widget-mcp",
145+
"version": "0.3.0",
146+
"transport": {
147+
"type": "stdio"
148+
}
149+
}
150+
]
151+
}
152+
```
153+
154+
### Runtime Model
155+
156+
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.
157+
158+
Rust MCP authors have two first-class distribution paths:
159+
160+
- **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.
161+
- **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."
162+
163+
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.
164+
165+
### Ownership Verification
166+
167+
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:
168+
169+
```markdown README.md highlight={5}
170+
# Widget MCP Server
171+
172+
A Rust-native MCP server for widget operations.
173+
174+
- MCP Registry name: `mcp-name: io.github.username/widget-mcp`
175+
```
176+
177+
**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.
178+
128179
## Docker/OCI Images
129180

130181
For Docker/OCI images, the MCP Registry currently supports:

‎internal/validators/registries/cargo.go‎

Lines changed: 25 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,12 @@ var (
2121

2222
// CargoReadmeMetaResponse is the structure returned by the crates.io readme metadata endpoint.
2323
//
24-
// crates.io's /api/v1/crates/{name}/{version}/readme endpoint returns 200 OK with a JSON
25-
// body containing a `url` field that points to the rendered README on the static CDN —
26-
// rather than emitting a 302 redirect. Validators must follow the pointer to retrieve
27-
// the actual README content.
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.
2830
type CargoReadmeMetaResponse struct {
2931
URL string `json:"url"`
3032
}
@@ -69,6 +71,14 @@ func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) er
6971
pkg.RegistryBaseURL, model.RegistryTypeCargo, model.RegistryURLCrates)
7072
}
7173

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 {
7282
client := &http.Client{Timeout: 10 * time.Second}
7383
// crates.io's crawler policy expects a non-generic User-Agent identifying the source.
7484
userAgent := "MCP-Registry-Validator/1.0 (https://registry.modelcontextprotocol.io)"
@@ -93,6 +103,10 @@ func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) er
93103
defer metaResp.Body.Close()
94104

95105
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+
}
96110
return fmt.Errorf("cargo package '%s' metadata fetch failed (status: %d)", pkg.Identifier, metaResp.StatusCode)
97111
}
98112

@@ -118,10 +132,14 @@ func ValidateCargo(ctx context.Context, pkg model.Package, serverName string) er
118132
}
119133
defer readmeResp.Body.Close()
120134

121-
// Missing crates and missing versions surface as 403 (S3 default for missing keys),
122-
// not 404. Treat any non-200 as "not found" — matches the shape of the npm/PyPI
123-
// validators and surfaces the actual status code for debugging.
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.
124139
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+
}
125143
return fmt.Errorf("cargo package '%s' version '%s' not found on crates.io (status: %d)", pkg.Identifier, pkg.Version, readmeResp.StatusCode)
126144
}
127145

‎internal/validators/registries/cargo_test.go‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@ package registries_test
22

33
import (
44
"context"
5+
"encoding/json"
6+
"fmt"
7+
"net/http"
8+
"net/http/httptest"
9+
"strings"
510
"testing"
611

712
"github.com/modelcontextprotocol/registry/internal/validators/registries"
@@ -175,3 +180,100 @@ func TestValidateCargo_ServerNameFormats(t *testing.T) {
175180
})
176181
}
177182
}
183+
184+
// TestValidateCargo_PositivePathMock exercises the success branch: a README
185+
// that contains the exact mcp-name token must return no error. Uses httptest
186+
// to stand in for crates.io, so the test is hermetic — it doesn't depend on
187+
// any live crate publishing a specific mcp-name line or on network reachability.
188+
// Calls the test-only ValidateCargoREADME shim so the mock URL can take the
189+
// place of https://crates.io without tripping the exact-baseURL guard.
190+
func TestValidateCargo_PositivePathMock(t *testing.T) {
191+
ctx := context.Background()
192+
const serverName = "io.github.test/positive-path"
193+
194+
var mock *httptest.Server
195+
mock = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
196+
if strings.HasSuffix(r.URL.Path, "/readme") {
197+
w.Header().Set("Content-Type", "application/json")
198+
if err := json.NewEncoder(w).Encode(map[string]string{
199+
"url": mock.URL + "/static-readme",
200+
}); err != nil {
201+
t.Fatalf("encode meta response: %v", err)
202+
}
203+
return
204+
}
205+
// Rendered README HTML containing the mcp-name token.
206+
fmt.Fprintf(w, "<html><body><p>some content</p><p>mcp-name: %s</p></body></html>", serverName)
207+
}))
208+
defer mock.Close()
209+
210+
pkg := model.Package{
211+
RegistryType: model.RegistryTypeCargo,
212+
RegistryBaseURL: mock.URL,
213+
Identifier: "test-crate",
214+
Version: "0.1.0",
215+
}
216+
217+
err := registries.ValidateCargoREADME(ctx, pkg, serverName)
218+
assert.NoError(t, err, "validator should accept a README containing the exact mcp-name token")
219+
}
220+
221+
// TestValidateCargo_LivePositivePath is the live anchor — it validates against
222+
// rust-faf-mcp v0.3.1 on real crates.io, the first crate published with the
223+
// mcp-name token as visible markdown (v0.3.0 used a hidden HTML comment, which
224+
// crates.io strips during README rendering — see package-types.mdx for the
225+
// cargo-specific gotcha). Complements TestValidateCargo_PositivePathMock:
226+
// the mock proves the validator works in principle (hermetic, fast); the live
227+
// anchor proves it works against the real crates.io API + static CDN pipeline.
228+
//
229+
// If this test ever starts failing, check (in order):
230+
// 1. Has rust-faf-mcp v0.3.1 been yanked or replaced?
231+
// 2. Did crates.io change its README rendering pipeline (e.g., start
232+
// stripping markdown lines that look like email-like tokens)?
233+
// 3. Is the test machine network-blocked from crates.io or static.crates.io?
234+
func TestValidateCargo_LivePositivePath(t *testing.T) {
235+
ctx := context.Background()
236+
237+
pkg := model.Package{
238+
RegistryType: model.RegistryTypeCargo,
239+
Identifier: "rust-faf-mcp",
240+
Version: "0.3.1",
241+
}
242+
243+
err := registries.ValidateCargo(ctx, pkg, "io.github.Wolfe-Jam/rust-faf-mcp")
244+
assert.NoError(t, err, "validator should accept the live rust-faf-mcp v0.3.1 crate (the canonical live anchor for cargo positive-path)")
245+
}
246+
247+
// TestValidateCargo_TransientUpstreamError exercises the 5xx-as-transient branch:
248+
// a 502/503 from static.crates.io is upstream availability, not "crate missing",
249+
// and the error message must signal a retryable failure rather than imply the
250+
// crate doesn't exist (the previous behavior, flagged in PR #1207 review).
251+
func TestValidateCargo_TransientUpstreamError(t *testing.T) {
252+
ctx := context.Background()
253+
254+
var mock *httptest.Server
255+
mock = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
256+
if strings.HasSuffix(r.URL.Path, "/readme") {
257+
w.Header().Set("Content-Type", "application/json")
258+
_ = json.NewEncoder(w).Encode(map[string]string{
259+
"url": mock.URL + "/static-readme",
260+
})
261+
return
262+
}
263+
// Simulate static.crates.io 502 — upstream blip, not a missing crate.
264+
http.Error(w, "bad gateway", http.StatusBadGateway)
265+
}))
266+
defer mock.Close()
267+
268+
pkg := model.Package{
269+
RegistryType: model.RegistryTypeCargo,
270+
RegistryBaseURL: mock.URL,
271+
Identifier: "test-crate",
272+
Version: "0.1.0",
273+
}
274+
275+
err := registries.ValidateCargoREADME(ctx, pkg, "io.github.test/transient")
276+
assert.Error(t, err)
277+
assert.Contains(t, err.Error(), "transient")
278+
assert.NotContains(t, err.Error(), "not found", "transient upstream errors should not be reported as 'not found'")
279+
}
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
package registries
2+
3+
// ValidateCargoREADME exposes the package-private validateCargoREADME to the
4+
// external _test package so httptest-driven tests can exercise the README-fetch
5+
// and mcp-name token-match pipeline against a mock server, bypassing the
6+
// exact-baseURL guard that the public ValidateCargo enforces.
7+
//
8+
// Intended for cargo_test.go's positive-path and transient-error tests only.
9+
var ValidateCargoREADME = validateCargoREADME

0 commit comments

Comments
 (0)