Public: anyone can read this; the crew can change it.
The agent card lists what a stranger may call, not all 199 tools, and agrees with llms.txt #12411
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/12398-the-agent-card-lists-what-a-stranger-may → main 7 commits fork 2 threads · 2 unresolved
3 files
changed +85
−10
src/core/mcp_card.ts +32 −4
| @@ -157,10 +157,10 @@ export const toolsKey = (): string => cardTools.map((t) => t.name).join(","); | ||
| 157 | 157 | /** |
| 158 | 158 | * The agent card (A2A, protocol 0.3.0, the stable subset: name, description, |
| 159 | 159 | * url, version, protocolVersion, capabilities, default modes, skills; the |
| 160 | * sign-in is named by `securitySchemes`). One skill per MCP tool, from the | |
| 161 | * same list `mcpCard` names under `tools`. | |
| 160 | * sign-in is named by `securitySchemes`). With a token, one skill per MCP tool, | |
| 161 | * from the same list `mcpCard` names under `tools`; without, see `agentSkills`. | |
| 162 | 162 | */ |
| 163 | export function agentCard(origin: string, now: Running = running()) { | |
| 163 | export function agentCard(origin: string, now: Running = running(), signedIn = true) { | |
| 164 | 164 | const { url, oauth } = mcpPointers(origin); |
| 165 | 165 | return { |
| 166 | 166 | protocolVersion: "0.3.0", |
| @@ -176,10 +176,38 @@ export function agentCard(origin: string, now: Running = running()) { | ||
| 176 | 176 | mcp: { endpoint: url, card: `${origin}${DISCOVERY.card}`, protectedResourceMetadata: oauth, tokenFreeTools: [...TOKEN_FREE_TOOLS] }, |
| 177 | 177 | defaultInputModes: ["application/json"], |
| 178 | 178 | defaultOutputModes: ["application/json"], |
| 179 | skills: cardTools.map((t) => ({ id: t.name, name: t.name, description: t.description, tags: ["mcp"] })), | |
| 179 | // Which list `skills` is: "full" is every tool; | |
| 180 | // "open" is the token-free ones and a count of the rest. | |
| 181 | skillsScope: signedIn ? "full" : "open", | |
| 182 | skills: agentSkills(origin, signedIn), | |
| 180 | 183 | }; |
| 181 | 184 | } |
| 182 | 185 | |
| 186 | /** | |
| 187 | * How many tools an account opens beyond the token-free ones: | |
| 188 | * the number /llms.txt prints for a stranger. | |
| 189 | */ | |
| 190 | export const moreAfterSignIn = (): number => cardTools.filter((t) => !TOKEN_FREE_TOOLS.includes(t.name)).length; | |
| 191 | ||
| 192 | /** | |
| 193 | * A reader with a token gets one skill per tool; a stranger gets the | |
| 194 | * token-free tools and one entry counting the rest (the card is the first | |
| 195 | * thing an agent reads, so it stays small). | |
| 196 | */ | |
| 197 | function agentSkills(origin: string, signedIn: boolean) { | |
| 198 | const skill = (t: { name: string; description: string }) => ({ id: t.name, name: t.name, description: t.description, tags: ["mcp"] }); | |
| 199 | if (signedIn) return cardTools.map(skill); | |
| 200 | return [ | |
| 201 | ...cardTools.filter((t) => TOKEN_FREE_TOOLS.includes(t.name)).map(skill), | |
| 202 | { | |
| 203 | id: "more-after-sign-in", | |
| 204 | name: "more-after-sign-in", | |
| 205 | description: `${moreAfterSignIn()} more tools with an account: call tools/list on ${origin}/mcp once signed in.`, | |
| 206 | tags: ["mcp", "sign-in"], | |
| 207 | }, | |
| 208 | ]; | |
| 209 | } | |
| 210 | ||
| 183 | 211 | /** |
| 184 | 212 | * The server card. The format is still a draft, so only what we can keep |
| 185 | 213 | * true is named: who answers, where, over what transport, how to sign in, |
src/web/standards.ts +5 −3
| @@ -126,7 +126,7 @@ const discoveryBodies = new Map<string, { inputs: string; body: string; etag: st | ||
| 126 | 126 | * body reads (the plugin repo offered, the running build), so the body is |
| 127 | 127 | * made once per origin until that changes. A matching If-None-Match is a 304. |
| 128 | 128 | */ |
| 129 | function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, type: string, cache: string, pretty = false): Response { | |
| 129 | function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, type: string, cache: string, pretty = false, vary?: string): Response { | |
| 130 | 130 | const key = `${kind} ${ctx.url.origin}`; |
| 131 | 131 | let kept = discoveryBodies.get(key); |
| 132 | 132 | if (kept === undefined || kept.inputs !== inputs) { |
| @@ -139,7 +139,7 @@ function discovery(ctx: Ctx, kind: string, inputs: string, make: () => unknown, | ||
| 139 | 139 | if (discoveryBodies.size >= 48) discoveryBodies.delete(discoveryBodies.keys().next().value!); |
| 140 | 140 | discoveryBodies.set(key, kept); |
| 141 | 141 | } |
| 142 | const headers = { etag: kept.etag, "cache-control": cache, "access-control-allow-origin": "*" }; | |
| 142 | const headers = { etag: kept.etag, "cache-control": cache, "access-control-allow-origin": "*", ...(vary !== undefined ? { vary } : {}) }; | |
| 143 | 143 | if (holds(ctx.request.headers.get("if-none-match"), kept.etag)) return new Response(null, { status: 304, headers }); |
| 144 | 144 | return new Response(kept.body, { headers: { ...headers, "content-type": type } }); |
| 145 | 145 | } |
| @@ -159,7 +159,9 @@ export async function mcpJson(ctx: Ctx): Promise<Response> { | ||
| 159 | 159 | export async function agentCardJson(ctx: Ctx): Promise<Response> { |
| 160 | 160 | await loadMcp(); |
| 161 | 161 | const now = running(); |
| 162 | return discovery(ctx, "agent-card", JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now), "application/json", "public, max-age=3600", true); | |
| 162 | // The same reader test /llms.txt uses, so the two agree on who sees the full list. | |
| 163 | const signedIn = ctx.auth.user !== undefined; | |
| 164 | return discovery(ctx, `agent-card ${signedIn}`, JSON.stringify([now.version, toolsKey()]), () => agentCard(ctx.url.origin, now, signedIn), "application/json", signedIn ? "private, max-age=3600" : "public, max-age=3600", true, "Cookie, Authorization"); | |
outdated
|
||
| 163 | 165 | } |
| 164 | 166 | |
| 165 | 167 | /** GET /.well-known/api-catalog — RFC 9727: one linkset naming each API's description and docs. Anonymous. */ |
test/agent-card.test.ts +48 −3
| @@ -3,19 +3,28 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | ||
| 3 | 3 | import { mkdtemp, rm } from "node:fs/promises"; |
| 4 | 4 | import { tmpdir } from "node:os"; |
| 5 | 5 | import { join } from "node:path"; |
| 6 | import { moreAfterSignIn, TOKEN_FREE_TOOLS } from "../src/core/mcp_card.ts"; | |
| 6 | 7 | import { createApp } from "../src/app.ts"; |
| 7 | 8 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 8 | 9 | import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; |
| 10 | import { createUser } from "../src/core/users.ts"; | |
| 11 | import { createToken } from "../src/core/tokens.ts"; | |
| 9 | 12 | import { serve, type Servers } from "../src/http/server.ts"; |
| 10 | 13 | |
| 11 | 14 | describe("the agent card", () => { |
| 12 | 15 | let dataDir: string; |
| 13 | 16 | let servers: Servers; |
| 14 | 17 | let base: string; |
| 18 | let app: ReturnType<typeof createApp>; | |
| 19 | let bearer: string; | |
| 15 | 20 | beforeAll(async () => { |
| 16 | 21 | dataDir = await mkdtemp(join(tmpdir(), "forge-agent-card-")); |
| 17 | servers = await serve(createApp({ dataDir, port: 0 })); | |
| 22 | app = createApp({ dataDir, port: 0 }); | |
| 23 | servers = await serve(app); | |
| 18 | 24 | base = servers.url; |
| 25 | const made = await createUser(app.db, { origin: "seed", trusted: true, username: "cardreader", email: "[email protected]", password: "correct horse battery 1", isAdmin: false }); | |
| 26 | if (!made.ok) throw new Error("user"); | |
| 27 | bearer = createToken(app.db, made.value.id, "t", "rw").token; | |
| 19 | 28 | }); |
| 20 | 29 | afterAll(async () => { |
| 21 | 30 | await servers.stop(); |
| @@ -41,8 +50,11 @@ describe("the agent card", () => { | ||
| 41 | 50 | expect(card.mcp.endpoint).toBe(card.url); |
| 42 | 51 | }); |
| 43 | 52 | |
| 44 | test("its skills are exactly the tools mcp.json lists", async () => { | |
| 45 | const agent = (await (await fetch(`${base}/.well-known/agent-card.json`)).json()) as any; | |
| 53 | const auth = () => ({ headers: { authorization: `Bearer ${bearer}` } }); | |
| 54 | ||
| 55 | test("with a token its skills are exactly the tools mcp.json lists", async () => { | |
| 56 | const res = await fetch(`${base}/.well-known/agent-card.json`, auth()); | |
| 57 | const agent = (await res.json()) as any; | |
| 46 | 58 | const mcp = (await (await fetch(`${base}/.well-known/mcp.json`)).json()) as any; |
| 47 | 59 | expect(mcp.tools.length).toBeGreaterThan(10); |
| 48 | 60 | expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...mcp.tools].sort()); |
| @@ -50,5 +62,38 @@ describe("the agent card", () => { | ||
| 50 | 62 | const served = [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL].map((t) => t.name); |
| 51 | 63 | expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...new Set(served)].sort()); |
| 52 | 64 | for (const s of agent.skills) expect(s.description.length).toBeGreaterThan(0); |
| 65 | expect(res.headers.get("vary")).toContain("Authorization"); | |
| 66 | expect(agent.skillsScope).toBe("full"); | |
| 67 | expect(agent.skills.some((s: any) => s.id === "more-after-sign-in")).toBe(false); | |
| 68 | // An account's view is never stored by a shared cache. | |
| 69 | expect(res.headers.get("cache-control")).toBe("private, max-age=3600"); | |
| 70 | }); | |
| 71 | ||
| 72 | test("a stranger gets the open tools and one line for the rest, under 8 KB", async () => { | |
| 73 | const res = await fetch(`${base}/.well-known/agent-card.json`); | |
| 74 | const text = await res.text(); | |
| 75 | expect(text.length).toBeLessThan(8 * 1024); | |
| 76 | expect(res.headers.get("vary")).toContain("Authorization"); | |
| 77 | const ids = JSON.parse(text).skills.map((s: any) => s.id); | |
| 78 | expect(JSON.parse(text).skillsScope).toBe("open"); | |
| 79 | expect(res.headers.get("cache-control")).toBe("public, max-age=3600"); | |
| 80 | expect(ids.at(-1)).toBe("more-after-sign-in"); | |
| 81 | expect(ids.slice(0, -1).sort()).toEqual([...TOKEN_FREE_TOOLS].sort()); | |
| 82 | }); | |
| 83 | ||
| 84 | test("the ETag differs by reader and each is honoured", async () => { | |
| 85 | const a = await fetch(`${base}/.well-known/agent-card.json`); | |
| 86 | const b = await fetch(`${base}/.well-known/agent-card.json`, auth()); | |
| 87 | expect(a.headers.get("etag")).not.toBe(b.headers.get("etag")); | |
| 88 | const again = await fetch(`${base}/.well-known/agent-card.json`, { headers: { "if-none-match": a.headers.get("etag")! } }); | |
| 89 | expect(again.status).toBe(304); | |
| 90 | }); | |
| 91 | ||
| 92 | test("the count the card gives a stranger is the number /llms.txt prints", async () => { | |
| 93 | const card = (await (await fetch(`${base}/.well-known/agent-card.json`)).json()) as any; | |
| 94 | const more = card.skills.at(-1).description.match(/^(\d+) more tools/)[1]; | |
| 95 | const llms = await (await fetch(`${base}/llms.txt`)).text(); | |
| 96 | expect(llms).toContain(`- ${more} more tools with an account`); | |
| 97 | expect(Number(more)).toBe(moreAfterSignIn()); | |
| 53 | 98 | }); |
| 54 | 99 | }); |
new above
offline
The signed-in branch returns the bare tool list. Issue box 2 asks the card to say it is the full list: add a field (e.g.
skillsScope: "full"vs"open", or a leading sentence in the card description) so an agent can tell which one it holds, and test it.