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

MCP `orgs`: read an organization, its teams and their members, and create one, with the same rules as the API #5102

Parked opened this
Closed without merging

scout/forge:scout/4797-mcp-orgs-read-an-organization-its-teams → main 9 commits fork 1 thread · 1 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +165 −1
docs/MCP.md +1
@@ -82,6 +82,7 @@ for a tunnel and a forge that sleeps.
8282 | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes |
8383 | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes |
8484 | `usage` | `{ 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 | |
85 | `orgs` | `{ action, org?, name? }`: `mine` lists your organizations, `read` one with the teams you may see and their members, `create` one (rw token); as `/api/v1/user/orgs`, `/orgs/:org` with its teams and members, and `POST /api/v1/orgs`: unknown org is not found, a taken, reserved or invalid name is refused | yes |
8586 | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes |
8687 | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes |
8788 | `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 |
src/http/mcp.ts +48 −1
@@ -249,7 +249,9 @@ import { COPIES_PER_DAY, makeItYours } from "../actions/make_it_yours.ts";
249249 import { deleteOriginApp, listOriginApps, registerOriginApp } from "../actions/origins.ts";
250250 import { connectMessage } from "./api.ts";
251251 import { resourceMetadataUrl } from "./oauth.ts";
252 import { body, boundedBody, json } from "./respond.ts";
252 import { body, boundedBody, json, publicProfile } from "./respond.ts";
253 import { createOrg } from "../actions/orgs.ts";
254 import { listOrgsForUser, listTeamMembers, listTeamsVisibleTo } from "../core/orgs.ts";
253255 import { sizesView } from "../spawn/sizes.ts";
254256 import type { Router } from "./router.ts";
255257 import { mayReadRuns, runForReader, runLog } from "../actions/runs.ts";
@@ -290,6 +292,14 @@ const bad = (error: string, message: string): Answer => ({
290292 message,
291293 });
292294
295 const ORG_SAYS: Record<string, string> = {
296 invalid_name: "that is not a name an organization can have",
297 name_taken: "that name is taken",
298 name_reserved: "that name is reserved",
299 unverified: "verify your email first",
300 agent_cannot_own: "an agent cannot own an organization",
301 };
302
293303 interface Tool {
294304 readonly name: string;
295305 readonly description: string;
@@ -4156,6 +4166,43 @@ const TOOLS: readonly Tool[] = [
41564166 return good({ says: `${changed.value.name} saved at ${changed.value.dial}%.`, ...changed.value });
41574167 },
41584168 },
4169 {
4170 name: "orgs",
4171 description: "Your orgs; read one with its teams and members; create one.",
4172 inputSchema: {
4173 type: "object",
4174 properties: {
4175 action: { type: "string", enum: ["mine", "read", "create"] },
4176 org: { type: "string", maxLength: 64 },
4177 name: { type: "string", maxLength: 64 },
4178 },
4179 },
4180 // `create` founds an account, so the tool is announced as a write; `mine`
4181 // and `read` never pass `name` and stay open to an ro token.
4182 writes: true,
4183 readsWithout: "name",
4184 run(ctx, user, args) {
4185 const { action, org, name } = args;
4186 if (action === "mine") return good({ orgs: listOrgsForUser(ctx.app.db, user.id).map(publicProfile) });
4187 if (action === "read") {
4188 const found = typeof org === "string" ? getOrg(ctx.app.db, org) : undefined;
4189 if (!found) return bad("not_found", "no such organization");
4190 // Only the teams the reader may see, as GET /api/v1/orgs/:org says.
4191 const teams = listTeamsVisibleTo(ctx.app.db, found.id, user).map((t) => ({
4192 name: t.name,
4193 permission: t.permission,
4194 members: listTeamMembers(ctx.app.db, t.id).map(publicProfile),
4195 }));
4196 return good({ id: found.id, ...publicProfile(found), teams });
4197 }
4198 if (action === "create") {
4199 const made = createOrg(ctx.app, user, typeof name === "string" ? name : "");
4200 if (!made.ok) return bad(made.error, ORG_SAYS[made.error] ?? made.error);
4201 return good({ id: made.value.id, username: made.value.username, kind: "org" });
4202 }
4203 return bad("invalid", "action is mine, read or create");
4204 },
4205 },
41594206 {
41604207 name: "cloud_accounts",
41614208 description:
test/mcp-orgs.test.ts added +115
@@ -0,0 +1,115 @@
1 /**
2 * The `orgs` tool is the organization API over MCP: the same functions, so
3 * the same rules. A person makes one and reads it back; a stranger sees no
4 * teams; a bad or taken name is refused with the API's code.
5 */
6 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { createToken } from "../src/core/tokens.ts";
12 import { createUser } from "../src/core/users.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { promote } from "./helpers/members.ts";
15
16 describe("MCP orgs", () => {
17 let dataDir: string;
18 let app: App;
19 let servers: Servers;
20 let aliceRw: string;
21 let aliceRo: string;
22 let bobRw: string;
23 let id = 1;
24
25 const tool = async (token: string, args: unknown) => {
26 const res = await fetch(`${servers.url}/mcp`, {
27 method: "POST",
28 headers: {
29 "content-type": "application/json",
30 accept: "application/json, text/event-stream",
31 authorization: `Bearer ${token}`,
32 },
33 body: JSON.stringify({
34 jsonrpc: "2.0",
35 id: id++,
36 method: "tools/call",
37 params: { name: "orgs", arguments: args },
38 }),
39 });
40 const body: any = await res.json();
41 const text: string = body.result.content[0].text;
42 return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
43 };
44
45 beforeAll(async () => {
46 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-orgs-"));
47 app = createApp({ dataDir, port: 0 });
48 servers = await serve(app);
49 const a = await createUser(app.db, { origin: "seed", trusted: true,
50 username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
51 if (!a.ok) throw new Error(a.error);
52 promote(app.db, a.value);
53 const b = await createUser(app.db, { origin: "seed", trusted: true,
54 username: "bob", email: "[email protected]", password: "a-good-passphrase" });
55 if (!b.ok) throw new Error(b.error);
56 promote(app.db, b.value);
57 aliceRw = createToken(app.db, a.value.id, "rw", "rw").token;
58 aliceRo = createToken(app.db, a.value.id, "ro", "ro").token;
59 bobRw = createToken(app.db, b.value.id, "rw", "rw").token;
60 }, 30_000);
61
62 afterAll(async () => {
63 servers.stop();
64 app.close();
65 await rm(dataDir, { recursive: true, force: true });
66 });
67
68 test("a person creates an org and reads it back with its teams and members", async () => {
69 const made = await tool(aliceRw, { action: "create", name: "acme" });
70 expect(made.value).toMatchObject({ username: "acme", kind: "org" });
71 const org = (await tool(aliceRw, { action: "read", org: "acme" })).value;
72 expect(org.username).toBe("acme");
73 expect(org.teams.map((t: any) => t.name)).toEqual(["Owners"]);
74 expect(org.teams[0].members.map((m: any) => m.username)).toEqual(["alice"]);
75 const mine = await tool(aliceRw, { action: "mine" });
76 expect(mine.value.orgs.map((o: any) => o.username)).toEqual(["acme"]);
77 expect((await tool(bobRw, { action: "mine" })).value.orgs).toEqual([]);
78 });
79
80 test("a non-member sees no teams and an unknown org is not found", async () => {
81 const org = (await tool(bobRw, { action: "read", org: "acme" })).value;
82 expect(org.teams).toEqual([]);
83 expect((await tool(bobRw, { action: "read", org: "nope" })).error).toContain("no such organization");
84 expect((await tool(bobRw, { action: "read" })).error).toContain("no such organization");
85 });
86
87 test("a taken, reserved or invalid name is refused with the API's code", async () => {
88 expect((await tool(bobRw, { action: "create", name: "acme" })).error).toContain("name_taken");
89 expect((await tool(bobRw, { action: "create", name: "alice" })).error).toContain("name_taken");
90 expect((await tool(bobRw, { action: "create", name: "admin" })).error).toContain("name_reserved");
91 expect((await tool(bobRw, { action: "create", name: "not a name!" })).error).toContain("invalid_name");
92 expect((await tool(bobRw, { action: "create" })).error).toContain("invalid");
93 });
94
95 test("a read-only token reads but does not create", async () => {
96 expect((await tool(aliceRo, { action: "mine" })).value.orgs).toHaveLength(1);
97 expect((await tool(aliceRo, { action: "create", name: "beta" })).error).toContain("forbidden");
98 });
99
100 test("tools/list announces orgs as a write, not read-only", async () => {
101 const res = await fetch(`${servers.url}/mcp`, {
102 method: "POST",
103 headers: {
104 "content-type": "application/json",
105 accept: "application/json, text/event-stream",
106 authorization: `Bearer ${aliceRw}`,
107 },
108 body: JSON.stringify({ jsonrpc: "2.0", id: 9999, method: "tools/list" }),
109 });
110 const body: any = await res.json();
111 const orgs = body.result.tools.find((t: any) => t.name === "orgs");
112 // readOnlyHint defaults to false, so a write carries no annotation
113 expect(orgs.annotations?.readOnlyHint).not.toBe(true);
114 });
115 });
test/mcp.test.ts +1
@@ -265,6 +265,7 @@ describe("the forge over MCP", () => {
265265 "limits",
266266 "app_env",
267267 "teams",
268 "orgs",
268269 "cloud_accounts",
269270 "cloud_account",
270271 "quotas",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs