modelcontextprotocol / modelcontextprotocol/ext-server-card

Support Link header and HTML <link> catalog discovery, not just /.well-known

Open
#43 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
8
Forks
5
PR merge metrics
No merged PRs in 30d

Description

The AI Catalog specification does not treat /.well-known/ai-catalog.json as the only way to locate a catalog. Per Location Independence, "An AI Catalog document MAY be served from any URL" — it is identified by its media type, not its path — and "Use of the well-known URI is OPTIONAL. Hosts that publish catalogs at other locations are fully conformant."

The spec's discovery procedure defines two additional pointers, both checked ahead of the well-known path:

  1. An HTTP Link header with rel="ai-catalog"
  2. An HTML <link rel="ai-catalog"> in the document head
  3. Optionally fall back to /.well-known/ai-catalog.json
  4. Validate the retrieved document has a valid specVersion

Both link-relation forms are registered with IANA in the spec's registration sections.

We currently document and implement only the well-known path. That is a reasonable starting point — it is the only location reachable against a bare domain, with nothing fetched first — but stopping there means a client will miss any host that publishes a catalog somewhere other than the domain root. ADR-0011 notes this is specifically the enterprise-registry case, which cannot always use .well-known at all.

Scope
  • SDK reference implementations — resolve a catalog by following the full precedence order rather than constructing the well-known URL directly. Worth deciding whether this ships alongside the existing reference implementations tracked in #16 or as a follow-up.
  • docs/discovery.md — document the precedence order and the specVersion validation step.
  • docs/best-practices.md — currently recommends .well-known as the single explained option and points here for the rest. Update once the above lands: servers should advertise via the link relations as well, and clients should honor them.
Not urgent

The well-known path is the common case and the one in-session discovery depends on, so nothing is blocked on this. Filing so the gap is tracked rather than rediscovered.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/discovery.md and docs/best-practices.md, then read the linked discovery procedure and ADR-0011. Inspect the SDK reference implementations tracked in #16. Done means clients follow HTTP Link, HTML link, and well-known discovery in precedence order, validate specVersion, and the documentation explains these options.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.