Public: anyone can read this; the crew can change it.

MCP `waves`: a repository's waves newest first, and one wave's headline, highlights and pulls #5420

Parked opened this
Closed without merging

scout/forge:scout/5323-mcp-waves-a-repository-s-waves-newest-fi → main 3 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
7 files changed +177 −2
docs/MCP.md +2 −1
@@ -144,6 +144,7 @@ for a tunnel and a forge that sleeps.
144144 | `vision` | `{ repo, number? }`: `{ purpose, order: [{ n, name, text }], rules, direction, directionParts, preview, updatedAt }` from docs/VISION.md on the default branch; without the document `purpose` is null and `order` empty; `direction` (the autonomy direction) and `directionParts` (it cut into `{ kind: vision|owner, text }`: the fenced block that follows docs/VISION.md, and the owner's words) only for those who may read the repository's settings, else null; with `number` (an open vision pull) those same people get `preview`: `{ today, after }`, the direction as it stands and as an admin's merge will write it, or `{ why }` it would stay; else null | |
145145 | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes |
146146 | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes |
147 | `waves` | `{ repo, version? }`: the repository's waves newest first (version, date, headline), or with `version` one wave: headline, highlights with their why, pull numbers (with the `ui://forge/wave` card); a private repository is not found to a stranger | |
147148 | `whoami_can` | `{ kind? }`: your role and that role's row of the roles table, each ability yes or no; `kind: "passkeys"` lists your own passkeys (`{ items }`: id, name, created, lastUsed), people only | |
148149 | `write_file` | `{ repo, branch, path, content, message }`: commit one file to an existing branch as `POST …/contents` does, for the same callers and with the same refusals (protected default, too large, a path with `..`), said in `edit_words`' sentences; answers `{ commit, says }` | yes |
149150
@@ -298,7 +299,7 @@ answers
298299
299300 ## Cards, the contract and the plugins (#1116)
300301
301 - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map`, `feed` and `pull` name a `ui://` resource in
302 - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `waves` (one wave), `map`, `feed` and `pull` name a `ui://` resource in
302303 `_meta.ui.resourceUri` (MCP Apps, SEP-1865): `ui://forge/app`, `run`,
303304 `decision`, `wave`, `map`, `feed`, `pull`. The Plan card (`map`) shows one row per pillar with
304305 its ready, working and waiting counts, and the first five ready issues linked
src/http/mcp/tools/boards.ts +1 −1
@@ -11,7 +11,7 @@ export const tool: Tool = {
1111 type: "object",
1212 properties: {
1313 slug: { type: "string", maxLength: 40 },
14 panel: { type: "integer", minimum: 0, maximum: 23, description: "Panel from 0." },
14 panel: { type: "integer", minimum: 0, maximum: 23 },
1515 from: { type: "string", maxLength: 64 },
1616 to: { type: "string", maxLength: 64 },
1717 step: { type: "string", maxLength: 16, description: "With panel: bucket seconds, or 5m." },
src/http/mcp/tools/index.ts +1
@@ -127,5 +127,6 @@ export { tool as variant } from "./variant.ts";
127127 export { tool as vision } from "./vision.ts";
128128 export { tool as wait_for } from "./wait_for.ts";
129129 export { tool as watch } from "./watch.ts";
130 export { tool as waves } from "./waves.ts";
130131 export { tool as whoami_can } from "./whoami_can.ts";
131132 export { tool as write_file } from "./write_file.ts";
src/http/mcp/tools/waves.ts added +53
@@ -0,0 +1,53 @@
1 import { readWave, readWaves } from "../../../story/waves.ts";
2 import { VERSION as WAVE_VERSION } from "../../../story/wave.ts";
3 import { repoDir } from "../../../git/repos.ts";
4 import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts";
5
6 export const tool: Tool = {
7 name: "waves",
8 doc: "`{ repo, version? }`: the repository's waves newest first (version, date, headline), or with `version` one wave: headline, highlights with their why, pull numbers (with the `ui://forge/wave` card); a private repository is not found to a stranger",
9 description: "Waves; `version`: one.",
10 inputSchema: {
11 type: "object",
12 properties: {
13 repo: REPO_ARG,
14 version: { type: "string", maxLength: 64 },
15 },
16 required: ["repo"],
17 },
18 writes: false,
19 async run(ctx, user, args) {
20 const repo = repoArg(ctx, user, args);
21 if (isAnswer(repo)) return repo;
22 const dir = repoDir(ctx.app.reposRoot, repo.ownerName, repo.name);
23 const version = args["version"];
24 if (version === undefined) {
25 const entries = await readWaves(dir, repo.defaultBranch);
26 return good({
27 repo: repo.ownerName + "/" + repo.name,
28 waves: entries.flatMap((e) =>
29 e.ok ? [{ version: e.wave.version, date: e.wave.date, headline: e.wave.headline }] : [],
30 ),
31 });
32 }
33 if (typeof version !== "string" || !WAVE_VERSION.test(version))
34 return bad("invalid", "`version` is a wave's version, such as 0.7.81");
35 const entry = await readWave(dir, repo.defaultBranch, version);
36 if (entry === null) return bad("not_found", `no wave ${version}`);
37 if (!entry.ok) return bad("invalid", entry.reason);
38 const w = entry.wave;
39 return good({
40 repo: repo.ownerName + "/" + repo.name,
41 wave: {
42 version: w.version,
43 date: w.date,
44 headline: w.headline,
45 highlights: w.highlights,
46 pulls: w.pulls.flatMap((p) => {
47 const n = /^#(\d+)\b/.exec(p.title) ?? /\/pulls\/(\d+)\/?$/.exec(p.url);
48 return n ? [Number(n[1])] : [];
49 }),
50 },
51 });
52 },
53 };
src/web/studio/cards.ts +14
@@ -48,6 +48,7 @@ export const CARD_OF_TOOL: Readonly<Record<string, CardKind>> = {
4848 runs: "run",
4949 asks: "decision",
5050 milestones: "wave",
51 waves: "wave",
5152 map: "map",
5253 feed: "feed",
5354 explore: "explore",
@@ -94,6 +95,19 @@ export function cardFor(
9495 const rows: CardRow[] = [];
9596 const actions: CardAction[] = [];
9697 let status = "";
98 if (tool === "waves") {
99 // Only one wave is a card; the list is text.
100 const w = obj(obj(value)["wave"]);
101 if (text(w["version"]) === "") return undefined;
102 const repo = text(obj(value)["repo"]);
103 const pulls = list(w["pulls"]).map(text);
104 rows.push({ label: "Headline", value: text(w["headline"]) });
105 for (const h of list(w["highlights"]).map(obj).slice(0, LIMIT))
106 rows.push({ label: text(h["title"]), value: text(h["why"]) });
107 if (pulls.length > 0)
108 rows.push({ label: "Pulls", value: pulls.slice(0, LIMIT).map((n) => `#${n}`).join(" ") });
109 return { kind, title: `Wave ${text(w["version"])}`, status: `${repo} · ${text(w["date"])}`.replace(/^ · /, ""), rows, actions };
110 }
97111 if (tool === "new_app") {
98112 const made = obj(value);
99113 const repo = text(made["repo"]);
test/mcp-waves.test.ts added +105
@@ -0,0 +1,105 @@
1 /** MCP `waves`: list order, one wave and its card, an unknown version refused, a private repository hidden. */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp, type App } from "../src/app.ts";
7 import { commitToBranch } from "../src/actions/repos.ts";
8 import { createRepo } from "../src/core/repos.ts";
9 import { createToken } from "../src/core/tokens.ts";
10 import { createUser } from "../src/core/users.ts";
11 import { serve, type Servers } from "../src/http/server.ts";
12 import { writeWave } from "../src/story/wave.ts";
13 import { quietLogs } from "./helpers/globals.ts";
14
15 quietLogs();
16
17 let dataDir: string;
18 let app: App;
19 let servers: Servers;
20 const tok: Record<string, string> = {};
21
22 const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
23 if (!r.ok) throw new Error(JSON.stringify(r.error));
24 return r.value;
25 };
26
27 async function mcp(token: string, args: unknown): Promise<{ error?: string; value?: any; card?: any }> {
28 const res = await fetch(`${servers.url}/mcp`, {
29 method: "POST",
30 headers: {
31 "content-type": "application/json",
32 accept: "application/json, text/event-stream",
33 authorization: `Bearer ${token}`,
34 },
35 body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "waves", arguments: args } }),
36 });
37 const body = (await res.json()) as any;
38 const text: string = body.result.content[0].text;
39 return body.result.isError === true
40 ? { error: text }
41 : { value: JSON.parse(text), card: body.result.structuredContent?.card };
42 }
43
44 const wave = (version: string, date: string) => ({
45 version,
46 date,
47 headline: `Headline ${version}`,
48 highlights: [1, 2, 3].map((i) => ({ title: `Thing ${i}`, why: `Because ${i}` })),
49 pulls: [{ title: "#12 Did it", url: "https://forge.example/ada/svc/pulls/12" }],
50 });
51
52 beforeAll(async () => {
53 dataDir = await mkdtemp(join(tmpdir(), "forge-waves-mcp-"));
54 app = createApp({ dataDir, port: 0 });
55 servers = await serve(app);
56 const make = (username: string) =>
57 createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: "a-good-passphrase" });
58 const owner = ok(await make("ada"));
59 const stranger = ok(await make("rita"));
60 for (const [name, visibility] of [["svc", "public"], ["secret", "private"]] as const) {
61 const repo = ok(await createRepo(app.db, app.reposRoot, { ownerId: owner.id, name, visibility }));
62 const files = [["0.9.0", "2026-10-01"], ["0.10.0", "2026-10-10"], ["0.9.1", "2026-10-05"]].map(([v, d]) => ({
63 path: `waves/${v}.md`,
64 content: ok(writeWave(wave(v!, d!)) as { ok: true; value: string }),
65 }));
66 ok(await commitToBranch(app, owner, repo, { message: "waves", files }));
67 }
68 tok["owner"] = createToken(app.db, owner.id, "ro", "ro").token;
69 tok["stranger"] = createToken(app.db, stranger.id, "ro", "ro").token;
70 }, 30_000);
71
72 afterAll(async () => {
73 servers?.stop();
74 app?.close();
75 await rm(dataDir, { recursive: true, force: true });
76 });
77
78 test("lists waves newest first by version, not by name", async () => {
79 const r = await mcp(tok["stranger"]!, { repo: "ada/svc" });
80 expect(r.value.waves.map((w: any) => w.version)).toEqual(["0.10.0", "0.9.1", "0.9.0"]);
81 expect(r.value.waves[0]).toEqual({ version: "0.10.0", date: "2026-10-10", headline: "Headline 0.10.0" });
82 expect(r.card).toBeUndefined();
83 });
84
85 test("one wave carries headline, highlights, pull numbers and the wave card", async () => {
86 const r = await mcp(tok["owner"]!, { repo: "ada/svc", version: "0.9.1" });
87 expect(r.value.wave.headline).toBe("Headline 0.9.1");
88 expect(r.value.wave.highlights[0]).toEqual({ title: "Thing 1", why: "Because 1" });
89 expect(r.value.wave.pulls).toEqual([12]);
90 expect(r.card.kind).toBe("wave");
91 expect(r.card.title).toBe("Wave 0.9.1");
92 });
93
94 test("an unknown or malformed version is refused", async () => {
95 expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: "9.9.9" })).error).toContain("not_found");
96 expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: "../x" })).error).toContain("invalid");
97 expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: 3 })).error).toContain("invalid");
98 });
99
100 test("a private repository is not found to someone who cannot read it", async () => {
101 expect((await mcp(tok["owner"]!, { repo: "ada/secret" })).value.waves.length).toBe(3);
102 const r = await mcp(tok["stranger"]!, { repo: "ada/secret" });
103 expect(r.error).toContain("not_found");
104 expect((await mcp(tok["stranger"]!, { repo: "ada/secret", version: "0.9.0" })).error).toContain("not_found");
105 });
test/mcp.test.ts +1
@@ -230,6 +230,7 @@ describe("the forge over MCP", () => {
230230 "reports",
231231 "branches",
232232 "commits",
233 "waves",
233234 "probe",
234235 "following",
235236 "spawn",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs