Public: anyone can read this; the crew can change it.
/llms.txt lists every MCP tool with its one-line purpose, generated from the tool registry, and a test fails when one is missing #5920
scout/forge:scout/5903-llms-txt-lists-every-mcp-tool-with-its-o → main 1 commit fork
3 files
changed +57
−0
src/http/mcp.ts +28
| @@ -5105,6 +5105,34 @@ function reportCall(ctx: Ctx, message: unknown): unknown | undefined { | ||
| 5105 | 5105 | const NOT_HERE = (allow: string): Response => |
| 5106 | 5106 | new Response(null, { status: 405, headers: { allow } }); |
| 5107 | 5107 | |
| 5108 | /** The first sentence of a description on one line: what an outside agent needs to choose a tool. */ | |
| 5109 | export const oneLine = (description: string): string => { | |
| 5110 | const flat = description.replace(/\s+/g, " ").trim(); | |
| 5111 | const end = flat.search(/[.!?](\s|$)/); | |
| 5112 | const first = end < 0 ? flat : flat.slice(0, end + 1); | |
| 5113 | return first.length > 200 ? `${first.slice(0, 199)}…` : first; | |
| 5114 | }; | |
| 5115 | ||
| 5116 | let toolLines: string[] | undefined; | |
| 5117 | /** | |
| 5118 | * One line per tool for /llms.txt, from the registry tools/list is built | |
| 5119 | * from; the same for every reader. The registry is fixed at start, so it is | |
| 5120 | * built once. | |
| 5121 | */ | |
| 5122 | export function mcpToolLines(): readonly string[] { | |
| 5123 | toolLines ??= [ | |
| 5124 | ...TOOLS.map((t) => { | |
| 5125 | const marks = [ | |
| 5126 | ...(t.adminOnly === true || t.needsAdminScope === true ? ["(admin)"] : []), | |
| 5127 | ...(t.writes ? ["(writes)"] : []), | |
| 5128 | ]; | |
| 5129 | return `- ${[`${t.name}: ${oneLine(t.description)}`, ...marks].join(" ")}`; | |
| 5130 | }), | |
| 5131 | `- ${REPORT_TOOL.name}: ${oneLine(REPORT_TOOL.description)}`, | |
| 5132 | ]; | |
| 5133 | return toolLines; | |
| 5134 | } | |
| 5135 | ||
| 5108 | 5136 | /** Every tool name the forge lists, admin-only ones included. */ |
| 5109 | 5137 | export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name]; |
| 5110 | 5138 |
src/web/standards.ts +5
| @@ -24,6 +24,7 @@ import releases from "../core/releases.json" with { type: "json" }; | ||
| 24 | 24 | import { markPng, type MarkShape } from "../design/mark.ts"; |
| 25 | 25 | import { metaThemeColor } from "../design/themes.ts"; |
| 26 | 26 | import { BODY_MAX, TITLE_MAX } from "../core/reports.ts"; |
| 27 | import { mcpToolLines } from "../http/mcp.ts"; | |
| 27 | 28 | import { llmsRepos, sitemapRepos } from "../core/listings.ts"; |
| 28 | 29 | import { canRead, getRepo } from "../core/repos.ts"; |
| 29 | 30 | import type { Ctx } from "../http/context.ts"; |
| @@ -292,6 +293,10 @@ export function llmsTxt(ctx: Ctx): Response { | ||
| 292 | 293 | `- API: ${o}/api/v1, Authorization: Bearer <token>`, |
| 293 | 294 | `- OpenAPI: GET ${o}/api/v1/openapi.json (redirects to ${o}/contract/openapi.json)`, |
| 294 | 295 | "", |
| 296 | "## MCP tools", | |
| 297 | "", | |
| 298 | ...mcpToolLines(), | |
| 299 | "", | |
| 295 | 300 | "## Public repositories", |
| 296 | 301 | "", |
| 297 | 302 | // Names and addresses only: a description is whatever its owner |
test/llms-mcp-tools.test.ts added +24
| @@ -0,0 +1,24 @@ | ||
| 1 | /** /llms.txt lists every MCP tool, from the registry (#5903). */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { llmsTxt } from "../src/web/standards.ts"; | |
| 4 | import { mcpToolLines, toolNames, oneLine } from "../src/http/mcp.ts"; | |
| 5 | import { createApp } from "../src/app.ts"; | |
| 6 | import { mkdtempSync } from "node:fs"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | ||
| 10 | test("the ## MCP tools section matches the registry, line for line", async () => { | |
| 11 | const app = createApp({ dataDir: mkdtempSync(join(tmpdir(), "forge-llms-tools-")), port: 0, forgeRepo: "a/forge" }); | |
| 12 | const url = new URL("http://x.test/llms.txt"); | |
| 13 | const res = llmsTxt({ app, url, request: new Request(url.href) } as never); | |
| 14 | expect(res.headers.get("cache-control")).toContain("max-age"); | |
| 15 | const body = await res.text(); | |
| 16 | const section = body.split("## MCP tools\n")[1]!.split("\n## ")[0]!.split("\n").filter((l) => l.startsWith("- ")); | |
| 17 | const names = section.map((l) => l.slice(2).split(": ")[0]); | |
| 18 | expect(names).toEqual(toolNames()); | |
| 19 | expect(section).toEqual([...mcpToolLines()]); | |
| 20 | expect(new Set(names).size).toBe(names.length); | |
| 21 | expect(section.every((l) => !l.includes("\n"))).toBe(true); | |
| 22 | expect(oneLine("A b.\n More text.")).toBe("A b."); | |
| 23 | app.close(); | |
| 24 | }); |
new above
offline