docs: add server.json as a first-class catalog type (application/mcp-server+json)#54
Draft
tadasant wants to merge 10 commits into
Draft
docs: add server.json as a first-class catalog type (application/mcp-server+json)#54tadasant wants to merge 10 commits into
tadasant wants to merge 10 commits into
Conversation
…rver+json) Register application/mcp-server+json as a known type for the MCP Registry server.json document (distinct from the Server Card's application/mcp-server-card+json), and add a 'Mapping to MCP Registry server.json' appendix describing the first-class mapping. Stacked on docs/update-server-json-mapping. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
|
Preview: https://ai-catalog.io/pr/54/ This comment is updated automatically while the pull request preview is available. |
…example Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…mples
Replace placeholder registry URLs (.../servers/{name}/server.json) with the
real MCP Registry API form .../v0/servers/{url-encoded-name}/versions/{version},
and use verified-real server names/versions (com.pulsemcp/remote-filesystem,
com.pulsemcp.servers/pulse-fetch). Reconcile the urn:air identifiers with the
reverse-DNS registry names per ADR 0015.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…literation Add an ADR 0015 link and note that publisher/namespace in the urn:air form are the publisher domain and a chosen category, not a transliteration of the registry name's reverse-DNS segments (so .servers does not appear in the URN). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… first-class branch
On the stacked branch the server.json appendix exists, so the Server Card scope note links to it rather than disclaiming coverage. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…ialize-handshake reference
…atic' consistency
… framing Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #53
This PR is stacked on top of #53 (
docs/update-server-json-mapping). Its base branch isdocs/update-server-json-mapping, notmain— review/merge #53 first. The diff against its base is just theserver.json-as-first-class change below.What this does
Reintroduces the MCP Registry
server.jsonmapping that #53 removed, but as a first-class cataloged artifact type rather than an experimental footnote.Key changes
New known media type
application/mcp-server+jsonfor an MCP Registryserver.jsondocument, registered in both the spec's known-types list and ADR 0014 (under "Integrated Ecosystem & Third-Party Types").New appendix
Mapping to MCP Registry server.jsondescribing the first-class mapping: a Catalog Entry whoseurlpoints to theserver.jsondocument withtypeapplication/mcp-server+json. Includes a conceptual mapping table, an entry example, an "MCP Registry as AI Catalog" example, and a "Relationship to MCP Server Cards" section.Two-types framing. The appendix is explicit that the MCP ecosystem has two distinct server artifacts, each with its own
type:application/mcp-server-card+json(runtime discovery / connection details)server.json→application/mcp-server+json(installable package descriptor)A catalog entry references whichever fits; a domain MAY list both.
Examples use real MCP Registry URLs. Every
server.jsonexampleurluses the actual registry API formhttps://registry.modelcontextprotocol.io/v0/servers/{url-encoded-name}/versions/{version}(the/in the reverse-DNS name encoded as%2F), with verified-real servers/versions (com.pulsemcp/remote-filesystem0.1.5,com.pulsemcp.servers/pulse-fetch0.2.14). The appendix also explains how a registry name maps to theurn:air:{publisher}:{namespace}:{name}identifier per ADR 0015.Note on the naming distinction (issue #9 / PR #18)
ext-server-card issue #9 / PR #18 deliberately chose
application/mcp-server-card+jsonfor the Server Card so it would not collide with the Registryserver.jsonconcept. This PR is the other half of that decision: it allocates the unqualifiedapplication/mcp-server+jsonto the Registryserver.jsondocument itself. The two types are complementary, not competing.Verification
python tools/build_spec.py), exit 0,dist/index.htmlproduced.application/mcp-server+jsonappears in the spec known-types list and ADR 0014 (verified the HTML renders it; 11 occurrences in built output across the new appendix + lists).#mapping-to-mcp-serversmatches the generated headingid(verified in built HTML).idaudit shows the only unresolved anchors (metadata-extensibility,resolving-an-artifacts-display-name,version-handling) are pre-existing onmain; none are introduced or referenced by this change.type: "application/mcp-server+json"withurn:air:identifiers.com.pulsemcp%2Fremote-filesystem/versions/0.1.5,com.pulsemcp.servers%2Fpulse-fetch/versions/0.2.14) return HTTP 200 fromregistry.modelcontextprotocol.io, with responseserver.name/version/repositorymatching the example values; the prose's/v0/servers/{name}/versions/{version}+server/_metaenvelope description was confirmed against that response.Status
Draft — do not merge. Stacked on #53; awaiting Tadas's review and rewrite.