Public: anyone can read this; the crew can change it.
MCP `tags`: a repository's tags, newest first #4966
scout/forge:scout/4900-mcp-tags-a-repository-s-tags-newest-firs → main 2 commits fork
5 files
changed +141
−7
docs/MCP.md +1
| @@ -50,6 +50,7 @@ for a tunnel and a forge that sleeps. | ||
| 50 | 50 | | `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 | |
| 51 | 51 | | `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 | |
| 52 | 52 | | `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 | |
| 53 | | `tags` | `{ repo }`: the repository's tags, newest first, each with its `name`, `oid` and the `commit` beneath it | no | | |
| 53 | 54 | | `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 | | |
| 54 | 55 | | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | | |
| 55 | 56 | | `following` | where a fork stands against what it follows, and what the crew is doing about it | | |
src/git/read.ts +2
| @@ -388,10 +388,12 @@ export interface Ref { | ||
| 388 | 388 | export async function listRefs( |
| 389 | 389 | dir: string, |
| 390 | 390 | prefix = "refs/", |
| 391 | sort?: string, | |
| 391 | 392 | ): Promise<Result<Ref[], GitFailure>> { |
| 392 | 393 | const result = await runGit( |
| 393 | 394 | [ |
| 394 | 395 | "for-each-ref", |
| 396 | ...(sort === undefined ? [] : [`--sort=${sort}`]), | |
| 395 | 397 | "--format=%(refname)%00%(objectname)%00%(*objectname)", |
| 396 | 398 | "--", |
| 397 | 399 | prefix, |
src/http/mcp.ts +39 −7
| @@ -133,7 +133,7 @@ import { repoGraph } from "../core/dependencies.ts"; | ||
| 133 | 133 | import { pillarView } from "../core/pillars.ts"; |
| 134 | 134 | import { createBranch, deleteBranch } from "../actions/branches.ts"; |
| 135 | 135 | import { listBranches } from "../git/branches.ts"; |
| 136 | import { commitLog } from "../git/read.ts"; | |
| 136 | import { commitLog, listRefs } from "../git/read.ts"; | |
| 137 | 137 | import { repoDir } from "../git/repos.ts"; |
| 138 | 138 | import { runGit } from "../git/env.ts"; |
| 139 | 139 | import { isSafeRef, isSafeTreePath } from "../git/guard.ts"; |
| @@ -599,7 +599,11 @@ const TOOLS: readonly Tool[] = [ | ||
| 599 | 599 | { |
| 600 | 600 | name: "tell", |
| 601 | 601 | description: |
| 602 | <<<<<<< HEAD | |
| 603 | "Tell an app's crew what should change (first line is the title). Without `repo` it is kept, answering a thought id.", | |
| 604 | ======= | |
| 602 | 605 | "Tell an app's crew what should change (first line is the title). Without `repo` it is only kept; answers a thought id.", |
| 606 | >>>>>>> origin/main | |
| 603 | 607 | inputSchema: { |
| 604 | 608 | type: "object", |
| 605 | 609 | properties: { |
| @@ -978,7 +982,11 @@ const TOOLS: readonly Tool[] = [ | ||
| 978 | 982 | { |
| 979 | 983 | name: "close", |
| 980 | 984 | description: |
| 985 | <<<<<<< HEAD | |
| 986 | "Close an issue or pull, or reopen it (`state` open); PATCH's refusals apply. `reason`: done, dropped, split (`into`).", | |
| 987 | ======= | |
| 981 | 988 | "Close an issue or pull, or reopen it (`state` open); PATCH refusals apply. `reason`: done, dropped, split (`into`).", |
| 989 | >>>>>>> origin/main | |
| 982 | 990 | inputSchema: { |
| 983 | 991 | type: "object", |
| 984 | 992 | properties: { |
| @@ -1090,7 +1098,11 @@ const TOOLS: readonly Tool[] = [ | ||
| 1090 | 1098 | { |
| 1091 | 1099 | name: "asks_act", |
| 1092 | 1100 | description: |
| 1101 | <<<<<<< HEAD | |
| 1102 | "Decide many asks: dismiss, decline, ship (never undone), close, mute, replan. `items`: `asks` ids/`issue:<id>`.", | |
| 1103 | ======= | |
| 1093 | 1104 | "Decide many asks: dismiss, decline, ship (never undone), close (`reason`), mute, replan. `items`: ids from `asks`, or `issue:<id>`.", |
| 1105 | >>>>>>> origin/main | |
| 1094 | 1106 | inputSchema: { |
| 1095 | 1107 | type: "object", |
| 1096 | 1108 | properties: { |
| @@ -1681,7 +1693,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 1681 | 1693 | { |
| 1682 | 1694 | name: "decisions_by", |
| 1683 | 1695 | description: |
| 1684 | "The standing rule for a repository's parked hand-over cards: `me`, `decider`, or `decider_tell`. Without `by`, reads it.", | |
| 1696 | "The rule for a repository's parked hand-over cards: `me`, `decider`, `decider_tell`. Without `by`, reads it.", | |
| 1685 | 1697 | inputSchema: { |
| 1686 | 1698 | type: "object", |
| 1687 | 1699 | properties: { |
| @@ -1896,6 +1908,22 @@ const TOOLS: readonly Tool[] = [ | ||
| 1896 | 1908 | return good({ says: `Deleted ${gone.value.name}.`, url: base }); |
| 1897 | 1909 | }, |
| 1898 | 1910 | }, |
| 1911 | { | |
| 1912 | name: "tags", | |
| 1913 | description: "A repository's tags, newest first.", | |
| 1914 | inputSchema: { type: "object", properties: { repo: REPO_ARG }, required: ["repo"] }, | |
| 1915 | writes: false, | |
| 1916 | async run(ctx, user, args) { | |
| 1917 | const repo = repoArg(ctx, user, args); | |
| 1918 | if (isAnswer(repo)) return repo; | |
| 1919 | const refs = await listRefs(repoDir(ctx.app.reposRoot, repo.ownerName, repo.name), "refs/tags/", "-creatordate"); | |
| 1920 | return good({ | |
| 1921 | tags: refs.ok | |
| 1922 | ? refs.value.map((r) => ({ name: r.name.replace("refs/tags/", ""), oid: r.oid, commit: r.peeled ?? r.oid })) | |
| 1923 | : [], | |
| 1924 | }); | |
| 1925 | }, | |
| 1926 | }, | |
| 1899 | 1927 | { |
| 1900 | 1928 | name: "commits", |
| 1901 | 1929 | description: |
| @@ -2094,7 +2122,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2094 | 2122 | { |
| 2095 | 2123 | name: "claim_link", |
| 2096 | 2124 | description: |
| 2097 | "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one then stops at once. Nothing changes without it.", | |
| 2125 | "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one stops. Nothing changes without it.", | |
| 2098 | 2126 | inputSchema: { |
| 2099 | 2127 | type: "object", |
| 2100 | 2128 | properties: { |
| @@ -2584,7 +2612,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2584 | 2612 | { |
| 2585 | 2613 | name: "front_page", |
| 2586 | 2614 | description: |
| 2587 | "The forge's front page as a stranger sees it. A site admin also gets the picks and sets them with `pinned`, `hidden`, `weights`.", | |
| 2615 | "The front page as a stranger sees it. A site admin also gets the picks, set with `pinned`, `hidden`, `weights`.", | |
| 2588 | 2616 | inputSchema: { |
| 2589 | 2617 | type: "object", |
| 2590 | 2618 | properties: { |
| @@ -2823,7 +2851,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 2823 | 2851 | { |
| 2824 | 2852 | name: "limb", |
| 2825 | 2853 | description: |
| 2826 | "One action on a plan limb: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 2854 | "Limb action: `defer`, `resume` (`pillar`), `close` (`reason`), `raise`/`lower` (`under`), `replan`, `takeback`, `undo`.", | |
| 2827 | 2855 | inputSchema: { |
| 2828 | 2856 | type: "object", |
| 2829 | 2857 | properties: { |
| @@ -2997,7 +3025,11 @@ const TOOLS: readonly Tool[] = [ | ||
| 2997 | 3025 | { |
| 2998 | 3026 | name: "spend", |
| 2999 | 3027 | description: |
| 3028 | <<<<<<< HEAD | |
| 3029 | "Report what your session spent on an app's work the forge did not run: who, model, tokens/dollars, issue or pull.", | |
| 3030 | ======= | |
| 3000 | 3031 | "Report what your session spent on work the forge did not run: who, model, tokens or dollars, issue or pull.", |
| 3032 | >>>>>>> origin/main | |
| 3001 | 3033 | inputSchema: { |
| 3002 | 3034 | type: "object", |
| 3003 | 3035 | properties: { |
| @@ -3488,7 +3520,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3488 | 3520 | { |
| 3489 | 3521 | name: "flow", |
| 3490 | 3522 | description: |
| 3491 | "The forge's pipeline (forge admin): per stage counts, `oldestWaiting`, `capacity`, the bottleneck, merge `queue`, `reviewing` (reviews in flight per reviewer).", | |
| 3523 | "The pipeline (forge admin): stage counts, `oldestWaiting`, `capacity`, bottleneck, merge `queue`, `reviewing`.", | |
| 3492 | 3524 | inputSchema: { type: "object", properties: {} }, |
| 3493 | 3525 | writes: false, |
| 3494 | 3526 | run(ctx, user) { |
| @@ -3764,7 +3796,7 @@ const TOOLS: readonly Tool[] = [ | ||
| 3764 | 3796 | { |
| 3765 | 3797 | name: "signup", |
| 3766 | 3798 | description: |
| 3767 | "Who may sign up: open (default); invite lets in only a person with an open invite link; closed refuses every new account. With `mode`, plans.", | |
| 3799 | "Who may sign up: open (default); invite needs an open invite link; closed refuses all. With `mode`, plans.", | |
| 3768 | 3800 | inputSchema: { |
| 3769 | 3801 | type: "object", |
| 3770 | 3802 | properties: { |
test/mcp-tags.test.ts added +98
| @@ -0,0 +1,98 @@ | ||
| 1 | /** MCP `tags`: a repository's tags newest first, and a private repository's tags are not found 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 } from "../src/actions/repos.ts"; | |
| 8 | import { createRepo } from "../src/core/repos.ts"; | |
| 9 | import { createToken } from "../src/core/tokens.ts"; | |
| 10 | import { createUser } from "../src/core/users.ts"; | |
| 11 | import { repoDir } from "../src/git/repos.ts"; | |
| 12 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 13 | import { quietLogs } from "./helpers/globals.ts"; | |
| 14 | ||
| 15 | quietLogs(); | |
| 16 | ||
| 17 | let dataDir: string; | |
| 18 | let app: App; | |
| 19 | let servers: Servers; | |
| 20 | const tok: Record<string, string> = {}; | |
| 21 | ||
| 22 | const ok = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => { | |
| 23 | if (!r.ok) throw new Error(JSON.stringify(r.error)); | |
| 24 | return r.value; | |
| 25 | }; | |
| 26 | ||
| 27 | async function mcp(token: string, args: unknown): Promise<{ error?: string; value?: any }> { | |
| 28 | const res = await fetch(`${servers.url}/mcp`, { | |
| 29 | method: "POST", | |
| 30 | headers: { | |
| 31 | "content-type": "application/json", | |
| 32 | accept: "application/json, text/event-stream", | |
| 33 | authorization: `Bearer ${token}`, | |
| 34 | }, | |
| 35 | body: JSON.stringify({ | |
| 36 | jsonrpc: "2.0", | |
| 37 | id: 1, | |
| 38 | method: "tools/call", | |
| 39 | params: { name: "tags", arguments: args }, | |
| 40 | }), | |
| 41 | }); | |
| 42 | const body = (await res.json()) as any; | |
| 43 | const text: string = body.result.content[0].text; | |
| 44 | return body.result.isError === true ? { error: text } : { value: JSON.parse(text) }; | |
| 45 | } | |
| 46 | ||
| 47 | function tag(dir: string, name: string, date: string): void { | |
| 48 | const r = Bun.spawnSync(["git", "tag", "-a", "-m", name, name, "HEAD"], { | |
| 49 | cwd: dir, | |
| 50 | env: { ...process.env, GIT_COMMITTER_DATE: date, GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "[email protected]" }, | |
| 51 | }); | |
| 52 | if (r.exitCode !== 0) throw new Error(r.stderr.toString()); | |
| 53 | } | |
| 54 | ||
| 55 | beforeAll(async () => { | |
| 56 | dataDir = await mkdtemp(join(tmpdir(), "forge-tags-mcp-")); | |
| 57 | app = createApp({ dataDir, port: 0 }); | |
| 58 | servers = await serve(app); | |
| 59 | const make = (username: string) => | |
| 60 | createUser(app.db, { | |
| 61 | origin: "seed", | |
| 62 | trusted: true, | |
| 63 | username, | |
| 64 | email: `${username}@forge.local`, | |
| 65 | password: "a-good-passphrase", | |
| 66 | }); | |
| 67 | const owner = ok(await make("ada")); | |
| 68 | const stranger = ok(await make("rita")); | |
| 69 | for (const [name, visibility] of [["pub", "public"], ["priv", "private"]] as const) { | |
| 70 | const repo = ok(await createRepo(app.db, app.reposRoot, { ownerId: owner.id, name, visibility })); | |
| 71 | ok(await commitToBranch(app, owner, repo, { message: "seed", files: [{ path: "a.txt", content: "a\n" }] })); | |
| 72 | const dir = repoDir(app.reposRoot, "ada", name); | |
| 73 | tag(dir, "v1.0.0", "2026-01-01T00:00:00Z"); | |
| 74 | tag(dir, "v0.9.0", "2026-03-01T00:00:00Z"); | |
| 75 | tag(dir, "v1.1.0", "2026-02-01T00:00:00Z"); | |
| 76 | } | |
| 77 | tok["owner"] = createToken(app.db, owner.id, "o", "ro").token; | |
| 78 | tok["stranger"] = createToken(app.db, stranger.id, "s", "ro").token; | |
| 79 | }, 30_000); | |
| 80 | ||
| 81 | afterAll(async () => { | |
| 82 | servers?.stop(); | |
| 83 | app?.close(); | |
| 84 | await rm(dataDir, { recursive: true, force: true }); | |
| 85 | }); | |
| 86 | ||
| 87 | test("tags are listed newest first, each with its commit", async () => { | |
| 88 | const { value } = await mcp(tok["stranger"]!, { repo: "ada/pub" }); | |
| 89 | expect(value.tags.map((t: any) => t.name)).toEqual(["v0.9.0", "v1.1.0", "v1.0.0"]); | |
| 90 | expect(value.tags[0].commit).toMatch(/^[0-9a-f]{40}$/); | |
| 91 | expect(value.tags[0].commit).not.toBe(value.tags[0].oid); | |
| 92 | }); | |
| 93 | ||
| 94 | test("a private repository's tags are not found for a stranger, and are listed for its owner", async () => { | |
| 95 | expect((await mcp(tok["stranger"]!, { repo: "ada/priv" })).error).toContain("not_found"); | |
| 96 | expect((await mcp(tok["owner"]!, { repo: "ada/priv" })).value.tags).toHaveLength(3); | |
| 97 | expect((await mcp(tok["owner"]!, { repo: "nope/none" })).error).toContain("not_found"); | |
| 98 | }); |
test/mcp.test.ts +1
| @@ -208,6 +208,7 @@ describe("the forge over MCP", () => { | ||
| 208 | 208 | "archive", |
| 209 | 209 | "trail", |
| 210 | 210 | "events", |
| 211 | "tags", | |
| 211 | 212 | "branches", |
| 212 | 213 | "commits", |
| 213 | 214 | "probe", |
new above
offline