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 #7409
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/5323-mcp-waves-a-repository-s-waves-newest-fi → main 6 commits fork 4 threads · 4 unresolved
6 files
changed +185
−1
docs/MCP.md +2 −1
| @@ -186,6 +186,7 @@ for a tunnel and a forge that sleeps. | ||
| 186 | 186 | | `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 | | |
| 187 | 187 | | `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 | |
| 188 | 188 | | `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 | |
| 189 | | `waves` | `{ repo, version? }`: the repository's waves newest first (version, date, headline; a broken file is `{ version, error }`), 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 | | | |
| 189 | 190 | | `whoami_can` | `{ kind?, remove? }`: 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; `remove: id` with `kind: "passkeys"` removes one of them, as Settings → Passkeys does (an admin-scope token, never an agent) | yes | |
| 190 | 191 | | `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 | |
| 191 | 192 | |
| @@ -355,7 +356,7 @@ answers | ||
| 355 | 356 | |
| 356 | 357 | ## Cards, the contract and the plugins (#1116) |
| 357 | 358 | |
| 358 | - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map`, `feed` and `pull` name a `ui://` resource in | |
| 359 | - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `waves` (one wave), `map`, `feed` and `pull` name a `ui://` resource in | |
| 359 | 360 | `_meta.ui.resourceUri` (MCP Apps, SEP-1865): `ui://forge/app`, `run`, |
| 360 | 361 | `decision`, `wave`, `map`, `feed`, `pull`. The Plan card (`map`) shows one row per pillar with |
| 361 | 362 | its ready, working and waiting counts, and the first five ready issues linked |
src/http/mcp/tools/index.ts +1
| @@ -155,5 +155,6 @@ export { tool as variant } from "./variant.ts"; | ||
| 155 | 155 | export { tool as vision } from "./vision.ts"; |
| 156 | 156 | export { tool as wait_for } from "./wait_for.ts"; |
| 157 | 157 | export { tool as watch } from "./watch.ts"; |
| 158 | export { tool as waves } from "./waves.ts"; | |
| 158 | 159 | export { tool as whoami_can } from "./whoami_can.ts"; |
| 159 | 160 | 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; a broken file is `{ version, error }`), 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.map((e) => | |
| 29 | e.ok ? { version: e.wave.version, date: e.wave.date, headline: e.wave.headline } : { version: e.file.replace(/\.md$/, ""), error: e.reason }, | |
| 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 = /\/pulls\/(\d+)\/?$/.exec(p.url); | |
outdated
High: the title is matched first, and pull titles often start with an issue number ( |
||
| 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>> = { | ||
| 48 | 48 | runs: "run", |
| 49 | 49 | asks: "decision", |
| 50 | 50 | milestones: "wave", |
| 51 | waves: "wave", | |
| 51 | 52 | map: "map", |
| 52 | 53 | feed: "feed", |
| 53 | 54 | explore: "explore", |
| @@ -96,6 +97,19 @@ export function cardFor( | ||
| 96 | 97 | const rows: CardRow[] = []; |
| 97 | 98 | const actions: CardAction[] = []; |
| 98 | 99 | let status = ""; |
| 100 | if (tool === "waves") { | |
| 101 | // Only one wave is a card; the list is text. | |
| 102 | const w = obj(obj(value)["wave"]); | |
| 103 | if (text(w["version"]) === "") return undefined; | |
| 104 | const repo = text(obj(value)["repo"]); | |
| 105 | const pulls = list(w["pulls"]).map(text); | |
| 106 | rows.push({ label: "Headline", value: text(w["headline"]) }); | |
| 107 | for (const h of list(w["highlights"]).map(obj).slice(0, LIMIT)) | |
| 108 | rows.push({ label: text(h["title"]), value: text(h["why"]) }); | |
| 109 | if (pulls.length > 0) | |
| 110 | rows.push({ label: "Pulls", value: pulls.slice(0, LIMIT).map((n) => `#${n}`).join(" ") }); | |
| 111 | return { kind, title: `Wave ${text(w["version"])}`, status: `${repo} · ${text(w["date"])}`.replace(/^ · /, ""), rows, actions }; | |
| 112 | } | |
| 99 | 113 | if (tool === "new_app") { |
| 100 | 114 | const made = obj(value); |
| 101 | 115 | const repo = text(made["repo"]); |
test/mcp-waves.test.ts added +114
| @@ -0,0 +1,114 @@ | ||
| 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: "#99 follow-up", url: "https://forge.example/ada/svc/pulls/12" }], | |
outdated
Here the title's number and the URL's agree, so a title-first parse passes. Use a title naming another number ( |
||
| 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 | if (name === "svc") files.push({ path: "waves/broken.md", content: "nope" }); | |
| 67 | ok(await commitToBranch(app, owner, repo, { message: "waves", files })); | |
| 68 | } | |
| 69 | tok["owner"] = createToken(app.db, owner.id, "ro", "ro").token; | |
| 70 | tok["stranger"] = createToken(app.db, stranger.id, "ro", "ro").token; | |
| 71 | }, 30_000); | |
| 72 | ||
| 73 | afterAll(async () => { | |
| 74 | servers?.stop(); | |
| 75 | app?.close(); | |
| 76 | await rm(dataDir, { recursive: true, force: true }); | |
| 77 | }); | |
| 78 | ||
| 79 | test("lists waves newest first by version, not by name", async () => { | |
| 80 | const r = await mcp(tok["stranger"]!, { repo: "ada/svc" }); | |
| 81 | expect(r.value.waves.map((w: any) => w.version)).toEqual(["0.10.0", "0.9.1", "0.9.0", "broken"]); | |
| 82 | expect(r.value.waves[0]).toEqual({ version: "0.10.0", date: "2026-10-10", headline: "Headline 0.10.0" }); | |
| 83 | expect(r.card).toBeUndefined(); | |
| 84 | }); | |
| 85 | ||
| 86 | test("a wave file that does not parse is listed last with its reason", async () => { | |
| 87 | const r = await mcp(tok["owner"]!, { repo: "ada/svc" }); | |
| 88 | const last = r.value.waves[3]; | |
| 89 | expect(Object.keys(last).sort()).toEqual(["error", "version"]); | |
| 90 | expect(last.version).toBe("broken"); | |
| 91 | expect(last.error).toContain("waves/broken.md"); | |
| 92 | }); | |
| 93 | ||
| 94 | test("one wave carries headline, highlights, pull numbers and the wave card", async () => { | |
| 95 | const r = await mcp(tok["owner"]!, { repo: "ada/svc", version: "0.9.1" }); | |
| 96 | expect(r.value.wave.headline).toBe("Headline 0.9.1"); | |
| 97 | expect(r.value.wave.highlights[0]).toEqual({ title: "Thing 1", why: "Because 1" }); | |
| 98 | expect(r.value.wave.pulls).toEqual([12]); | |
| 99 | expect(r.card.kind).toBe("wave"); | |
| 100 | expect(r.card.title).toBe("Wave 0.9.1"); | |
| 101 | }); | |
| 102 | ||
| 103 | test("an unknown or malformed version is refused", async () => { | |
| 104 | expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: "9.9.9" })).error).toContain("not_found"); | |
| 105 | expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: "../x" })).error).toContain("invalid"); | |
| 106 | expect((await mcp(tok["owner"]!, { repo: "ada/svc", version: 3 })).error).toContain("invalid"); | |
| 107 | }); | |
| 108 | ||
| 109 | test("a private repository is not found to someone who cannot read it", async () => { | |
| 110 | expect((await mcp(tok["owner"]!, { repo: "ada/secret" })).value.waves.length).toBe(3); | |
| 111 | const r = await mcp(tok["stranger"]!, { repo: "ada/secret" }); | |
| 112 | expect(r.error).toContain("not_found"); | |
| 113 | expect((await mcp(tok["stranger"]!, { repo: "ada/secret", version: "0.9.0" })).error).toContain("not_found"); | |
| 114 | }); |
test/mcp.test.ts +1
| @@ -240,6 +240,7 @@ describe("the forge over MCP", () => { | ||
| 240 | 240 | "reports", |
| 241 | 241 | "branches", |
| 242 | 242 | "commits", |
| 243 | "waves", | |
| 243 | 244 | "probe", |
| 244 | 245 | "following", |
| 245 | 246 | "spawn", |
new above
offline
This branch (a broken file becomes
{ version: file without .md, error }) is new since my last review, and no test covers it. Add a brokenwaves/broken.mdto the fixture and assert that this entry comes last in the list.