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

Merged opened this

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

Merged

scout/forge:scout/14365-what-api-v1-here-offers-an-anonymous-age → main 5 commits fork

  • Merged. scout/14365-what-api-v1-here-offers-an-anonymous-age was merged into main as deaebeb.

Review

Sign in to review this change.
8 files changed +52 −15
src/actions/here.ts +2 −2
@@ -371,7 +371,7 @@ function keptActions(
371371 ];
372372 case "changelog":
373373 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") },
375375 { do: "follow it as a feed", http: "GET /changelog.atom", account: false },
376376 ];
377377 case "templates":
@@ -472,7 +472,6 @@ function forgeActions(
472472 ...tokenFree("offer"),
473473 },
474474 {
475 // The HTTP route is open, but the MCP tool is not, so no claim is made.
476475 do: "see how to help build this forge",
477476 http: "GET /api/v1/contribute",
478477 mcp: "contribute",
@@ -482,6 +481,7 @@ function forgeActions(
482481 do: "see what went live",
483482 http: "GET /api/v1/changelog",
484483 mcp: "releases",
484 ...tokenFree("releases"),
485485 },
486486 ...(getAgentStart(app.db) === "off"
487487 ? []
src/core/mcp_card.ts +1 −1
@@ -96,7 +96,7 @@ export function apiCatalog(origin: string) {
9696 * `http/mcp.ts` answers these and refuses the rest with 401. The card and
9797 * `/api/v1/here` both read this list, so they cannot drift.
9898 */
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"];
100100
101101 /** A thin plugin the forge ships for a harness: where its source is and its one install line. */
102102 export interface HarnessPlugin {
src/http/mcp.ts +13
@@ -32,6 +32,8 @@ import { html } from "../web/html.ts";
3232 import type { Router } from "./router.ts";
3333 import { clientBucket } from "./peer.ts";
3434 import { TOKEN_FREE_TOOLS } from "../core/mcp_card.ts";
35 import { shippedAnswer } from "../release/answer.ts";
36 import { welcome } from "../system/telemetry.ts";
3537 import { exploreRun, searchRun } from "./mcp/reads.ts";
3638 import { greppable, searchKind } from "../core/search.ts";
3739 import { strangerCodeSearch } from "./strangers.ts";
@@ -380,8 +382,19 @@ export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = {
380382 offer: offerAnswer,
381383 explore: (ctx, id, args) => readAnswer(ctx, id, "explore", args),
382384 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)) }] } }),
383387 };
384388
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
385398 /**
386399 * The token-free tools that are also ordinary tools (`report` and `start` are
387400 * 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", () => {
245245
246246 test("anonymous reaches exactly the token-free tools, and each refuses hostile arguments by name, leaving nothing behind", async () => {
247247 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"]);
249249 const reached: string[] = [];
250250 for (const name of toolNames()) {
251251 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", () => {
261261 do: "see how to help build this forge",
262262 http: "GET /api/v1/contribute",
263263 mcp: "contribute",
264 account: false,
264265 });
265266 expect(size).toBeLessThan(2048);
266267 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", () => {
276277 do: "see what went live",
277278 http: "GET /api/v1/changelog",
278279 mcp: "releases",
280 account: false,
279281 });
280282 expect(size).toBeLessThan(2048);
281283 }
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
5252 // then the guide line (#12069, about 100 bytes); nothing else was cut to make room.
5353 // 7.5 KiB since the check.txt door's line, and since explore and search (#12406)
5454 // 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);
5758 expect(res.headers.get("vary")).toContain("Cookie");
5859 expect(res.headers.get("vary")).toContain("Authorization");
5960 const listed = section(body);
60 expect(listed).toHaveLength(6);
61 expect(listed).toHaveLength(8);
6162 expect(listed[0]).toStartWith("- report: ");
6263 expect(listed[1]).toStartWith("- start: ");
6364 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: ");
6669 // 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");
7073 });
7174
7275 test("every tool the anonymous text names is one tools/list returns", async () => {
7376 const names = section(await fetch(`${servers.url}/llms.txt`).then((r) => r.text()))
7477 .map((l) => /^- ([a-z_]+): /.exec(l)?.[1])
7578 .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"]);
7780 const returned: string[] = [];
7881 let cursor: string | undefined;
7982 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
8080 expect(res.headers.get("www-authenticate")).toContain('error="invalid_token"');
8181 }
8282 });
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";
55 import { join } from "node:path";
66 import { createApp, type App } from "../src/app.ts";
77 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";
99 import { running } from "../src/kernel/version.ts";
1010
1111 describe("the MCP server card", () => {
@@ -42,7 +42,7 @@ describe("the MCP server card", () => {
4242 expect(card.version).toBe(running().version);
4343 expect(card.transport).toBe("streamable-http");
4444 expect(card.endpoint).toBe(`${base}/mcp`);
45 expect(card.tokenFreeTools).toEqual(["report", "offer", "start", "explore", "search"]);
45 expect(card.tokenFreeTools).toEqual([...TOKEN_FREE_TOOLS]);
4646
4747 // Without a token the endpoint refuses everything but `report`.
4848 const report = await fetch(card.endpoint, {

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs