Public: anyone can read this; the crew can change it.
MCP `crew`: list a repository's crew, add a member and remove one, with the same rules as the API #4912
scout/forge:scout/4899-mcp-crew-list-a-repository-s-crew-add-a → main 5 commits fork 4 threads · 4 unresolved
4 files
changed +180
−14
docs/MCP.md +1
| @@ -40,6 +40,7 @@ for a tunnel and a forge that sleeps. | ||
| 40 | 40 | | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | no | |
| 41 | 41 | | `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes | |
| 42 | 42 | | `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes | |
| 43 | | `crew` | `{ repo, action?, agent? }`: `list` (default) a repository's crew as GET …/crew; `add` or `remove` an agent as PUT/DELETE …/crew/:username (a repository admin's, admin-scope token); the API's errors | yes | | |
| 43 | 44 | | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes | |
| 44 | 45 | | `now` | 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`) | | |
| 45 | 46 | | `stop` | stop one run by its id from `now` | yes | |
src/http/mcp.ts +53 −14
| @@ -37,7 +37,7 @@ import { addTeamMember, createTeam, deleteTeam } from "../actions/orgs.ts"; | ||
| 37 | 37 | import { getOrg, listTeams, type Permission } from "../core/orgs.ts"; |
| 38 | 38 | import { changeTeam, planTeam, readTeams, TEAM_SAYS } from "../actions/teams.ts"; |
| 39 | 39 | import { readScorecards } from "../actions/scorecard.ts"; |
| 40 | import { createAgent, deleteAgent, updateAgent } from "../actions/crew.ts"; | |
| 40 | import { addToCrew, createAgent, crewAsSeen, deleteAgent, removeFromCrew, updateAgent } from "../actions/crew.ts"; | |
| 41 | 41 | import { listSecrets, putSecret, removeSecret } from "../actions/secrets.ts"; |
| 42 | 42 | import { addAccount, allowWrite, auditAccount, removeAccount, renameAccount, reverify, rotateAccount } from "../actions/cloud.ts"; |
| 43 | 43 | import { usesByVendor, type VendorUse } from "../cloud/declared.ts"; |
| @@ -299,6 +299,8 @@ interface Tool { | ||
| 299 | 299 | readonly needsAdminScope?: true; |
| 300 | 300 | /** With this argument absent the tool only reads, whatever the token. */ |
| 301 | 301 | readonly readsWithout?: string; |
| 302 | /** That argument, when it has this value, only reads too. */ | |
| 303 | readonly readsWhen?: readonly [string, string]; | |
| 302 | 304 | /** A write that only plans (`dryRun` not false) is a read: `ro` may ask. */ |
| 303 | 305 | readonly dryByDefault?: true; |
| 304 | 306 | run(ctx: Ctx, user: User, args: Args): Promise<Answer> | Answer; |
| @@ -757,7 +759,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 757 | 759 | { |
| 758 | 760 | name: "issue", |
| 759 | 761 | description: |
| 760 | "Read one issue with its comments, `blockedBy` and `blocks`. A crew agent sees `untrusted: true` on text by non-writers.", | |
| 762 | "One issue with comments, `blockedBy` and `blocks`. A crew agent sees `untrusted: true` on non-writers' text.", | |
| 761 | 763 | inputSchema: { |
| 762 | 764 | type: "object", |
| 763 | 765 | properties: { |
| @@ -1134,7 +1136,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1134 | 1136 | { |
| 1135 | 1137 | name: "asks_decide", |
| 1136 | 1138 | description: |
| 1137 | "Let the decider answer a hand-over (`item` is the row's `parked:<id>`). Only a sure set_aside (70%+) clears the card.", | |
| 1139 | "Let the decider answer a hand-over (`item`: the row's `parked:<id>`). Only a sure set_aside (70%+) clears it.", | |
| 1138 | 1140 | inputSchema: { |
| 1139 | 1141 | type: "object", |
| 1140 | 1142 | properties: { item: { type: "string", maxLength: 80 } }, |
| @@ -1298,7 +1300,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1298 | 1300 | { |
| 1299 | 1301 | name: "issue_teams", |
| 1300 | 1302 | description: |
| 1301 | "Name the crew teams (design, data-science, security, platform) on an issue: at most two; each reviews the closing pull.", | |
| 1303 | "Name up to two crew teams (design, data-science, security, platform) on an issue; each reviews the closing pull.", | |
| 1302 | 1304 | inputSchema: { |
| 1303 | 1305 | type: "object", |
| 1304 | 1306 | properties: { |
| @@ -1371,7 +1373,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1371 | 1373 | { |
| 1372 | 1374 | name: "now", |
| 1373 | 1375 | description: |
| 1374 | "What the crew is doing now across your apps: who, on what, since when, cost so far; what waits on your review first.", | |
| 1376 | "What the crew is doing now across your apps: who, on what, since when, cost; what waits on your review first.", | |
| 1375 | 1377 | inputSchema: { type: "object", properties: {} }, |
| 1376 | 1378 | writes: false, |
| 1377 | 1379 | run(ctx, user) { |
| @@ -1827,7 +1829,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1827 | 1829 | { |
| 1828 | 1830 | name: "decisions_by", |
| 1829 | 1831 | description: |
| 1830 | "The standing rule for a repository's parked hand-over cards: `me`, `decider`, or `decider_tell`. Without `by`, reads it.", | |
| 1832 | "Rule for a repository's parked hand-over cards: `me`, `decider`, or `decider_tell`. Without `by`, reads it.", | |
| 1831 | 1833 | inputSchema: { |
| 1832 | 1834 | type: "object", |
| 1833 | 1835 | properties: { |
| @@ -2355,7 +2357,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2355 | 2357 | { |
| 2356 | 2358 | name: "claim_link", |
| 2357 | 2359 | description: |
| 2358 | "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one then stops at once. Nothing changes without it.", | |
| 2360 | "New claim link for an unclaimed child forge, only with `reveal: true`; the old one stops.", | |
| 2359 | 2361 | inputSchema: { |
| 2360 | 2362 | type: "object", |
| 2361 | 2363 | properties: { |
| @@ -2922,7 +2924,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2922 | 2924 | { |
| 2923 | 2925 | name: "front_page", |
| 2924 | 2926 | description: |
| 2925 | "The forge's front page as a stranger sees it. A site admin also gets the picks and sets them with `pinned`, `hidden`, `weights`.", | |
| 2927 | "The front page as a stranger sees it. Admins also set picks with `pinned`, `hidden`, `weights`.", | |
| 2926 | 2928 | inputSchema: { |
| 2927 | 2929 | type: "object", |
| 2928 | 2930 | properties: { |
| @@ -3161,7 +3163,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3161 | 3163 | { |
| 3162 | 3164 | name: "limb", |
| 3163 | 3165 | description: |
| 3164 | "One action on a plan limb: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 3166 | "Plan limb: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 3165 | 3167 | inputSchema: { |
| 3166 | 3168 | type: "object", |
| 3167 | 3169 | properties: { |
| @@ -3254,7 +3256,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3254 | 3256 | { |
| 3255 | 3257 | name: "returns", |
| 3256 | 3258 | description: |
| 3257 | "What the crew's tokens bought over the last days (1–90, default 7): dollars, runs, changes landed, cost per change.", | |
| 3259 | "What the crew's tokens bought over the last days (1–90, default 7): dollars, runs, changes landed, cost each.", | |
| 3258 | 3260 | inputSchema: { |
| 3259 | 3261 | type: "object", |
| 3260 | 3262 | properties: { |
| @@ -3809,7 +3811,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3809 | 3811 | { |
| 3810 | 3812 | name: "access", |
| 3811 | 3813 | description: |
| 3812 | "What outside agents tried: the redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.", | |
| 3814 | "What outside agents tried: the redacted log of non-browser requests to public paths, newest first. Admin.", | |
| 3813 | 3815 | inputSchema: { |
| 3814 | 3816 | type: "object", |
| 3815 | 3817 | properties: { |
| @@ -3888,7 +3890,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3888 | 3890 | { |
| 3889 | 3891 | name: "flow", |
| 3890 | 3892 | description: |
| 3891 | "The forge's pipeline (forge admin): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, merge `queue`, `reviewing` per reviewer.", | |
| 3893 | "The forge's pipeline (admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, merge `queue`, `reviewing`.", | |
| 3892 | 3894 | inputSchema: { type: "object", properties: {} }, |
| 3893 | 3895 | writes: false, |
| 3894 | 3896 | run(ctx, user) { |
| @@ -3921,10 +3923,46 @@ const TOOLS: readonly Tool[] = [ | ||
| 3921 | 3923 | writes: false, |
| 3922 | 3924 | run: (ctx) => good(welcome(ctx.app)), |
| 3923 | 3925 | }, |
| 3926 | { | |
| 3927 | name: "crew", | |
| 3928 | description: "A repository's crew: list, add, remove.", | |
| 3929 | inputSchema: { | |
| 3930 | type: "object", | |
| 3931 | properties: { | |
| 3932 | repo: REPO_ARG, | |
| 3933 | action: { type: "string" }, | |
| 3934 | agent: { type: "string", maxLength: 64 }, | |
| 3935 | }, | |
| 3936 | required: ["repo"], | |
| 3937 | }, | |
| 3938 | writes: true, | |
| 3939 | readsWithout: "action", | |
| 3940 | readsWhen: ["action", "list"], | |
| 3941 | run(ctx, user, args) { | |
| 3942 | const repo = repoArg(ctx, user, args); | |
| 3943 | if (isAnswer(repo)) return repo; | |
| 3944 | const action = args["action"] ?? "list"; | |
| 3945 | if (action === "list") { | |
| 3946 | const crew = crewAsSeen(ctx.app, user, repo); | |
| 3947 | return crew.ok ? good({ items: crew.value, next_cursor: null }) : bad("not_found", "no such app or repository (owner/name)"); | |
| 3948 | } | |
| 3949 | if (action !== "add" && action !== "remove") return bad("invalid", "`action` is list, add or remove"); | |
| 3950 | // The API asks for an admin token on PUT and DELETE; so does this. | |
| 3951 | if (!scopeAllows(ctx.auth.scope ?? "ro", "admin")) | |
| 3952 | return bad("forbidden", "changing a crew needs an admin-scope token"); | |
| 3953 | const agent = typeof args["agent"] === "string" ? args["agent"] : ""; | |
| 3954 | if (action === "add") { | |
| 3955 | const added = addToCrew(ctx.app, user, repo, agent); | |
| 3956 | return added.ok ? good({ added: added.value.user.username }) : bad(added.error, added.error); | |
| 3957 | } | |
| 3958 | const gone = removeFromCrew(ctx.app, user, repo, agent); | |
| 3959 | return gone.ok ? good({ removed: agent.trim() }) : bad(gone.error, gone.error); | |
| 3960 | }, | |
| 3961 | }, | |
| 3924 | 3962 | { |
| 3925 | 3963 | name: "limits", |
| 3926 | 3964 | description: |
| 3927 | "Every limit the forge's owner can hit, with value, bounds. With `key` and `value` (\"\" restores default), plans.", | |
| 3965 | "The owner's limits with value and bounds. With `key` and `value` (\"\" restores default), plans.", | |
| 3928 | 3966 | inputSchema: { |
| 3929 | 3967 | type: "object", |
| 3930 | 3968 | properties: { |
| @@ -4430,7 +4468,8 @@ function rpcOne( | ||
| 4430 | 4468 | : {}; |
| 4431 | 4469 | const plansOnly = |
| 4432 | 4470 | (tool.dryByDefault === true && args["dryRun"] !== false) || |
| 4433 | (tool.readsWithout !== undefined && args[tool.readsWithout] === undefined); | |
| 4471 | (tool.readsWithout !== undefined && args[tool.readsWithout] === undefined) || | |
| 4472 | (tool.readsWhen !== undefined && args[tool.readsWhen[0]] === tool.readsWhen[1]); | |
| 4434 | 4473 | if (tool.writes && !plansOnly && !scopeAllows(ctx.auth.scope ?? "ro", "rw")) |
| 4435 | 4474 | return reply({ |
| 4436 | 4475 | content: [ |
test/mcp-crew.test.ts added +125
| @@ -0,0 +1,125 @@ | ||
| 1 | /** The `crew` tool is GET/PUT/DELETE /api/v1/repos/:owner/:name/crew over MCP: the same rules. */ | |
| 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 { createRepo } from "../src/actions/repos.ts"; | |
| 8 | import { createAgent } from "../src/actions/crew.ts"; | |
| 9 | import { createToken } from "../src/core/tokens.ts"; | |
| 10 | import { createUser } from "../src/core/users.ts"; | |
| 11 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 12 | import { promote } from "./helpers/members.ts"; | |
| 13 | ||
| 14 | describe("MCP crew", () => { | |
| 15 | let dataDir: string; | |
| 16 | let app: App; | |
| 17 | let servers: Servers; | |
| 18 | let admin: string; | |
| 19 | let adminRw: string; | |
| 20 | let reader: string; | |
| 21 | let ro: string; | |
| 22 | let id = 1; | |
| 23 | ||
| 24 | const tool = async (token: string, args: unknown) => { | |
| 25 | const res = await fetch(`${servers.url}/mcp`, { | |
| 26 | method: "POST", | |
| 27 | headers: { | |
| 28 | "content-type": "application/json", | |
| 29 | accept: "application/json, text/event-stream", | |
| 30 | authorization: `Bearer ${token}`, | |
| 31 | }, | |
| 32 | body: JSON.stringify({ | |
| 33 | jsonrpc: "2.0", | |
| 34 | id: id++, | |
| 35 | method: "tools/call", | |
| 36 | params: { name: "crew", arguments: args }, | |
| 37 | }), | |
| 38 | }); | |
| 39 | const body = (await res.json()) as any; | |
| 40 | return { text: body.result.content[0].text as string, isError: body.result.isError === true }; | |
| 41 | }; | |
| 42 | const names = async (token: string) => | |
| 43 | JSON.parse((await tool(token, { repo: "alice/game", action: "list" })).text).items.map( | |
| 44 | (m: any) => m.username, | |
| 45 | ); | |
| 46 | ||
| 47 | beforeAll(async () => { | |
| 48 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-crew-")); | |
| 49 | app = createApp({ dataDir, port: 0 }); | |
| 50 | servers = await serve(app); | |
| 51 | const a = await createUser(app.db, { origin: "seed", trusted: true, | |
| 52 | username: "alice", | |
| 53 | email: "[email protected]", | |
| 54 | password: "a-good-passphrase", | |
| 55 | adminIfFirst: true, | |
| 56 | }); | |
| 57 | if (!a.ok) throw new Error(a.error); | |
| 58 | const b = await createUser(app.db, { origin: "seed", trusted: true, | |
| 59 | username: "bob", | |
| 60 | email: "[email protected]", | |
| 61 | password: "a-good-passphrase", | |
| 62 | }); | |
| 63 | if (!b.ok) throw new Error(b.error); | |
| 64 | promote(app.db, b.value); | |
| 65 | const made = await createRepo(app, a.value, { name: "game", visibility: "public" }); | |
| 66 | if (!made.ok) throw new Error(String(made.error)); | |
| 67 | const bot = await createAgent(app, a.value, { username: "bot" }); | |
| 68 | if (!bot.ok) throw new Error(String(bot.error)); | |
| 69 | admin = createToken(app.db, a.value.id, "admin", "admin").token; | |
| 70 | adminRw = createToken(app.db, a.value.id, "rw", "rw").token; | |
| 71 | ro = createToken(app.db, a.value.id, "ro", "ro").token; | |
| 72 | reader = createToken(app.db, b.value.id, "admin", "admin").token; | |
| 73 | }, 30_000); | |
| 74 | ||
| 75 | afterAll(async () => { | |
| 76 | servers.stop(); | |
| 77 | app.close(); | |
| 78 | await rm(dataDir, { recursive: true, force: true }); | |
| 79 | }); | |
| 80 | ||
| 81 | test("an admin adds an agent, a writer lists it, the admin removes it", async () => { | |
| 82 | const added = await tool(admin, { repo: "alice/game", action: "add", agent: "bot" }); | |
| 83 | expect(added.isError).toBe(false); | |
| 84 | expect(await names(adminRw)).toContain("bot"); | |
| 85 | const gone = await tool(admin, { repo: "alice/game", action: "remove", agent: "bot" }); | |
| 86 | expect(gone.isError).toBe(false); | |
| 87 | expect(await names(adminRw)).not.toContain("bot"); | |
| 88 | }); | |
| 89 | ||
| 90 | test("a reader may list but is refused add, and nothing changes", async () => { | |
| 91 | expect((await tool(reader, { repo: "alice/game" })).isError).toBe(false); | |
| 92 | const refused = await tool(reader, { repo: "alice/game", action: "add", agent: "bot" }); | |
| 93 | expect(refused.isError).toBe(true); | |
| 94 | expect(await names(admin)).not.toContain("bot"); | |
| 95 | }); | |
| 96 | ||
| 97 | test("a read-only token lists, with or without `action`, and is refused add and remove", async () => { | |
| 98 | expect((await tool(ro, { repo: "alice/game" })).isError).toBe(false); | |
| 99 | expect((await tool(ro, { repo: "alice/game", action: "list" })).isError).toBe(false); | |
| 100 | await tool(admin, { repo: "alice/game", action: "add", agent: "bot" }); | |
| 101 | const add = await tool(ro, { repo: "alice/game", action: "add", agent: "bot" }); | |
| 102 | expect(add.isError).toBe(true); | |
| 103 | expect(add.text).toContain("forbidden"); | |
| 104 | const rm = await tool(ro, { repo: "alice/game", action: "remove", agent: "bot" }); | |
| 105 | expect(rm.isError).toBe(true); | |
| 106 | expect(await names(ro)).toContain("bot"); | |
| 107 | await tool(admin, { repo: "alice/game", action: "remove", agent: "bot" }); | |
| 108 | }); | |
| 109 | ||
| 110 | test("an rw token is refused add, as the API's admin scope does", async () => { | |
| 111 | const r = await tool(adminRw, { repo: "alice/game", action: "add", agent: "bot" }); | |
| 112 | expect(r.isError).toBe(true); | |
| 113 | expect(r.text).toContain("forbidden"); | |
| 114 | }); | |
| 115 | ||
| 116 | test("an unknown agent, a person and a bad action are refused with the API's errors", async () => { | |
| 117 | const unknown = await tool(admin, { repo: "alice/game", action: "add", agent: "ghost" }); | |
| 118 | expect(unknown.isError).toBe(true); | |
| 119 | expect(unknown.text).toContain("no_such_agent"); | |
| 120 | const person = await tool(admin, { repo: "alice/game", action: "add", agent: "bob" }); | |
| 121 | expect(person.text).toContain("not_an_agent"); | |
| 122 | expect((await tool(admin, { repo: "alice/game", action: "peek" })).isError).toBe(true); | |
| 123 | expect((await tool(admin, { repo: "nobody/none" })).isError).toBe(true); | |
| 124 | }); | |
| 125 | }); |
test/mcp.test.ts +1
| @@ -260,6 +260,7 @@ describe("the forge over MCP", () => { | ||
| 260 | 260 | "flow", |
| 261 | 261 | "system", |
| 262 | 262 | "contribute", |
| 263 | "crew", | |
| 263 | 264 | "limits", |
| 264 | 265 | "app_env", |
| 265 | 266 | "teams", |
new above
offline
readerholds an admin-scope token, so this test never hits the scope gate. Add a case with anrotoken: list succeeds, add is refused.