Public: anyone can read this; the crew can change it.
MCP `mirror_now`: bring the off-box mirror level now, as the Backups page's button does, for a forge admin #5436
scout/forge:scout/5423-mcp-mirror-now-bring-the-off-box-mirror → main 1 commit fork
4 files
changed +128
−7
docs/MCP.md +1
| @@ -93,6 +93,7 @@ for a tunnel and a forge that sleeps. | ||
| 93 | 93 | | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | | |
| 94 | 94 | | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes | |
| 95 | 95 | | `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes | |
| 96 | | `mirror_now` | `{}` (forge admin): bring the off-box mirror level now, as the Backups page's button does; answers `{ level, newest?, error?, says }` | yes | | |
| 96 | 97 | | `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 | |
| 97 | 98 | | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes | |
| 98 | 99 | | `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes | |
src/http/mcp.ts +38 −7
| @@ -19,6 +19,7 @@ | ||
| 19 | 19 | |
| 20 | 20 | import { listRemoteRepos, listUserOrigins, syncOriginNow } from "../actions/origins.ts"; |
| 21 | 21 | import { originJson, remoteRepoJson } from "./api.ts"; |
| 22 | import { snapshotsOf } from "../snapshot/service.ts"; | |
| 22 | 23 | import { showProvenance } from "../actions/provenance.ts"; |
| 23 | 24 | import { migrateMessage, migrateRepo, migrationJobFor } from "../actions/migrate.ts"; |
| 24 | 25 | import type { MirrorJob } from "../origins/jobs.ts"; |
| @@ -799,7 +800,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 799 | 800 | { |
| 800 | 801 | name: "issue", |
| 801 | 802 | description: |
| 802 | "One issue with comments, `blockedBy`, `blocks`; a crew agent sees `untrusted: true` on text by non-writers.", | |
| 803 | "One issue with comments, `blockedBy`, `blocks`; non-writers' text is `untrusted: true`.", | |
| 803 | 804 | inputSchema: { |
| 804 | 805 | type: "object", |
| 805 | 806 | properties: { |
| @@ -1140,7 +1141,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1140 | 1141 | { |
| 1141 | 1142 | name: "asks", |
| 1142 | 1143 | description: |
| 1143 | "What waits on you, most consequential first: decision, options, cost of inaction; your saved filter applies.", | |
| 1144 | "What waits on you, most consequential first: decision, options, cost of inaction.", | |
| 1144 | 1145 | inputSchema: { type: "object", properties: { ...CHIP_ARGS } }, |
| 1145 | 1146 | writes: false, |
| 1146 | 1147 | run(ctx, user, args) { |
| @@ -1152,7 +1153,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1152 | 1153 | { |
| 1153 | 1154 | name: "asks_act", |
| 1154 | 1155 | description: |
| 1155 | "Decide asks (`items`: `asks` ids, `issue:<id>`): dismiss, decline, ship (never undone), close (`reason`), mute, replan.", | |
| 1156 | "Decide asks (`items`: `asks` ids, `issue:<id>`): dismiss, decline, ship (final), close (`reason`), mute, replan.", | |
| 1156 | 1157 | inputSchema: { |
| 1157 | 1158 | type: "object", |
| 1158 | 1159 | properties: { |
| @@ -2672,7 +2673,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2672 | 2673 | { |
| 2673 | 2674 | name: "propose_to_parent_forge", |
| 2674 | 2675 | description: |
| 2675 | "Offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers that pull.", | |
| 2676 | "Offer this forge's landed change to its parent as a pull on `child/<name>/…`.", | |
| 2676 | 2677 | inputSchema: { |
| 2677 | 2678 | type: "object", |
| 2678 | 2679 | properties: { repo: REPO_ARG }, |
| @@ -3701,6 +3702,36 @@ const TOOLS: readonly Tool[] = [ | ||
| 3701 | 3702 | }); |
| 3702 | 3703 | }, |
| 3703 | 3704 | }, |
| 3705 | { | |
| 3706 | name: "mirror_now", | |
| 3707 | description: "Level the off-box mirror now (admin).", | |
| 3708 | inputSchema: { type: "object", properties: {} }, | |
| 3709 | writes: true, | |
| 3710 | adminOnly: true, | |
| 3711 | async run(ctx) { | |
| 3712 | const state = await snapshotsOf(ctx.app)?.mirrorNow(); | |
| 3713 | if (state === undefined) | |
| 3714 | return good({ level: false, says: "This forge has no mirror to bring level." }); | |
| 3715 | if (state.sourceError !== undefined) | |
| 3716 | return good({ | |
| 3717 | level: false, | |
| 3718 | error: state.sourceError, | |
| 3719 | says: `The snapshots could not be read from the destination, so the mirror was not touched: ${state.sourceError}`, | |
| 3720 | }); | |
| 3721 | if (state.failingSince === undefined) | |
| 3722 | return good({ | |
| 3723 | level: true, | |
| 3724 | ...(state.newest ? { newest: state.newest } : {}), | |
| 3725 | says: `The mirror is level${state.newest ? ` at ${state.newest}` : ""}.`, | |
| 3726 | }); | |
| 3727 | return good({ | |
| 3728 | level: false, | |
| 3729 | ...(state.newest ? { newest: state.newest } : {}), | |
| 3730 | error: state.error ?? "unknown reason", | |
| 3731 | says: `The mirror is not level: ${state.error ?? "unknown reason"}`, | |
| 3732 | }); | |
| 3733 | }, | |
| 3734 | }, | |
| 3704 | 3735 | { |
| 3705 | 3736 | name: "repo_labels", |
| 3706 | 3737 | description: |
| @@ -4088,7 +4119,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4088 | 4119 | { |
| 4089 | 4120 | name: "access", |
| 4090 | 4121 | description: |
| 4091 | "What outside agents tried: redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.", | |
| 4122 | "What outside agents tried: redacted non-browser requests to public paths, newest first, max 500. Admin.", | |
| 4092 | 4123 | inputSchema: { |
| 4093 | 4124 | type: "object", |
| 4094 | 4125 | properties: { |
| @@ -4167,7 +4198,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4167 | 4198 | { |
| 4168 | 4199 | name: "flow", |
| 4169 | 4200 | description: |
| 4170 | "The pipeline (forge admin): per-stage counts, `oldestWaiting`, `capacity`, bottleneck, `queue`, `reviewing` by reviewer.", | |
| 4201 | "The pipeline (forge admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, `queue`, `reviewing`.", | |
| 4171 | 4202 | inputSchema: { type: "object", properties: {} }, |
| 4172 | 4203 | writes: false, |
| 4173 | 4204 | run(ctx, user) { |
| @@ -4405,7 +4436,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4405 | 4436 | { |
| 4406 | 4437 | name: "quotas", |
| 4407 | 4438 | description: |
| 4408 | "Per-account repository and app quotas (number or null; not enforced yet). With `key`, `value` (\"\" clears), plans.", | |
| 4439 | "Per-account repo and app quotas (number or null; not enforced yet). With `key`, `value` (\"\" clears), plans.", | |
| 4409 | 4440 | inputSchema: { |
| 4410 | 4441 | type: "object", |
| 4411 | 4442 | properties: { |
test/mcp-mirror-now.test.ts added +88
| @@ -0,0 +1,88 @@ | ||
| 1 | /** `mirror_now` is the Backups page's "bring the mirror level" button over MCP, for a forge admin. */ | |
| 2 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync, rmSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createApp, type App } from "../src/app.ts"; | |
| 7 | import { createToken } from "../src/core/tokens.ts"; | |
| 8 | import { createUser } from "../src/core/users.ts"; | |
| 9 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 10 | import { startSnapshots, type SnapshotsHandle } from "../src/snapshot/service.ts"; | |
| 11 | import { dirStore } from "../src/snapshot/store.ts"; | |
| 12 | ||
| 13 | describe("MCP mirror_now", () => { | |
| 14 | let root: string; | |
| 15 | let app: App; | |
| 16 | let servers: Servers; | |
| 17 | let svc: SnapshotsHandle | undefined; | |
| 18 | let admin: string; | |
| 19 | let bob: string; | |
| 20 | let n = 1; | |
| 21 | ||
| 22 | const call = async (token: string) => { | |
| 23 | const res = await fetch(`${servers.url}/mcp`, { | |
| 24 | method: "POST", | |
| 25 | headers: { | |
| 26 | "content-type": "application/json", | |
| 27 | accept: "application/json, text/event-stream", | |
| 28 | authorization: `Bearer ${token}`, | |
| 29 | }, | |
| 30 | body: JSON.stringify({ | |
| 31 | jsonrpc: "2.0", | |
| 32 | id: n++, | |
| 33 | method: "tools/call", | |
| 34 | params: { name: "mirror_now", arguments: {} }, | |
| 35 | }), | |
| 36 | }); | |
| 37 | const body: any = await res.json(); | |
| 38 | if (body.error) return { error: body.error.message as string }; | |
| 39 | const text: string = body.result.content[0].text; | |
| 40 | return body.result.isError === true ? { error: text } : { value: JSON.parse(text) }; | |
| 41 | }; | |
| 42 | ||
| 43 | beforeAll(async () => { | |
| 44 | root = mkdtempSync(join(tmpdir(), "forge-mcp-mirror-now-")); | |
| 45 | app = createApp({ dataDir: root, port: 0 }); | |
| 46 | const mk = async (username: string, first: boolean) => { | |
| 47 | const u = await createUser(app.db, { | |
| 48 | origin: "seed", trusted: true, username, | |
| 49 | email: `${username}@forge.local`, password: "a-good-passphrase", adminIfFirst: first, | |
| 50 | }); | |
| 51 | if (!u.ok) throw new Error(u.error); | |
| 52 | return u.value; | |
| 53 | }; | |
| 54 | const alice = await mk("alice", true); | |
| 55 | const b = await mk("bob", false); | |
| 56 | admin = createToken(app.db, alice.id, "a", "admin").token; | |
| 57 | bob = createToken(app.db, b.id, "b", "admin").token; | |
| 58 | servers = await serve(app); | |
| 59 | }, 30_000); | |
| 60 | ||
| 61 | afterAll(async () => { | |
| 62 | servers.stop(); | |
| 63 | await svc?.stop(); | |
| 64 | app.close(); | |
| 65 | rmSync(root, { recursive: true, force: true }); | |
| 66 | }); | |
| 67 | ||
| 68 | test("no mirror answers the page's sentence", async () => { | |
| 69 | const r: any = await call(admin); | |
| 70 | expect(r.value).toEqual({ level: false, says: "This forge has no mirror to bring level." }); | |
| 71 | }); | |
| 72 | ||
| 73 | test("a non-admin is refused", async () => { | |
| 74 | const r: any = await call(bob); | |
| 75 | expect(r.value).toBeUndefined(); | |
| 76 | }); | |
| 77 | ||
| 78 | test("with a local destination and mirror, it reports level", async () => { | |
| 79 | svc = startSnapshots(app, dirStore(join(root, "store")), { | |
| 80 | version: "t", | |
| 81 | nightly: false, | |
| 82 | mirror: dirStore(join(root, "offbox")), | |
| 83 | }); | |
| 84 | const r: any = await call(admin); | |
| 85 | expect(r.value.level).toBe(true); | |
| 86 | expect(r.value.says).toStartWith("The mirror is level"); | |
| 87 | }); | |
| 88 | }); |
test/mcp.test.ts +1
| @@ -253,6 +253,7 @@ describe("the forge over MCP", () => { | ||
| 253 | 253 | "spend", |
| 254 | 254 | "usage", |
| 255 | 255 | "labels", |
| 256 | "mirror_now", | |
| 256 | 257 | "repo_labels", |
| 257 | 258 | "wait_for", |
| 258 | 259 | "confirm_wait", |
new above
offline