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
scout/forge:scout/5323-mcp-waves-a-repository-s-waves-newest-fi → main 3 commits fork 3 threads · 3 unresolved
7 files
changed +177
−2
docs/MCP.md +2 −1
| @@ -144,6 +144,7 @@ for a tunnel and a forge that sleeps. | ||
| 144 | 144 | | `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 | | |
| 145 | 145 | | `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 | |
| 146 | 146 | | `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 | | | |
| 147 | 148 | | `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 | | |
| 148 | 149 | | `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 | |
| 149 | 150 | |
| @@ -298,7 +299,7 @@ answers | ||
| 298 | 299 | |
| 299 | 300 | ## Cards, the contract and the plugins (#1116) |
| 300 | 301 | |
| 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 | |
| 302 | 303 | `_meta.ui.resourceUri` (MCP Apps, SEP-1865): `ui://forge/app`, `run`, |
| 303 | 304 | `decision`, `wave`, `map`, `feed`, `pull`. The Plan card (`map`) shows one row per pillar with |
| 304 | 305 | 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 = { | ||
| 11 | 11 | type: "object", |
| 12 | 12 | properties: { |
| 13 | 13 | 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 }, | |
| 15 | 15 | from: { type: "string", maxLength: 64 }, |
| 16 | 16 | to: { type: "string", maxLength: 64 }, |
| 17 | 17 | 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"; | ||
| 127 | 127 | export { tool as vision } from "./vision.ts"; |
| 128 | 128 | export { tool as wait_for } from "./wait_for.ts"; |
| 129 | 129 | export { tool as watch } from "./watch.ts"; |
| 130 | export { tool as waves } from "./waves.ts"; | |
| 130 | 131 | export { tool as whoami_can } from "./whoami_can.ts"; |
| 131 | 132 | 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>> = { | ||
| 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", |
| @@ -94,6 +95,19 @@ export function cardFor( | ||
| 94 | 95 | const rows: CardRow[] = []; |
| 95 | 96 | const actions: CardAction[] = []; |
| 96 | 97 | 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 | } | |
| 97 | 111 | if (tool === "new_app") { |
| 98 | 112 | const made = obj(value); |
| 99 | 113 | 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", () => { | ||
| 230 | 230 | "reports", |
| 231 | 231 | "branches", |
| 232 | 232 | "commits", |
| 233 | "waves", | |
| 233 | 234 | "probe", |
| 234 | 235 | "following", |
| 235 | 236 | "spawn", |
new above
offline