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
scout/forge:scout/5461-mcp-notify-read-set-or-turn-off-the-call → main 5 commits fork 5 threads · 5 unresolved
5 files
changed +132
−0
docs/MCP.md +1
| @@ -92,6 +92,7 @@ for a tunnel and a forge that sleeps. | ||
| 92 | 92 | | `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 | |
| 93 | 93 | | `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 | |
| 94 | 94 | | `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 | | |
| 95 | 96 | | `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`) | | |
| 96 | 97 | | `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 | |
| 97 | 98 | | `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"; | ||
| 72 | 72 | export { tool as model_grant } from "./model_grant.ts"; |
| 73 | 73 | export { tool as new_app } from "./new_app.ts"; |
| 74 | 74 | export { tool as next_steps } from "./next_steps.ts"; |
| 75 | export { tool as notify } from "./notify.ts"; | |
| 75 | 76 | export { tool as now } from "./now.ts"; |
| 76 | 77 | export { tool as org_teams } from "./org_teams.ts"; |
| 77 | 78 | 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", | |
| 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 |
||
| 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 |
||
| 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", () => { | ||
| 244 | 244 | "converge", |
| 245 | 245 | "family", |
| 246 | 246 | "next_steps", |
| 247 | "notify", | |
| 247 | 248 | "thought", |
| 248 | 249 | "asked", |
| 249 | 250 | "assigned", |
new above
offline
With this entry,
tools/listcomes to 37,121 bytes, 121 over the 37,000-byte headroom intest/mcp-size.test.ts, so the suite is red. Wait for #6217's budget decision, then rebase so the test passes.