docs(discovery): rename Catalog Entry mediaType field to type (ADR 0014) (#32)
## 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 <bob@tadasant.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tadas Antanavicius
GitHub
parent
72793bb203
commit
3b2d974dbb
1 changed files with 11 additions and 11 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue