Public: anyone can read this; the crew can change it.
MCP `forks`: a repository's forks the caller may see, each with how far ahead and behind it is, as /forks shows #5917
scout/forge:scout/5902-mcp-forks-a-repository-s-forks-the-calle → main 1 commit fork 2 threads · 2 unresolved
4 files
changed +150
−14
docs/MCP.md +1
| @@ -31,6 +31,7 @@ for a tunnel and a forge that sleeps. | ||
| 31 | 31 | | `app_deploy` | `{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }` | yes | |
| 32 | 32 | | `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes | |
| 33 | 33 | | `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` | | |
| 34 | | `forks` | `{ repo }`: the forks of a repository you can see, as its `/forks` page counts them: `{ parent, forks: [{ repo, ahead, behind, updatedAt }] }`; `ahead` and `behind` are commits against the parent's default branch (null when git cannot say), `updatedAt` the fork's newest commit time; a private fork you cannot read is absent | | | |
| 34 | 35 | | `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes | |
| 35 | 36 | | `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes | |
| 36 | 37 | | `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` | | |
src/http/mcp.ts +50 −14
| @@ -20,6 +20,7 @@ | ||
| 20 | 20 | import { listRemoteRepos, listUserOrigins, syncOriginNow } from "../actions/origins.ts"; |
| 21 | 21 | import { originJson, remoteRepoJson } from "./api.ts"; |
| 22 | 22 | import { FAMILY_WORDS } from "../actions/family_words.ts"; |
| 23 | import { forkDrift } from "../actions/forks.ts"; | |
| 23 | 24 | import { showProvenance } from "../actions/provenance.ts"; |
| 24 | 25 | import { |
| 25 | 26 | APP_ALREADY_YOURS, |
| @@ -184,6 +185,7 @@ import { | ||
| 184 | 185 | canWrite, |
| 185 | 186 | forkParentFor, |
| 186 | 187 | getRepo, |
| 188 | visibleForks, | |
| 187 | 189 | getReposByIds, |
| 188 | 190 | isDecisionsBy, |
| 189 | 191 | ownerFactRepoIds, |
| @@ -655,6 +657,40 @@ const TOOLS: readonly Tool[] = [ | ||
| 655 | 657 | }); |
| 656 | 658 | }, |
| 657 | 659 | }, |
| 660 | { | |
| 661 | name: "forks", | |
| 662 | description: | |
| 663 | "Visible forks, with ahead and behind.", | |
| 664 | inputSchema: { | |
| 665 | type: "object", | |
| 666 | properties: { repo: REPO_ARG }, | |
| 667 | required: ["repo"], | |
| 668 | }, | |
| 669 | writes: false, | |
| 670 | async run(ctx, user, args) { | |
| 671 | const repo = repoArg(ctx, user, args); | |
| 672 | if (isAnswer(repo)) return repo; | |
| 673 | const forks = await Promise.all( | |
| 674 | visibleForks(ctx.app.db, repo.id, user).map(async (fork) => { | |
| 675 | const [drift, tip] = await Promise.all([ | |
| 676 | forkDrift(ctx.app, fork, repo), | |
| 677 | commitLog( | |
| 678 | repoDir(ctx.app.reposRoot, fork.ownerName, fork.name), | |
| 679 | `refs/heads/${fork.defaultBranch}`, | |
| 680 | { limit: 1 }, | |
| 681 | ), | |
| 682 | ]); | |
| 683 | return { | |
| 684 | repo: `${fork.ownerName}/${fork.name}`, | |
| 685 | ahead: drift.ahead, | |
| 686 | behind: drift.behind, | |
| 687 | updatedAt: tip.ok ? (tip.value[0]?.date ?? null) : null, | |
| 688 | }; | |
| 689 | }), | |
| 690 | ); | |
| 691 | return good({ parent: `${repo.ownerName}/${repo.name}`, forks }); | |
| 692 | }, | |
| 693 | }, | |
| 658 | 694 | { |
| 659 | 695 | name: "repo_settings", |
| 660 | 696 | description: |
| @@ -721,7 +757,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 721 | 757 | { |
| 722 | 758 | name: "tell", |
| 723 | 759 | description: |
| 724 | "Tell an app's crew what should change (first line is the title). No `repo`: kept, answers a thought id.", | |
| 760 | "Tell an app's crew what should change (first line is the title). No `repo`: kept as a thought.", | |
One of 13 unrelated description rewrites spread across mcp.ts to make room under the tools/list byte cap. Each one is a new conflict with the open pulls on these tools. Revert all of them; raise the byte budget as its own issue if it really blocks. |
||
| 725 | 761 | inputSchema: { |
| 726 | 762 | type: "object", |
| 727 | 763 | properties: { |
| @@ -859,7 +895,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 859 | 895 | { |
| 860 | 896 | name: "issue", |
| 861 | 897 | description: |
| 862 | "One issue with comments, `blockedBy`, `blocks`; crew agents see `untrusted: true` on non-writers' text.", | |
| 898 | "One issue with comments, `blockedBy`, `blocks`; `untrusted: true` marks non-writers' text.", | |
| 863 | 899 | inputSchema: { |
| 864 | 900 | type: "object", |
| 865 | 901 | properties: { |
| @@ -928,7 +964,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 928 | 964 | { |
| 929 | 965 | name: "pull", |
| 930 | 966 | description: |
| 931 | "Read a pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.", | |
| 967 | "Read a pull; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.", | |
| 932 | 968 | inputSchema: { |
| 933 | 969 | type: "object", |
| 934 | 970 | properties: { |
| @@ -1029,7 +1065,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1029 | 1065 | { |
| 1030 | 1066 | name: "variant", |
| 1031 | 1067 | description: |
| 1032 | "Like or dislike one pull among its variants; a later vote replaces it; a dislike closes it (`reason`).", | |
| 1068 | "Like or dislike a pull among its variants; a later vote replaces it; a dislike closes it.", | |
| 1033 | 1069 | inputSchema: { |
| 1034 | 1070 | type: "object", |
| 1035 | 1071 | properties: { |
| @@ -1214,7 +1250,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1214 | 1250 | { |
| 1215 | 1251 | name: "asks", |
| 1216 | 1252 | description: |
| 1217 | "What waits on you, most consequential first: decision, options, cost of inaction; your saved filter applies", | |
| 1253 | "What waits on you, most consequential first; your saved filter applies", | |
| 1218 | 1254 | inputSchema: { type: "object", properties: { ...CHIP_ARGS } }, |
| 1219 | 1255 | writes: false, |
| 1220 | 1256 | run(ctx, user, args) { |
| @@ -1226,7 +1262,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1226 | 1262 | { |
| 1227 | 1263 | name: "asks_act", |
| 1228 | 1264 | description: |
| 1229 | "Decide asks (`items`: ask ids, `issue:<id>`): dismiss, decline, ship (final), close (`reason`), mute, replan", | |
| 1265 | "Decide asks (`items`: ask ids, `issue:<id>`): dismiss, decline, ship, close (`reason`), mute, replan", | |
| 1230 | 1266 | inputSchema: { |
| 1231 | 1267 | type: "object", |
| 1232 | 1268 | properties: { |
| @@ -3636,7 +3672,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3636 | 3672 | { |
| 3637 | 3673 | name: "returns", |
| 3638 | 3674 | description: |
| 3639 | "What the crew's tokens bought over `days` (1–90, default 7): dollars, runs, landed, cost per change.", | |
| 3675 | "What the crew's tokens bought over `days` (1–90, default 7): dollars, runs, landed.", | |
| 3640 | 3676 | inputSchema: { |
| 3641 | 3677 | type: "object", |
| 3642 | 3678 | properties: { |
| @@ -3661,7 +3697,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3661 | 3697 | { |
| 3662 | 3698 | name: "review", |
| 3663 | 3699 | description: |
| 3664 | "Approve a pull, or request changes with a `reason` (required for changes); your own pull is refused.", | |
| 3700 | "Approve a pull, or request changes with a `reason`; your own pull is refused.", | |
| 3665 | 3701 | inputSchema: { |
| 3666 | 3702 | type: "object", |
| 3667 | 3703 | properties: { |
| @@ -4114,7 +4150,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4114 | 4150 | { |
| 4115 | 4151 | name: "hold", |
| 4116 | 4152 | description: |
| 4117 | "Hold a pull (`why`) or let it go (`release: true`): while held nothing reviews or lands it. Writers.", | |
| 4153 | "Hold a pull (`why`) or let it go (`release: true`): held, nothing reviews or lands it.", | |
| 4118 | 4154 | inputSchema: { |
| 4119 | 4155 | type: "object", |
| 4120 | 4156 | properties: { |
| @@ -4266,7 +4302,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4266 | 4302 | { |
| 4267 | 4303 | name: "prompts", |
| 4268 | 4304 | description: |
| 4269 | "An app's prompt sources (Instagram): list, add (`kind`, `token`, `at`), run or remove (`id`). Repository admin token.", | |
| 4305 | "An app's prompt sources: list, add (`kind`, `token`, `at`), run or remove (`id`). Admin token.", | |
| 4270 | 4306 | inputSchema: { |
| 4271 | 4307 | type: "object", |
| 4272 | 4308 | properties: { |
| @@ -4409,7 +4445,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4409 | 4445 | { |
| 4410 | 4446 | name: "system", |
| 4411 | 4447 | description: |
| 4412 | "The forge's machine now: CPU, load, memory, disk, network, processes. Forge admin or telemetry:read.", | |
| 4448 | "The forge's machine now: CPU, load, memory, disk, network, processes. Admin or telemetry:read.", | |
| 4413 | 4449 | inputSchema: { type: "object", properties: {} }, |
| 4414 | 4450 | writes: false, |
| 4415 | 4451 | run(ctx, user) { |
| @@ -4450,7 +4486,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4450 | 4486 | { |
| 4451 | 4487 | name: "contribute", |
| 4452 | 4488 | description: |
| 4453 | "For an arriving agent: what this forge is, its bottleneck, “help wanted” issues, how to propose.", | |
| 4489 | "For an arriving agent: what this forge is, its bottleneck, “help wanted”, how to propose.", | |
| 4454 | 4490 | inputSchema: { type: "object", properties: {} }, |
| 4455 | 4491 | writes: false, |
| 4456 | 4492 | run: (ctx) => good(welcome(ctx.app)), |
| @@ -4589,7 +4625,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4589 | 4625 | { |
| 4590 | 4626 | name: "cloud_accounts", |
| 4591 | 4627 | description: |
| 4592 | "Cloud accounts (forge admin): each provider token's use, verification, write permission, calls today.", | |
| 4628 | "Cloud accounts (admin): each provider token's use, verification, write permission.", | |
| 4593 | 4629 | inputSchema: { type: "object", properties: {} }, |
| 4594 | 4630 | // A read, but marked a write so a `ro` token never lists the accounts; it |
| 4595 | 4631 | // is a forge admin's and the audit rows name every vendor call. |
| @@ -4605,7 +4641,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 4605 | 4641 | { |
| 4606 | 4642 | name: "cloud_account", |
| 4607 | 4643 | description: |
| 4608 | "Change a cloud account (admin token): `verb` attach, verify, rotate, rename, remove, allow_writes, audit", | |
| 4644 | "Change a cloud account (admin): `verb` attach, verify, rotate, rename, remove, allow_writes, audit", | |
| 4609 | 4645 | inputSchema: { |
| 4610 | 4646 | type: "object", |
| 4611 | 4647 | properties: { |
test/mcp-forks.test.ts added +98
| @@ -0,0 +1,98 @@ | ||
| 1 | /** MCP `forks`: each visible fork with its drift from the parent; a private fork is absent for a stranger. */ | |
| 2 | import { afterAll, beforeAll, 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 { commitToBranch, forkRepo, updateRepoSettings, createRepo } from "../src/actions/repos.ts"; | |
| 8 | import { createToken } from "../src/core/tokens.ts"; | |
| 9 | import { createUser, type User } from "../src/core/users.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import { promote } from "./helpers/members.ts"; | |
| 12 | import { quietLogs } from "./helpers/globals.ts"; | |
| 13 | ||
| 14 | quietLogs(); | |
| 15 | ||
| 16 | let dataDir: string; | |
| 17 | let app: App; | |
| 18 | let servers: Servers; | |
| 19 | const tok: Record<string, string> = {}; | |
| 20 | ||
| 21 | const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => { | |
| 22 | if (!r.ok) throw new Error(JSON.stringify(r.error)); | |
| 23 | return r.value; | |
| 24 | }; | |
| 25 | ||
| 26 | async function forks(token: string, repo: string): Promise<any> { | |
| 27 | const res = await fetch(`${servers.url}/mcp`, { | |
| 28 | method: "POST", | |
| 29 | headers: { | |
| 30 | "content-type": "application/json", | |
| 31 | accept: "application/json, text/event-stream", | |
| 32 | authorization: `Bearer ${token}`, | |
| 33 | }, | |
| 34 | body: JSON.stringify({ | |
| 35 | jsonrpc: "2.0", | |
| 36 | id: 1, | |
| 37 | method: "tools/call", | |
| 38 | params: { name: "forks", arguments: { repo } }, | |
| 39 | }), | |
| 40 | }); | |
| 41 | const body = (await res.json()) as any; | |
| 42 | return { error: body.result.isError === true, ...JSON.parse(body.result.content[0].text) }; | |
| 43 | } | |
| 44 | ||
| 45 | beforeAll(async () => { | |
| 46 | dataDir = await mkdtemp(join(tmpdir(), "forge-forks-mcp-")); | |
| 47 | app = createApp({ dataDir, port: 0 }); | |
| 48 | servers = await serve(app); | |
| 49 | const users: Record<string, User> = {}; | |
| 50 | for (const [name, first] of [["ada", true], ["bob", false], ["cy", false], ["dee", false], ["eve", false]] as const) { | |
| 51 | users[name] = ok( | |
| 52 | await createUser(app.db, { | |
| 53 | origin: "seed", | |
| 54 | trusted: true, | |
| 55 | username: name, | |
| 56 | email: `${name}@forge.local`, | |
| 57 | password: "a-good-passphrase", | |
| 58 | adminIfFirst: first, | |
| 59 | }), | |
| 60 | ); | |
| 61 | tok[name] = createToken(app.db, users[name]!.id, "t", "ro").token; | |
| 62 | } | |
| 63 | promote(app.db, users["bob"]!, users["cy"]!, users["dee"]!, users["eve"]!); | |
| 64 | const lib = ok(await createRepo(app, users["ada"]!, { name: "lib", visibility: "public" })); | |
| 65 | const seed = (u: User, r: typeof lib, branch: string | undefined, file: string) => | |
| 66 | commitToBranch(app, u, r, { ...(branch ? { branch } : {}), message: file, files: [{ path: file, content: `${file}\n` }] }); | |
| 67 | ok(await seed(users["ada"]!, lib, undefined, "README.md")); | |
| 68 | const ahead = ok(await forkRepo(app, users["bob"]!, lib)); | |
| 69 | const behind = ok(await forkRepo(app, users["cy"]!, lib)); | |
| 70 | const secret = ok(await forkRepo(app, users["dee"]!, lib)); | |
| 71 | ok(await updateRepoSettings(app, users["dee"]!, secret, { visibility: "private" })); | |
| 72 | ok(await seed(users["bob"]!, ahead, undefined, "mine.md")); | |
| 73 | ok(await seed(users["ada"]!, lib, undefined, "next.md")); | |
| 74 | // bob is now one ahead and one behind; cy only behind. | |
| 75 | void behind; | |
| 76 | }, 60_000); | |
| 77 | ||
| 78 | afterAll(async () => { | |
| 79 | servers.stop(); | |
| 80 | app.close(); | |
| 81 | await rm(dataDir, { recursive: true, force: true }); | |
| 82 | }); | |
| 83 | ||
| 84 | test("lists forks with how far each is ahead and behind", async () => { | |
| 85 | const a = await forks(tok["eve"]!, "ada/lib"); | |
| 86 | expect(a.parent).toBe("ada/lib"); | |
| 87 | const by = Object.fromEntries(a.forks.map((f: any) => [f.repo, f])); | |
| 88 | expect(by["bob/lib"]).toMatchObject({ ahead: 1, behind: 1 }); | |
| 89 | expect(by["cy/lib"]).toMatchObject({ ahead: 0, behind: 1 }); | |
| 90 | expect(typeof by["bob/lib"].updatedAt).toBe("string"); | |
| 91 | }); | |
| 92 | ||
| 93 | test("a private fork is absent for a stranger and present for its owner", async () => { | |
| 94 | const stranger = await forks(tok["eve"]!, "ada/lib"); | |
| 95 | expect(stranger.forks.map((f: any) => f.repo).sort()).toEqual(["bob/lib", "cy/lib"]); | |
| 96 | const owner = await forks(tok["dee"]!, "ada/lib"); | |
| 97 | expect(owner.forks.map((f: any) => f.repo)).toContain("dee/lib"); | |
| 98 | }); |
test/mcp.test.ts +1
| @@ -175,6 +175,7 @@ describe("the forge over MCP", () => { | ||
| 175 | 175 | "app_deploy", |
| 176 | 176 | "new_app", |
| 177 | 177 | "repo", |
| 178 | "forks", | |
| 178 | 179 | "here", |
| 179 | 180 | "tell", |
| 180 | 181 | "share", |
new above
offline
Adds a tool to src/http/mcp.ts, which the direction freezes until #5924 splits it into one file per tool. Re-cut this onto that layout as its own module.