Public: anyone can read this; the crew can change it.
An agent with no token offers a patch through the MCP: `offer` answers like `report`, same words as the HTTP door #12830
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/12814-an-agent-with-no-token-offers-a-patch-th → main 5 commits fork 1 thread · 1 unresolved
19 files
changed +289
−40
docs/MCP.md +8 −3
| @@ -241,11 +241,16 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`; | ||
| 241 | 241 | | `write_file` | — | No shell? Commit one file to a branch | 342 | |
| 242 | 242 | | `report` | — | Report a problem in a public repository, no account needed | 468 | |
| 243 | 243 | | `start` | `contribute` | Start building with no account: an account, a repo, a live app and a token in one call | 387 | |
| 244 | | `offer` | — | Offer a patch to a public repository, no account needed; a person reads it first | 362 | | |
| 244 | 245 | <!-- mcp-tools:end --> |
| 245 | 246 | |
| 246 | Four tools need no token, for the same reach as their HTTP doors: `report`, | |
| 247 | `start`, `explore` and `search` (`TOKEN_FREE_TOOLS` in `src/core/mcp_card.ts`). | |
| 248 | Called with no token, `explore` and `search` run the functions the HTTP doors | |
| 247 | Five tools need no token, for the same reach as their HTTP doors: `report`, | |
| 248 | `offer`, `start`, `explore` and `search` (`TOKEN_FREE_TOOLS` in `src/core/mcp_card.ts`). | |
| 249 | `offer` (`{ repo, title, body?, patch }`) calls `fileOffer`, the action behind | |
| 250 | `POST /api/v1/repos/{owner}/{name}/offers`, with the same refusal words (the 422 | |
| 251 | reasons, `rate_limited`, `queue_full`; a private repository answers `not_found`); | |
| 252 | it is the one open call whose body may be larger than 64 KB (a patch, up to | |
| 253 | `OFFER_REQUEST_MAX`). Called with no token, `explore` and `search` run the functions the HTTP doors | |
| 249 | 254 | call with no account, so they read only what is public (a private repository |
| 250 | 255 | is absent), and a stranger's code search takes the same per-address slot as |
| 251 | 256 | `/api/v1/search`. Called with a token they are unchanged and see what the |
src/actions/here.ts +6
| @@ -322,6 +322,12 @@ function forgeActions( | ||
| 322 | 322 | mcp: "report", |
| 323 | 323 | ...tokenFree("report"), |
| 324 | 324 | }, |
| 325 | { | |
| 326 | do: "offer a patch to a public repository", | |
| 327 | http: "POST /api/v1/repos/{owner}/{name}/offers", | |
| 328 | mcp: "offer", | |
| 329 | ...tokenFree("offer"), | |
| 330 | }, | |
| 325 | 331 | { |
| 326 | 332 | // The HTTP route is open, but the MCP tool is not, so no claim is made. |
| 327 | 333 | do: "see how to help build this forge", |
src/core/mcp_card.ts +1 −1
| @@ -58,7 +58,7 @@ export function apiCatalog(origin: string) { | ||
| 58 | 58 | * `http/mcp.ts` answers these and refuses the rest with 401. The card and |
| 59 | 59 | * `/api/v1/here` both read this list, so they cannot drift. |
| 60 | 60 | */ |
| 61 | export const TOKEN_FREE_TOOLS: readonly string[] = ["report", "start", "explore", "search"]; | |
| 61 | export const TOKEN_FREE_TOOLS: readonly string[] = ["report", "offer", "start", "explore", "search"]; | |
| 62 | 62 | |
| 63 | 63 | /** A thin plugin the forge ships for a harness: where its source is and its one install line. */ |
| 64 | 64 | export interface HarnessPlugin { |
src/http/mcp.ts +29 −7
| @@ -25,7 +25,8 @@ import type { User } from "../core/users.ts"; | ||
| 25 | 25 | import type { Ctx, Handler } from "./context.ts"; |
| 26 | 26 | import { running } from "../kernel/version.ts"; |
| 27 | 27 | import { bearerChallenge } from "./oauth.ts"; |
| 28 | import { body, boundedBody, json } from "./respond.ts"; | |
| 28 | import { body, json } from "./respond.ts"; | |
| 29 | import { readBounded } from "./limits.ts"; | |
| 29 | 30 | import { page, signInHref } from "../web/layout.ts"; |
| 30 | 31 | import { html } from "../web/html.ts"; |
| 31 | 32 | import type { Router } from "./router.ts"; |
| @@ -48,6 +49,8 @@ import { CONVERSATION_BRIEF } from "../crew/conversation_brief.ts"; | ||
| 48 | 49 | import { TOOLS } from "./mcp/tools.ts"; |
| 49 | 50 | import { READ_ONLY_REFUSAL, noToolNamed, withNextStep } from "./mcp/hints.ts"; |
| 50 | 51 | import { DEFAULT_TOOLS, wantsAll } from "./mcp/catalog.ts"; |
| 52 | import { OFFER_TOOL, offerAnswer } from "./mcp/offer.ts"; | |
| 53 | import { OFFER_REQUEST_MAX } from "../actions/offer.ts"; | |
| 51 | 54 | |
| 52 | 55 | const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"] as const; |
| 53 | 56 | /** The tools/list entries for these tools, then `report`: what is served, and what docs/MCP.md measures. */ |
| @@ -64,7 +67,7 @@ export function toolEntries(tools: readonly (typeof TOOLS)[number][]) { | ||
| 64 | 67 | ? {} |
| 65 | 68 | : { _meta: { ui: { resourceUri: CARD_URI(CARD_OF_TOOL[t.name]!) }, "openai/outputTemplate": CARD_URI(CARD_OF_TOOL[t.name]!) } }), |
| 66 | 69 | })), |
| 67 | ...[REPORT_TOOL, START_TOOL].map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })), | |
| 70 | ...[REPORT_TOOL, START_TOOL, OFFER_TOOL].map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })), | |
| 68 | 71 | ]; |
| 69 | 72 | } |
| 70 | 73 | |
| @@ -281,6 +284,7 @@ function rpcOne( | ||
| 281 | 284 | * public repository (`actions/reports.ts`), with the same limits as the |
| 282 | 285 | * page and the API. Everything else here needs a token. |
| 283 | 286 | */ |
| 287 | export { OFFER_TOOL }; | |
| 284 | 288 | export const REPORT_TOOL = { |
| 285 | 289 | name: "report", |
| 286 | 290 | /** Its line in /llms.txt's `## MCP tools`; never sent to a client. */ |
| @@ -338,6 +342,7 @@ type FreeHandler = (ctx: Ctx, id: unknown, args: Args) => unknown; | ||
| 338 | 342 | export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = { |
| 339 | 343 | report: reportAnswer, |
| 340 | 344 | start: startAnswer, |
| 345 | offer: offerAnswer, | |
| 341 | 346 | explore: (ctx, id, args) => readAnswer(ctx, id, "explore", args), |
| 342 | 347 | search: (ctx, id, args) => readAnswer(ctx, id, "search", args), |
| 343 | 348 | }; |
| @@ -496,7 +501,7 @@ const NOT_HERE = (allow: string): Response => | ||
| 496 | 501 | new Response(null, { status: 405, headers: { allow } }); |
| 497 | 502 | |
| 498 | 503 | /** Every tool name the forge lists, admin-only ones included. */ |
| 499 | export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name, START_TOOL.name]; | |
| 504 | export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name, START_TOOL.name, OFFER_TOOL.name]; | |
| 500 | 505 | |
| 501 | 506 | /** What each tool declares about itself, for the test that walks them all. */ |
| 502 | 507 | export const toolRegistry = () => |
| @@ -508,6 +513,16 @@ export const toolRegistry = () => | ||
| 508 | 513 | plansOnly: (args: Args) => plansOnly(t, args), |
| 509 | 514 | })); |
| 510 | 515 | |
| 516 | /** Bytes as a JSON object, or `{}` for anything else. */ | |
| 517 | function parseObject(bytes: Uint8Array): Record<string, unknown> { | |
| 518 | try { | |
| 519 | const value: unknown = JSON.parse(new TextDecoder().decode(bytes)); | |
| 520 | return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {}; | |
| 521 | } catch { | |
| 522 | return {}; | |
| 523 | } | |
| 524 | } | |
| 525 | ||
| 511 | 526 | export function mcpRoutes(router: Router<Handler>): void { |
| 512 | 527 | router.add("POST", "/mcp", async (ctx) => { |
| 513 | 528 | const user = ctx.auth.user; |
| @@ -525,12 +540,19 @@ export function mcpRoutes(router: Router<Handler>): void { | ||
| 525 | 540 | } |
| 526 | 541 | // A stranger may call the token-free tools and nothing else, so their body is read |
| 527 | 542 | // to a hard byte limit and no further. |
| 528 | const message = await boundedBody(ctx.request, REQUEST_MAX); | |
| 529 | if (message === "too_large") | |
| 543 | // An offer carries a patch, so it may be larger; every other call keeps the small limit. | |
| 544 | const bytes = await readBounded(ctx.request, OFFER_REQUEST_MAX); | |
| 545 | const parsed = bytes === "too_large" ? {} : parseObject(bytes); | |
| 546 | const params = parsed["params"]; | |
| 547 | const offering = | |
| 548 | typeof params === "object" && params !== null && (params as Record<string, unknown>)["name"] === "offer"; | |
| 549 | // The cap is on the bytes that arrived, not on a re-serialization of them. | |
| 550 | if (bytes === "too_large" || (!offering && bytes.byteLength > REQUEST_MAX)) | |
| 530 | 551 | return json( |
| 531 | 552 | { error: "too_large", message: `at most ${REQUEST_MAX} bytes without a token` }, |
| 532 | 553 | 413, |
| 533 | 554 | ); |
| 555 | const message = parsed; | |
| 534 | 556 | const reported = openToolCall(ctx, message, false); |
| 535 | 557 | if (reported !== undefined) return json(await reported); |
| 536 | 558 | // The refusal keeps the OAuth challenge a client starts from, and names |
| @@ -538,9 +560,9 @@ export function mcpRoutes(router: Router<Handler>): void { | ||
| 538 | 560 | return new Response( |
| 539 | 561 | JSON.stringify({ |
| 540 | 562 | error: "unauthorized", |
| 541 | hint: "Send `Authorization: Bearer <token>` with a token you hold, then repeat the call; without one, only the `report` tool answers.", | |
| 563 | hint: "Send `Authorization: Bearer <token>` with a token you hold, then repeat the call; without one, only `report`, `start` and `offer` answer.", | |
| 542 | 564 | message: |
| 543 | "send a forge token: Authorization: Bearer <token>. Without one, the tool `start` (tools/call, name \"start\", arguments {name, description?, agent?}) makes you an account, a repo and a live app with a token; and the tool `report` (tools/call, name \"report\", arguments {repo, title, body?, page?, agent?}) files a problem report on a public repository; see /llms.txt", | |
| 565 | "send a forge token: Authorization: Bearer <token>. Without one, the tool `start` (tools/call, name \"start\", arguments {name, description?, agent?}) makes you an account, a repo and a live app with a token; the tool `report` (tools/call, name \"report\", arguments {repo, title, body?, page?, agent?}) files a problem report on a public repository; and the tool `offer` (tools/call, name \"offer\", arguments {repo, title, patch}) offers a patch to a public repository; see /llms.txt", | |
| 544 | 566 | report: { |
| 545 | 567 | method: "tools/call", |
| 546 | 568 | name: "report", |
src/http/mcp/load.ts +2 −2
| @@ -36,8 +36,8 @@ export function loadMcp(): Promise<Mcp> { | ||
| 36 | 36 | .then(async (tools) => [await import("../mcp.ts"), tools] as const) |
| 37 | 37 | .then( |
| 38 | 38 | ([mcp, tools]) => { |
| 39 | setMcpTools(tools.TOOLS, [mcp.REPORT_TOOL, mcp.START_TOOL]); | |
| 40 | setCardTools([...tools.TOOLS, mcp.REPORT_TOOL, mcp.START_TOOL]); | |
| 39 | setMcpTools(tools.TOOLS, [mcp.REPORT_TOOL, mcp.START_TOOL, mcp.OFFER_TOOL]); | |
| 40 | setCardTools([...tools.TOOLS, mcp.REPORT_TOOL, mcp.START_TOOL, mcp.OFFER_TOOL]); | |
| 41 | 41 | return { ...mcp, ...tools }; |
| 42 | 42 | }, |
| 43 | 43 | (error: unknown) => { |
src/http/mcp/offer.ts added +74
| @@ -0,0 +1,74 @@ | ||
| 1 | /** | |
| 2 | * `offer`, the third tool open without a token: a stranger's patch on a public repository, | |
| 3 | * through the same action and words as `POST /api/v1/repos/:owner/:name/offers` | |
| 4 | * (`actions/offer.ts`). It becomes a pull a person reads before anything runs. A call with a | |
| 5 | * token is treated the same: this door is for outsiders, and a private repository is | |
| 6 | * `not_found` whoever asks. | |
| 7 | */ | |
| 8 | import { fileOffer, OFFER_BODY_MAX, OFFER_HINT, OFFER_RECEIVED, OFFER_TITLE_MAX, OFFER_WORDS, type OfferRefusal } from "../../actions/offer.ts"; | |
| 9 | import { getRepo } from "../../core/repos.ts"; | |
| 10 | import type { Ctx } from "../context.ts"; | |
| 11 | import { clientBucket } from "../peer.ts"; | |
| 12 | import { retryAfterOf } from "../respond.ts"; | |
| 13 | import { REPO_ARG, str, type Args } from "./shared.ts"; | |
| 14 | ||
| 15 | /** A full queue drains as people read offers; no clock says when: a minute, as the HTTP door. */ | |
| 16 | const QUEUE_RETRY = 60; | |
| 17 | ||
| 18 | export const OFFER_TOOL = { | |
| 19 | name: "offer", | |
| 20 | /** Its line in /llms.txt's `## MCP tools`; never sent to a client. */ | |
| 21 | doc: "`{ repo, title, body?, patch }`: offer a change to a public repository with no token; `patch` is a unified diff (`git diff`) of text files, at most 200 KB; it becomes a pull a person reads before anything runs", | |
| 22 | writes: true, | |
| 23 | description: "Offer a patch to a public repository, no account needed; a person reads it first.", | |
| 24 | inputSchema: { | |
| 25 | type: "object", | |
| 26 | properties: { | |
| 27 | repo: REPO_ARG, | |
| 28 | title: { type: "string", maxLength: OFFER_TITLE_MAX }, | |
| 29 | body: { type: "string", maxLength: OFFER_BODY_MAX }, | |
| 30 | patch: { type: "string", description: "Unified diff." }, | |
| 31 | }, | |
| 32 | required: ["repo", "title", "patch"], | |
| 33 | }, | |
| 34 | } as const; | |
| 35 | ||
| 36 | const NEXT = "Next: call `offer` with `repo` as owner/name of a public repository, a `title` and a `patch`."; | |
| 37 | ||
| 38 | export async function offerAnswer(ctx: Ctx, id: unknown, args: Args): Promise<unknown> { | |
| 39 | const text = (t: string, isError = false) => ({ | |
| 40 | jsonrpc: "2.0", | |
| 41 | id, | |
| 42 | result: { content: [{ type: "text", text: t }], ...(isError ? { isError } : {}) }, | |
| 43 | }); | |
| 44 | const notFound = () => text(`not_found: no such public repository. ${NEXT}`, true); | |
| 45 | const [owner, name, ...rest] = str(args["repo"]).split("/"); | |
| 46 | const repo = owner && name && rest.length === 0 ? getRepo(ctx.app.db, owner, name) : undefined; | |
| 47 | if (repo === undefined) return notFound(); | |
| 48 | const filed = await fileOffer( | |
| 49 | ctx.app, | |
| 50 | repo, | |
| 51 | { title: args["title"], body: args["body"], patch: args["patch"] }, | |
| 52 | clientBucket(ctx.request), | |
| 53 | ); | |
| 54 | if (!filed.ok) { | |
| 55 | const e = filed.error; | |
| 56 | if (e.error === "not_found") return notFound(); | |
| 57 | if (e.error === "rate_limited") | |
| 58 | return text(`rate_limited: too many offers; try again in ${retryAfterOf(e.retryAfter)} seconds. Next: wait, then call \`offer\` again.`, true); | |
| 59 | if (e.error === "queue_full") | |
| 60 | return text(`queue_full: this repository has many offers waiting; try again in ${QUEUE_RETRY} seconds. Next: wait, then call \`offer\` again.`, true); | |
| 61 | if (e.error === "unavailable") | |
| 62 | return text(`unavailable: offers cannot be taken just now; try again in ${QUEUE_RETRY} seconds. Next: wait, then call \`offer\` again.`, true); | |
| 63 | const why: OfferRefusal = e.error; | |
| 64 | return text(`${why}: ${OFFER_WORDS[why]}; ${OFFER_HINT}. Next: call \`offer\` again with the \`${why.startsWith("patch") ? "patch" : why.startsWith("body") ? "body" : "title"}\` fixed.`, true); | |
| 65 | } | |
| 66 | return text( | |
| 67 | JSON.stringify({ | |
| 68 | number: filed.value.number, | |
| 69 | state: "open", | |
| 70 | url: `${ctx.url.origin}/${repo.ownerName}/${repo.name}/pulls/${filed.value.number}`, | |
| 71 | message: OFFER_RECEIVED, | |
| 72 | }), | |
| 73 | ); | |
| 74 | } |
src/http/mcp_table.ts +2 −1
| @@ -5,6 +5,7 @@ | ||
| 5 | 5 | * markers; test/mcp-table.test.ts fails, naming the tool, when they differ. |
| 6 | 6 | */ |
| 7 | 7 | import { REPORT_TOOL, START_TOOL, toolEntries } from "./mcp.ts"; |
| 8 | import { OFFER_TOOL } from "./mcp/offer.ts"; | |
| 8 | 9 | import { TOOLS } from "./mcp/tools.ts"; |
| 9 | 10 | |
| 10 | 11 | export const TABLE_BEGIN = "<!-- mcp-tools:begin (generated by src/http/mcp_table.ts; edit the code, then run `bun scripts/mcp-table.ts`) -->"; |
| @@ -70,7 +71,7 @@ export function firstSentence(text: string): string { | ||
| 70 | 71 | |
| 71 | 72 | export function toolRows(): ToolRow[] { |
| 72 | 73 | const entries = toolEntries(TOOLS); |
| 73 | const schemas = new Map<string, unknown>([...TOOLS.map((t) => [t.name, t.inputSchema] as const), [REPORT_TOOL.name, REPORT_TOOL.inputSchema], [START_TOOL.name, START_TOOL.inputSchema]]); | |
| 74 | const schemas = new Map<string, unknown>([...TOOLS.map((t) => [t.name, t.inputSchema] as const), [REPORT_TOOL.name, REPORT_TOOL.inputSchema], [START_TOOL.name, START_TOOL.inputSchema], [OFFER_TOOL.name, OFFER_TOOL.inputSchema]]); | |
| 74 | 75 | return entries.map((entry) => ({ |
| 75 | 76 | name: entry.name, |
| 76 | 77 | doors: doorsOf(schemas.get(entry.name)), |
test/agent-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 } from "../src/app.ts"; |
| 7 | 7 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 8 | import { REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 8 | import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 9 | 9 | import { serve, type Servers } from "../src/http/server.ts"; |
| 10 | 10 | |
| 11 | 11 | describe("the agent card", () => { |
| @@ -47,7 +47,7 @@ describe("the agent card", () => { | ||
| 47 | 47 | expect(mcp.tools.length).toBeGreaterThan(10); |
| 48 | 48 | expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...mcp.tools].sort()); |
| 49 | 49 | // The list tools/list serves, not the one both cards are built from. |
| 50 | const served = [...TOOLS, REPORT_TOOL, START_TOOL].map((t) => t.name); | |
| 50 | const served = [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL].map((t) => t.name); | |
| 51 | 51 | expect(agent.skills.map((s: any) => s.id).sort()).toEqual([...new Set(served)].sort()); |
| 52 | 52 | for (const s of agent.skills) expect(s.description.length).toBeGreaterThan(0); |
| 53 | 53 | }); |
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", "report", "search", "start"]); | |
| 248 | expect(free).toEqual(["explore", "offer", "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/llms-anonymous.test.ts +11 −10
| @@ -49,27 +49,28 @@ test("the anonymous text is small, varies by reader, and lists the open tools pl | ||
| 49 | 49 | // 6.5 KiB until the three doors (#12015, about 440 bytes) opened the text, |
| 50 | 50 | // then the guide line (#12069, about 100 bytes); nothing else was cut to make room. |
| 51 | 51 | // 7.5 KiB since the check.txt door's line, and since explore and search (#12406) |
| 52 | // moved from counted to listed: 8 KiB. | |
| 53 | expect(Buffer.byteLength(body)).toBeLessThan(8 * 1024); | |
| 52 | // moved from counted to listed: 8 KiB. 8.5 KiB with offer's line (about 250 bytes). | |
| 53 | expect(Buffer.byteLength(body)).toBeLessThan(8.5 * 1024); | |
| 54 | 54 | expect(res.headers.get("vary")).toContain("Cookie"); |
| 55 | 55 | expect(res.headers.get("vary")).toContain("Authorization"); |
| 56 | 56 | const listed = section(body); |
| 57 | expect(listed).toHaveLength(5); | |
| 57 | expect(listed).toHaveLength(6); | |
| 58 | 58 | expect(listed[0]).toStartWith("- report: "); |
| 59 | 59 | expect(listed[1]).toStartWith("- start: "); |
| 60 | expect(listed[2]).toStartWith("- explore: "); | |
| 61 | expect(listed[3]).toStartWith("- search: "); | |
| 60 | expect(listed[2]).toStartWith("- offer: "); | |
| 61 | expect(listed[3]).toStartWith("- explore: "); | |
| 62 | expect(listed[4]).toStartWith("- search: "); | |
| 62 | 63 | // The open tools in the index are listed, so the rest is counted without them. |
| 63 | expect(listed[4]).toContain(`${TOOLS.length - 2} more tools with an account`); | |
| 64 | expect(listed[4]).toContain("tools/list"); | |
| 65 | expect(listed[4]).toContain("/contract/openapi.json"); | |
| 64 | expect(listed[5]).toContain(`${TOOLS.length - 2} more tools with an account`); | |
| 65 | expect(listed[5]).toContain("tools/list"); | |
| 66 | expect(listed[5]).toContain("/contract/openapi.json"); | |
| 66 | 67 | }); |
| 67 | 68 | |
| 68 | 69 | test("every tool the anonymous text names is one tools/list returns", async () => { |
| 69 | 70 | const names = section(await fetch(`${servers.url}/llms.txt`).then((r) => r.text())) |
| 70 | 71 | .map((l) => /^- ([a-z_]+): /.exec(l)?.[1]) |
| 71 | 72 | .filter((n): n is string => n !== undefined); |
| 72 | expect(names).toEqual(["report", "start", "explore", "search"]); | |
| 73 | expect(names).toEqual(["report", "start", "offer", "explore", "search"]); | |
| 73 | 74 | const returned: string[] = []; |
| 74 | 75 | let cursor: string | undefined; |
| 75 | 76 | do { |
| @@ -88,7 +89,7 @@ test("a signed-in reader still gets every tool and report", async () => { | ||
| 88 | 89 | const body = await fetch(`${servers.url}/llms.txt`, { |
| 89 | 90 | headers: { authorization: `Bearer ${token}` }, |
| 90 | 91 | }).then((r) => r.text()); |
| 91 | expect(section(body)).toHaveLength(TOOLS.length + 2); | |
| 92 | expect(section(body)).toHaveLength(TOOLS.length + 3); | |
| 92 | 93 | }); |
| 93 | 94 | |
| 94 | 95 | test("the OpenAPI line names ?tag= and the tags", async () => { |
test/llms-etag.test.ts +2 −2
| @@ -9,7 +9,7 @@ import { createToken } from "../src/core/tokens.ts"; | ||
| 9 | 9 | import { createUser } from "../src/core/users.ts"; |
| 10 | 10 | import { callableBy, setMcpTools, type Listed } from "../src/web/llms_tools.ts"; |
| 11 | 11 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 12 | import { REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 12 | import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 13 | 13 | |
| 14 | 14 | let dataDir: string; |
| 15 | 15 | let app: ReturnType<typeof createApp>; |
| @@ -71,7 +71,7 @@ test("a changed tool list changes the anonymous ETag", async () => { | ||
| 71 | 71 | const after = (await get()).headers.get("etag"); |
| 72 | 72 | expect(after).not.toBe(before); |
| 73 | 73 | } finally { |
| 74 | setMcpTools(TOOLS, [REPORT_TOOL, START_TOOL]); | |
| 74 | setMcpTools(TOOLS, [REPORT_TOOL, START_TOOL, OFFER_TOOL]); | |
| 75 | 75 | } |
| 76 | 76 | }); |
| 77 | 77 |
test/llms-tools.test.ts +2 −2
| @@ -6,7 +6,7 @@ import { tmpdir } from "node:os"; | ||
| 6 | 6 | import { join } from "node:path"; |
| 7 | 7 | import { createApp } from "../src/app.ts"; |
| 8 | 8 | import { serve, type Servers } from "../src/http/server.ts"; |
| 9 | import { REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 9 | import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts"; | |
| 10 | 10 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 11 | 11 | import { createToken } from "../src/core/tokens.ts"; |
| 12 | 12 | import { createUser } from "../src/core/users.ts"; |
| @@ -46,7 +46,7 @@ describe("/llms.txt MCP tools", () => { | ||
| 46 | 46 | expect(start).toBeGreaterThan(-1); |
| 47 | 47 | const end = lines.findIndex((l, i) => i > start && l.startsWith("## ")); |
| 48 | 48 | const listed = lines.slice(start + 1, end).filter((l) => l.startsWith("- ")); |
| 49 | const expected = [...TOOLS, REPORT_TOOL, START_TOOL].map((t: Listed) => { | |
| 49 | const expected = [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL].map((t: Listed) => { | |
| 50 | 50 | const admin = t.adminOnly === true || t.needsAdminScope === true ? " (admin)" : ""; |
| 51 | 51 | return `- ${t.name}: ${(t.doc ?? t.description).replace(/\s+/g, " ").trim()}${admin}${t.writes ? " (writes)" : ""}${TOKEN_FREE_TOOLS.includes(t.name) ? " (no account)" : ""}`; |
| 52 | 52 | }); |
test/mcp-card.test.ts +1 −1
| @@ -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", "start", "explore", "search"]); | |
| 45 | expect(card.tokenFreeTools).toEqual(["report", "offer", "start", "explore", "search"]); | |
| 46 | 46 | |
| 47 | 47 | // Without a token the endpoint refuses everything but `report`. |
| 48 | 48 | const report = await fetch(card.endpoint, { |
test/mcp-ro-refuses-writes.test.ts +1 −1
| @@ -139,7 +139,7 @@ describe("every MCP tool that writes refuses a read-only token", () => { | ||
| 139 | 139 | if (t.annotations?.readOnlyHint === true) continue; |
| 140 | 140 | // `report` and `start` are the token-free tools: a stranger may call |
| 141 | 141 | // them, so an `ro` token is no less than no token; fuzz-mcp holds them. |
| 142 | if (t.name === "report" || t.name === "start") continue; | |
| 142 | if (t.name === "report" || t.name === "start" || t.name === "offer") continue; | |
| 143 | 143 | const before = rows(); |
| 144 | 144 | const got = await call(t.name, writeArgs(t.name)); |
| 145 | 145 | const after = rows(); |
test/mcp-table.test.ts +1 −1
| @@ -89,5 +89,5 @@ test("the bytes are those of an admin's real tools/list response", async () => { | ||
| 89 | 89 | }, 30_000); |
| 90 | 90 | |
| 91 | 91 | test("the entry builder is the one tools/list uses", () => { |
| 92 | expect(toolEntries(TOOLS).length).toBe(TOOLS.length + 2); | |
| 92 | expect(toolEntries(TOOLS).length).toBe(TOOLS.length + 3); | |
| 93 | 93 | }); |
test/mcp-tools.test.ts +6 −5
| @@ -10,7 +10,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises"; | ||
| 10 | 10 | import { tmpdir } from "node:os"; |
| 11 | 11 | import { join } from "node:path"; |
| 12 | 12 | import { indexText, toolFiles } from "../scripts/mcp-tools.ts"; |
| 13 | import { REPORT_TOOL, START_TOOL, toolNames } from "../src/http/mcp.ts"; | |
| 13 | import { OFFER_TOOL, REPORT_TOOL, START_TOOL, toolNames } from "../src/http/mcp.ts"; | |
| 14 | 14 | import { byName } from "../src/http/mcp/shared.ts"; |
| 15 | 15 | import { TOOLS } from "../src/http/mcp/tools.ts"; |
| 16 | 16 | import { toolsSection } from "../src/web/llms_tools.ts"; |
| @@ -43,7 +43,8 @@ describe("the gathered tools", () => { | ||
| 43 | 43 | test("are the files, sorted, one each, and `report` beside them", () => { |
| 44 | 44 | expect(TOOLS.map((t) => t.name)).toEqual(files); |
| 45 | 45 | expect(files).not.toContain("report"); |
| 46 | expect(toolNames()).toEqual([...files, "report", "start"]); | |
| 46 | expect(files).not.toContain("offer"); | |
| 47 | expect(toolNames()).toEqual([...files, "report", "start", "offer"]); | |
| 47 | 48 | }); |
| 48 | 49 | |
| 49 | 50 | test("the index is current: run `bun scripts/mcp-tools.ts`", () => { |
| @@ -66,12 +67,12 @@ describe("the gathered tools", () => { | ||
| 66 | 67 | |
| 67 | 68 | describe("the live tool list", () => { |
| 68 | 69 | test("every tool's `doc` is its line in /llms.txt's tools section", () => { |
| 69 | const section = toolsSection([...TOOLS, REPORT_TOOL, START_TOOL]); | |
| 70 | for (const t of [...TOOLS, REPORT_TOOL, START_TOOL]) { | |
| 70 | const section = toolsSection([...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL]); | |
| 71 | for (const t of [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL]) { | |
| 71 | 72 | const line = section.find((l) => l.startsWith(`- ${t.name}: `)); |
| 72 | 73 | expect([t.name, line?.includes(t.doc ?? t.description) ?? false]).toEqual([t.name, true]); |
| 73 | 74 | } |
| 74 | expect(section.filter((l) => l.startsWith("- ")).length).toBe(TOOLS.length + 2); | |
| 75 | expect(section.filter((l) => l.startsWith("- ")).length).toBe(TOOLS.length + 3); | |
| 75 | 76 | }); |
| 76 | 77 | |
| 77 | 78 | test("a pull adding a tool file and its index line needs no docs file", async () => { |
test/mcp.test.ts +2 −1
| @@ -40,9 +40,10 @@ import { askForReviews } from "./helpers/reviews.ts"; | ||
| 40 | 40 | |
| 41 | 41 | /** tools/list's order: the tools by name, then `report`. */ |
| 42 | 42 | const sortedThenReport = (names: string[]): string[] => [ |
| 43 | ...names.filter((n) => n !== "report" && n !== "start").sort((a, b) => a.localeCompare(b)), | |
| 43 | ...names.filter((n) => n !== "report" && n !== "start" && n !== "offer").sort((a, b) => a.localeCompare(b)), | |
| 44 | 44 | "report", |
| 45 | 45 | "start", |
| 46 | "offer", | |
| 46 | 47 | ]; |
| 47 | 48 | |
| 48 | 49 | describe("the forge over MCP", () => { |
test/offer-limits.test.ts +24
| @@ -81,6 +81,15 @@ describe("offer limits", () => { | ||
| 81 | 81 | }); |
| 82 | 82 | expect(res.status).toBe(429); |
| 83 | 83 | expect(((await res.json()) as any).error).toBe("queue_full"); |
| 84 | // The MCP door, with no token, says the same word. | |
| 85 | const viaMcp = await fetch(`${servers.url}/mcp`, { | |
| 86 | method: "POST", | |
| 87 | headers: { "content-type": "application/json", "x-forwarded-for": "10.9.0.2" }, | |
| 88 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "offer", arguments: { repo: "alice/queue", title: "late", patch: patchFor(102) } } }), | |
| 89 | }); | |
| 90 | const said = ((await viaMcp.json()) as any).result; | |
| 91 | expect(said.isError).toBe(true); | |
| 92 | expect(said.content[0].text.startsWith("queue_full: ")).toBe(true); | |
| 84 | 93 | }, 60_000); |
| 85 | 94 | |
| 86 | 95 | test("one repository takes 10 offers a minute from different sources, then 429 over HTTP", async () => { |
| @@ -98,6 +107,21 @@ describe("offer limits", () => { | ||
| 98 | 107 | expect(res.headers.get("retry-after")).not.toBeNull(); |
| 99 | 108 | }, 60_000); |
| 100 | 109 | |
| 110 | test("a stranger's report is capped on the bytes that arrived: padded JSON over 64 KB is 413, an offer of that size is not", async () => { | |
| 111 | const call = (name: string, args: unknown, pad: number) => | |
| 112 | fetch(`${servers.url}/mcp`, { | |
| 113 | method: "POST", | |
| 114 | headers: { "content-type": "application/json", "x-forwarded-for": "10.9.2.1" }, | |
| 115 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) + " ".repeat(pad), | |
| 116 | }); | |
| 117 | // Small once parsed and re-serialized, over the limit on the wire. | |
| 118 | const report = await call("report", { repo: "alice/perrepo", title: "x" }, 70_000); | |
| 119 | expect(report.status).toBe(413); | |
| 120 | expect(((await report.json()) as any).error).toBe("too_large"); | |
| 121 | const offer = await call("offer", { repo: "alice/nowhere", title: "x", patch: patchFor(1) }, 70_000); | |
| 122 | expect(offer.status).toBe(200); | |
| 123 | }); | |
| 124 | ||
| 101 | 125 | test("the forge takes 30 offers a minute across repositories, then refuses even a repository with room", async () => { |
| 102 | 126 | // A fresh forge: its own limits, and the clock stands still inside one minute. The limits are |
| 103 | 127 | // taken before any git work, so an offer to an empty repository (patch_does_not_apply, cheap) |
test/offer-stranger.test.ts +114
| @@ -158,4 +158,118 @@ describe("offers from outside", () => { | ||
| 158 | 158 | const spec: any = await (await fetch(`${servers.url}/contract/openapi.json`)).json(); |
| 159 | 159 | expect(Object.keys(spec.paths).some((p) => p.endsWith("/offers"))).toBe(true); |
| 160 | 160 | }); |
| 161 | ||
| 162 | describe("through the MCP `offer` tool, with no token", () => { | |
| 163 | let fresh: Repo; | |
| 164 | // Their own repositories: the per-repository minute is shared by every test above. | |
| 165 | beforeAll(async () => { | |
| 166 | for (const name of ["viamcp"]) { | |
| 167 | const made = await createRepo(app, alice, { name, visibility: "public" }); | |
| 168 | if (!made.ok) throw new Error(String(made.error)); | |
| 169 | const r = getRepo(app.db, "alice", name)!; | |
| 170 | const seeded = await editFiles(app, alice, r, { files: [{ path: "hello.txt", content: "hello\nworld\n" }], message: "first" }); | |
| 171 | if (!seeded.ok) throw new Error(JSON.stringify(seeded.error)); | |
| 172 | fresh = r; | |
| 173 | } | |
| 174 | }, 30_000); | |
| 175 | ||
| 176 | const mcp = async (args: Record<string, unknown>, source = `10.2.0.${n++}`) => { | |
| 177 | const res = await fetch(`${servers.url}/mcp`, { | |
| 178 | method: "POST", | |
| 179 | headers: { "content-type": "application/json", "x-forwarded-for": source }, | |
| 180 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "offer", arguments: args } }), | |
| 181 | }); | |
| 182 | expect(res.status).toBe(200); | |
| 183 | const r = ((await res.json()) as any).result; | |
| 184 | return { error: r.isError === true, text: r.content[0].text as string }; | |
| 185 | }; | |
| 186 | ||
| 187 | test("the happy path stores the same stranger's pull as the HTTP door", async () => { | |
| 188 | const count = () => app.db.query<{ n: number }, [string]>("SELECT COUNT(*) AS n FROM pull JOIN issue ON issue.id = pull.issue_id WHERE issue.repo_id = ?1").get(fresh.id)!.n; | |
| 189 | const before = count(); | |
| 190 | const out = await mcp({ repo: "alice/viamcp", title: "Say there", body: "friendlier", patch: PATCH }); | |
| 191 | expect(out.error).toBe(false); | |
| 192 | const done = JSON.parse(out.text); | |
| 193 | expect(done.state).toBe("open"); | |
| 194 | expect(done.url).toBe(`${servers.url}/alice/viamcp/pulls/${done.number}`); | |
| 195 | expect(count()).toBe(before + 1); | |
| 196 | const pull = getPull(app.db, fresh.id, done.number)!; | |
| 197 | expect(isStrangerPull(app.db, fresh, pull)).toBe(true); | |
| 198 | expect(guestWaits(app.db, pull)).toBe(true); | |
| 199 | }); | |
| 200 | ||
| 201 | test("a patch larger than the small stranger limit still arrives", async () => { | |
| 202 | const pad = "x".repeat(70 * 1024); | |
| 203 | const big = `diff --git a/pad.txt b/pad.txt\nnew file mode 100644\n--- /dev/null\n+++ b/pad.txt\n@@ -0,0 +1 @@\n+${pad}\n`; | |
| 204 | expect((await mcp({ repo: "alice/viamcp", title: "Pad", patch: big })).error).toBe(false); | |
| 205 | }); | |
| 206 | ||
| 207 | test("every 422 reason is the HTTP door's word", async () => { | |
| 208 | const cases: [Record<string, unknown>, string][] = [ | |
| 209 | [{ title: "", patch: PATCH }, "empty_title"], | |
| 210 | [{ title: "t".repeat(201), patch: PATCH }, "title_too_long"], | |
| 211 | [{ title: "t", body: "b".repeat(8001), patch: PATCH }, "body_too_long"], | |
| 212 | [{ title: "t" }, "patch_missing"], | |
| 213 | [{ title: "t", patch: "x".repeat(OFFER_PATCH_MAX + 1) }, "patch_too_large"], | |
| 214 | [{ title: "t", patch: "a\0b" }, "patch_not_text"], | |
| 215 | [{ title: "t", patch: PATCH.replace(/hello\.txt/g, ".git/config") }, "patch_touches_git"], | |
| 216 | [{ title: "t", patch: PATCH.replace(/hello\.txt/g, "../x") }, "patch_bad_path"], | |
| 217 | [{ title: "t", patch: PATCH.replace("-world", "-nothing here") }, "patch_does_not_apply"], | |
| 218 | ]; | |
| 219 | for (const [args, reason] of cases) { | |
| 220 | const out = await mcp({ repo: "alice/viamcp", ...args }); | |
| 221 | const http: any = await (await offer({ ...args }, "/api/v1/repos/alice/viamcp/offers")).json(); | |
| 222 | expect(out.error).toBe(true); | |
| 223 | expect(out.text.startsWith(`${reason}: `)).toBe(true); | |
| 224 | expect(http.error).toBe(reason); | |
| 225 | expect(out.text).toContain(http.message); | |
| 226 | } | |
| 227 | }); | |
| 228 | ||
| 229 | test("a private, a missing and a malformed repository answer not_found", async () => { | |
| 230 | const before = branches(); | |
| 231 | for (const repo of ["alice/secret", "alice/none", "alice", "a/b/c", ""]) { | |
| 232 | const out = await mcp({ repo, title: "t", patch: PATCH }); | |
| 233 | expect(out.error).toBe(true); | |
| 234 | expect(out.text.startsWith("not_found: ")).toBe(true); | |
| 235 | } | |
| 236 | expect(await branches()).toEqual(await before); | |
| 237 | }); | |
| 238 | ||
| 239 | test("one source is limited to three a minute (rate_limited)", async () => { | |
| 240 | // A forge of its own: the forge-wide minute is spent by the tests above. | |
| 241 | const dir = await mkdtemp(join(tmpdir(), "forge-offer-mcp-limit-")); | |
| 242 | const own = createApp({ dataDir: dir, port: 0 }); | |
| 243 | const srv = await serve(own); | |
| 244 | try { | |
| 245 | const u = await createUser(own.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true }); | |
| 246 | if (!u.ok) throw new Error(u.error); | |
| 247 | const made = await createRepo(own, u.value, { name: "game", visibility: "public" }); | |
| 248 | if (!made.ok) throw new Error(String(made.error)); | |
| 249 | await editFiles(own, u.value, made.value, { files: [{ path: "hello.txt", content: "hello\nworld\n" }], message: "first" }); | |
| 250 | const call = async () => { | |
| 251 | const res = await fetch(`${srv.url}/mcp`, { | |
| 252 | method: "POST", | |
| 253 | headers: { "content-type": "application/json", "x-forwarded-for": "10.9.9.9" }, | |
| 254 | body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "offer", arguments: { repo: "bob/game", title: "t", patch: PATCH } } }), | |
| 255 | }); | |
| 256 | return ((await res.json()) as any).result; | |
| 257 | }; | |
| 258 | for (let i = 0; i < 3; i++) expect((await call()).isError).toBeUndefined(); | |
| 259 | const fourth = await call(); | |
| 260 | expect(fourth.isError).toBe(true); | |
| 261 | expect(fourth.content[0].text.startsWith("rate_limited: ")).toBe(true); | |
| 262 | } finally { | |
| 263 | srv.stop(); | |
| 264 | own.close(); | |
| 265 | await rm(dir, { recursive: true, force: true }); | |
| 266 | } | |
| 267 | }, 30_000); | |
| 268 | ||
| 269 | test("the gate lets a large body through for `offer` only", async () => { | |
| 270 | const big = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "report", arguments: { repo: "alice/viamcp", title: "t", body: "x".repeat(70_000) } } }; | |
| 271 | const res = await fetch(`${servers.url}/mcp`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(big) }); | |
| 272 | expect(res.status).toBe(413); | |
| 273 | }); | |
| 274 | }); | |
| 161 | 275 | }); |
new above
offline