Public: anyone can read this; the crew can change it.
The map MCP tool answers `view: "space"` with the facts the space page shows, so an agent sees the forge's growth too #12781
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12771-the-map-mcp-tool-answers-view-space-with → main 7 commits fork
5 files
changed +189
−3
docs/MCP.md +2 −1
| @@ -142,7 +142,7 @@ bytes in `tools/list`. After changing a tool run `bun scripts/mcp-table.ts`; | ||
| 142 | 142 | | `limits` | — | Every limit the owner can hit | 1101 | |
| 143 | 143 | | `maintenance` | `status`, `prepare`, `resume`, `pause-duty`, `resume-duty` | Prepare the forge for a power-off, check the drain, or end maintenance (admin) | 308 | |
| 144 | 144 | | `make_it_yours` | — | Fork an app you can see: code and history, following the original | 337 | |
| 145 | | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 416 | | |
| 145 | | `map` | — | An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first | 465 | | |
| 146 | 146 | | `merge` | `land` | Land a pull, as its page's Merge button does; a person's only | 362 | |
| 147 | 147 | | `migrate` | — | Bring a repo in by public `url` (`name`, `crew`), history and all | 269 | |
| 148 | 148 | | `milestones` | — | How far each ask is | 439 | |
| @@ -664,6 +664,7 @@ answers | ||
| 664 | 664 | becomes the "Told from" link on the issue; a bad one is refused. It differs |
| 665 | 665 | from `context.page`, which is any http(s) address appended as context, not |
| 666 | 666 | linked as the origin. |
| 667 | - **`map` with `view: "space"`** answers the same `spaceOf` as the space page and `space.json`, for the viewer's own scope (a guest sees what the page shows a guest); a junk `view` is an error naming `plan` and `space`; answers past 300 issues or 100 runs an actor are cut and say `truncated: true` with `total`; no tool was added and no ceiling moved. | |
| 667 | 668 | - **`ready` and `startable`.** `map` (and `GET …/map`) carries both. `ready` is |
| 668 | 669 | every open issue with nothing open in front, held or working ones included, |
| 669 | 670 | and the page's Ready now section reads it. `startable` is the numbers from |
docs/features/space.md +2
| @@ -12,6 +12,8 @@ is `/:owner/:name/space.json`, the same plane for an agent. In the terminal it i | ||
| 12 | 12 | - **Crew.** Their avatars sit on the issue they are working; tap one (or its name in the bar) to see what they are on. |
| 13 | 13 | - **Share.** The view is in the address hash: `#x=…&y=…&z=…` (centre in world units, zoom relative to Fit) and `&t=` (minutes since the epoch) when scrubbed back. |
| 14 | 14 | |
| 15 | The MCP `map` tool answers `view: "space"` with the same `spaceOf` result, scoped to the caller like the page. | |
| 16 | ||
| 15 | 17 | ## How it is built |
| 16 | 18 | |
| 17 | 19 | - `src/web/space_model.ts` — pure placement: treemap of regions, grid of cells per cluster. Plain data in, compact arrays out. |
src/http/mcp/map_space.ts added +18
| @@ -0,0 +1,18 @@ | ||
| 1 | /** What an agent's space answer carries: the page draws the rest, a reader's context cannot. */ | |
| 2 | export const SPACE_ISSUES_MAX = 300; | |
| 3 | export const SPACE_RUNS_MAX = 100; | |
| 4 | ||
| 5 | /** `spaceOf`, cut to the ceilings; `truncated` says so, `total` counts the issues there were. */ | |
| 6 | export function cappedSpace(space: Record<string, unknown>): Record<string, unknown> { | |
| 7 | const issues = Array.isArray(space["issues"]) ? space["issues"] : []; | |
| 8 | const crew = Array.isArray(space["crew"]) ? (space["crew"] as { runs?: unknown[] }[]) : []; | |
| 9 | const runsCut = crew.some((c) => (c.runs?.length ?? 0) > SPACE_RUNS_MAX); | |
| 10 | if (issues.length <= SPACE_ISSUES_MAX && !runsCut) return space; | |
| 11 | return { | |
| 12 | ...space, | |
| 13 | issues: issues.slice(0, SPACE_ISSUES_MAX), | |
| 14 | crew: crew.map((c) => ({ ...c, runs: (c.runs ?? []).slice(0, SPACE_RUNS_MAX) })), | |
| 15 | truncated: true, | |
| 16 | total: issues.length, | |
| 17 | }; | |
| 18 | } |
src/http/mcp/tools/map.ts +11 −2
| @@ -4,19 +4,23 @@ import { mapHeldFor } from "../../../crew/held.ts"; | ||
| 4 | 4 | import { pillarView } from "../../../core/pillars.ts"; |
| 5 | 5 | import { askToLiveFor } from "../../../web/ask_to_live.ts"; |
| 6 | 6 | import { listActiveRuns } from "../../../core/runs.ts"; |
| 7 | import { spaceOf } from "../../../web/space_read.ts"; | |
| 7 | 8 | import { roadmapOf } from "../../../web/roadmap.ts"; |
| 8 | 9 | import { mapJson, marksFor, withoutDone } from "../../../web/pages/map.ts"; |
| 9 | 10 | import { putIssueFirst } from "../../../actions/first.ts"; |
| 11 | import { cappedSpace } from "../map_space.ts"; | |
| 10 | 12 | import { bad, good, type Tool, APP_ARG, planRepo, isAnswer, issueArg } from "../shared.ts"; |
| 11 | 13 | |
| 14 | const VIEWS = ["plan", "space"]; | |
| 15 | ||
| 12 | 16 | export const tool: Tool = { |
| 13 | 17 | name: "map", |
| 14 | doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); draws the `ui://forge/map` card", | |
| 18 | doc: "an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`, `done` to list closed issues too; `roadmap` for the pillars in order with ETAs; `first: <number>` puts that ready issue first, for writers: a reader is forbidden, a closed or blocked issue invalid); `view: \"space\"` for the space page's facts; draws the `ui://forge/map` card", | |
| 15 | 19 | description: |
| 16 | 20 | "An app's plan: ready or waiting, critical path, crew, parkedTwice; `done` adds closed; `first: N` ranks N first.", |
| 17 | 21 | inputSchema: { |
| 18 | 22 | type: "object", |
| 19 | properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, first: { type: "integer", minimum: 1 } }, | |
| 23 | properties: { app: APP_ARG, done: { type: "boolean" }, roadmap: { type: "boolean" }, first: { type: "integer", minimum: 1 }, view: { type: "string", enum: VIEWS } }, | |
| 20 | 24 | required: ["app"], |
| 21 | 25 | }, |
| 22 | 26 | writes: true, |
| @@ -24,6 +28,11 @@ export const tool: Tool = { | ||
| 24 | 28 | async run(ctx, user, args) { |
| 25 | 29 | const repo = planRepo(ctx, user, args); |
| 26 | 30 | if (isAnswer(repo)) return repo; |
| 31 | const view = args["view"]; | |
| 32 | if (view !== undefined && (typeof view !== "string" || !VIEWS.includes(view))) { | |
| 33 | return bad("bad_view", `view is one of ${VIEWS.join(", ")}`); | |
| 34 | } | |
| 35 | if (view === "space") return good({ ...cappedSpace(spaceOf(ctx.app, repo, user)) }); | |
| 27 | 36 | if (args["first"] !== undefined) { |
| 28 | 37 | const issue = issueArg(ctx, repo, args, "first"); |
| 29 | 38 | if ("ok" in issue) return issue; |
test/mcp-map-space.test.ts added +156
| @@ -0,0 +1,156 @@ | ||
| 1 | /** | |
| 2 | * MCP `map` with `view: "space"` answers what `spaceOf` gives the caller; | |
| 3 | * a junk view names the valid values. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { createRepo } from "../src/actions/repos.ts"; | |
| 11 | import { addDependency } from "../src/core/dependencies.ts"; | |
| 12 | import { createIssue } from "../src/core/issues.ts"; | |
| 13 | import { createToken } from "../src/core/tokens.ts"; | |
| 14 | import { createUser } from "../src/core/users.ts"; | |
| 15 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 16 | import { SPACE_ISSUES_MAX } from "../src/http/mcp/map_space.ts"; | |
| 17 | import { spaceOf } from "../src/web/space_read.ts"; | |
| 18 | import { getRepo } from "../src/core/repos.ts"; | |
| 19 | const stable = (v: unknown) => ({ ...JSON.parse(JSON.stringify(v)), now: 0, weekStart: 0 }); | |
| 20 | import { promote } from "./helpers/members.ts"; | |
| 21 | ||
| 22 | describe("MCP map view space", () => { | |
| 23 | let dataDir: string; | |
| 24 | let app: App; | |
| 25 | let servers: Servers; | |
| 26 | let aliceTok: string; | |
| 27 | let carolTok: string; | |
| 28 | let id = 1; | |
| 29 | ||
| 30 | const call = async (token: string, args: unknown) => { | |
| 31 | const res = await fetch(`${servers.url}/mcp`, { | |
| 32 | method: "POST", | |
| 33 | headers: { | |
| 34 | "content-type": "application/json", | |
| 35 | accept: "application/json, text/event-stream", | |
| 36 | authorization: `Bearer ${token}`, | |
| 37 | }, | |
| 38 | body: JSON.stringify({ | |
| 39 | jsonrpc: "2.0", | |
| 40 | id: id++, | |
| 41 | method: "tools/call", | |
| 42 | params: { name: "map", arguments: args }, | |
| 43 | }), | |
| 44 | }); | |
| 45 | const body: any = await res.json(); | |
| 46 | const text: string = body.result.content[0].text; | |
| 47 | return body.result.isError === true ? { error: text } : { value: JSON.parse(text) }; | |
| 48 | }; | |
| 49 | ||
| 50 | beforeAll(async () => { | |
| 51 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-map-space-")); | |
| 52 | app = createApp({ dataDir, port: 0 }); | |
| 53 | servers = await serve(app); | |
| 54 | const mk = async (username: string, first = false) => { | |
| 55 | const u = await createUser(app.db, { | |
| 56 | origin: "seed", | |
| 57 | trusted: true, | |
| 58 | username, | |
| 59 | email: `${username}@forge.local`, | |
| 60 | password: "a-good-passphrase", | |
| 61 | adminIfFirst: first, | |
| 62 | }); | |
| 63 | if (!u.ok) throw new Error(u.error); | |
| 64 | promote(app.db, u.value); | |
| 65 | return u.value; | |
| 66 | }; | |
| 67 | const alice = await mk("alice", true); | |
| 68 | const carol = await mk("carol"); | |
| 69 | aliceTok = createToken(app.db, alice.id, "rw", "rw").token; | |
| 70 | carolTok = createToken(app.db, carol.id, "rw", "rw").token; | |
| 71 | const made = await createRepo(app, alice, { name: "one", visibility: "public" }); | |
| 72 | if (!made.ok) throw new Error(String(made.error)); | |
| 73 | const repoId = made.value.id; | |
| 74 | const open = (title: string) => { | |
| 75 | const i = createIssue(app.db, { repoId, authorId: alice.id, title }); | |
| 76 | if (!i.ok) throw new Error(i.error); | |
| 77 | return i.value; | |
| 78 | }; | |
| 79 | open("one"); | |
| 80 | open("two"); | |
| 81 | open("three"); | |
| 82 | const blocked = open("four"); | |
| 83 | const blocker = open("five"); | |
| 84 | const dep = addDependency(app.db, blocked, blocker, alice.id); | |
| 85 | if (!dep.ok) throw new Error(String(dep.error)); | |
| 86 | const closed = open("six"); | |
| 87 | app.db.query("UPDATE issue SET state = 'closed' WHERE id = ?1").run(closed.id); | |
| 88 | }, 30_000); | |
| 89 | ||
| 90 | afterAll(async () => { | |
| 91 | servers.stop(); | |
| 92 | app.close(); | |
| 93 | await rm(dataDir, { recursive: true, force: true }); | |
| 94 | }); | |
| 95 | ||
| 96 | test("space is the spaceOf result for the caller", async () => { | |
| 97 | const repo = getRepo(app.db, "alice", "one")!; | |
| 98 | const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string }; | |
| 99 | const got = await call(aliceTok, { app: "alice/one", view: "space" }); | |
| 100 | expect(got.error).toBeUndefined(); | |
| 101 | expect(stable(got.value)).toEqual(stable(spaceOf(app, repo, { id: alice.id } as any))); | |
| 102 | expect(got.value.issues.length).toBeGreaterThan(0); | |
| 103 | }); | |
| 104 | ||
| 105 | test("a junk view is an error naming the valid values", async () => { | |
| 106 | const got = await call(aliceTok, { app: "alice/one", view: "bogus" }); | |
| 107 | expect(got.error).toContain("plan"); | |
| 108 | expect(got.error).toContain("space"); | |
| 109 | }); | |
| 110 | ||
| 111 | test("a private app is refused to one who may not read it, and open to its owner", async () => { | |
| 112 | const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string }; | |
| 113 | const made = await createRepo(app, alice as any, { name: "hidden", visibility: "private" }); | |
| 114 | if (!made.ok) throw new Error(String(made.error)); | |
| 115 | const issue = createIssue(app.db, { repoId: made.value.id, authorId: alice.id, title: "secret plan" }); | |
| 116 | if (!issue.ok) throw new Error(issue.error); | |
| 117 | const mine = await call(aliceTok, { app: "alice/hidden", view: "space" }); | |
| 118 | expect(mine.error).toBeUndefined(); | |
| 119 | expect(JSON.stringify(mine.value)).toContain("secret plan"); | |
| 120 | const theirs = await call(carolTok, { app: "alice/hidden", view: "space" }); | |
| 121 | expect(theirs.value).toBeUndefined(); | |
| 122 | expect(theirs.error).toBeDefined(); | |
| 123 | expect(theirs.error).not.toContain("secret plan"); | |
| 124 | }); | |
| 125 | ||
| 126 | test("a public app reads the same for another caller as spaceOf gives that caller", async () => { | |
| 127 | const repo = getRepo(app.db, "alice", "one")!; | |
| 128 | const carol = app.db.query("SELECT id FROM user WHERE username='carol'").get() as { id: string }; | |
| 129 | const got = await call(carolTok, { app: "alice/one", view: "space" }); | |
| 130 | expect(got.error).toBeUndefined(); | |
| 131 | expect(stable(got.value)).toEqual(stable(spaceOf(app, repo, { id: carol.id } as any))); | |
| 132 | }); | |
| 133 | ||
| 134 | test("a junk view with `first` set writes nothing", async () => { | |
| 135 | const before = await call(aliceTok, { app: "alice/one" }); | |
| 136 | const order = JSON.stringify(before.value.ready); | |
| 137 | const got = await call(aliceTok, { app: "alice/one", view: "bogus", first: 2 }); | |
| 138 | expect(got.error).toContain("space"); | |
| 139 | expect(JSON.stringify((await call(aliceTok, { app: "alice/one" })).value.ready)).toBe(order); | |
| 140 | }); | |
| 141 | ||
| 142 | test("a large app's answer is cut and says so", async () => { | |
| 143 | const alice = app.db.query("SELECT id FROM user WHERE username='alice'").get() as { id: string }; | |
| 144 | const made = await createRepo(app, alice as any, { name: "big", visibility: "public" }); | |
| 145 | if (!made.ok) throw new Error(String(made.error)); | |
| 146 | for (let n = 0; n < SPACE_ISSUES_MAX + 20; n++) { | |
| 147 | createIssue(app.db, { repoId: made.value.id, authorId: alice.id, title: `t${n}` }); | |
| 148 | } | |
| 149 | const got = await call(aliceTok, { app: "alice/big", view: "space" }); | |
| 150 | expect(got.value.issues.length).toBe(SPACE_ISSUES_MAX); | |
| 151 | expect(got.value.truncated).toBe(true); | |
| 152 | expect(got.value.total).toBe(SPACE_ISSUES_MAX + 20); | |
| 153 | const small = await call(aliceTok, { app: "alice/one", view: "space" }); | |
| 154 | expect(small.value.truncated).toBeUndefined(); | |
| 155 | }); | |
| 156 | }); |
new above
offline