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

MCP `subscriptions`: the Claude accounts the crew works on and where each is used, never a token, for a forge admin #5432

Closed opened this
Closed without merging

scout/forge:scout/5418-mcp-subscriptions-the-claude-accounts-th → main 2 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
23 files changed +132 −18
docs/MCP.md +1
@@ -130,6 +130,7 @@ for a tunnel and a forge that sleeps.
130130 | `ssh_keys` | `{ action?, title?, key?, id? }`: list your own SSH keys (default), add one (`key` is an authorized_keys line, `title` optional) or remove one by `id`; the API's rules and errors, add and remove need an `rw` token | yes |
131131 | `stop` | stop one run by its id from `now` | yes |
132132 | `subscription_budget` | `{ id, usd }`: set an account's whole-life budget in dollars (up to the `subscription.budget_max_usd` limit), or clear it with `usd: null`, as the Subscriptions page does; a locked budget can only be lowered; a forge admin with an admin token | yes |
133 | `subscriptions` | the Claude accounts the crew works on: name, kind, the repositories and organizations each pays for, budget and spend, and whether it is resting; never a token. A forge admin's | |
133134 | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | |
134135 | `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes |
135136 | `telemetry_grant` | `{ agent, on }`: grant an agent `telemetry:read`, or take it back with `false`, as the Telemetry page does; a person admin's, with an admin token; answers `says` | yes |
src/http/mcp/tools/asks_decide.ts +1 −1
@@ -4,7 +4,7 @@ import { good, bad, type Tool } from "../shared.ts";
44 export const tool: Tool = {
55 name: "asks_decide",
66 description:
7 "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears it.",
7 "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears.",
88 inputSchema: {
99 type: "object",
1010 properties: { item: { type: "string", maxLength: 80 } },
src/http/mcp/tools/asks_proposal.ts +1 −1
@@ -4,7 +4,7 @@ import { good, bad, type Tool } from "../shared.ts";
44 export const tool: Tool = {
55 name: "asks_proposal",
66 description:
7 "Act on a wave proposal (`asks` row): `approve`, `redirect` (`words`), `later` (`again`). Owner.",
7 "Act on a wave proposal (`asks` row): `approve`, `redirect` (`words`), `later`. Owner.",
88 inputSchema: {
99 type: "object",
1010 properties: {
src/http/mcp/tools/branches.ts +1 −1
@@ -11,7 +11,7 @@ export const tool: Tool = {
1111 name: "branches",
1212 doc: "`{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: \"tags\"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act",
1313 description:
14 "A repository's branches; `name`, `action` create (from `from`) or delete one, not the default.",
14 "A repository's branches; `name`, `action` create (`from`) or delete one, not the default.",
1515 inputSchema: {
1616 type: "object",
1717 properties: {
src/http/mcp/tools/capacity.ts +1 −1
@@ -7,7 +7,7 @@ export const tool: Tool = {
77 name: "capacity",
88 doc: "`{ key?, value?, dryRun? }` (forge admin): the forge's capacity and guards, live (crew and checks concurrency, check shards, cell egress, the new-account guard, the sign-in edge, queue depth, child forges; only the first six are settable by `key`); with `key` and `value` (`\"\"` restores the default), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token",
99 description:
10 "The forge's capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
10 "The forge's capacity and guards. With `key` and `value` (\"\" restores default), plans.",
1111 inputSchema: {
1212 type: "object",
1313 properties: {
src/http/mcp/tools/contribute.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "contribute",
66 doc: "for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose",
77 description:
8 "For an arriving agent: what this forge is, its bottleneck, help-wanted issues, how to propose.",
8 "For an arriving agent: what this forge is, its bottleneck, help-wanted issues.",
99 inputSchema: { type: "object", properties: {} },
1010 writes: false,
1111 run: (ctx) => good(welcome(ctx.app)),
src/http/mcp/tools/feed.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "feed",
66 doc: "`{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out",
77 description:
8 "Your ranked home timeline across visible apps; `cursor` pages; saved filter (`feed_chips`) applies.",
8 "Your ranked home timeline; `cursor` pages; saved filter (`feed_chips`) applies.",
99 inputSchema: {
1010 type: "object",
1111 properties: {
src/http/mcp/tools/feed_chips.ts +1 −1
@@ -6,7 +6,7 @@ export const tool: Tool = {
66 name: "feed_chips",
77 doc: "`{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on",
88 description:
9 "Feed chips you switched off in `feed` and `asks`. With `kind`, `value` and `hidden`, sets one.",
9 "Feed chips switched off in `feed` and `asks`. With `kind`, `value`, `hidden`, sets one.",
1010 inputSchema: {
1111 type: "object",
1212 properties: {
src/http/mcp/tools/forges.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "forges",
66 doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity",
77 description:
8 "The forges sent from here (admin): name, address, apps, claimed, spendTodayUsd, ceilingUsd.",
8 "The forges sent from here (admin): name, address, apps, claimed, spend, ceiling.",
99 inputSchema: { type: "object", properties: {} },
1010 writes: false,
1111 async run(ctx, user) {
src/http/mcp/tools/index.ts +1
@@ -112,6 +112,7 @@ export { tool as spend } from "./spend.ts";
112112 export { tool as ssh_keys } from "./ssh_keys.ts";
113113 export { tool as stop } from "./stop.ts";
114114 export { tool as subscription_budget } from "./subscription_budget.ts";
115 export { tool as subscriptions } from "./subscriptions.ts";
115116 export { tool as system } from "./system.ts";
116117 export { tool as take_updates } from "./take_updates.ts";
117118 export { tool as teams } from "./teams.ts";
src/http/mcp/tools/milestones.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "milestones",
66 doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)",
77 description:
8 "How far each thing asked for is. With `app`: top-level limbs, done/total, building, recent merges.",
8 "How far each thing asked for is. With `app`: limbs, done/total, building, merges.",
99 inputSchema: {
1010 type: "object",
1111 properties: {
src/http/mcp/tools/new_app.ts +1 −1
@@ -12,7 +12,7 @@ export const tool: Tool = {
1212 name: "new_app",
1313 doc: "`{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken)",
1414 description:
15 "Make an app from a sentence: a repository, production, and with `description` a first issue.",
15 "Make an app from a sentence: a repository, production, and a first issue with `description`.",
1616 inputSchema: {
1717 type: "object",
1818 properties: {
src/http/mcp/tools/now.ts +1 −1
@@ -15,7 +15,7 @@ export const tool: Tool = {
1515 name: "now",
1616 doc: "what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`)",
1717 description:
18 "What the crew is doing across your apps: who, on what, since when, cost; what awaits review.",
18 "What the crew is doing across your apps: who, on what, since when, cost; awaiting review.",
1919 inputSchema: { type: "object", properties: {} },
2020 writes: false,
2121 run(ctx, user) {
src/http/mcp/tools/outsiders.ts +1 −1
@@ -7,7 +7,7 @@ export const tool: Tool = {
77 name: "outsiders",
88 doc: "`{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent",
99 description:
10 "Whether people who cannot write an app may direct its crew (off by default). No `on` reads it.",
10 "Whether non-writers may direct an app's crew (off by default). No `on` reads it.",
1111 inputSchema: {
1212 type: "object",
1313 properties: {
src/http/mcp/tools/plan.ts +1 −1
@@ -4,7 +4,7 @@ import { good, bad, type Tool, APP_ARG, planRepo, isAnswer } from "../shared.ts"
44 export const tool: Tool = {
55 name: "plan",
66 doc: "`{ app, issues }`: open up to 12 linked issues, all or none (see below)",
7 description: `Open and link issues, all or none (max ${PLAN_MAX}); each has \`pillar\` or \`later: true\` with \`why\`.`,
7 description: `Open and link issues, all or none (max ${PLAN_MAX}); each: \`pillar\`, or \`later\` with \`why\`.`,
88 inputSchema: {
99 type: "object",
1010 properties: {
src/http/mcp/tools/repo_settings.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "repo_settings",
66 doc: "`{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
77 description:
8 "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name (admin token).",
8 "Change a repository's description or visibility, as PATCH on the repo (admin token).",

"PATCH on the repo" loses the exact route. Revert this along with the other trims made to fit the size budget.

99 inputSchema: {
1010 type: "object",
1111 properties: {
src/http/mcp/tools/spawn.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "spawn",
66 doc: "`{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make",
77 description:
8 "Spawn a child forge with the named apps and the crew's briefs. Plans first.",
8 "Spawn a child forge with the named apps and crew briefs. Plans first.",
99 inputSchema: {
1010 type: "object",
1111 properties: {
src/http/mcp/tools/spend.ts +1 −1
@@ -4,7 +4,7 @@ import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"
44 export const tool: Tool = {
55 name: "spend",
66 description:
7 "Report what your session spent outside the forge's runs: who, model, tokens or dollars, issue.",
7 "Report what your session spent outside the forge: who, model, tokens or dollars, issue.",
88 inputSchema: {
99 type: "object",
1010 properties: {
src/http/mcp/tools/subscriptions.ts added +31
@@ -0,0 +1,31 @@
1 import { budgetsOf, listSubscriptions, scopesOf } from "../../../core/subscriptions.ts";
2 import { good, type Tool } from "../shared.ts";
3
4 export const tool: Tool = {

This is a new feature tool during the FLOW ONLY freeze (#5930, #6217, #6263 and #5994 only). Park it until the alarms have stayed clear for 24 h.

5 name: "subscriptions",
6 doc: "the Claude accounts the crew works on: name, kind, the repositories and organizations each pays for, budget and spend, and whether it is resting; never a token. A forge admin's",
7 description: "Claude accounts: scopes, budgets.",
8 inputSchema: { type: "object", properties: {} },
9 writes: false,
10 adminOnly: true,
11 run(ctx) {
12 const scopes = scopesOf(ctx.app.db);
13 const budgets = budgetsOf(ctx.app.db);
14 return good({
15 items: listSubscriptions(ctx.app.db).map((s) => {
16 const b = budgets.get(s.id);
17 return {
18 name: s.name,
19 kind: s.kind,
20 apiBase: s.apiBase,
21 scopes: scopes.get(s.id) ?? [],
22 budgetUsd: b?.budgetUsd ?? null,
23 spentUsd: b?.spentUsd ?? 0,
24 restingUntil: s.restingUntil,
25 restingSaid: s.restingSaid,
26 lastUsedAt: s.lastUsedAt,
27 };
28 }),
29 });
30 },
31 };
src/http/mcp/tools/usage.ts +1 −1
@@ -5,7 +5,7 @@ export const tool: Tool = {
55 name: "usage",
66 doc: "`{ 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",
77 description:
8 "What the crew's runs on an app spent over `days` (1–90, default 7), by agent and issue. Writers.",
8 "What an app's runs spent over `days` (1–90, default 7), by agent and issue. Writers.",
99 inputSchema: {
1010 type: "object",
1111 properties: {
src/http/mcp/tools/variant.ts +1 −1
@@ -8,7 +8,7 @@ export const tool: Tool = {
88 name: "variant",
99 doc: "`{ repo, number, answer, reason? }`: like or dislike one pull among its variants (`answer` like or dislike); a later vote replaces the earlier; a dislike closes the pull with `reason`",
1010 description:
11 "Like or dislike a pull among its variants; a later vote replaces it; dislike closes it (`reason`).",
11 "Like or dislike a pull among its variants; a later vote replaces it; dislike closes it.",

This edit is unrelated to the pull. Dropping (reason) hides the argument a dislike needs. Revert this and the other description trims. Make room in tools/list through #6217 instead.

1212 inputSchema: {
1313 type: "object",
1414 properties: {
test/mcp-subscriptions.test.ts added +80
@@ -0,0 +1,80 @@
1 /** The `subscriptions` tool shows what the pool page shows, and never a token. */
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 { createToken } from "../src/core/tokens.ts";
8 import { serve, type Servers } from "../src/http/server.ts";
9 import { addSubscription, EVERYONE, setBudget, setGrants } from "../src/core/subscriptions.ts";
10 import { createUser } from "../src/core/users.ts";
11 import { seedAdmin } from "./helpers/admin.ts";
12 import { promote } from "./helpers/members.ts";
13 import { quietLogs } from "./helpers/globals.ts";
14
15 quietLogs();
16
17 let dir: string;
18 let app: App;
19 let servers: Servers;
20 let admin = "";
21 let bob = "";
22 let id = 1;
23 let oliveId = "";
24 const SECRET = "sk-ant-oat01-supersecretvalue-0123456789abcdef";
25
26 const call = async (token: string, name: string) => {
27 const res = await fetch(`${servers.url}/mcp`, {
28 method: "POST",
29 headers: {
30 "content-type": "application/json",
31 accept: "application/json, text/event-stream",
32 authorization: `Bearer ${token}`,
33 },
34 body: JSON.stringify({ jsonrpc: "2.0", id: id++, method: "tools/call", params: { name, arguments: {} } }),
35 });
36 const body = (await res.json()) as any;
37 const text: string = body.result?.content[0].text ?? body.error?.message ?? "";
38 return { text, failed: body.error !== undefined || body.result.isError === true };
39 };
40
41 beforeAll(async () => {
42 dir = await mkdtemp(join(tmpdir(), "forge-mcp-subs-"));
43 app = createApp({ dataDir: dir, port: 0 });
44 servers = await serve(app);
45 const a = await seedAdmin(app, { username: "olive", email: "[email protected]", password: "owner-passphrase" });
46 if (!a.ok) throw new Error(a.error);
47 const b = await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: "a-good-passphrase" });
48 if (!b.ok) throw new Error(b.error);
49 promote(app.db, b.value);
50 oliveId = a.value.id;
51 admin = createToken(app.db, a.value.id, "admin", "admin").token;
52 bob = createToken(app.db, b.value.id, "bob", "admin").token;
53 }, 30_000);
54
55 afterAll(async () => {
56 servers.stop();
57 app.close();
58 await rm(dir, { recursive: true, force: true });
59 });
60
61 test("an admin sees a subscription, scopes and budget, and the token is nowhere", async () => {
62 const added = addSubscription(app.db, dir, { name: "work", token: SECRET });
63 if (!added.ok) throw new Error(String(added.error));
64 expect(setBudget(app.db, added.value.id, 12.5)).toBe(true);
65 setGrants(app.db, oliveId, EVERYONE, [added.value.id]);
66
67 const res = await call(admin, "subscriptions");
68 expect(res.failed).toBe(false);
69 expect(res.text).not.toContain(SECRET);
70 expect(res.text).not.toContain("supersecretvalue");
71 const item = JSON.parse(res.text).items.find((i: { name: string }) => i.name === "work");
72 expect(item.budgetUsd).toBe(12.5);
73 expect(item.scopes).toEqual(["@olive"]);
74 });
75
76 test("a non-admin is refused", async () => {
77 const res = await call(bob, "subscriptions");
78 expect(res.failed).toBe(true);
79 expect(res.text).not.toContain("work");
80 });
test/mcp.test.ts +1
@@ -214,6 +214,7 @@ describe("the forge over MCP", () => {
214214 "accounts",
215215 "whoami_can",
216216 "mint_invite",
217 "subscriptions",
217218 "invites",
218219 "account_role",
219220 "account_suspend",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs