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
scout/forge:scout/4797-mcp-orgs-read-an-organization-its-teams → main 9 commits fork 1 thread · 1 unresolved
4 files
changed +165
−1
docs/MCP.md +1
| @@ -82,6 +82,7 @@ for a tunnel and a forge that sleeps. | ||
| 82 | 82 | | `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 | |
| 83 | 83 | | `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 | |
| 84 | 84 | | `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 | | |
| 85 | 86 | | `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 | |
| 86 | 87 | | `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 | |
| 87 | 88 | | `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"; | ||
| 249 | 249 | import { deleteOriginApp, listOriginApps, registerOriginApp } from "../actions/origins.ts"; |
| 250 | 250 | import { connectMessage } from "./api.ts"; |
| 251 | 251 | 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"; | |
| 253 | 255 | import { sizesView } from "../spawn/sizes.ts"; |
| 254 | 256 | import type { Router } from "./router.ts"; |
| 255 | 257 | import { mayReadRuns, runForReader, runLog } from "../actions/runs.ts"; |
| @@ -290,6 +292,14 @@ const bad = (error: string, message: string): Answer => ({ | ||
| 290 | 292 | message, |
| 291 | 293 | }); |
| 292 | 294 | |
| 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 | ||
| 293 | 303 | interface Tool { |
| 294 | 304 | readonly name: string; |
| 295 | 305 | readonly description: string; |
| @@ -4156,6 +4166,43 @@ const TOOLS: readonly Tool[] = [ | ||
| 4156 | 4166 | return good({ says: `${changed.value.name} saved at ${changed.value.dial}%.`, ...changed.value }); |
| 4157 | 4167 | }, |
| 4158 | 4168 | }, |
| 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 | }, | |
| 4159 | 4206 | { |
| 4160 | 4207 | name: "cloud_accounts", |
| 4161 | 4208 | 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", () => { | ||
| 265 | 265 | "limits", |
| 266 | 266 | "app_env", |
| 267 | 267 | "teams", |
| 268 | "orgs", | |
| 268 | 269 | "cloud_accounts", |
| 269 | 270 | "cloud_account", |
| 270 | 271 | "quotas", |
new above
offline