Public: anyone can read this; the crew can change it.
What /api/v1/here offers an anonymous agent works through the MCP too: `releases` and `contribute` answer without a token, or `here` stops naming them #14381
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14365-what-api-v1-here-offers-an-anonymous-age → main 5 commits fork
8 files
changed +52
−15
src/actions/here.ts +2 −2
| @@ -371,7 +371,7 @@ function keptActions( | ||
| 371 | 371 | ]; |
| 372 | 372 | case "changelog": |
| 373 | 373 | return [ |
| 374 | { do: "read what went live", http: "GET /api/v1/changelog", mcp: "releases" }, | |
| 374 | { do: "read what went live", http: "GET /api/v1/changelog", mcp: "releases", ...tokenFree("releases") }, | |
| 375 | 375 | { do: "follow it as a feed", http: "GET /changelog.atom", account: false }, |
| 376 | 376 | ]; |
| 377 | 377 | case "templates": |
| @@ -472,7 +472,6 @@ function forgeActions( | ||
| 472 | 472 | ...tokenFree("offer"), |
| 473 | 473 | }, |
| 474 | 474 | { |
| 475 | // The HTTP route is open, but the MCP tool is not, so no claim is made. | |
| 476 | 475 | do: "see how to help build this forge", |
| 477 | 476 | http: "GET /api/v1/contribute", |
| 478 | 477 | mcp: "contribute", |
| @@ -482,6 +481,7 @@ function forgeActions( | ||
| 482 | 481 | do: "see what went live", |
| 483 | 482 | http: "GET /api/v1/changelog", |
| 484 | 483 | mcp: "releases", |
| 484 | ...tokenFree("releases"), | |
| 485 | 485 | }, |
| 486 | 486 | ...(getAgentStart(app.db) === "off" |
| 487 | 487 | ? [] |
src/core/mcp_card.ts +1 −1
| @@ -96,7 +96,7 @@ export function apiCatalog(origin: string) { | ||
| 96 | 96 | * `http/mcp.ts` answers these and refuses the rest with 401. The card and |
| 97 | 97 | * `/api/v1/here` both read this list, so they cannot drift. |
| 98 | 98 | */ |
| 99 | export const TOKEN_FREE_TOOLS: readonly string[] = ["report", "offer", "start", "explore", "search"]; | |
| 99 | export const TOKEN_FREE_TOOLS: readonly string[] = ["report", "offer", "start", "explore", "search", "releases", "contribute"]; | |
| 100 | 100 | |
| 101 | 101 | /** A thin plugin the forge ships for a harness: where its source is and its one install line. */ |
| 102 | 102 | export interface HarnessPlugin { |
src/http/mcp.ts +13
| @@ -32,6 +32,8 @@ import { html } from "../web/html.ts"; | ||
| 32 | 32 | import type { Router } from "./router.ts"; |
| 33 | 33 | import { clientBucket } from "./peer.ts"; |
| 34 | 34 | import { TOKEN_FREE_TOOLS } from "../core/mcp_card.ts"; |
| 35 | import { shippedAnswer } from "../release/answer.ts"; | |
| 36 | import { welcome } from "../system/telemetry.ts"; | |
| 35 | 37 | import { exploreRun, searchRun } from "./mcp/reads.ts"; |
| 36 | 38 | import { greppable, searchKind } from "../core/search.ts"; |
| 37 | 39 | import { strangerCodeSearch } from "./strangers.ts"; |
| @@ -380,8 +382,19 @@ export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = { | ||
| 380 | 382 | offer: offerAnswer, |
| 381 | 383 | explore: (ctx, id, args) => readAnswer(ctx, id, "explore", args), |
| 382 | 384 | search: (ctx, id, args) => readAnswer(ctx, id, "search", args), |
| 385 | releases: publicReleases, | |
| 386 | contribute: (ctx, id) => ({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(welcome(ctx.app)) }] } }), | |
| 383 | 387 | }; |
| 384 | 388 | |
| 389 | /** | |
| 390 | * `releases` for a stranger: what `GET /api/v1/changelog` answers anyone (public repositories | |
| 391 | * only), whatever the arguments; the kept-release list is for whoever may read /releases. | |
| 392 | */ | |
| 393 | async function publicReleases(ctx: Ctx, id: unknown, args: Args): Promise<unknown> { | |
| 394 | const answer = await shippedAnswer(ctx.app, typeof args["repo"] === "string" ? args["repo"] : null); | |
| 395 | return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(answer) }] } }; | |
| 396 | } | |
| 397 | ||
| 385 | 398 | /** |
| 386 | 399 | * The token-free tools that are also ordinary tools (`report` and `start` are |
| 387 | 400 | * not in TOOLS): a stranger's call goes through the handler (as no one, so |
test/fuzz-mcp.test.ts +1 −1
| @@ -245,7 +245,7 @@ describe("MCP fuzz: hostile arguments get a named refusal", () => { | ||
| 245 | 245 | |
| 246 | 246 | test("anonymous reaches exactly the token-free tools, and each refuses hostile arguments by name, leaving nothing behind", async () => { |
| 247 | 247 | const free = Object.keys(TOKEN_FREE_HANDLERS).sort(); |
| 248 | expect(free).toEqual(["explore", "offer", "report", "search", "start"]); | |
| 248 | expect(free).toEqual(["contribute", "explore", "offer", "releases", "report", "search", "start"]); | |
| 249 | 249 | const reached: string[] = []; |
| 250 | 250 | for (const name of toolNames()) { |
| 251 | 251 | const a = await call(undefined, name, { repo: "../../etc", title: BIG, __proto__: { admin: true } }); |
test/here-manifest.test.ts +2
| @@ -261,6 +261,7 @@ describe("the manifest: what you can do here, as who you are", () => { | ||
| 261 | 261 | do: "see how to help build this forge", |
| 262 | 262 | http: "GET /api/v1/contribute", |
| 263 | 263 | mcp: "contribute", |
| 264 | account: false, | |
| 264 | 265 | }); |
| 265 | 266 | expect(size).toBeLessThan(2048); |
| 266 | 267 | expect(does((await manifest("/acme/game", who)).body)).not.toContain( |
| @@ -276,6 +277,7 @@ describe("the manifest: what you can do here, as who you are", () => { | ||
| 276 | 277 | do: "see what went live", |
| 277 | 278 | http: "GET /api/v1/changelog", |
| 278 | 279 | mcp: "releases", |
| 280 | account: false, | |
| 279 | 281 | }); |
| 280 | 282 | expect(size).toBeLessThan(2048); |
| 281 | 283 | } |
test/llms-anonymous.test.ts +12 −9
| @@ -52,28 +52,31 @@ test("the anonymous text is small, varies by reader, and lists the open tools pl | ||
| 52 | 52 | // then the guide line (#12069, about 100 bytes); nothing else was cut to make room. |
| 53 | 53 | // 7.5 KiB since the check.txt door's line, and since explore and search (#12406) |
| 54 | 54 | // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes); |
| 55 | // 9 KiB so a longer origin, named 45 times, cannot tip it. | |
| 56 | expect(Buffer.byteLength(body)).toBeLessThan(9 * 1024); | |
| 55 | // 9 KiB so a longer origin, named 45 times, cannot tip it. 10 KiB with contribute and | |
| 56 | // releases opened to strangers. | |
| 57 | expect(Buffer.byteLength(body)).toBeLessThan(10 * 1024); | |
| 57 | 58 | expect(res.headers.get("vary")).toContain("Cookie"); |
| 58 | 59 | expect(res.headers.get("vary")).toContain("Authorization"); |
| 59 | 60 | const listed = section(body); |
| 60 | expect(listed).toHaveLength(6); | |
| 61 | expect(listed).toHaveLength(8); | |
| 61 | 62 | expect(listed[0]).toStartWith("- report: "); |
| 62 | 63 | expect(listed[1]).toStartWith("- start: "); |
| 63 | 64 | expect(listed[2]).toStartWith("- offer: "); |
| 64 | expect(listed[3]).toStartWith("- explore: "); | |
| 65 | expect(listed[4]).toStartWith("- search: "); | |
| 65 | expect(listed[3]).toStartWith("- contribute: "); | |
| 66 | expect(listed[4]).toStartWith("- explore: "); | |
| 67 | expect(listed[5]).toStartWith("- releases: "); | |
| 68 | expect(listed[6]).toStartWith("- search: "); | |
| 66 | 69 | // The open tools in the index are listed, so the rest is counted without them. |
| 67 | expect(listed[5]).toContain(`${TOOLS.length - 2} more tools with an account`); | |
| 68 | expect(listed[5]).toContain("tools/list"); | |
| 69 | expect(listed[5]).toContain("/contract/openapi.json"); | |
| 70 | expect(listed[7]).toContain(`${TOOLS.length - 4} more tools with an account`); | |
| 71 | expect(listed[7]).toContain("tools/list"); | |
| 72 | expect(listed[7]).toContain("/contract/openapi.json"); | |
| 70 | 73 | }); |
| 71 | 74 | |
| 72 | 75 | test("every tool the anonymous text names is one tools/list returns", async () => { |
| 73 | 76 | const names = section(await fetch(`${servers.url}/llms.txt`).then((r) => r.text())) |
| 74 | 77 | .map((l) => /^- ([a-z_]+): /.exec(l)?.[1]) |
| 75 | 78 | .filter((n): n is string => n !== undefined); |
| 76 | expect(names).toEqual(["report", "start", "offer", "explore", "search"]); | |
| 79 | expect(names).toEqual(["report", "start", "offer", "contribute", "explore", "releases", "search"]); | |
| 77 | 80 | const returned: string[] = []; |
| 78 | 81 | let cursor: string | undefined; |
| 79 | 82 | do { |
test/mcp-anonymous-session.test.ts +19
| @@ -80,3 +80,22 @@ test("a token that was sent and is not good is invalid_token, never the free lis | ||
| 80 | 80 | expect(res.headers.get("www-authenticate")).toContain('error="invalid_token"'); |
| 81 | 81 | } |
| 82 | 82 | }); |
| 83 | ||
| 84 | test("every mcp name anonymous /api/v1/here offers is listed, in the instructions, and callable with no token (#14365)", async () => { | |
| 85 | const here = (await (await fetch(`${servers.url}/api/v1/here`)).json()) as any; | |
| 86 | const offered = [...new Set(here.can.filter((a: any) => a.mcp !== undefined).map((a: any) => a.mcp))] as string[]; | |
| 87 | expect(offered).toContain("releases"); | |
| 88 | expect(offered).toContain("contribute"); | |
| 89 | const list = (await (await post({ jsonrpc: "2.0", id: 1, method: "tools/list" })).json()) as any; | |
| 90 | const listed = list.result.tools.map((t: { name: string }) => t.name); | |
| 91 | const init = (await (await post({ jsonrpc: "2.0", id: 2, method: "initialize", params: {} })).json()) as any; | |
| 92 | for (const name of offered) { | |
| 93 | expect(listed).toContain(name); | |
| 94 | expect(init.result.instructions).toContain(`\`${name}\``); | |
| 95 | const call = (await (await post({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name, arguments: {} } })).json()) as any; | |
| 96 | expect(call.error).toBeUndefined(); | |
| 97 | expect(call.result.content[0].type).toBe("text"); | |
| 98 | } | |
| 99 | const shipped = JSON.parse(((await (await post({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: "releases", arguments: {} } })).json()) as any).result.content[0].text); | |
| 100 | expect(shipped).toHaveProperty("live"); | |
| 101 | }); |
test/mcp-card.test.ts +2 −2
| @@ -5,7 +5,7 @@ import { tmpdir } from "node:os"; | ||
| 5 | 5 | import { join } from "node:path"; |
| 6 | 6 | import { createApp, type App } from "../src/app.ts"; |
| 7 | 7 | import { serve, type Servers } from "../src/http/server.ts"; |
| 8 | import { mcpCard } from "../src/core/mcp_card.ts"; | |
| 8 | import { mcpCard, TOKEN_FREE_TOOLS } from "../src/core/mcp_card.ts"; | |
| 9 | 9 | import { running } from "../src/kernel/version.ts"; |
| 10 | 10 | |
| 11 | 11 | describe("the MCP server card", () => { |
| @@ -42,7 +42,7 @@ describe("the MCP server card", () => { | ||
| 42 | 42 | expect(card.version).toBe(running().version); |
| 43 | 43 | expect(card.transport).toBe("streamable-http"); |
| 44 | 44 | expect(card.endpoint).toBe(`${base}/mcp`); |
| 45 | expect(card.tokenFreeTools).toEqual(["report", "offer", "start", "explore", "search"]); | |
| 45 | expect(card.tokenFreeTools).toEqual([...TOKEN_FREE_TOOLS]); | |
| 46 | 46 | |
| 47 | 47 | // Without a token the endpoint refuses everything but `report`. |
| 48 | 48 | const report = await fetch(card.endpoint, { |
new above
offline