From 3b2d974dbbc1bcf899e0ed2ef49a91758853c9a6 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Mon, 13 Jul 2026 12:35:28 -0700 Subject: [PATCH] docs(discovery): rename Catalog Entry mediaType field to type (ADR 0014) (#32) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What Adapts the **MCP Catalog Entry** in `docs/discovery.md` to [AI Catalog PR #37](https://github.com/Agent-Card/ai-catalog/pull/37) / ADR 0014, which renames the `CatalogEntry.mediaType` member to **`type`** and reframes its description as an open-text *type identifier* rather than a strict IANA media type. Changes (docs-only, `docs/discovery.md`): - Renames the `mediaType` member to `type` in the Catalog Entry table. - Updates the member description to mirror ADR 0014: "An identifier specifying the type of the referenced artifact." - Updates the `type` key in all four example catalog entries. - Updates the client-validation prose (`type` set to … / "ignore entries with unrecognized types"). ## Rebase / conflict resolution This branch was rebased onto the current `main` to resolve a merge conflict in `docs/discovery.md`. The conflict came from changes that landed on `main` after this branch was cut: - **#31** — `urn:air:` identifier adaptation (ADR 0015). **Preserved.** - **#39 / #14** — removal of the `displayName` field from MCP Catalog entries. **Preserved** — this PR does **not** reintroduce `displayName`; it only renames the field `mediaType` → `type` on top of main's current structure. The resolved diff is exactly the `mediaType` → `type` rename (table row, four examples, validation prose) applied on top of main — nothing from either side's intent was dropped. ## Scope decision — value deliberately kept as `application/mcp-server-card+json` This PR renames the **field only**. The value stays `application/mcp-server-card+json` and is **not** changed to ADR 0014's known-type `application/mcp-server+json`. Rationale: - ADR 0014 explicitly makes `type` an **open-text** format ("any string value is accepted"); `application/mcp-server+json` is a non-binding "known type," and ecosystem types are "governed externally" (i.e., by MCP). So keeping a more precise MCP-governed value is compatible with ADR 0014, not a contradiction. - This repo **deliberately** chose `application/mcp-server-card+json` over `application/mcp-server+json` (issue #9 / PR #18) to avoid colliding with the MCP Registry's `server.json` concept — a distinction the README documents in "Relationship to the MCP Registry." **Flag for maintainers:** AI Catalog's ADR 0014 known-types list uses `application/mcp-server+json` for MCP. Whether this repo should also adopt that value (reversing issue #9 / PR #18 and re-introducing the `server.json` naming collision) is a separate, more consequential decision and is intentionally **out of scope** here. Happy to file a cross-repo issue if maintainers want to pursue it. ## What is intentionally NOT changed - The **Server Card document's own HTTP media type** (`Accept` / `Content-Type` negotiation, the reserved `/server-card` location prose). That is a genuine IANA media type, not the renamed catalog field, and ADR 0014 does not touch it. - `schema.ts` / `schema.json` — the Server Card schema has no `mediaType`/`type` member; this convention lives only in the discovery doc. ## Verification - [x] Rebased onto latest `main`; merge conflict in `docs/discovery.md` resolved, preserving both #31 (`urn:air:`) and #39 (`displayName` removal). PR now reports `MERGEABLE`. - [x] `npm run check` — `schema.json` up to date, `tsc --noEmit` clean - [x] `npm run validate` — all 7 examples pass - [x] `npm run format:check` — `docs/discovery.md` clean, including markdown table re-alignment - [x] Verified zero `mediaType` field tokens remain (`git grep mediaType` → no matches) - [x] Verified the Server Card HTTP media-type prose was left intact (no over-reach) - [x] **CI green** — `build`, `Analyze (actions)`, and `CodeQL` all pass on the rebased head ([run](https://github.com/modelcontextprotocol/experimental-ext-server-card/actions/runs/29278815978)) - [x] Independent fresh-eyes subagent review: **APPROVE** (rename complete & correct; no `displayName` reintroduced; value unchanged; Server Card media-type prose intact; no stray `mediaType`; no conflict markers) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: tadasant Co-authored-by: Claude Opus 4.8 --- docs/discovery.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index d46e446..ced0146 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -50,11 +50,11 @@ An MCP Catalog document is a JSON object that MUST contain the following members Each entry in the `entries` array describes a single MCP server and MUST contain: -| Member | Type | Required | Description | -| :----------- | :----- | :------- | :------------------------------------------------------------------------------------ | -| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | -| `mediaType` | string | Yes | The media type of the referenced artifact. MUST be `application/mcp-server-card+json` | -| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | +| Member | Type | Required | Description | +| :----------- | :----- | :------- | :------------------------------------------------------------------------------------------------------- | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | +| `type` | string | Yes | An identifier specifying the type of the referenced artifact. MUST be `application/mcp-server-card+json` | +| `url` | string | Yes | URL where the full [Server Card](#mcp-server-cards) can be retrieved | An MCP Catalog entry carries no human-readable-name field. Every entry references a [Server Card](#mcp-server-cards), and the Server Card's `title` is the source of truth for @@ -100,7 +100,7 @@ A domain hosting a single MCP server: "entries": [ { "identifier": "urn:air:example.com:weather", - "mediaType": "application/mcp-server-card+json", + "type": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" } ] @@ -117,17 +117,17 @@ A domain hosting several MCP servers, each with its own server card: "entries": [ { "identifier": "urn:air:acme.com:code-review", - "mediaType": "application/mcp-server-card+json", + "type": "application/mcp-server-card+json", "url": "https://acme.com/code-review/server-card" }, { "identifier": "urn:air:acme.com:docs-search", - "mediaType": "application/mcp-server-card+json", + "type": "application/mcp-server-card+json", "url": "https://acme.com/docs-search/server-card" }, { "identifier": "urn:air:acme.com:ci-cd", - "mediaType": "application/mcp-server-card+json", + "type": "application/mcp-server-card+json", "url": "https://acme.com/ci-cd/server-card" } ] @@ -155,8 +155,8 @@ flowchart TD [Server Card Location](#server-card-location)) 4. Use the server card metadata to configure and establish an MCP connection -Clients SHOULD validate that each entry has `mediaType` set to `application/mcp-server-card+json` -and ignore entries with unrecognized media types. +Clients SHOULD validate that each entry has `type` set to `application/mcp-server-card+json` +and ignore entries with unrecognized types. ## MCP Server Cards