Skip to content

Make the extension card-only: remove registry Server/package types (v2)#28

Open
dsp-ant wants to merge 1 commit into
mainfrom
card-only-schema
Open

Make the extension card-only: remove registry Server/package types (v2)#28
dsp-ant wants to merge 1 commit into
mainfrom
card-only-schema

Conversation

@dsp-ant

@dsp-ant dsp-ant commented Jun 11, 2026

Copy link
Copy Markdown
Member

What this does

Makes this extension card-only and remote-only: removes the registry-shaped Server type and all package-installation types, so the only document shape this repo defines is ServerCard (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 Server superset 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's server.json, which is owned by the registry, not by this extension.

What changed

  • schema.ts: removed Server, Package, the three package transports, and the Argument/PositionalArgument/NamedArgument helpers that only package types referenced. Kept ServerCard, Remote, Repository, Icon, MetaObject, and the Input/KeyValueInput helpers that remotes still need for URL templating and headers. Folded InputWithVariables into KeyValueInput, its only remaining subtype.
  • Strictness: the generator now passes --noExtraProps, so Server Card objects are closed (additionalProperties: false) and a document containing packages (or any unknown field) is rejected. _meta stays open as the extension point — MetaObject uses an interface-with-index-signature form, with a comment explaining why that form is load-bearing under the flag.
  • Versioning: this is a breaking change for schema consumers, so the $schema URL family bumps from /v1/ to /v2/ per the README's convention. The $schema pattern is also pinned to server-card.schema.json (the generic [^/]+ wildcard only existed to admit server.schema.json).
  • Examples/tests: removed examples/Server/; added invalid examples with-packages.json (a card with packages must fail validation) and wrong-schema-name.json (the removed server.schema.json URL must fail). validate-examples.ts now only knows about ServerCard and fails (instead of exiting green) if no examples are found.
  • README: replaced the companion-Server framing with a "Relationship to the MCP Registry" section — package metadata lives in the registry's server.json schema; 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.md only references Server Cards, so it needed no changes (and this PR deliberately doesn't touch the open question in #26 about the Catalog itself).

Breaking changes (called out per the contribution guidelines)

  • The Server definition and all package types are gone from schema.json.
  • v2 schemas reject unknown properties everywhere, not just packages — a v1 card with any undeclared field is invalid under v2. Any revision of the shape now publishes a new vN family; extension data belongs in _meta.

How this was verified

  • npm run check — regenerating schema.json from schema.ts produces no diff, and tsc passes.
  • npm run validate — all 8 examples pass: 2 valid remote-only cards validate cleanly; 6 invalid ones (including the packages card and the stale server.schema.json URL) are rejected.
  • npm run format:check passes.
  • A repo-wide grep for package/registry terms (packages, npm, pypi, oci, nuget, mcpb, stdio, uvx, docker, runtimeHint) returns only the intentional mentions in the registry-relationship section, the versioning history note, and the invalid example that exists to be rejected.

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.

- 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
- bump the schema URL family from /v1/ to /v2/ (breaking change)
- remove Server examples; add an invalid example asserting that a card with
  packages fails validation
- README: replace the companion-Server framing with a 'Relationship to the
  MCP Registry' section
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant