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

MCP `notify`: read, set or turn off the caller's own phone notify URL, with the same rules as Settings #5517

Closed opened this
Closed without merging

scout/forge:scout/5461-mcp-notify-read-set-or-turn-off-the-call → main 5 commits fork 5 threads · 5 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
5 files changed +132 −0
docs/MCP.md +1
@@ -92,6 +92,7 @@ for a tunnel and a forge that sleeps.
9292 | `mirror_set` | `{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key | yes |
9393 | `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 |
9494 | `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner | |
95 | `notify` | `{ url? }`: with no argument, whether the caller's phone notify URL is set, as its host only; with `url` save it by Settings' rules and words, empty turns it off; a person, never an agent, and saving needs an admin-scope token | yes |
9596 | `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) | |
9697 | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes |
9798 | `orgs` | `{ org? }`: without `org`, the organizations you belong to; with it, the organization, the teams you may see and each team's members; the same as GET `/api/v1/user/orgs`, `/api/v1/orgs/:org`, `…/teams` and `…/members` | |
src/http/mcp/tools/index.ts +1
@@ -72,6 +72,7 @@ export { tool as model_ceiling } from "./model_ceiling.ts";
7272 export { tool as model_grant } from "./model_grant.ts";
7373 export { tool as new_app } from "./new_app.ts";
7474 export { tool as next_steps } from "./next_steps.ts";
75 export { tool as notify } from "./notify.ts";
7576 export { tool as now } from "./now.ts";
7677 export { tool as org_teams } from "./org_teams.ts";
7778 export { tool as orgs } from "./orgs.ts";
src/http/mcp/tools/notify.ts added +28
@@ -0,0 +1,28 @@
1 import { NOTIFY_ERRORS, notifyHost, notifyUrlOf, setNotifyUrl } from "../../../crew/notify.ts";
2 import { scopeAllows } from "../../../core/tokens.ts";
3 import { good, bad, type Tool } from "../shared.ts";
4
5 export const tool: Tool = {
6 name: "notify",
7 doc: "`{ url? }`: with no argument, whether the caller's phone notify URL is set, as its host only; with `url` save it by Settings' rules and words, empty turns it off; a person, never an agent, and saving needs an admin-scope token",

With this entry, tools/list comes to 37,121 bytes, 121 over the 37,000-byte headroom in test/mcp-size.test.ts, so the suite is red. Wait for #6217's budget decision, then rebase so the test passes.

8 description: "Your phone notify URL.",
9 inputSchema: {
10 type: "object",
11 properties: { url: { type: "string" } },
12 },
13 writes: true,
14 run(ctx, user, args) {
15 if (user.kind === "agent") return bad("forbidden", "phone notifications are a person's, not an agent's");
16 if (args["url"] === undefined) {
17 const host = notifyHost(notifyUrlOf(ctx.app.db, user.id));
18 return good(host === undefined ? { set: false, says: "No notify URL is set." } : { set: true, host, says: `Notifying ${host}.` });
19 }
20 if (!scopeAllows(ctx.auth.scope ?? "ro", "admin")) return bad("forbidden", "changing the notify URL needs an admin token");
outdated

High: this write only needs rw (the generic writes gate). The Settings page needs admin scope (readForm(ctx, "admin")). Check scopeAllows(ctx.auth.scope ?? "ro", "admin") here before saving, so an rw token cannot redirect a person's notifications.

21 if (typeof args["url"] !== "string") return bad("invalid", "`url` is a string");
22 const saved = setNotifyUrl(ctx.app.db, user.id, args["url"]);
23 if (!saved.ok) return bad(saved.error, NOTIFY_ERRORS[saved.error]);
24 ctx.app.bus.append({ kind: "account.notify_set", actorId: user.id });
25 const host = notifyHost(notifyUrlOf(ctx.app.db, user.id));
26 return good(host === undefined ? { set: false, says: "Notifications are off." } : { set: true, host, says: `Notifying ${host}.` });
27 },
28 };
test/mcp-notify.test.ts added +101
@@ -0,0 +1,101 @@
1 /**
2 * The `notify` tool is POST /settings/notify over MCP: the same rules and
3 * words, the host only on the way out, a person only.
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 { createAgent } from "../src/actions/crew.ts";
11 import { createToken } from "../src/core/tokens.ts";
12 import { NOTIFY_ERRORS, notifyUrlOf } from "../src/crew/notify.ts";
13 import { serve, type Servers } from "../src/http/server.ts";
14 import { seedAdmin } from "./helpers/admin.ts";
15
16 describe("MCP notify", () => {
17 let dataDir: string;
18 let app: App;
19 let servers: Servers;
20 let ownerId: string;
21 let ownerToken: string;
22 let rwToken: string;
23 let botToken: string;
24 let id = 1;
25
26 beforeAll(async () => {
27 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-notify-"));
28 app = createApp({ dataDir, port: 0, url: "https://forge.example" });
29 servers = await serve(app);
30 const owner = await seedAdmin(app, { username: "olive", email: "[email protected]", password: "owner-passphrase" });
31 if (!owner.ok) throw new Error(owner.error);
32 ownerId = owner.value.id;
33 ownerToken = createToken(app.db, ownerId, "t", "admin").token;
outdated

The owner's token is rw, which the page would refuse for this write. Use an admin-scope token for set/clear, and add a case where an rw token's { url } is refused and the stored URL is unchanged.

34 rwToken = createToken(app.db, ownerId, "t", "rw").token;
35 const made = await createAgent(app, owner.value, { username: "bot", brief: "Be brief." });
36 if (!made.ok) throw new Error(String(made.error));
37 botToken = createToken(app.db, made.value.user.id, "t", "rw").token;
38 });
39 afterAll(async () => {
40 servers.stop();
41 app.close();
42 await rm(dataDir, { recursive: true, force: true });
43 });
44
45 const ask = async (token: string, args: Record<string, unknown>) => {
46 const res = await fetch(`${servers.url}/mcp`, {
47 method: "POST",
48 headers: {
49 "content-type": "application/json",
50 accept: "application/json, text/event-stream",
51 authorization: `Bearer ${token}`,
52 },
53 body: JSON.stringify({ jsonrpc: "2.0", id: id++, method: "tools/call", params: { name: "notify", arguments: args } }),
54 });
55 const body: any = await res.json();
56 return { isError: body.result.isError === true, text: body.result.content[0].text as string };
57 };
58
59 test("set, then read back the host and never the path", async () => {
60 const set = await ask(ownerToken, { url: "https://ntfy.example.com/secret-topic?auth=abc" });
61 expect(set.isError).toBe(false);
62 expect(set.text).not.toContain("secret-topic");
63 expect(notifyUrlOf(app.db, ownerId)).toContain("secret-topic");
64 const read = await ask(ownerToken, {});
65 expect(JSON.parse(read.text)).toMatchObject({ set: true, host: "ntfy.example.com" });
66 expect(read.text).not.toContain("secret-topic");
67 expect(read.text).not.toContain("abc");
68 expect(app.db.query("SELECT 1 FROM event WHERE kind = 'account.notify_set'").all().length).toBeGreaterThan(0);
69 });
70
71 test("an address on a private network is refused with the page's words", async () => {
72 const res = await ask(ownerToken, { url: "https://192.168.1.5/topic" });
73 expect(res.isError).toBe(true);
74 expect(res.text).toContain(NOTIFY_ERRORS.private_host);
75 });
76
77 test("an empty url turns it off", async () => {
78 await ask(ownerToken, { url: "https://ntfy.example.com/t" });
79 const off = await ask(ownerToken, { url: "" });
80 expect(off.isError).toBe(false);
81 expect(notifyUrlOf(app.db, ownerId)).toBeUndefined();
82 expect(JSON.parse((await ask(ownerToken, {})).text).set).toBe(false);
83 });
84
85 test("an rw token may read but not save, and the stored URL stays", async () => {
86 await ask(ownerToken, { url: "https://ntfy.example.com/kept" });
87 const res = await ask(rwToken, { url: "https://evil.example.net/steal" });
88 expect(res.isError).toBe(true);
89 expect(res.text).toContain("forbidden");
90 expect(notifyUrlOf(app.db, ownerId)).toContain("kept");
91 expect((await ask(rwToken, { url: "" })).isError).toBe(true);
92 expect(notifyUrlOf(app.db, ownerId)).toContain("kept");
93 expect(JSON.parse((await ask(rwToken, {})).text)).toMatchObject({ set: true, host: "ntfy.example.com" });
94 });
95
96 test("an agent token is refused", async () => {
97 const res = await ask(botToken, {});
98 expect(res.isError).toBe(true);
99 expect(res.text).toContain("forbidden");
100 });
101 });
test/mcp.test.ts +1
@@ -244,6 +244,7 @@ describe("the forge over MCP", () => {
244244 "converge",
245245 "family",
246246 "next_steps",
247 "notify",
247248 "thought",
248249 "asked",
249250 "assigned",

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs