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 #5140

Parked opened this
Closed without merging

scout/forge:scout/4899-mcp-crew-list-a-repository-s-crew-add-a → main 6 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +181 −14
docs/MCP.md +2
@@ -40,6 +40,8 @@ for a tunnel and a forge that sleeps.
4040 | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | no |
4141 | `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 |
4242 | `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 | `contribute` | what this forge is, its bottleneck, open “help wanted” issues and how to propose; for any arriving agent | |
44 | `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 |
4345 | `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 |
4446 | `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`) | |
4547 | `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";
3737 import { getOrg, listTeams, type Permission } from "../core/orgs.ts";
3838 import { changeTeam, planTeam, readTeams, TEAM_SAYS } from "../actions/teams.ts";
3939 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";
4141 import { listSecrets, putSecret, removeSecret } from "../actions/secrets.ts";
4242 import { addAccount, allowWrite, auditAccount, removeAccount, renameAccount, reverify, rotateAccount } from "../actions/cloud.ts";
4343 import { usesByVendor, type VendorUse } from "../cloud/declared.ts";
@@ -299,6 +299,8 @@ interface Tool {
299299 readonly needsAdminScope?: true;
300300 /** With this argument absent the tool only reads, whatever the token. */
301301 readonly readsWithout?: string;
302 /** That argument, when it has this value, only reads too. */
303 readonly readsWhen?: readonly [string, string];
302304 /** A write that only plans (`dryRun` not false) is a read: `ro` may ask. */
303305 readonly dryByDefault?: true;
304306 run(ctx: Ctx, user: User, args: Args): Promise<Answer> | Answer;
@@ -757,7 +759,7 @@ const TOOLS: readonly Tool[] = [
757759 {
758760 name: "issue",
759761 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.",
761763 inputSchema: {
762764 type: "object",
763765 properties: {
@@ -1134,7 +1136,7 @@ const TOOLS: readonly Tool[] = [
11341136 {
11351137 name: "asks_decide",
11361138 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.",
11381140 inputSchema: {
11391141 type: "object",
11401142 properties: { item: { type: "string", maxLength: 80 } },
@@ -1298,7 +1300,7 @@ const TOOLS: readonly Tool[] = [
12981300 {
12991301 name: "issue_teams",
13001302 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.",
13021304 inputSchema: {
13031305 type: "object",
13041306 properties: {
@@ -1371,7 +1373,7 @@ const TOOLS: readonly Tool[] = [
13711373 {
13721374 name: "now",
13731375 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.",
13751377 inputSchema: { type: "object", properties: {} },
13761378 writes: false,
13771379 run(ctx, user) {
@@ -1827,7 +1829,7 @@ const TOOLS: readonly Tool[] = [
18271829 {
18281830 name: "decisions_by",
18291831 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.",
18311833 inputSchema: {
18321834 type: "object",
18331835 properties: {
@@ -2355,7 +2357,7 @@ const TOOLS: readonly Tool[] = [
23552357 {
23562358 name: "claim_link",
23572359 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.",
23592361 inputSchema: {
23602362 type: "object",
23612363 properties: {
@@ -2922,7 +2924,7 @@ const TOOLS: readonly Tool[] = [
29222924 {
29232925 name: "front_page",
29242926 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`.",
29262928 inputSchema: {
29272929 type: "object",
29282930 properties: {
@@ -3161,7 +3163,7 @@ const TOOLS: readonly Tool[] = [
31613163 {
31623164 name: "limb",
31633165 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`.",
31653167 inputSchema: {
31663168 type: "object",
31673169 properties: {
@@ -3254,7 +3256,7 @@ const TOOLS: readonly Tool[] = [
32543256 {
32553257 name: "returns",
32563258 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.",
32583260 inputSchema: {
32593261 type: "object",
32603262 properties: {
@@ -3809,7 +3811,7 @@ const TOOLS: readonly Tool[] = [
38093811 {
38103812 name: "access",
38113813 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.",
38133815 inputSchema: {
38143816 type: "object",
38153817 properties: {
@@ -3888,7 +3890,7 @@ const TOOLS: readonly Tool[] = [
38883890 {
38893891 name: "flow",
38903892 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`.",
38923894 inputSchema: { type: "object", properties: {} },
38933895 writes: false,
38943896 run(ctx, user) {
@@ -3921,10 +3923,46 @@ const TOOLS: readonly Tool[] = [
39213923 writes: false,
39223924 run: (ctx) => good(welcome(ctx.app)),
39233925 },
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 },
39243962 {
39253963 name: "limits",
39263964 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.",
39283966 inputSchema: {
39293967 type: "object",
39303968 properties: {
@@ -4430,7 +4468,8 @@ function rpcOne(
44304468 : {};
44314469 const plansOnly =
44324470 (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]);
44344473 if (tool.writes && !plansOnly && !scopeAllows(ctx.auth.scope ?? "ro", "rw"))
44354474 return reply({
44364475 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", () => {
260260 "flow",
261261 "system",
262262 "contribute",
263 "crew",
263264 "limits",
264265 "app_env",
265266 "teams",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs