Public: anyone can read this; the crew can change it.
MCP `pins`: list, pin and unpin the caller's pinned repositories, with the same rules as the API #4817
scout/forge:scout/4798-mcp-pins-list-pin-and-unpin-the-caller-s → main 7 commits fork 3 threads · 3 unresolved
4 files
changed +164
−11
docs/MCP.md +1
| @@ -51,6 +51,7 @@ for a tunnel and a forge that sleeps. | ||
| 51 | 51 | | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes | |
| 52 | 52 | | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no | |
| 53 | 53 | | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes | |
| 54 | | `pins` | `{ action?, repo? }`: `list` (the default) the caller's pinned repositories; `pin` or `unpin` `repo`, as `PUT`/`DELETE /api/v1/user/pins/:owner/:name` do. A repository the caller cannot see is not found | yes | | |
| 54 | 55 | | `branches` | `{ repo, name?, action?, from? }`: without `name`, lists the branches; 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 | yes | |
| 55 | 56 | | `commits` | `{ repo, ref?, limit? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers | | |
| 56 | 57 | | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | | |
src/http/mcp.ts +47 −11
| @@ -242,6 +242,7 @@ import type { Router } from "./router.ts"; | ||
| 242 | 242 | import { mayReadRuns, runForReader, runLog } from "../actions/runs.ts"; |
| 243 | 243 | import { manifestFor } from "../actions/here.ts"; |
| 244 | 244 | import { clientBucket } from "./peer.ts"; |
| 245 | import { listPinned as listPinnedRepos, pinRepo, unpinRepo } from "../actions/origins.ts"; | |
| 245 | 246 | import { listPinned as listPinnedPanels, movePinned, pinPanel, unpinPanel } from "../actions/board-pins.ts"; |
| 246 | 247 | import { deleteBoard, listAllBoards, showBoard, writeBoard, type BoardError } from "../actions/boards.ts"; |
| 247 | 248 | import { panelData, parseWindow } from "../boards/panel_data.ts"; |
| @@ -609,7 +610,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 609 | 610 | { |
| 610 | 611 | name: "tell", |
| 611 | 612 | description: |
| 612 | "Tell an app's crew what should change (first line is the title). Without `repo` it is only kept; answers a thought id.", | |
| 613 | "Tell an app's crew what should change (first line is the title). Without `repo` it is only kept; returns an id.", | |
| 613 | 614 | inputSchema: { |
| 614 | 615 | type: "object", |
| 615 | 616 | properties: { |
| @@ -747,7 +748,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 747 | 748 | { |
| 748 | 749 | name: "issue", |
| 749 | 750 | description: |
| 750 | "Read one issue with its comments, `blockedBy` and `blocks`. A crew agent sees `untrusted: true` on text by non-writers.", | |
| 751 | "Read one issue with its comments, `blockedBy` and `blocks`. Text by non-writers is `untrusted: true`.", | |
| 751 | 752 | inputSchema: { |
| 752 | 753 | type: "object", |
| 753 | 754 | properties: { |
| @@ -1100,14 +1101,14 @@ const TOOLS: readonly Tool[] = [ | ||
| 1100 | 1101 | { |
| 1101 | 1102 | name: "asks_act", |
| 1102 | 1103 | description: |
| 1103 | "Decide many asks: dismiss, decline, ship (never undone), close (`reason`), mute, replan. `items`: ids from `asks`, or `issue:<id>`.", | |
| 1104 | "Decide asks: dismiss, decline, ship (final), close (`reason`), mute, replan. `items`: ids from `asks`, or `issue:<id>`.", | |
| 1104 | 1105 | inputSchema: { |
| 1105 | 1106 | type: "object", |
| 1106 | 1107 | properties: { |
| 1107 | 1108 | action: { type: "string", enum: ["dismiss", "decline", "mute", "ship", "close", "replan"] }, |
| 1108 | 1109 | items: { type: "array", items: { type: "string" }, maxItems: 100 }, |
| 1109 | 1110 | reason: { type: "string", maxLength: 300 }, |
| 1110 | dryRun: { type: "boolean", description: "false to apply" }, | |
| 1111 | dryRun: { type: "boolean", description: "false applies" }, | |
| 1111 | 1112 | }, |
| 1112 | 1113 | required: ["action", "items"], |
| 1113 | 1114 | }, |
| @@ -1124,7 +1125,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1124 | 1125 | { |
| 1125 | 1126 | name: "asks_decide", |
| 1126 | 1127 | description: |
| 1127 | "Let the decider answer a hand-over (`item` is the row's `parked:<id>`). Only a sure set_aside (70%+) clears the card.", | |
| 1128 | "The decider answers a hand-over (`item`: the row's `parked:<id>`). Only a sure set_aside (70%+) clears it.", | |
| 1128 | 1129 | inputSchema: { |
| 1129 | 1130 | type: "object", |
| 1130 | 1131 | properties: { item: { type: "string", maxLength: 80 } }, |
| @@ -1288,7 +1289,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1288 | 1289 | { |
| 1289 | 1290 | name: "issue_teams", |
| 1290 | 1291 | description: |
| 1291 | "Name the crew teams (design, data-science, security, platform) on an issue: at most two; each reviews the closing pull.", | |
| 1292 | "Name up to two crew teams (design, data-science, security, platform) on an issue; each reviews the closing pull.", | |
| 1292 | 1293 | inputSchema: { |
| 1293 | 1294 | type: "object", |
| 1294 | 1295 | properties: { |
| @@ -1776,7 +1777,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1776 | 1777 | { |
| 1777 | 1778 | name: "decisions_by", |
| 1778 | 1779 | description: |
| 1779 | "The standing rule for a repository's parked hand-over cards: `me`, `decider`, or `decider_tell`. Without `by`, reads it.", | |
| 1780 | "A repository's rule for parked hand-over cards: `me`, `decider`, `decider_tell`. Without `by`, reads it.", | |
| 1780 | 1781 | inputSchema: { |
| 1781 | 1782 | type: "object", |
| 1782 | 1783 | properties: { |
| @@ -2247,7 +2248,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2247 | 2248 | { |
| 2248 | 2249 | name: "claim_link", |
| 2249 | 2250 | description: |
| 2250 | "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one then stops at once. Nothing changes without it.", | |
| 2251 | "New claim link for an unclaimed child forge, only with `reveal: true`; the old one stops.", | |
| 2251 | 2252 | inputSchema: { |
| 2252 | 2253 | type: "object", |
| 2253 | 2254 | properties: { |
| @@ -2814,7 +2815,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2814 | 2815 | { |
| 2815 | 2816 | name: "front_page", |
| 2816 | 2817 | description: |
| 2817 | "The forge's front page as a stranger sees it. A site admin also gets the picks and sets them with `pinned`, `hidden`, `weights`.", | |
| 2818 | "The front page as a stranger sees it. A site admin also gets the picks and sets `pinned`, `hidden`, `weights`.", | |
| 2818 | 2819 | inputSchema: { |
| 2819 | 2820 | type: "object", |
| 2820 | 2821 | properties: { |
| @@ -3053,7 +3054,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3053 | 3054 | { |
| 3054 | 3055 | name: "limb", |
| 3055 | 3056 | description: |
| 3056 | "One action on a plan limb: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 3057 | "One limb action: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 3057 | 3058 | inputSchema: { |
| 3058 | 3059 | type: "object", |
| 3059 | 3060 | properties: { |
| @@ -3639,7 +3640,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3639 | 3640 | { |
| 3640 | 3641 | name: "access", |
| 3641 | 3642 | description: |
| 3642 | "What outside agents tried: the redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.", | |
| 3643 | "Redacted log of non-browser requests to public paths, newest first, max 500. Forge admin.", | |
| 3643 | 3644 | inputSchema: { |
| 3644 | 3645 | type: "object", |
| 3645 | 3646 | properties: { |
| @@ -4116,6 +4117,41 @@ const TOOLS: readonly Tool[] = [ | ||
| 4116 | 4117 | return done.ok ? good({ ...done.value }) : bad(done.error, "that could not be pinned"); |
| 4117 | 4118 | }, |
| 4118 | 4119 | }, |
| 4120 | { | |
| 4121 | name: "pins", | |
| 4122 | description: "Your pinned repositories: list, or pin/unpin `repo`.", | |
| 4123 | inputSchema: { | |
| 4124 | type: "object", | |
| 4125 | properties: { | |
| 4126 | action: { type: "string", enum: ["list", "pin", "unpin"] }, | |
| 4127 | repo: REPO_ARG, | |
| 4128 | }, | |
| 4129 | }, | |
| 4130 | writes: true, | |
| 4131 | readsWithout: "repo", | |
| 4132 | run(ctx, user, args) { | |
| 4133 | const action = args["action"] ?? "list"; | |
| 4134 | if (action !== "list" && action !== "pin" && action !== "unpin") | |
| 4135 | return bad("invalid", "action is list, pin or unpin"); | |
| 4136 | if (action === "list") { | |
| 4137 | const pins = listPinnedRepos(ctx.app, user); | |
| 4138 | const repos = getReposByIds(ctx.app.db, pins.map((p) => p.repoId)); | |
| 4139 | return good({ | |
| 4140 | pins: pins.flatMap((pin) => { | |
| 4141 | const repo = repos.get(pin.repoId); | |
| 4142 | if (!repo || !canRead(ctx.app.db, repo, user)) return []; | |
| 4143 | return [{ repo: `${repo.ownerName}/${repo.name}`, pinnedAt: pin.createdAt }]; | |
| 4144 | }), | |
| 4145 | }); | |
| 4146 | } | |
| 4147 | const repo = repoArg(ctx, user, args); | |
| 4148 | if (isAnswer(repo)) return repo; | |
| 4149 | const done = action === "pin" ? pinRepo(ctx.app, user, repo) : unpinRepo(ctx.app, user, repo); | |
| 4150 | return done.ok | |
| 4151 | ? good({ repo: `${repo.ownerName}/${repo.name}`, pinned: action === "pin" }) | |
| 4152 | : bad(done.error, action === "pin" ? "that could not be pinned" : "that repository is not pinned"); | |
| 4153 | }, | |
| 4154 | }, | |
| 4119 | 4155 | { |
| 4120 | 4156 | name: "board_delete", |
| 4121 | 4157 | description: |
test/mcp-pins.test.ts added +115
| @@ -0,0 +1,115 @@ | ||
| 1 | /** | |
| 2 | * The `pins` tool is /api/v1/user/pins over MCP: the caller's own pins, the | |
| 3 | * same visibility rule, the same scope gate. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 6 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 7 | import { tmpdir } from "node:os"; | |
| 8 | import { join } from "node:path"; | |
| 9 | import { createApp, type App } from "../src/app.ts"; | |
| 10 | import { createRepo } from "../src/actions/repos.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 | ||
| 15 | describe("MCP pins", () => { | |
| 16 | let dataDir: string; | |
| 17 | let app: App; | |
| 18 | let servers: Servers; | |
| 19 | let aliceRw: string; | |
| 20 | let bobRw: string; | |
| 21 | let bobRo: 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: "pins", arguments: args }, | |
| 37 | }), | |
| 38 | }); | |
| 39 | const body: any = await res.json(); | |
| 40 | const text: string = body.result.content[0].text; | |
| 41 | return body.result.isError === true ? { error: text } : { value: JSON.parse(text) }; | |
| 42 | }; | |
| 43 | const listed = async (token: string) => | |
| 44 | (await tool(token, {})).value.pins.map((p: any) => p.repo); | |
| 45 | ||
| 46 | beforeAll(async () => { | |
| 47 | dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-pins-")); | |
| 48 | app = createApp({ dataDir, port: 0 }); | |
| 49 | servers = await serve(app); | |
| 50 | const mk = async (username: string, first = false) => { | |
| 51 | const u = await createUser(app.db, { | |
| 52 | origin: "seed", | |
| 53 | trusted: true, | |
| 54 | username, | |
| 55 | email: `${username}@forge.local`, | |
| 56 | password: "a-good-passphrase", | |
| 57 | adminIfFirst: first, | |
| 58 | }); | |
| 59 | if (!u.ok) throw new Error(u.error); | |
| 60 | return u.value; | |
| 61 | }; | |
| 62 | const alice = await mk("alice", true); | |
| 63 | const bob = await mk("bob"); | |
| 64 | aliceRw = createToken(app.db, alice.id, "rw", "rw").token; | |
| 65 | bobRw = createToken(app.db, bob.id, "rw", "rw").token; | |
| 66 | bobRo = createToken(app.db, bob.id, "ro", "ro").token; | |
| 67 | for (const [name, visibility] of [["open", "public"], ["secret", "private"], ["later", "public"]] as const) { | |
| 68 | const made = await createRepo(app, alice, { name, visibility }); | |
| 69 | if (!made.ok) throw new Error(String(made.error)); | |
| 70 | } | |
| 71 | }, 30_000); | |
| 72 | ||
| 73 | afterAll(async () => { | |
| 74 | servers.stop(); | |
| 75 | app.close(); | |
| 76 | await rm(dataDir, { recursive: true, force: true }); | |
| 77 | }); | |
| 78 | ||
| 79 | test("a person pins, lists and unpins; the list is theirs alone", async () => { | |
| 80 | expect(await listed(bobRw)).toEqual([]); | |
| 81 | expect((await tool(bobRw, { action: "pin", repo: "alice/open" })).value).toEqual({ | |
| 82 | repo: "alice/open", | |
| 83 | pinned: true, | |
| 84 | }); | |
| 85 | expect(await listed(bobRw)).toEqual(["alice/open"]); | |
| 86 | expect(await listed(aliceRw)).toEqual([]); | |
| 87 | expect((await tool(bobRw, { action: "unpin", repo: "alice/open" })).value.pinned).toBe(false); | |
| 88 | expect(await listed(bobRw)).toEqual([]); | |
| 89 | expect((await tool(bobRw, { action: "unpin", repo: "alice/open" })).error).toContain("not_found"); | |
| 90 | }); | |
| 91 | ||
| 92 | test("a private repository the caller cannot see is not found", async () => { | |
| 93 | expect((await tool(bobRw, { action: "pin", repo: "alice/secret" })).error).toContain("not_found"); | |
| 94 | expect((await tool(bobRw, { action: "pin", repo: "alice/nope" })).error).toContain("not_found"); | |
| 95 | expect(await listed(bobRw)).toEqual([]); | |
| 96 | expect((await tool(aliceRw, { action: "pin", repo: "alice/secret" })).value.pinned).toBe(true); | |
| 97 | }); | |
| 98 | ||
| 99 | test("a pin on a repository that later went private is no longer listed", async () => { | |
| 100 | await tool(bobRw, { action: "pin", repo: "alice/later" }); | |
| 101 | expect(await listed(bobRw)).toEqual(["alice/later"]); | |
| 102 | app.db.run("UPDATE repo SET visibility = 'private' WHERE name = 'later'"); | |
| 103 | expect(await listed(bobRw)).toEqual([]); | |
| 104 | expect(await listed(aliceRw)).not.toContain("alice/later"); | |
| 105 | await tool(aliceRw, { action: "pin", repo: "alice/later" }); | |
| 106 | expect(await listed(aliceRw)).toContain("alice/later"); | |
| 107 | }); | |
| 108 | ||
| 109 | test("a read-only token lists but is refused pin and unpin; a bad action is invalid", async () => { | |
| 110 | expect(await listed(bobRo)).toEqual([]); | |
| 111 | expect((await tool(bobRo, { action: "pin", repo: "alice/open" })).error).toContain("forbidden"); | |
| 112 | expect((await tool(bobRo, { action: "unpin", repo: "alice/open" })).error).toContain("forbidden"); | |
| 113 | expect((await tool(bobRw, { action: "nuke", repo: "alice/open" })).error).toContain("invalid"); | |
| 114 | }); | |
| 115 | }); |
test/mcp.test.ts +1
| @@ -268,6 +268,7 @@ describe("the forge over MCP", () => { | ||
| 268 | 268 | "boards", |
| 269 | 269 | "board_write", |
| 270 | 270 | "board_pins", |
| 271 | "pins", | |
| 271 | 272 | "board_delete", |
| 272 | 273 | "report", |
| 273 | 274 | ]); |
new above
offline