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

MCP `here` takes an app URL and answers what its /__forge/ door shows: app, environment, pull, who is working, and the links home #5869

Parked opened this
Closed without merging

scout/forge:scout/5858-mcp-here-takes-an-app-url-and-answers-wh → main 5 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +235 −16
src/apps/crew.ts +26 −14
@@ -27,9 +27,21 @@ export function crewNow(
2727 /** When given, the reads are named on it: `app`, `pull`, `working`. */
2828 request?: Request,
2929 ): CrewNow | undefined {
30 return crewAll(db, forgeUrl, app, env, viewerId, request)[0];
31 }
32
33 /** Everyone working on the app now, by the same rules as `crewNow`. */
34 export function crewAll(
35 db: Database,
36 forgeUrl: string,
37 app: AppRecord,
38 env: string,
39 viewerId: string | undefined,
40 request?: Request,
41 ): CrewNow[] {
3042 const phase = <T>(name: string, work: () => T): T =>
3143 request === undefined ? work() : timePhase(request, name, work);
32 if (viewerId === undefined) return undefined;
44 if (viewerId === undefined) return [];
3345 const seen = phase("app", () => {
3446 const viewer = getUserById(db, viewerId);
3547 const repo = getRepoById(db, app.repoId);
@@ -37,29 +49,29 @@ export function crewNow(
3749 if (!canRead(db, repo, viewer)) return undefined;
3850 return { viewer, repo };
3951 });
40 if (seen === undefined) return undefined;
52 if (seen === undefined) return [];
4153 const { viewer, repo } = seen;
4254 const number = /^pull-(\d+)$/.exec(env)?.[1];
43 if (number === undefined && env !== "production") return undefined;
55 if (number === undefined && env !== "production") return [];
4456 const pulled = phase("pull", () => {
4557 if (number === undefined) return { issueId: undefined };
4658 const pull = getIssue(db, repo.id, Number(number));
4759 if (pull === undefined || !mayView(db, repo, pull, viewer)) return undefined;
4860 return { issueId: pull.id as string | undefined };
4961 });
50 if (pulled === undefined) return undefined;
62 if (pulled === undefined) return [];
5163 // A run on a sealed issue is not the viewer's to know of.
52 const run = phase("working", () =>
53 workingAgentRuns(db, repo.id, pulled.issueId).find((r) =>
54 mayViewId(db, repo, r.issueId, viewer),
55 ),
64 return phase("working", () =>
65 workingAgentRuns(db, repo.id, pulled.issueId)
66 .filter((r) => mayViewId(db, repo, r.issueId, viewer))
67 .map((run) => {
68 const actor = run.actorId === null ? undefined : getUserById(db, run.actorId);
69 return {
70 who: actor?.username ?? "the crew",
71 url: new URL(`/${repo.ownerName}/${repo.name}/runs/${run.id}`, forgeUrl).href,
72 };
73 }),
5674 );
57 if (run === undefined) return undefined;
58 const actor = run.actorId === null ? undefined : getUserById(db, run.actorId);
59 return {
60 who: actor?.username ?? "the crew",
61 url: new URL(`/${repo.ownerName}/${repo.name}/runs/${run.id}`, forgeUrl).href,
62 };
6375 }
6476
6577 /**
src/apps/here.ts added +64
@@ -0,0 +1,64 @@
1 /**
2 * What an app's `/__forge/` door shows, for an agent holding the app's link:
3 * the same facts (`pillWhere`, `crewAll`, `reportUrl`) the door and pill
4 * render from, as plain data. Anyone the door would turn away is refused.
5 */
6
7 import { getRepoById, canEnterApp } from "../core/repos.ts";
8 import { mayView } from "../core/sealed.ts";
9 import { getIssue } from "../core/issues.ts";
10 import type { User } from "../core/users.ts";
11 import type { AppsRuntime } from "./runtime.ts";
12 import { crewAll } from "./crew.ts";
13 import { isHostPort, pillWhere, reportUrl, resolveAppHostname } from "./proxy.ts";
14
15 export type Here = {
16 app: string;
17 repo: string | null;
18 environment: string;
19 pull: { number: number; title: string } | null;
20 working: string[];
21 links: { home: string; repo: string | null; report: string | null };
22 };
23
24 /** `undefined` is the door's refusal: not an app host here, or not yours to enter. */
25 export function hereOf(runtime: AppsRuntime, link: string, user: User): Here | undefined {
26 let host: string;
27 try {
28 const url = new URL(link);
29 if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
30 host = url.host;
31 } catch {
32 return undefined;
33 }
34 if (!isHostPort(host)) return undefined;
35 const app = runtime.app;
36 const target = resolveAppHostname(app, runtime.options.domain, host);
37 if (target === undefined || target === "unknown" || target.nested) return undefined;
38 const repo = getRepoById(app.db, target.app.repoId);
39 if (repo === undefined || repo.archivedAt != null) return undefined;
40 if (!canEnterApp(app.db, repo, target.app, user)) return undefined;
41 const number = /^pull-(\d+)$/.exec(target.env)?.[1];
42 if (number !== undefined) {
43 const pull = getIssue(app.db, repo.id, Number(number));
44 if (pull?.sealed === true && !mayView(app.db, repo, pull, user)) return undefined;
45 }
46 const where = pillWhere(runtime, target, { id: user.id, name: user.username, role: "user" });
47 const forgeUrl = runtime.options.forgeUrl;
48 const report = reportUrl(runtime, target);
49 return {
50 app: where.app,
51 repo: where.repo ?? null,
52 environment: target.env,
53 pull:
54 where.pull !== undefined && where.title !== undefined
55 ? { number: where.pull, title: where.title }
56 : null,
57 working: crewAll(app.db, forgeUrl, target.app, target.env, user.id).map((c) => c.who),
58 links: {
59 home: forgeUrl,
60 repo: where.repo === undefined ? null : new URL(`/${where.repo}`, forgeUrl).href,
61 report: report?.href ?? null,
62 },
63 };
64 }
src/apps/proxy.ts +1 −1
@@ -543,7 +543,7 @@ function admit(
543543 * form (`actions/reports.ts`), when both the app and the repository are
544544 * public. A private one offers nothing, and a nested host is its guest's.
545545 */
546 function reportUrl(runtime: AppsRuntime, target: AppTarget): URL | undefined {
546 export function reportUrl(runtime: AppsRuntime, target: AppTarget): URL | undefined {
547547 if (target.nested || target.app.access !== "public") return undefined;
548548 const repo = getRepoById(runtime.app.db, target.app.repoId);
549549 if (repo === undefined || !canRead(runtime.app.db, repo, undefined))
src/http/mcp/tools/here.ts +6 −1
@@ -1,10 +1,12 @@
1 import { appsRuntime } from "../../../apps/runtime.ts";
2 import { hereOf } from "../../../apps/here.ts";
13 import { manifestFor } from "../../../actions/here.ts";
24 import { good, bad, type Tool, str } from "../shared.ts";
35
46 export const tool: Tool = {
57 name: "here",
68 description:
7 "What you can do on a forge page: each open action with its HTTP route and MCP tool.",
9 "What you can do on a forge page, as who you are: each open action with its HTTP route and MCP tool. Given an app's link instead: its app, repo, environment, pull, who is working and the links home, as its /__forge/ door shows.",
810 inputSchema: {
911 type: "object",
1012 properties: { url: { type: "string", maxLength: 2000 } },
@@ -13,6 +15,9 @@ export const tool: Tool = {
1315 writes: false,
1416 run(ctx, user, args) {
1517 const raw = str(args["url"]);
18 const runtime = appsRuntime(ctx.app);
19 const door = runtime === undefined || raw.length > 2000 ? undefined : hereOf(runtime, raw, user);
20 if (door !== undefined) return good(door);
1621 const parsed = URL.parse(raw, ctx.url.origin);
1722 if (parsed === null || parsed.origin !== ctx.url.origin)
1823 return bad("not_found", "not a page of this forge");
test/mcp-here.test.ts added +138
@@ -0,0 +1,138 @@
1 /**
2 * The `here` tool answers what an app's `/__forge/` door shows, for a link:
3 * production and a preview, and the door's refusal for a foreign host and
4 * for a private app the caller may not enter.
5 */
6 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
7 import { mkdtemp, rm } from "node:fs/promises";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { createApp, type App } from "../src/app.ts";
11 import { AppsRuntime } from "../src/apps/runtime.ts";
12 import { newApp } from "../src/actions/apps.ts";
13 import { openPull } from "../src/actions/pulls.ts";
14 import { commitToBranch } from "../src/actions/repos.ts";
15 import { getRepo } from "../src/core/repos.ts";
16 import { createUser, getUserByName } from "../src/core/users.ts";
17 import { serve, type Servers } from "../src/http/server.ts";
18 import { seedAdmin } from "./helpers/admin.ts";
19 import { promote } from "./helpers/members.ts";
20 import { tokenFor } from "./helpers/tokens.ts";
21
22 describe("MCP here", () => {
23 let dataDir: string;
24 let app: App;
25 let servers: Servers;
26 let runtime: AppsRuntime;
27 let aliceRw: string;
28 let bobRw: string;
29 let pull = 0;
30 let id = 1;
31
32 const tool = async (token: string, args: unknown) => {
33 const res = await fetch(`${servers.url}/mcp`, {
34 method: "POST",
35 headers: {
36 "content-type": "application/json",
37 accept: "application/json, text/event-stream",
38 authorization: `Bearer ${token}`,
39 },
40 body: JSON.stringify({
41 jsonrpc: "2.0",
42 id: id++,
43 method: "tools/call",
44 params: { name: "here", arguments: args },
45 }),
46 });
47 const body: any = await res.json();
48 const text: string = body.result.content[0].text;
49 return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
50 };
51
52 beforeAll(async () => {
53 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-app-deploy-"));
54 app = createApp({ dataDir, port: 0 });
55 servers = await serve(app);
56 runtime = new AppsRuntime(app, {
57 domain: "apps.test",
58 scheme: "http",
59 publicPort: servers.port,
60 forgeUrl: servers.url,
61 });
62 await runtime.start();
63 await seedAdmin(app, { username: "alice", email: "[email protected]", password: "a-good-passphrase" });
64 const b = await createUser(app.db, {
65 origin: "seed",
66 trusted: true,
67 username: "bob",
68 email: "[email protected]",
69 password: "a-good-passphrase",
70 });
71 if (!b.ok) throw new Error(b.error);
72 promote(app.db, b.value);
73 const alice = getUserByName(app.db, "alice")!;
74 const made = await newApp(app, alice, { name: "hello", visibility: "public" } as never);
75 if (!made.ok) throw new Error(String(made.error));
76 const repo = getRepo(app.db, "alice", "hello")!;
77 const committed = await commitToBranch(app, alice, repo, {
78 branch: "greeting",
79 base: repo.defaultBranch,
80 message: "Say hello",
81 files: [{ path: "GREETING.md", content: "hi\n" }],
82 });
83 if (!committed.ok) throw new Error(JSON.stringify(committed.error));
84 const opened = await openPull(app, alice, repo, {
85 title: "Say hello",
86 baseBranch: repo.defaultBranch,
87 headBranch: "greeting",
88 });
89 if (!opened.ok) throw new Error(String(opened.error));
90 pull = opened.value.number;
91 const secret = await newApp(app, alice, { name: "vault", visibility: "private" } as never);
92 if (!secret.ok) throw new Error(String(secret.error));
93 aliceRw = tokenFor(app, "alice", "rw");
94 bobRw = tokenFor(app, "bob", "rw");
95 }, 30_000);
96
97 afterAll(async () => {
98 await runtime.stop();
99 servers.stop();
100 app.close();
101 await rm(dataDir, { recursive: true, force: true });
102 });
103
104 const host = (label: string) => `http://${label}.apps.test:${servers.port}/anything`;
105
106 test("production: app, repo, no pull, the links home", async () => {
107 const r = await tool(bobRw, { url: host("hello") });
108 expect(r.value.app).toBe("hello");
109 expect(r.value.repo).toBe("alice/hello");
110 expect(r.value.environment).toBe("production");
111 expect(r.value.pull).toBeNull();
112 expect(r.value.working).toEqual([]);
113 expect(r.value.links.home).toBe(servers.url);
114 expect(r.value.links.repo).toBe(`${servers.url}/alice/hello`);
115 expect(r.value.links.report).toBe(`${servers.url}/alice/hello/report`);
116 });
117
118 test("a preview names its pull", async () => {
119 const r = await tool(bobRw, { url: host(`hello--${pull}`) });
120 expect(r.value.environment).toBe(`pull-${pull}`);
121 expect(r.value.pull).toEqual({ number: pull, title: "Say hello" });
122 });
123
124 test("a foreign host and a bad link are refused in the forge's words", async () => {
125 for (const url of ["https://example.com/", "ftp://hello.apps.test/", host("nothing")]) {
126 const r = await tool(aliceRw, { url });
127 expect(r.error).toMatch(/not a page of this forge|no such page here/);
128 }
129 });
130
131 test("a private app the caller cannot enter is refused like a missing one", async () => {
132 const owner = await tool(aliceRw, { url: host("vault") });
133 expect(owner.value.repo).toBe("alice/vault");
134 const stranger = await tool(bobRw, { url: host("vault") });
135 const missing = await tool(bobRw, { url: host("nothing") });
136 expect(stranger.error).toBe(missing.error);
137 });
138 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs