docs(discovery): drop displayName from MCP Catalog entries (#14)#39
Merged
Conversation
Make the MCP Catalog entry field `displayName` optional rather than required, so an entry strictly requires only `identifier`, `mediaType`, and `url`. The referenced Server Card is the source of truth for a server's human-readable name, so an entry may omit `displayName` and let clients read the name from the card at `url`. This follows the upstream AI Catalog change (ADR 0016, Agent-Card/ai-catalog#39, merged 2026-06-26), which likewise made the catalog entry displayName optional. Matching it preserves the guarantee that MCP Catalog entries remain a drop-in subset of AI Catalog entries. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rather than making the MCP Catalog entry field displayName optional, drop it from the MCP Catalog entirely. Every MCP Catalog entry references a Server Card, and the Server Card's `title` is the source of truth for the server's human-readable name. Documenting displayName on the entry — even as optional — only invites publishers to duplicate a name that already lives in the card and risks it drifting out of sync. An MCP Catalog entry now requires only identifier, mediaType, and url. The doc notes that AI Catalog defines an OPTIONAL displayName (ADR 0016, Agent-Card/ai-catalog#39); because it is optional upstream, an MCP entry that omits it remains a valid drop-in subset of an AI Catalog entry. Removes displayName from the field table and from all catalog examples. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
tadasant
changed the title
SamMorrowDrums
approved these changes
Jul 13, 2026
8 tasks
SamMorrowDrums
pushed a commit
that referenced
this pull request
Jul 13, 2026
…14) (#32) ## What Adapts the **MCP Catalog Entry** in `docs/discovery.md` to [AI Catalog PR #37](Agent-Card/ai-catalog#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 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
2 participants
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.
Summary
Removes the
displayNamefield from MCP Catalog entries indocs/discovery.md. An MCP Catalog entry now requires onlyidentifier,mediaType, andurl— there is no human-readable-name field on the entry at all.Resolves #14.
Rationale
Issue #14 originally proposed making
displayNameoptional, gated on the upstream AI Catalog spec doing the same. That gate resolved — Agent-Card/ai-catalog#39 ("make Catalog Entry displayName optional (not required), ADR 0016") merged 2026-06-26: Agent-Card/ai-catalog#39.But for the MCP-scoped catalog we can go one step further and drop the field entirely, which is cleaner:
titleis the source of truth for the server's human-readable name. A client fetches that card anyway (the discovery flow retrieves the card aturlfor connection details), so it can read the name straight from the card.displayNameon the entry — even as optional — only invites publishers to duplicate a name that already lives in the card, where it can drift out of sync. This is the general-AI-Catalog concern (some non-MCP/non-A2A artifacts have no baked-in name) not applying to us: an MCP entry always points at a card that carries its owntitle.This still preserves the drop-in-subset guarantee. AI Catalog makes
displayNameoptional (ADR 0016), so an MCP Catalog entry that omits it remains valid as-is inside a full AI Catalog document. The two specs agree; MCP simply declines to use the field and defers to the Server Card'stitle. The doc states this explicitly so the intentional omission is clear rather than looking like an oversight.What changed (
docs/discovery.mdonly)displayNamerow. Entry now lists onlyidentifier,mediaType,url(all required).title, plus a paragraph documenting the AI-Catalog compatibility (optionaldisplayNameupstream → MCP entry is still a drop-in subset).displayNamefrom the single-server example and from all three entries in the multiple-servers example.Docs/spec-text only. No TypeScript or JSON Schema changes were needed — the catalog entry shape lives entirely in
discovery.md;schema.ts/schema.jsondescribe the Server Card itself and never encoded the catalog entry'sdisplayName, so there was no schema coupling to update.Verification
npm run checkpasses (schema.json up to date;tsc --noEmitclean) — docs-only diffnpm run validatepasses (all 7 Server Card examples validate as expected)npm run format:checkclean fordocs/discovery.md(ranprettier --write; remaining warnings are AO-injected untracked files not present in CI)displayNamesweep: the field is gone from the table and every example; the only remaining mentions are the deliberate AI-Catalog compatibility note explaining why MCP omits it — no contradictory "required"/"optional-field" language remains