Public: anyone can read this; the crew can change it.
/.well-known/ carries an agent card and an api-catalog naming the MCP, the OAuth metadata and the report door #13687
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13661-well-known-carries-an-agent-card-and-an → main 1 commit fork
2 files
changed +21
−0
src/core/mcp_card.ts +13
| @@ -50,6 +50,11 @@ export const DISCOVERY = { | ||
| 50 | 50 | api: "/api/v1", |
| 51 | 51 | } as const; |
| 52 | 52 | |
| 53 | /** | |
| 54 | * The OAuth metadata documents the catalog names (llms.txt names the resource one by its own line). | |
| 55 | */ | |
| 56 | const OAUTH_META = { server: "/.well-known/oauth-authorization-server", resource: "/.well-known/oauth-protected-resource" } as const; | |
| 57 | ||
| 53 | 58 | /** The `Link` header value that points at the catalog (RFC 9727 §3). */ |
| 54 | 59 | export const API_CATALOG_LINK = `<${DISCOVERY.catalog}>; rel="api-catalog"`; |
| 55 | 60 | |
| @@ -65,6 +70,14 @@ export function apiCatalog(origin: string) { | ||
| 65 | 70 | { |
| 66 | 71 | anchor: mcpPointers(origin).url, |
| 67 | 72 | "service-desc": [{ href: `${origin}${DISCOVERY.card}`, type: "application/json" }], |
| 73 | // The agent card, and the OAuth metadata a client signs in by. The report door is the | |
| 74 | // token-free `report` tool on this MCP, so it is named by the card, not by a link of its | |
| 75 | // own. | |
| 76 | "service-meta": [ | |
| 77 | { href: `${origin}${DISCOVERY.agentCard}`, type: "application/json", title: "agent card" }, | |
| 78 | { href: `${origin}${OAUTH_META.server}`, type: "application/json", title: "OAuth authorization server metadata" }, | |
| 79 | { href: `${origin}${OAUTH_META.resource}`, type: "application/json", title: "OAuth protected resource metadata" }, | |
| 80 | ], | |
| 68 | 81 | "service-doc": [{ href: `${origin}${DISCOVERY.docs}`, type: "text/plain" }], |
| 69 | 82 | }, |
| 70 | 83 | ], |
test/api-catalog.test.ts +8
| @@ -37,6 +37,14 @@ test("the catalog is a cacheable linkset naming each API", async () => { | ||
| 37 | 37 | expect(descs).toEqual(["/contract/openapi.json", "/.well-known/mcp.json"]); |
| 38 | 38 | }); |
| 39 | 39 | |
| 40 | test("the MCP entry names the agent card and the OAuth metadata", async () => { | |
| 41 | const { linkset } = (await (await fetch(`${base}/.well-known/api-catalog`)).json()) as { | |
| 42 | linkset: Record<string, { href: string }[] | string>[]; | |
| 43 | }; | |
| 44 | const meta = (linkset[1]!["service-meta"] as { href: string }[]).map((h) => new URL(h.href).pathname); | |
| 45 | expect(meta).toEqual(["/.well-known/agent-card.json", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource"]); | |
| 46 | }); | |
| 47 | ||
| 40 | 48 | test("every href in it answers 200 without a redirect", async () => { |
| 41 | 49 | const { linkset } = (await (await fetch(`${base}/.well-known/api-catalog`)).json()) as { |
| 42 | 50 | linkset: Record<string, { href: string }[] | string>[]; |
new above
offline