Make the extension card-only: remove registry Server/package types#28
Make the extension card-only: remove registry Server/package types#28dsp-ant wants to merge 2 commits into
Conversation
tadasant
left a comment
tadasant
left a comment
There was a problem hiding this comment.
Seems reasonable to remove consideration for server.json in this extension schema and leaving that a Registry concern 👍 Will plan to port this work over there as we land this.
| ``` | ||
|
|
||
| Schema URLs are versioned by their `vN` segment rather than by date, so additive revisions of the v1 shape don't bump every published document's `$schema`. Breaking changes would publish a `v2` family. | ||
| Schema URLs are versioned by their `vN` segment rather than by date. `v2` schemas are closed (`additionalProperties: false`): a document using a field the schema doesn't declare is rejected, so any revision of the shape — additive or not — publishes a new `vN` family. Vendor-specific data belongs in namespaced `_meta`, which stays open. The `v1` family included the registry-shaped `Server` / `packages` types; they were removed in `v2` when the extension became card-only. |
There was a problem hiding this comment.
Are you sure about making additionalProperties: false here? I don't believe we have precedent for making objects in MCP closed-ended like this; is this intentionally the first?
| "description": "A command-line argument supplied to a package's binary or runtime." | ||
| }, | ||
| "Icon": { | ||
| "additionalProperties": false, |
There was a problem hiding this comment.
Doing additionalProperties: false at every layer here would be inconsistent with the current spec for fields like Icon
There was a problem hiding this comment.
Additionally Icon supports dark/light mode duplication, and has a bunch of caveats, as an example, the spec allows SVG, but specifically warns clients of possible security risks so most don't actually allow it. It also allows both inline and URL references, but URLs are subject to same-origin policy.
I don't know we want all that baggage but just flagging it up, so we consciously decide what we allow here.
There was a problem hiding this comment.
Looks like it carries the same as the official spec, which is probably fine, but could target a subset to avoid complexity.
| }, | ||
| "name": { | ||
| "description": "Name of the header or environment variable.", | ||
| "description": "Name of the header.", |
There was a problem hiding this comment.
| "description": "Name of the header.", | |
| "description": "Name of the input.", |
I think we should genericize wording here so it still makes sense for server.json definitions downstream.
Server Cards describe remote connectivity only. The Server type and the package-installation machinery (Package, PackageTransport, StdioTransport, StreamableHttpPackageTransport, SsePackageTransport, Argument helpers) were carried over from the abandoned core-spec PR when this repo was bootstrapped; locally-installable package metadata is owned by the MCP Registry's server.json schema, not by this extension. The schema is still pre-release, so the v1 family is edited in place rather than minting a v2. - schema.ts: drop Server and all package types; keep ServerCard, Remote, Repository, Icon, MetaObject, and the Input/KeyValueInput helpers that remotes still use for URL templating and headers - generate with --noExtraProps so a document containing packages (or any unknown property) is rejected; _meta stays open as the extension point - pin the $schema pattern to the single server-card.schema.json name - remove Server examples; add invalid examples asserting that a card with packages and a card naming the removed server.schema.json both fail validation - README: replace the companion-Server framing with a 'Relationship to the MCP Registry' section
dsp-ant
force-pushed
the
card-only-schema
branch
from
056d9f2 to
fd7940f
Compare
dsp-ant
changed the title
| "description": "A command-line argument supplied to a package's binary or runtime." | ||
| }, | ||
| "Icon": { | ||
| "additionalProperties": false, |
There was a problem hiding this comment.
Additionally Icon supports dark/light mode duplication, and has a bunch of caveats, as an example, the spec allows SVG, but specifically warns clients of possible security risks so most don't actually allow it. It also allows both inline and URL references, but URLs are subject to same-origin policy.
I don't know we want all that baggage but just flagging it up, so we consciously decide what we allow here.
3 participants
What this does
Makes this extension card-only and remote-only: removes the registry-shaped
Servertype and all package-installation types, so the only document shape this repo defines isServerCard(identity,remotes,icons,repository,websiteUrl,_meta).Why
The SEP-2127 review consensus was that a Server Card should describe remote (HTTP) connectivity only, with minimal information. The
Serversuperset and the package-install machinery (Package,PackageTransport,StdioTransport,StreamableHttpPackageTransport,SsePackageTransport,registryType,runtimeHint, runtime/package arguments,fileSha256, …) were carried over from the abandoned core-spec PR (modelcontextprotocol/modelcontextprotocol#2652) when this repo was bootstrapped in #1 — they were never kept by a deliberate decision. That shape is the MCP Registry'sserver.json, which is owned by the registry, not by this extension.The schema is still pre-release, so this edits the
v1family in place rather than minting av2.What changed
Server,Package, the three package transports, and theArgument/PositionalArgument/NamedArgumenthelpers that only package types referenced. KeptServerCard,Remote,Repository,Icon,MetaObject, and theInput/KeyValueInputhelpers that remotes still need for URL templating and headers. FoldedInputWithVariablesintoKeyValueInput, its only remaining subtype.--noExtraProps, so Server Card objects are closed (additionalProperties: false) and a document containingpackages(or any unknown field) is rejected._metastays open as the extension point —MetaObjectuses an interface-with-index-signature form, with a comment explaining why that form is load-bearing under the flag.$schemapattern: pinned toserver-card.schema.json(the generic[^/]+wildcard only existed to admit the now-removedserver.schema.json). The URL family staysv1.examples/Server/; added invalid exampleswith-packages.json(a card withpackagesmust fail validation) andwrong-schema-name.json(the removedserver.schema.jsonURL must fail).validate-examples.tsnow only knows aboutServerCardand fails (instead of exiting green) if no examples are found.Serverframing with a "Relationship to the MCP Registry" section — package metadata lives in the registry'sserver.jsonschema; a registry entry MAY reference or embed a card's remote info; vendors needing install hints can use namespaced_meta. The schema-URL and graduation-plan sections note that the closed-object behavior comes from the generator flag and must be carried over on graduation, since the main spec's generator doesn't pass--noExtraProps.The Catalog spec in
docs/discovery.mdonly references Server Cards, so it needed no changes (and this PR deliberately doesn't touch the open question in #26 about the Catalog itself).Schema-contract changes (called out per the contribution guidelines)
The
v1schema is pre-release, so these are in-place changes to an unpublished shape rather than a versioned break:Serverdefinition and all package types are gone fromschema.json.additionalProperties: false), not justpackages. Extension data belongs in_meta, which stays open.How this was verified
npm run check— regeneratingschema.jsonfromschema.tsproduces no diff, andtscpasses.npm run validate— all 8 examples pass: 2 valid remote-only cards validate cleanly; 6 invalid ones (including thepackagescard and the staleserver.schema.jsonURL) are rejected.npm run format:checkpasses.packages,npm,pypi,oci,nuget,mcpb,stdio,uvx,docker,runtimeHint) returns only the intentional mentions in the registry-relationship section and the invalid example that exists to be rejected.