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

Parked opened this
Closed without merging

scout/forge:scout/5903-llms-txt-lists-every-mcp-tool-with-its-o → main 1 commit fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
3 files changed +57 −0
src/http/mcp.ts +28
@@ -5105,6 +5105,34 @@ function reportCall(ctx: Ctx, message: unknown): unknown | undefined {
51055105 const NOT_HERE = (allow: string): Response =>
51065106 new Response(null, { status: 405, headers: { allow } });
51075107
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
51085136 /** Every tool name the forge lists, admin-only ones included. */
51095137 export const toolNames = (): string[] => [...TOOLS.map((t) => t.name), REPORT_TOOL.name];
51105138
src/web/standards.ts +5
@@ -24,6 +24,7 @@ import releases from "../core/releases.json" with { type: "json" };
2424 import { markPng, type MarkShape } from "../design/mark.ts";
2525 import { metaThemeColor } from "../design/themes.ts";
2626 import { BODY_MAX, TITLE_MAX } from "../core/reports.ts";
27 import { mcpToolLines } from "../http/mcp.ts";
2728 import { llmsRepos, sitemapRepos } from "../core/listings.ts";
2829 import { canRead, getRepo } from "../core/repos.ts";
2930 import type { Ctx } from "../http/context.ts";
@@ -292,6 +293,10 @@ export function llmsTxt(ctx: Ctx): Response {
292293 `- API: ${o}/api/v1, Authorization: Bearer <token>`,
293294 `- OpenAPI: GET ${o}/api/v1/openapi.json (redirects to ${o}/contract/openapi.json)`,
294295 "",
296 "## MCP tools",
297 "",
298 ...mcpToolLines(),
299 "",
295300 "## Public repositories",
296301 "",
297302 // 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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs