From e42749bfc2d59a288fef5181745cd9f6c95778b4 Mon Sep 17 00:00:00 2001 From: Tadas Antanavicius Date: Fri, 19 Jun 2026 05:17:11 -0700 Subject: [PATCH] docs(discovery): adopt AI Catalog `urn:air:` identifier convention (ADR 0015) (#31) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What & why Adopts the AI Catalog **`urn:air:`** identifier-naming convention standardized in [Agent-Card/ai-catalog#36](https://github.com/Agent-Card/ai-catalog/pull/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`](docs/discovery.md). It previously used a repo-local `urn:mcp:server:` URN. `docs/discovery.md` describes 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-anchored `urn:air:{publisher}:{namespace}:{name}` form. ### Changes (doc-only, `docs/discovery.md`) - Replace the `urn:mcp:server:` convention with the AI Catalog `urn:air:` form. - Document the segments for an MCP server: - **`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-DNS `name`), e.g. `weather`. - So a Server Card named `com.example/weather` can be referenced as `urn:air:example.com:weather`. - Update all 4 catalog examples accordingly. ### Design notes for reviewers - **Forward-DNS publisher**, anchored on the publisher's domain per ADR 0015. - **Server Card schema deliberately untouched.** `schema.ts`/`schema.json` have **no `identifier`/`identity` field** — the card carries `name` (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. - **Related open question:** issue #26 ("Remove the MCP Catalog") — this aligns the identifier format while the MCP Catalog exists and does not pre-empt that discussion. ## Verification - [x] **Self-review (fresh-eyes) done.** Ran independent in-process reviews of the diff across iterations; findings (an incorrectly-attributed `urn:air:local:` form; reverse- vs forward-DNS publisher) were addressed. - [x] **ADR 0015 cross-checked against source** — verified the `urn:air:{publisher}:{namespace}:{name}` form, the forward-domain example `urn:air:example.com:...`, and the optional namespace against the raw `adr/0015-agent-identifier-naming.md` in PR #36. - [x] **All 4 examples internally consistent** with the documented mapping; example `url` hosts match the publisher domains. - [x] **No stale references** — `grep` confirms zero remaining `urn:mcp:server:` occurrences. - [x] **Schema untouched & in sync** — `npm run check` → `✓ schema.json is up to date`; `tsc --noEmit` passes. - [x] **Examples validate** — `npm run validate` → `All 7 example(s) passed.` - [x] **Formatting** — `npm run format:check` (prettier) passes on all tracked files. - [x] **CI green** — confirmed on the pushed branch (`build`, `CodeQL`, `Analyze` all pass). Local proof: ``` $ npm run check ✓ schema.json is up to date (+ tsc --noEmit, no errors) $ npm run validate All 7 example(s) passed. $ npm run format:check All matched files use Prettier code style! ``` Documentation-only change; no UI and no runtime/logic behavior to exercise beyond the schema toolchain above. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: tadasant Co-authored-by: Claude Opus 4.8 --- docs/discovery.md | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/discovery.md b/docs/discovery.md index 7faffd9..8838b39 100644 --- a/docs/discovery.md +++ b/docs/discovery.md @@ -52,13 +52,31 @@ Each entry in the `entries` array describes a single MCP server and MUST contain | Member | Type | Required | Description | | :------------ | :----- | :------- | :------------------------------------------------------------------------------------ | -| `identifier` | string | Yes | A URN identifying this server (e.g., `urn:mcp:server:com.example/weather`) | +| `identifier` | string | Yes | A logical discovery URN for this server (e.g., `urn:air:example.com:weather`) | | `displayName` | string | Yes | A human-readable name for the server | | `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 | -The `identifier` MUST begin with `urn:mcp:server:` and end with the `name` value of the -referenced Server Card, with no characters in between. +The `identifier` is a **logical discovery name** that follows the +[AI Catalog](https://github.com/Agent-Card/ai-catalog) domain-anchored URN convention +standardized in [ADR 0015](https://github.com/Agent-Card/ai-catalog/pull/36): + +``` +urn:air:{publisher}:{namespace}:{name} +``` + +The segments are: + +- **`publisher`** — the publisher's domain (forward DNS), e.g. `example.com`. ADR 0015 + anchors the identifier on this domain. +- **`namespace`** — optional, populate if you wish in accordance with the AI Catalog specification +- **`name`** — the server's name suffix, i.e. the segment after the `/` in the referenced Server + Card's reverse-DNS `name`, e.g. `weather`. + +So a Server Card named `com.example/weather`, can be referenced as +`urn:air:example.com:weather`. Anchoring the identifier on the publisher's domain keeps +it globally unique and stable across infrastructure changes, and lets an MCP Catalog entry +be indexed as-is within a full AI Catalog document. ### Example: Single Server @@ -69,7 +87,7 @@ A domain hosting a single MCP server, using only the required fields: "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:com.example/weather", + "identifier": "urn:air:example.com:weather", "displayName": "Weather Service", "mediaType": "application/mcp-server-card+json", "url": "https://example.com/mcp/server-card" @@ -87,19 +105,19 @@ A domain hosting several MCP servers, each with its own server card: "specVersion": "draft", "entries": [ { - "identifier": "urn:mcp:server:com.acme/code-review", + "identifier": "urn:air:acme.com:code-review", "displayName": "Code Review Assistant", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/code-review/server-card" }, { - "identifier": "urn:mcp:server:com.acme/docs-search", + "identifier": "urn:air:acme.com:docs-search", "displayName": "Documentation Search", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/docs-search/server-card" }, { - "identifier": "urn:mcp:server:com.acme/ci-cd", + "identifier": "urn:air:acme.com:ci-cd", "displayName": "CI/CD Pipeline", "mediaType": "application/mcp-server-card+json", "url": "https://acme.com/ci-cd/server-card"