Public: anyone can read this; the crew can change it.

MCP `tags`: a repository's tags, newest first #5026

Parked opened this
Closed without merging

scout/forge:scout/4900-mcp-tags-a-repository-s-tags-newest-firs → main 2 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +141 −7
docs/MCP.md +1
@@ -50,6 +50,7 @@ for a tunnel and a forge that sleeps.
5050 | `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 |
5151 | `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 |
5252 | `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 |
5354 | `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 | |
5455 | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | |
5556 | `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 {
388388 export async function listRefs(
389389 dir: string,
390390 prefix = "refs/",
391 sort?: string,
391392 ): Promise<Result<Ref[], GitFailure>> {
392393 const result = await runGit(
393394 [
394395 "for-each-ref",
396 ...(sort === undefined ? [] : [`--sort=${sort}`]),
395397 "--format=%(refname)%00%(objectname)%00%(*objectname)",
396398 "--",
397399 prefix,
src/http/mcp.ts +39 −7
@@ -133,7 +133,7 @@ import { repoGraph } from "../core/dependencies.ts";
133133 import { pillarView } from "../core/pillars.ts";
134134 import { createBranch, deleteBranch } from "../actions/branches.ts";
135135 import { listBranches } from "../git/branches.ts";
136 import { commitLog } from "../git/read.ts";
136 import { commitLog, listRefs } from "../git/read.ts";
137137 import { repoDir } from "../git/repos.ts";
138138 import { runGit } from "../git/env.ts";
139139 import { isSafeRef, isSafeTreePath } from "../git/guard.ts";
@@ -599,7 +599,11 @@ const TOOLS: readonly Tool[] = [
599599 {
600600 name: "tell",
601601 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 =======
602605 "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
603607 inputSchema: {
604608 type: "object",
605609 properties: {
@@ -978,7 +982,11 @@ const TOOLS: readonly Tool[] = [
978982 {
979983 name: "close",
980984 description:
985 <<<<<<< HEAD
986 "Close an issue or pull, or reopen it (`state` open); PATCH's refusals apply. `reason`: done, dropped, split (`into`).",
987 =======
981988 "Close an issue or pull, or reopen it (`state` open); PATCH refusals apply. `reason`: done, dropped, split (`into`).",
989 >>>>>>> origin/main
982990 inputSchema: {
983991 type: "object",
984992 properties: {
@@ -1090,7 +1098,11 @@ const TOOLS: readonly Tool[] = [
10901098 {
10911099 name: "asks_act",
10921100 description:
1101 <<<<<<< HEAD
1102 "Decide many asks: dismiss, decline, ship (never undone), close, mute, replan. `items`: `asks` ids/`issue:<id>`.",
1103 =======
10931104 "Decide many asks: dismiss, decline, ship (never undone), close (`reason`), mute, replan. `items`: ids from `asks`, or `issue:<id>`.",
1105 >>>>>>> origin/main
10941106 inputSchema: {
10951107 type: "object",
10961108 properties: {
@@ -1681,7 +1693,7 @@ const TOOLS: readonly Tool[] = [
16811693 {
16821694 name: "decisions_by",
16831695 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.",
16851697 inputSchema: {
16861698 type: "object",
16871699 properties: {
@@ -1896,6 +1908,22 @@ const TOOLS: readonly Tool[] = [
18961908 return good({ says: `Deleted ${gone.value.name}.`, url: base });
18971909 },
18981910 },
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 },
18991927 {
19001928 name: "commits",
19011929 description:
@@ -2094,7 +2122,7 @@ const TOOLS: readonly Tool[] = [
20942122 {
20952123 name: "claim_link",
20962124 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.",
20982126 inputSchema: {
20992127 type: "object",
21002128 properties: {
@@ -2584,7 +2612,7 @@ const TOOLS: readonly Tool[] = [
25842612 {
25852613 name: "front_page",
25862614 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`.",
25882616 inputSchema: {
25892617 type: "object",
25902618 properties: {
@@ -2823,7 +2851,7 @@ const TOOLS: readonly Tool[] = [
28232851 {
28242852 name: "limb",
28252853 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`.",
28272855 inputSchema: {
28282856 type: "object",
28292857 properties: {
@@ -2997,7 +3025,11 @@ const TOOLS: readonly Tool[] = [
29973025 {
29983026 name: "spend",
29993027 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 =======
30003031 "Report what your session spent on work the forge did not run: who, model, tokens or dollars, issue or pull.",
3032 >>>>>>> origin/main
30013033 inputSchema: {
30023034 type: "object",
30033035 properties: {
@@ -3488,7 +3520,7 @@ const TOOLS: readonly Tool[] = [
34883520 {
34893521 name: "flow",
34903522 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`.",
34923524 inputSchema: { type: "object", properties: {} },
34933525 writes: false,
34943526 run(ctx, user) {
@@ -3764,7 +3796,7 @@ const TOOLS: readonly Tool[] = [
37643796 {
37653797 name: "signup",
37663798 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.",
37683800 inputSchema: {
37693801 type: "object",
37703802 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", () => {
208208 "archive",
209209 "trail",
210210 "events",
211 "tags",
211212 "branches",
212213 "commits",
213214 "probe",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs