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
scout/forge:scout/5418-mcp-subscriptions-the-claude-accounts-th → main 2 commits fork 3 threads · 3 unresolved
23 files
changed +132
−18
docs/MCP.md +1
| @@ -130,6 +130,7 @@ for a tunnel and a forge that sleeps. | ||
| 130 | 130 | | `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 | |
| 131 | 131 | | `stop` | stop one run by its id from `now` | yes | |
| 132 | 132 | | `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 | | | |
| 133 | 134 | | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | | |
| 134 | 135 | | `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 | |
| 135 | 136 | | `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"; | ||
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | name: "asks_decide", |
| 6 | 6 | 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.", | |
| 8 | 8 | inputSchema: { |
| 9 | 9 | type: "object", |
| 10 | 10 | 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"; | ||
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | name: "asks_proposal", |
| 6 | 6 | 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.", | |
| 8 | 8 | inputSchema: { |
| 9 | 9 | type: "object", |
| 10 | 10 | properties: { |
src/http/mcp/tools/branches.ts +1 −1
| @@ -11,7 +11,7 @@ export const tool: Tool = { | ||
| 11 | 11 | name: "branches", |
| 12 | 12 | 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", |
| 13 | 13 | 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.", | |
| 15 | 15 | inputSchema: { |
| 16 | 16 | type: "object", |
| 17 | 17 | properties: { |
src/http/mcp/tools/capacity.ts +1 −1
| @@ -7,7 +7,7 @@ export const tool: Tool = { | ||
| 7 | 7 | name: "capacity", |
| 8 | 8 | 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", |
| 9 | 9 | 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.", | |
| 11 | 11 | inputSchema: { |
| 12 | 12 | type: "object", |
| 13 | 13 | properties: { |
src/http/mcp/tools/contribute.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "contribute", |
| 6 | 6 | doc: "for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { type: "object", properties: {} }, |
| 10 | 10 | writes: false, |
| 11 | 11 | run: (ctx) => good(welcome(ctx.app)), |
src/http/mcp/tools/feed.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "feed", |
| 6 | 6 | 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", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/feed_chips.ts +1 −1
| @@ -6,7 +6,7 @@ export const tool: Tool = { | ||
| 6 | 6 | name: "feed_chips", |
| 7 | 7 | 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", |
| 8 | 8 | 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.", | |
| 10 | 10 | inputSchema: { |
| 11 | 11 | type: "object", |
| 12 | 12 | properties: { |
src/http/mcp/tools/forges.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "forges", |
| 6 | 6 | doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { type: "object", properties: {} }, |
| 10 | 10 | writes: false, |
| 11 | 11 | async run(ctx, user) { |
src/http/mcp/tools/index.ts +1
| @@ -112,6 +112,7 @@ export { tool as spend } from "./spend.ts"; | ||
| 112 | 112 | export { tool as ssh_keys } from "./ssh_keys.ts"; |
| 113 | 113 | export { tool as stop } from "./stop.ts"; |
| 114 | 114 | export { tool as subscription_budget } from "./subscription_budget.ts"; |
| 115 | export { tool as subscriptions } from "./subscriptions.ts"; | |
| 115 | 116 | export { tool as system } from "./system.ts"; |
| 116 | 117 | export { tool as take_updates } from "./take_updates.ts"; |
| 117 | 118 | export { tool as teams } from "./teams.ts"; |
src/http/mcp/tools/milestones.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "milestones", |
| 6 | 6 | 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)", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/new_app.ts +1 −1
| @@ -12,7 +12,7 @@ export const tool: Tool = { | ||
| 12 | 12 | name: "new_app", |
| 13 | 13 | 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)", |
| 14 | 14 | 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`.", | |
| 16 | 16 | inputSchema: { |
| 17 | 17 | type: "object", |
| 18 | 18 | properties: { |
src/http/mcp/tools/now.ts +1 −1
| @@ -15,7 +15,7 @@ export const tool: Tool = { | ||
| 15 | 15 | name: "now", |
| 16 | 16 | 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`)", |
| 17 | 17 | 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.", | |
| 19 | 19 | inputSchema: { type: "object", properties: {} }, |
| 20 | 20 | writes: false, |
| 21 | 21 | run(ctx, user) { |
src/http/mcp/tools/outsiders.ts +1 −1
| @@ -7,7 +7,7 @@ export const tool: Tool = { | ||
| 7 | 7 | name: "outsiders", |
| 8 | 8 | 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", |
| 9 | 9 | 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.", | |
| 11 | 11 | inputSchema: { |
| 12 | 12 | type: "object", |
| 13 | 13 | 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" | ||
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | name: "plan", |
| 6 | 6 | 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\`.`, | |
| 8 | 8 | inputSchema: { |
| 9 | 9 | type: "object", |
| 10 | 10 | properties: { |
src/http/mcp/tools/repo_settings.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "repo_settings", |
| 6 | 6 | 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`", |
| 7 | 7 | 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).", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/spawn.ts +1 −1
| @@ -5,7 +5,7 @@ export const tool: Tool = { | ||
| 5 | 5 | name: "spawn", |
| 6 | 6 | 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", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | 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" | ||
| 4 | 4 | export const tool: Tool = { |
| 5 | 5 | name: "spend", |
| 6 | 6 | 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.", | |
| 8 | 8 | inputSchema: { |
| 9 | 9 | type: "object", |
| 10 | 10 | 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 = { | ||
| 5 | 5 | name: "usage", |
| 6 | 6 | 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", |
| 7 | 7 | 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.", | |
| 9 | 9 | inputSchema: { |
| 10 | 10 | type: "object", |
| 11 | 11 | properties: { |
src/http/mcp/tools/variant.ts +1 −1
| @@ -8,7 +8,7 @@ export const tool: Tool = { | ||
| 8 | 8 | name: "variant", |
| 9 | 9 | 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`", |
| 10 | 10 | 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 |
||
| 12 | 12 | inputSchema: { |
| 13 | 13 | type: "object", |
| 14 | 14 | 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", () => { | ||
| 214 | 214 | "accounts", |
| 215 | 215 | "whoami_can", |
| 216 | 216 | "mint_invite", |
| 217 | "subscriptions", | |
| 217 | 218 | "invites", |
| 218 | 219 | "account_role", |
| 219 | 220 | "account_suspend", |
new above
offline
"PATCH on the repo" loses the exact route. Revert this along with the other trims made to fit the size budget.