docs: add server.json as a first-class catalog type (application/mcp-server+json)

[tadasant]

⚠️ AI-assisted draft. This PR's content (spec prose and description) was drafted by an AI assistant working on Tadas's behalf. Tadas will review, vet, and rewrite as needed, and will remove this disclosure once he has done so. Until then, treat this as a steered placeholder, not Tadas's finished position.

Stacked on #53

This PR is stacked on top of #53 (docs/update-server-json-mapping). Its base branch is docs/update-server-json-mapping, not main — review/merge #53 first. The diff against its base is just the server.json-as-first-class change below.

What this does

Reintroduces the MCP Registry server.json mapping 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+json for an MCP Registry server.json document, 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.json describing the first-class mapping: a Catalog Entry whose url points to the server.json document with type application/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:

  • MCP Server Card → application/mcp-server-card+json (static discovery / connection details)
  • MCP Registry 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.json example url uses the actual registry API form https://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-filesystem 0.1.5, com.pulsemcp.servers/pulse-fetch 0.2.14). The appendix also explains how a registry name maps to the urn:air:{publisher}:{namespace}:{name} identifier per ADR 0015.

• Omitted duplicative version/description from the example entries. Mirrors the same change in docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53's Server Card examples: these restate values the server.json document already carries (the drift argument that keeps displayName out of an entry). The example entries drop version/description; the conceptual mapping table keeps documenting them but its description/version rows justify the omission, parallel to the title row. For server.json, the entry's version-pinned url already identifies which version it points at.

• Applied the same drift-avoidance treatment to repository. server.json carries its own repository, so mapping it into entry metadata.repository duplicated a drift-prone value. The example already demonstrated the redundancy — the repo URL also appears in trustManifest.provenance[].sourceId — so the metadata.repository block is dropped from the example and the table row now justifies the omission (source/provenance links belong in the Trust Manifest). This mirrors the Server Card repository fix inherited from docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53.

• Dropped updatedAt from the entry example (registry-timestamp drift). The single-entry example carried "updatedAt": "2026-03-15T10:00:00Z", but the MCP Registry response already exposes its own publishedAt/updatedAt under _meta (verified live: registry.modelcontextprotocol.io returns _meta["io.modelcontextprotocol.registry/official"].updatedAt), so the entry field duplicated a value the source carries — and the hardcoded date had already drifted from the real one. Removed it from the example (bringing it to structural parity with docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53's Server Card entry example, which carries no updatedAt) and extended the _meta mapping-table row to record that the registry timestamps stay in the artifact.

• version keeps its multi-version carve-out here (deliberate divergence from the Server Card side). docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53 dropped the multi-version carve-out from the Server Card version row because a remote MCP server serves exactly one card. On the Registry server.json side that case is real — a registry genuinely serves multiple versions of a name — so this appendix's version row retains the "omitted unless the catalog lists multiple versions of one identifier" language, plus the note that the version-pinned url already identifies which version an entry points at.

Note on the naming distinction (issue #9 / PR #18)

ext-server-card issue #9 / PR #18 deliberately chose application/mcp-server-card+json for the Server Card so it would not collide with the Registry server.json concept. This PR is the other half of that decision: it allocates the unqualified application/mcp-server+json to the Registry server.json document itself. The two types are complementary, not competing.

Verification

• Spec builds locally with the exact CI command (python tools/build_spec.py), exit 0, dist/index.html produced.
• New type registered in both places — application/mcp-server+json appears in the spec known-types list and ADR 0014 (verified the HTML renders it; 11 occurrences in built output across the new appendix + lists).
• Cross-reference resolves — the appendix's link to #mapping-to-mcp-servers matches the generated heading id (verified in built HTML).
• No new broken anchors — built-HTML link/id audit shows the only unresolved anchors (metadata-extensibility, resolving-an-artifacts-display-name, version-handling) are pre-existing on main; none are introduced or referenced by this change.
• All JSON examples valid and use type: "application/mcp-server+json" with urn:air: identifiers.
• Duplicative fields removed cleanly — no server.json example entry carries version/description/metadata.repository/updatedAt (grep confirmed the appendix's only remaining updatedAt is the explanatory _meta table row, not an example value); version remains recoverable from the version-pinned url, the repo from trustManifest.provenance, and the timestamps from the registry _meta; the mapping table keeps documenting version/description/repository/_meta, each with its omission rationale. All 19 JSON examples still parse.
• Registry-timestamp drift verified live — curl of registry.modelcontextprotocol.io/v0/servers/com.pulsemcp%2Fremote-filesystem/versions/0.1.5 returns _meta["io.modelcontextprotocol.registry/official"] with publishedAt/updatedAt (2026-06-26…), confirming the removed entry updatedAt was both duplicative and stale against the source.
• Example URLs verified against the live registry — both example URLs (com.pulsemcp%2Fremote-filesystem/versions/0.1.5, com.pulsemcp.servers%2Fpulse-fetch/versions/0.2.14) return HTTP 200 from registry.modelcontextprotocol.io, with response server.name/version/repository matching the example values; the prose's /v0/servers/{name}/versions/{version} + server/_meta envelope description was confirmed against that response.
• Inherits docs: refactor MCP mapping appendix to Server Cards + align with MCP spec #53's discovery-flow reframe — the shared Server Card appendix's "Decentralized Discovery" section (reframed per ext-server-card PR #36) merges in cleanly; build passes on this branch.
• Fresh-eyes review performed in-process on the diff vs. the base branch; feedback addressed.
• CI green on the latest commit (confirmed via wait-for-CI after the final push).

Status

Draft — do not merge. Stacked on #53; awaiting Tadas's review and rewrite.

[github-actions]

Preview: https://ai-catalog.io/pr/54/

This comment is updated automatically while the pull request preview is available.