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

MCP `backups`: where snapshots go and the last ones taken, for a forge admin #5435

Parked opened this
Closed without merging

scout/forge:scout/5415-mcp-backups-where-snapshots-go-and-the-l → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +158 −18
docs/MCP.md +1
@@ -97,6 +97,7 @@ for a tunnel and a forge that sleeps.
9797 | `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 |
9898 | `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 |
9999 | `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes |
100 | `backups` | no input: for a forge admin, where snapshots go (kind and place, never a credential, or `null` with the page's sentence), the last fourteen the store holds (key, when, bytes) and the off-box mirror's state, as /settings/backups shows them | |
100101 | `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes |
101102 | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes |
102103 | `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes |
src/http/mcp.ts +58 −17
@@ -77,6 +77,10 @@ import {
7777 submitReview,
7878 } from "../actions/pulls.ts";
7979 import { originError } from "../web/pages/thread.ts";
80 import { NO_DESTINATION } from "../web/pages/backups.ts";
81 import { resolveDestination } from "../snapshot/destination.ts";
82 import { mirrorNeed } from "../snapshot/mirror.ts";
83 import { snapshotsOf } from "../snapshot/service.ts";
8084 import { holdPull, releasePull } from "../actions/holds.ts";
8185 import { openPlan, parsePlan, PLAN_MAX, proposePlan } from "../actions/plan.ts";
8286 import {
@@ -513,7 +517,7 @@ const TOOLS: readonly Tool[] = [
513517 {
514518 name: "new_app",
515519 description:
516 "Make an app from a sentence: a repository, production started, and with `description` a first issue.",
520 "Make an app from a sentence: a repository, production, and a first issue with `description`.",
517521 inputSchema: {
518522 type: "object",
519523 properties: {
@@ -598,7 +602,7 @@ const TOOLS: readonly Tool[] = [
598602 {
599603 name: "repo_settings",
600604 description:
601 "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name (admin token).",
605 "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name.",
602606 inputSchema: {
603607 type: "object",
604608 properties: {
@@ -634,7 +638,7 @@ const TOOLS: readonly Tool[] = [
634638 {
635639 name: "here",
636640 description:
637 "What you can do on a forge page, as who you are: each open action with its HTTP route and MCP tool.",
641 "What you can do on a forge page: each open action with its HTTP route and MCP tool.",
638642 inputSchema: {
639643 type: "object",
640644 properties: { url: { type: "string", maxLength: 2000 } },
@@ -661,7 +665,7 @@ const TOOLS: readonly Tool[] = [
661665 {
662666 name: "tell",
663667 description:
664 "Tell an app's crew what should change (first line is the title). No `repo`: kept, answers a thought id.",
668 "Tell an app's crew what should change (first line is the title). No `repo`: kept as a thought.",
665669 inputSchema: {
666670 type: "object",
667671 properties: {
@@ -740,7 +744,7 @@ const TOOLS: readonly Tool[] = [
740744 {
741745 name: "share",
742746 description:
743 "Share a feed item: no `to` tells the app's crew and owners, else its followers; daily budget each.",
747 "Share a feed item: no `to` tells the app's crew and owners, else followers; daily budget.",
744748 inputSchema: {
745749 type: "object",
746750 properties: {
@@ -767,7 +771,7 @@ const TOOLS: readonly Tool[] = [
767771 {
768772 name: "say",
769773 description:
770 "Say something on an issue or pull. A working builder hears it next; otherwise the next run does.",
774 "Say something on an issue or pull. A working builder hears it next, else the next run.",
771775 inputSchema: {
772776 type: "object",
773777 properties: {
@@ -799,7 +803,7 @@ const TOOLS: readonly Tool[] = [
799803 {
800804 name: "issue",
801805 description:
802 "One issue with comments, `blockedBy`, `blocks`; a crew agent sees `untrusted: true` on text by non-writers.",
806 "One issue with comments, `blockedBy`, `blocks`; crew agents see `untrusted: true` on non-writers' text.",
803807 inputSchema: {
804808 type: "object",
805809 properties: {
@@ -868,7 +872,7 @@ const TOOLS: readonly Tool[] = [
868872 {
869873 name: "pull",
870874 description:
871 "Read a pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.",
875 "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.",
872876 inputSchema: {
873877 type: "object",
874878 properties: {
@@ -911,7 +915,7 @@ const TOOLS: readonly Tool[] = [
911915 {
912916 name: "pulls",
913917 description:
914 "A repository's pulls, newest first. `state` open (default) or closed; `limit` 1-50 (default 20).",
918 "A repository's pulls, newest first. `state` open (default) or closed; `limit` 1-50.",
915919 inputSchema: {
916920 type: "object",
917921 properties: {
@@ -955,7 +959,7 @@ const TOOLS: readonly Tool[] = [
955959 {
956960 name: "variant",
957961 description:
958 "Like or dislike one pull among its variants; a later vote replaces it; a dislike closes it (`reason`).",
962 "Like or dislike a pull among variants; a later vote replaces it; a dislike closes it.",
959963 inputSchema: {
960964 type: "object",
961965 properties: {
@@ -996,7 +1000,7 @@ const TOOLS: readonly Tool[] = [
9961000 {
9971001 name: "edit",
9981002 description:
999 "Retitle or rewrite an issue or pull: yours, or any where you write; an agent edits only its own.",
1003 "Retitle or rewrite an issue or pull: yours, or where you write; agents only their own.",
10001004 inputSchema: {
10011005 type: "object",
10021006 properties: {
@@ -1140,7 +1144,7 @@ const TOOLS: readonly Tool[] = [
11401144 {
11411145 name: "asks",
11421146 description:
1143 "What waits on you, most consequential first: decision, options, cost of inaction; your saved filter applies.",
1147 "What waits on you, most consequential first: decision, options, cost of inaction; your filter applies.",
11441148 inputSchema: { type: "object", properties: { ...CHIP_ARGS } },
11451149 writes: false,
11461150 run(ctx, user, args) {
@@ -1152,7 +1156,7 @@ const TOOLS: readonly Tool[] = [
11521156 {
11531157 name: "asks_act",
11541158 description:
1155 "Decide asks (`items`: `asks` ids, `issue:<id>`): dismiss, decline, ship (never undone), close (`reason`), mute, replan.",
1159 "Decide asks (`items`: `asks` ids, `issue:<id>`): dismiss, decline, ship (final), close (`reason`), mute, replan.",
11561160 inputSchema: {
11571161 type: "object",
11581162 properties: {
@@ -2672,7 +2676,7 @@ const TOOLS: readonly Tool[] = [
26722676 {
26732677 name: "propose_to_parent_forge",
26742678 description:
2675 "Offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers that pull.",
2679 "Offer this forge's landed change to its parent as a pull on `child/<name>/…`.",
26762680 inputSchema: {
26772681 type: "object",
26782682 properties: { repo: REPO_ARG },
@@ -4038,7 +4042,7 @@ const TOOLS: readonly Tool[] = [
40384042 {
40394043 name: "prompts",
40404044 description:
4041 "An app's prompt sources (Instagram): list, add (`kind`, `token`, `at`), run or remove (`id`). Repository admin token.",
4045 "An app's prompt sources (Instagram): list, add (`kind`, `token`, `at`), run or remove (`id`). Repo admin.",
40424046 inputSchema: {
40434047 type: "object",
40444048 properties: {
@@ -4088,7 +4092,7 @@ const TOOLS: readonly Tool[] = [
40884092 {
40894093 name: "access",
40904094 description:
4091 "What outside agents tried: redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.",
4095 "What outside agents tried: redacted non-browser requests to public paths, newest first, max 500. Admin.",
40924096 inputSchema: {
40934097 type: "object",
40944098 properties: {
@@ -4167,7 +4171,7 @@ const TOOLS: readonly Tool[] = [
41674171 {
41684172 name: "flow",
41694173 description:
4170 "The pipeline (forge admin): per-stage counts, `oldestWaiting`, `capacity`, bottleneck, `queue`, `reviewing` by reviewer.",
4174 "The pipeline (admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, `queue`, `reviewing`.",
41714175 inputSchema: { type: "object", properties: {} },
41724176 writes: false,
41734177 run(ctx, user) {
@@ -4331,6 +4335,43 @@ const TOOLS: readonly Tool[] = [
43314335 return good({ says: `${changed.value.name} saved at ${changed.value.dial}%.`, ...changed.value });
43324336 },
43334337 },
4338 {
4339 name: "backups",
4340 description: "Backups (admin): destination, last snapshots, mirror.",
4341 inputSchema: { type: "object", properties: {} },
4342 adminOnly: true,
4343 writes: false,
4344 async run(ctx, user) {
4345 if (!user.isAdmin) return bad("not_found", "The page you asked for does not exist, or is not visible to you.");
4346 const dest = resolveDestination({ db: ctx.app.db, dataDir: ctx.app.config.dataDir, bus: ctx.app.bus });
4347 const svc = snapshotsOf(ctx.app);
4348 const mirror = svc?.mirrored();
4349 const need = mirrorNeed(mirror, Date.now());
4350 const mirrorSays = {
4351 configured: svc?.mirror !== undefined,
4352 where: svc?.mirror?.where ?? null,
4353 reachable: mirror?.reachable ?? null,
4354 syncedAt: mirror?.syncedAt ?? null,
4355 newest: mirror?.newest ?? null,
4356 problem: need?.sentence ?? null,
4357 };
4358 if (!dest || svc?.store === undefined)
4359 return good({ destination: null, says: NO_DESTINATION, snapshots: [], mirror: mirrorSays });
4360 let snapshots: { key: string; at: string; bytes: number }[] = [];
4361 let listing: string | null = null;
4362 try {
4363 snapshots = (await svc.list()).slice(0, 14).map((m) => ({ key: m.name, at: m.finishedAt, bytes: m.bytes }));
4364 } catch (error) {
4365 listing = String(error);
4366 }
4367 return good({
4368 destination: { kind: dest.source, where: svc.store.where },
4369 snapshots,
4370 listing,
4371 mirror: mirrorSays,
4372 });
4373 },
4374 },
43344375 {
43354376 name: "cloud_accounts",
43364377 description:
src/web/pages/backups.ts +5 −1
@@ -44,6 +44,10 @@ import { flashTo, fragment, page, redirect } from "../layout.ts";
4444 import { badge, btn, card, empty, fileSize, icon, row, time } from "../ui.ts";
4545 import { accountSections } from "./origins.ts";
4646
47 /** What the page says when the forge was given nowhere to put snapshots. */
48 export const NO_DESTINATION =
49 "This forge was given nowhere to put them. On the platform an app's bucket (S3_*) is the place; on a machine, FORGE_SNAPSHOT_DIR names a directory. Seal a bucket below, or restart with one set, and a snapshot is taken every night at 08:00 UTC.";
50
4751 function requireAdmin(ctx: Ctx): Response | undefined {
4852 if (!ctx.auth.user) return signInFirst(ctx);
4953 if (!ctx.auth.user.isAdmin) return notFoundPage(ctx);
@@ -273,7 +277,7 @@ export async function backupsPage(ctx: Ctx): Promise<Response> {
273277 })}${empty({
274278 icon: "download",
275279 title: "No snapshots are taken",
276 note: "This forge was given nowhere to put them. On the platform an app's bucket (S3_*) is the place; on a machine, FORGE_SNAPSHOT_DIR names a directory. Seal a bucket below, or restart with one set, and a snapshot is taken every night at 08:00 UTC.",
280 note: NO_DESTINATION,
277281 })}${form}`,
278282 ),
279283 );
test/mcp-backups.test.ts added +93
@@ -0,0 +1,93 @@
1 /** The `backups` tool is /settings/backups over MCP: admins only, no credential in any answer. */
2 import { afterAll, beforeAll, describe, 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 { 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 } from "../src/snapshot/service.ts";
11 import { dirStore } from "../src/snapshot/store.ts";
12 import { promote } from "./helpers/members.ts";
13
14 describe("MCP backups", () => {
15 let dataDir: string;
16 let app: App;
17 let servers: Servers;
18 let admin: string;
19 let other: string;
20 let id = 1;
21 const saved = { ...process.env };
22
23 const rpc = async (token: string, method: string, params?: unknown) => {
24 const res = await fetch(`${servers.url}/mcp`, {
25 method: "POST",
26 headers: {
27 "content-type": "application/json",
28 accept: "application/json, text/event-stream",
29 authorization: `Bearer ${token}`,
30 },
31 body: JSON.stringify({ jsonrpc: "2.0", id: id++, method, params }),
32 });
33 return (await res.json()) as any;
34 };
35 const call = async (token: string) => {
36 const body = await rpc(token, "tools/call", { name: "backups", arguments: {} });
37 return body.result ?? body.error;
38 };
39
40 beforeAll(async () => {
41 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-backups-"));
42 for (const k of Object.keys(process.env))
43 if (k.startsWith("S3_") || k === "FORGE_SNAPSHOT_DIR") delete process.env[k];
44 app = createApp({ dataDir, port: 0 });
45 servers = await serve(app);
46 const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice",
47 email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
48 if (!a.ok) throw new Error(a.error);
49 const b = await createUser(app.db, { origin: "seed", trusted: true, username: "bob",
50 email: "[email protected]", password: "a-good-passphrase" });
51 if (!b.ok) throw new Error(b.error);
52 promote(app.db, b.value);
53 admin = createToken(app.db, a.value.id, "admin", "admin").token;
54 other = createToken(app.db, b.value.id, "rw", "rw").token;
55 }, 30_000);
56
57 afterAll(async () => {
58 process.env = saved;
59 servers.stop();
60 app.close();
61 await rm(dataDir, { recursive: true, force: true });
62 });
63
64 test("an admin with no destination gets the page's sentence", async () => {
65 const r = await call(admin);
66 expect(r.isError).not.toBe(true);
67 const v = JSON.parse(r.content[0].text);
68 expect(v.destination).toBeNull();
69 expect(v.says).toContain("given nowhere to put them");
70 expect(v.snapshots).toEqual([]);
71 });
72
73 test("an admin with a local destination sees the snapshot", async () => {
74 const dir = join(dataDir, "snaps");
75 process.env["FORGE_SNAPSHOT_DIR"] = dir;
76 const svc = startSnapshots(app, dirStore(dir), { version: "t", nightly: false });
77 const made = await svc.now();
78 const r = await call(admin);
79 const v = JSON.parse(r.content[0].text);
80 expect(v.destination.kind).toBe("dir");
81 expect(v.destination.where).toBe(dirStore(dir).where);
82 expect(v.snapshots).toHaveLength(1);
83 expect(v.snapshots[0].key).toBe(made.name);
84 expect(v.snapshots[0].bytes).toBeGreaterThan(0);
85 expect(v.mirror.configured).toBe(false);
86 }, 30_000);
87
88 test("a non-admin is refused", async () => {
89 const r = await call(other);
90 expect(JSON.stringify(r)).not.toContain("snapshots");
91 expect(r.isError === true || r.code !== undefined).toBe(true);
92 });
93 });
test/mcp.test.ts +1
@@ -268,6 +268,7 @@ describe("the forge over MCP", () => {
268268 "limits",
269269 "app_env",
270270 "teams",
271 "backups",
271272 "cloud_accounts",
272273 "cloud_account",
273274 "quotas",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs