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

Parked opened this
Closed without merging

scout/forge:scout/4798-mcp-pins-list-pin-and-unpin-the-caller-s → main 7 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
4 files changed +164 −11
docs/MCP.md +1
@@ -51,6 +51,7 @@ for a tunnel and a forge that sleeps.
5151 | `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 |
5252 | `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 |
5353 | `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 |
5455 | `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 |
5556 | `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 | |
5657 | `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";
242242 import { mayReadRuns, runForReader, runLog } from "../actions/runs.ts";
243243 import { manifestFor } from "../actions/here.ts";
244244 import { clientBucket } from "./peer.ts";
245 import { listPinned as listPinnedRepos, pinRepo, unpinRepo } from "../actions/origins.ts";
245246 import { listPinned as listPinnedPanels, movePinned, pinPanel, unpinPanel } from "../actions/board-pins.ts";
246247 import { deleteBoard, listAllBoards, showBoard, writeBoard, type BoardError } from "../actions/boards.ts";
247248 import { panelData, parseWindow } from "../boards/panel_data.ts";
@@ -609,7 +610,7 @@ const TOOLS: readonly Tool[] = [
609610 {
610611 name: "tell",
611612 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.",
613614 inputSchema: {
614615 type: "object",
615616 properties: {
@@ -747,7 +748,7 @@ const TOOLS: readonly Tool[] = [
747748 {
748749 name: "issue",
749750 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`.",
751752 inputSchema: {
752753 type: "object",
753754 properties: {
@@ -1100,14 +1101,14 @@ const TOOLS: readonly Tool[] = [
11001101 {
11011102 name: "asks_act",
11021103 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>`.",
11041105 inputSchema: {
11051106 type: "object",
11061107 properties: {
11071108 action: { type: "string", enum: ["dismiss", "decline", "mute", "ship", "close", "replan"] },
11081109 items: { type: "array", items: { type: "string" }, maxItems: 100 },
11091110 reason: { type: "string", maxLength: 300 },
1110 dryRun: { type: "boolean", description: "false to apply" },
1111 dryRun: { type: "boolean", description: "false applies" },
11111112 },
11121113 required: ["action", "items"],
11131114 },
@@ -1124,7 +1125,7 @@ const TOOLS: readonly Tool[] = [
11241125 {
11251126 name: "asks_decide",
11261127 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.",
11281129 inputSchema: {
11291130 type: "object",
11301131 properties: { item: { type: "string", maxLength: 80 } },
@@ -1288,7 +1289,7 @@ const TOOLS: readonly Tool[] = [
12881289 {
12891290 name: "issue_teams",
12901291 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.",
12921293 inputSchema: {
12931294 type: "object",
12941295 properties: {
@@ -1776,7 +1777,7 @@ const TOOLS: readonly Tool[] = [
17761777 {
17771778 name: "decisions_by",
17781779 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.",
17801781 inputSchema: {
17811782 type: "object",
17821783 properties: {
@@ -2247,7 +2248,7 @@ const TOOLS: readonly Tool[] = [
22472248 {
22482249 name: "claim_link",
22492250 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.",
22512252 inputSchema: {
22522253 type: "object",
22532254 properties: {
@@ -2814,7 +2815,7 @@ const TOOLS: readonly Tool[] = [
28142815 {
28152816 name: "front_page",
28162817 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`.",
28182819 inputSchema: {
28192820 type: "object",
28202821 properties: {
@@ -3053,7 +3054,7 @@ const TOOLS: readonly Tool[] = [
30533054 {
30543055 name: "limb",
30553056 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`.",
30573058 inputSchema: {
30583059 type: "object",
30593060 properties: {
@@ -3639,7 +3640,7 @@ const TOOLS: readonly Tool[] = [
36393640 {
36403641 name: "access",
36413642 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.",
36433644 inputSchema: {
36443645 type: "object",
36453646 properties: {
@@ -4116,6 +4117,41 @@ const TOOLS: readonly Tool[] = [
41164117 return done.ok ? good({ ...done.value }) : bad(done.error, "that could not be pinned");
41174118 },
41184119 },
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 },
41194155 {
41204156 name: "board_delete",
41214157 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", () => {
268268 "boards",
269269 "board_write",
270270 "board_pins",
271 "pins",
271272 "board_delete",
272273 "report",
273274 ]);

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs