docs(discovery): adopt AI Catalog urn:air: identifier convention (ADR 0015)#31
Merged
Conversation
…DR 0015)
Align the MCP Catalog Entry `identifier` with the domain-anchored
`urn:air:{publisher}:{namespace}:{name}` naming convention standardized
in Agent-Card/ai-catalog#36 (ADR 0015), replacing the repo-local
`urn:mcp:server:<name>` format.
The MCP Catalog is documented as "a minimal, MCP-scoped subset of the AI
Catalog specification" whose entries "can be used as-is within a full AI
Catalog document" — a claim the old `urn:mcp:server:` format
contradicted. Maps the Server Card reverse-DNS `name` (`{publisher}/{name}`)
to `urn:air:{publisher}:mcp:{name}`, and clarifies that the discovery
`identifier` is decoupled from cryptographic trust identity per ADR 0015.
Doc-only change to docs/discovery.md; the Server Card schema has no
identifier field and is unchanged.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
…her note Address fresh-eyes review: ADR 0015 does not define a urn:air:local: form (it permits any open-text identifier for local/closed catalogs), and note that MCP's reverse-DNS publisher segment matches the ADR's own MCP examples. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Per review feedback, anchor the identifier on the publisher's forward-DNS domain (e.g. example.com) to match ADR 0015's framing that the publisher segment is a domain, and its canonical example urn:air:example.com:mcp:weather. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Re-pad the Catalog Entry table after the identifier example shortened; fixes the failing format:check CI step. No content change. Co-Authored-By: Claude Opus 4.8 <[email protected]>
SamMorrowDrums
approved these changes
Jun 18, 2026
Collaborator
|
Good catch, I hope this will remain stable from here. 🤞 |
Member
Author
|
@SamMorrowDrums let's wait for the AI Catalog PR to land before merging this AI Catalog is not stable yet, but we plan to have a target stable v1 date set during the next Thursday call |
This was referenced Jun 18, 2026
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 <[email protected]> Co-authored-by: Claude Opus 4.8 <[email protected]>
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
3 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.
What & why
Adopts the AI Catalog
urn:air:identifier-naming convention standardized in Agent-Card/ai-catalog#36 (ADR 0015) for this extension's discovery docs.This repo's only identifier-naming surface is the MCP Catalog Entry in
docs/discovery.md. It previously used a repo-localurn:mcp:server:<name>URN.docs/discovery.mddescribes the MCP Catalog as "a minimal, MCP-scoped subset of the AI Catalog specification" whose entries "can be used as-is within a full AI Catalog document" — a claim the old format contradicted, since the AI Catalog now standardizes the domain-anchoredurn:air:{publisher}:{namespace}:{name}form.Changes (doc-only,
docs/discovery.md)urn:mcp:server:<name>convention with the AI Catalogurn:air:form.publisher— the publisher's domain (forward DNS), e.g.example.com, matching ADR 0015's framing that the publisher is a domain.namespace— optional, populated per the AI Catalog specification (the examples omit it).name— the server-name suffix (the segment after the/in the referenced Server Card's reverse-DNSname), e.g.weather.com.example/weathercan be referenced asurn:air:example.com:weather.Design notes for reviewers
schema.ts/schema.jsonhave noidentifier/identityfield — the card carriesname(reverse-DNS) only — so this is a discovery-doc change, not a schema change. Keeps the PR minimal and avoids pre-empting unresolved SEP-2127 discussion.Verification
urn:air:local:form; reverse- vs forward-DNS publisher) were addressed.urn:air:{publisher}:{namespace}:{name}form, the forward-domain exampleurn:air:example.com:..., and the optional namespace against the rawadr/0015-agent-identifier-naming.mdin PR docs: add best practices for server and client implementors #36.urlhosts match the publisher domains.grepconfirms zero remainingurn:mcp:server:occurrences.npm run check→✓ schema.json is up to date;tsc --noEmitpasses.npm run validate→All 7 example(s) passed.npm run format:check(prettier) passes on all tracked files.build,CodeQL,Analyzeall pass).Local proof:
Documentation-only change; no UI and no runtime/logic behavior to exercise beyond the schema toolchain above.
🤖 Generated with Claude Code