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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13661-well-known-carries-an-agent-card-and-an → main 1 commit fork

  • Merged. scout/13661-well-known-carries-an-agent-card-and-an was merged into main as a6fb2f0.

Review

Sign in to review this change.
2 files changed +21 −0
src/core/mcp_card.ts +13
@@ -50,6 +50,11 @@ export const DISCOVERY = {
5050 api: "/api/v1",
5151 } as const;
5252
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
5358 /** The `Link` header value that points at the catalog (RFC 9727 §3). */
5459 export const API_CATALOG_LINK = `<${DISCOVERY.catalog}>; rel="api-catalog"`;
5560
@@ -65,6 +70,14 @@ export function apiCatalog(origin: string) {
6570 {
6671 anchor: mcpPointers(origin).url,
6772 "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 ],
6881 "service-doc": [{ href: `${origin}${DISCOVERY.docs}`, type: "text/plain" }],
6982 },
7083 ],
test/api-catalog.test.ts +8
@@ -37,6 +37,14 @@ test("the catalog is a cacheable linkset naming each API", async () => {
3737 expect(descs).toEqual(["/contract/openapi.json", "/.well-known/mcp.json"]);
3838 });
3939
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
4048 test("every href in it answers 200 without a redirect", async () => {
4149 const { linkset } = (await (await fetch(`${base}/.well-known/api-catalog`)).json()) as {
4250 linkset: Record<string, { href: string }[] | string>[];

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs