Public: anyone can read this; the crew can change it.
MCP `tell` takes `from` (a page URL on this forge or one of its apps) and the tell records it as where it was said, as a tell from the toolbar does #7366
scout/forge:scout/5907-mcp-tell-takes-from-a-page-url-on-this-f → main 5 commits fork
11 files
changed +120
−17
docs/MCP.md +1 −1
| @@ -230,7 +230,7 @@ enforces it); `dryRun` reads `false to apply` on every tool that takes it. The | ||
| 230 | 230 | longer sentences: |
| 231 | 231 | |
| 232 | 232 | - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token. |
| 233 | - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`. `tell.context`: where this was told from, for the builder. | |
| 233 | - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`; or an https address of a page on this forge or one of its apps (`slug.<domain>`, a preview `slug--N.<domain>`), kept as where it was said, as a toolbar tell keeps its page (`page:` in the issue; with no `repo`, on the thought, which `thought` answers as `page`). Anything else, a foreign host, credentials, or a non-URL, is `invalid`. `tell.context`: where this was told from, for the builder. | |
| 234 | 234 | - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) tells the owner in their inbox when this forge's code moves; `take-updates` opens a pull with the new code, and a person merges it. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed. |
| 235 | 235 | - `commits.ref`: branch, tag or commit; the default branch when absent. `report.page`: the http(s) address where the problem was seen. `plan.issues.pillar`: the pillar served, as `"P0"` or `"P0 Trust"`; `later: true` means no pillar and needs `why`. |
| 236 | 236 | - `explore.query`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|use|fresh|name`, `updated:1d|7d|30d` (only what moved in that window) and `archived:yes`. |
src/actions/tell_context.ts +30
| @@ -6,6 +6,9 @@ | ||
| 6 | 6 | * the tell as a plain block the issue shows and the agent reads. |
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | import { FROM_WORDS } from "./tell.ts"; | |
| 10 | import { parseAppHost } from "../apps/proxy.ts"; | |
| 11 | ||
| 9 | 12 | export interface TellContext { |
| 10 | 13 | readonly page?: string; |
| 11 | 14 | readonly pull?: number; |
| @@ -70,3 +73,30 @@ export function contextNote(c: TellContext | undefined): string { | ||
| 70 | 73 | ].filter((l) => l !== ""); |
| 71 | 74 | return lines.length === 0 ? "" : `\n\n---\nWhere this was told from:\n${lines.join("\n")}`; |
| 72 | 75 | } |
| 76 | ||
| 77 | /** What a `from` URL is refused with, at the MCP door. */ | |
| 78 | export const FROM_URL_WORDS = `${FROM_WORDS}; or an https address of a page on this forge or one of its apps`; | |
| 79 | ||
| 80 | /** | |
| 81 | * A page address given as `from`: https, no credentials, and on the forge's | |
| 82 | * own origin or one of its app hosts (`slug.<domain>`, `slug--N.<domain>`). | |
| 83 | * What passes is stored the way the toolbar stores its page; null otherwise. | |
| 84 | */ | |
| 85 | export function parsePageFrom( | |
| 86 | raw: unknown, | |
| 87 | forgeOrigin: string, | |
| 88 | appDomain: string | undefined, | |
| 89 | ): string | null { | |
| 90 | if (typeof raw !== "string" || raw.length > 2000 || /[\s\x00-\x1f\x7f]/.test(raw)) | |
| 91 | return null; | |
| 92 | const url = URL.parse(raw); | |
| 93 | if (url === null || url.username !== "" || url.password !== "") return null; | |
| 94 | const mine = url.origin === forgeOrigin; | |
| 95 | // https always; the forge's own origin as it is, so a forge on plain http | |
| 96 | // (local) can still point at its own pages. | |
| 97 | if (url.protocol !== "https:" && !mine) return null; | |
| 98 | if (!mine && (appDomain === undefined || parseAppHost(url.host, appDomain) === undefined)) | |
| 99 | return null; | |
| 100 | const ok = parseContext({ page: raw }); | |
| 101 | return ok === null || ok === undefined ? null : (ok.page ?? null); | |
| 102 | } |
src/actions/thought.ts +3 −2
| @@ -21,6 +21,7 @@ export function keepThought( | ||
| 21 | 21 | actor: User | undefined, |
| 22 | 22 | text: unknown, |
| 23 | 23 | source: ThoughtSource, |
| 24 | page: string | null = null, | |
| 24 | 25 | ): Result<{ id: string; receivedAt: string }, ThoughtError> { |
| 25 | 26 | if (!actor) return err("unauthorized"); |
| 26 | 27 | if (typeof text !== "string") return err("not_text"); |
| @@ -30,9 +31,9 @@ export function keepThought( | ||
| 30 | 31 | app.db.transaction(() => { |
| 31 | 32 | app.db |
| 32 | 33 | .query( |
| 33 | "INSERT INTO thought (id, author, text, source, received_at) VALUES (?1, ?2, ?3, ?4, ?5)", | |
| 34 | "INSERT INTO thought (id, author, text, source, received_at, page) VALUES (?1, ?2, ?3, ?4, ?5, ?6)", | |
| 34 | 35 | ) |
| 35 | .run(thoughtId, actor.id, text, source, receivedAt); | |
| 36 | .run(thoughtId, actor.id, text, source, receivedAt, page); | |
| 36 | 37 | // The text stays out of the outbox: the event says one arrived. |
| 37 | 38 | app.bus.append({ |
| 38 | 39 | kind: "thought.received", |
src/core/migration-pins/20261025100000-thought-page.pin added +1
| @@ -0,0 +1,1 @@ | ||
| 1 | ae86e1ec34a602ea297a677dd5e091d6597634e4bbef59242d6b10260427c20f |
src/core/migrations/20261025100000-thought-page.ts added +5
| @@ -0,0 +1,5 @@ | ||
| 1 | // The page a thought was said about, when an agent named one. Additive; the | |
| 2 | // thought's text stays as typed. | |
| 3 | export default ` | |
| 4 | ALTER TABLE thought ADD COLUMN page TEXT; | |
| 5 | `; |
src/core/placements.ts +5
| @@ -117,3 +117,8 @@ export function authorsWithUnplaced(db: Database, since: string): string[] { | ||
| 117 | 117 | export function thoughtAuthor(db: Database, thoughtId: string): string | undefined { |
| 118 | 118 | return db.query<{ author: string }, [string]>("SELECT author FROM thought WHERE id = ?1").get(thoughtId)?.author; |
| 119 | 119 | } |
| 120 | ||
| 121 | /** The page a thought was said about, when one was named. */ | |
| 122 | export function thoughtPage(db: Database, thoughtId: string): string | null { | |
| 123 | return db.query<{ page: string | null }, [string]>("SELECT page FROM thought WHERE id = ?1").get(thoughtId)?.page ?? null; | |
| 124 | } |
src/core/thoughts.ts +8 −6
| @@ -11,27 +11,29 @@ export interface Thought { | ||
| 11 | 11 | text: string; |
| 12 | 12 | source: string; |
| 13 | 13 | receivedAt: string; |
| 14 | /** The page it was said about, when one was named. */ | |
| 15 | page: string | null; | |
| 14 | 16 | } |
| 15 | 17 | |
| 16 | 18 | /** The author's newest thoughts received at or after `since` (ISO), newest first; the text exactly as kept. */ |
| 17 | 19 | export function recentThoughts(db: Database, authorId: string, limit: number, since = ""): Thought[] { |
| 18 | 20 | return db |
| 19 | 21 | .query< |
| 20 | { id: string; text: string; source: string; received_at: string }, | |
| 22 | { id: string; text: string; source: string; received_at: string; page: string | null }, | |
| 21 | 23 | [string, string, number] |
| 22 | 24 | >( |
| 23 | "SELECT id, text, source, received_at FROM thought WHERE author = ?1 AND received_at >= ?2 ORDER BY received_at DESC, id DESC LIMIT ?3", | |
| 25 | "SELECT id, text, source, received_at, page FROM thought WHERE author = ?1 AND received_at >= ?2 ORDER BY received_at DESC, id DESC LIMIT ?3", | |
| 24 | 26 | ) |
| 25 | 27 | .all(authorId, since, limit) |
| 26 | .map((r) => ({ id: r.id, text: r.text, source: r.source, receivedAt: r.received_at })); | |
| 28 | .map((r) => ({ id: r.id, text: r.text, source: r.source, receivedAt: r.received_at, page: r.page })); | |
| 27 | 29 | } |
| 28 | 30 | |
| 29 | 31 | /** One of the author's thoughts by id, or nothing (a thought is its author's alone). */ |
| 30 | 32 | export function thoughtOf(db: Database, authorId: string, id: string): Thought | undefined { |
| 31 | 33 | const r = db |
| 32 | .query<{ id: string; text: string; source: string; received_at: string }, [string, string]>( | |
| 33 | "SELECT id, text, source, received_at FROM thought WHERE author = ?1 AND id = ?2", | |
| 34 | .query<{ id: string; text: string; source: string; received_at: string; page: string | null }, [string, string]>( | |
| 35 | "SELECT id, text, source, received_at, page FROM thought WHERE author = ?1 AND id = ?2", | |
| 34 | 36 | ) |
| 35 | 37 | .get(authorId, id); |
| 36 | return r ? { id: r.id, text: r.text, source: r.source, receivedAt: r.received_at } : undefined; | |
| 38 | return r ? { id: r.id, text: r.text, source: r.source, receivedAt: r.received_at, page: r.page } : undefined; | |
| 37 | 39 | } |
src/http/mcp/tools/tell.ts +15 −5
| @@ -1,4 +1,5 @@ | ||
| 1 | import { contextNote, parseContext } from "../../../actions/tell_context.ts"; | |
| 1 | import { appsRuntime } from "../../../apps/runtime.ts"; | |
| 2 | import { FROM_URL_WORDS, contextNote, parseContext, parsePageFrom } from "../../../actions/tell_context.ts"; | |
| 2 | 3 | import { keepThought } from "../../../actions/thought.ts"; |
| 3 | 4 | import { FROM_WORDS, parseFrom, tell, toldWords, UNVERIFIED_WORDS } from "../../../actions/tell.ts"; |
| 4 | 5 | import { DIRECTION_NOTE } from "../../../crew/direct.ts"; |
| @@ -18,7 +19,7 @@ export const tool: Tool = { | ||
| 18 | 19 | type: "string", |
| 19 | 20 | maxLength: 512, |
| 20 | 21 | description: |
| 21 | "Forge path to link, as /a/b/pulls/3.", | |
| 22 | "Forge path to link, as /a/b/pulls/3; or an https page of this forge or one of its apps, kept as where it was said.", | |
| 22 | 23 | }, |
| 23 | 24 | context: { |
| 24 | 25 | type: "object", |
| @@ -35,8 +36,16 @@ export const tool: Tool = { | ||
| 35 | 36 | }, |
| 36 | 37 | writes: true, |
| 37 | 38 | async run(ctx, user, args) { |
| 39 | // A page address is where it was said; a path is a link (`parseFrom`). | |
| 40 | const fromPage = typeof args["from"] === "string" && /^https?:/i.test(args["from"]); | |
| 41 | const page = fromPage | |
| 42 | ? parsePageFrom(args["from"], ctx.url.origin, appsRuntime(ctx.app)?.options.domain) | |
| 43 | : null; | |
| 44 | if (fromPage && page === null) return bad("invalid", FROM_URL_WORDS); | |
| 38 | 45 | if (args["repo"] === undefined || args["repo"] === null) { |
| 39 | const kept = keepThought(ctx.app, user, args["text"], "mcp"); | |
| 46 | if (!fromPage && args["from"] !== undefined && parseFrom(args["from"]) === undefined) | |
| 47 | return bad("invalid", FROM_WORDS); | |
| 48 | const kept = keepThought(ctx.app, user, args["text"], "mcp", page); | |
| 40 | 49 | return kept.ok |
| 41 | 50 | ? good({ thought: kept.value.id }) |
| 42 | 51 | : bad( |
| @@ -46,13 +55,14 @@ export const tool: Tool = { | ||
| 46 | 55 | } |
| 47 | 56 | const repo = repoArg(ctx, user, args); |
| 48 | 57 | if (isAnswer(repo)) return repo; |
| 49 | const where = parseContext(args["context"]); | |
| 58 | const given = parseContext(args["context"]); | |
| 59 | const where = page === null || given === null ? given : { ...given, page }; | |
| 50 | 60 | if (where === null) |
| 51 | 61 | return bad( |
| 52 | 62 | "invalid", |
| 53 | 63 | "context is { page?: http(s) address, pull?: number, run?: id, commit?: hex, said?: words }", |
| 54 | 64 | ); |
| 55 | const from = parseFrom(args["from"]); | |
| 65 | const from = fromPage ? null : parseFrom(args["from"]); | |
| 56 | 66 | if (from === undefined) return bad("invalid", FROM_WORDS); |
| 57 | 67 | const told = await tell( |
| 58 | 68 | ctx.app, |
src/http/mcp/tools/thought.ts +3 −1
| @@ -1,4 +1,4 @@ | ||
| 1 | import { placementJson, placementOf, thoughtAuthor } from "../../../core/placements.ts"; | |
| 1 | import { placementJson, placementOf, thoughtAuthor, thoughtPage } from "../../../core/placements.ts"; | |
| 2 | 2 | import { linksFrom, linksTo } from "../../../core/thought_links.ts"; |
| 3 | 3 | import { good, bad, type Tool } from "../shared.ts"; |
| 4 | 4 | |
| @@ -20,10 +20,12 @@ export const tool: Tool = { | ||
| 20 | 20 | // Not yours and not there answer alike (a thought belongs to its author). |
| 21 | 21 | if (thoughtAuthor(ctx.app.db, thoughtId) !== user.id) |
| 22 | 22 | return bad("not_found", "no such thought"); |
| 23 | const saidAt = thoughtPage(ctx.app.db, thoughtId); | |
| 23 | 24 | const links = linksFrom(ctx.app.db, thoughtId); |
| 24 | 25 | const back = linksTo(ctx.app.db, thoughtId); |
| 25 | 26 | return good({ |
| 26 | 27 | id: thoughtId, |
| 28 | ...(saidAt === null ? {} : { page: saidAt }), | |
| 27 | 29 | placement: placementJson(placementOf(ctx.app.db, thoughtId)), |
| 28 | 30 | // The earlier thoughts this one repeats or takes back, and the later one that took it back. |
| 29 | 31 | repeats: links.repeats, |
test/mcp.test.ts +16
| @@ -1498,6 +1498,22 @@ describe("the forge over MCP", () => { | ||
| 1498 | 1498 | } |
| 1499 | 1499 | }); |
| 1500 | 1500 | |
| 1501 | test("a tell's `from` page is kept as the page it was said on, and a foreign one is refused", async () => { | |
| 1502 | const page = `${base}/alice/game/pulls/1`; | |
| 1503 | const told = await tool(rw, "tell", { repo: "alice/game", text: "about this page", from: page }); | |
| 1504 | expect(told.error).toBeUndefined(); | |
| 1505 | const issue = listIssues(app.db, game.id, {}).find((i) => i.title === "about this page"); | |
| 1506 | expect(issue?.body).toContain(`page: ${page}`); | |
| 1507 | const thought = await tool(rw, "tell", { text: "a thought about it", from: page }); | |
| 1508 | expect((await tool(rw, "thought", { id: thought.value.thought })).value.page).toBe(page); | |
| 1509 | for (const from of ["https://evil.example/x", "javascript:alert(1)", "not a url", "https://u:[email protected]/"]) { | |
| 1510 | const refused = await tool(rw, "tell", { repo: "alice/game", text: "nope", from }); | |
| 1511 | expect(refused.error).toContain("invalid"); | |
| 1512 | expect((await tool(rw, "tell", { text: "nope", from })).error).toContain("invalid"); | |
| 1513 | } | |
| 1514 | expect(listIssues(app.db, game.id, {}).some((i) => i.title === "nope")).toBe(false); | |
| 1515 | }); | |
| 1516 | ||
| 1501 | 1517 | test("GET /contract/openapi.json describes the public API", async () => { |
| 1502 | 1518 | const res = await fetch(`${base}/contract/openapi.json`); |
| 1503 | 1519 | expect(res.status).toBe(200); |
test/tell-context.test.ts +33 −2
| @@ -1,5 +1,5 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { contextNote, parseContext } from "../src/actions/tell_context.ts"; | |
| 1 | import { describe, expect, test } from "bun:test"; | |
| 2 | import { contextNote, parseContext, parsePageFrom } from "../src/actions/tell_context.ts"; | |
| 3 | 3 | |
| 4 | 4 | test("a page told with a #fragment is told without it", () => { |
| 5 | 5 | const c = parseContext({ page: "https://app.example.test/a?b=1#access_token=secret" }); |
| @@ -12,3 +12,34 @@ test("a page without a fragment is kept as it was", () => { | ||
| 12 | 12 | page: "https://app.example.test/a", |
| 13 | 13 | }); |
| 14 | 14 | }); |
| 15 | ||
| 16 | describe("parsePageFrom", () => { | |
| 17 | const forge = "https://forge.example"; | |
| 18 | const apps = "--forge.example"; | |
| 19 | test("a forge page and an app page pass; the fragment goes", () => { | |
| 20 | expect(parsePageFrom("https://forge.example/alice/notes/pulls/3#t=x", forge, apps)).toBe( | |
| 21 | "https://forge.example/alice/notes/pulls/3", | |
| 22 | ); | |
| 23 | expect(parsePageFrom("https://notes--forge.example/play?l=2", forge, apps)).toBe( | |
| 24 | "https://notes--forge.example/play?l=2", | |
| 25 | ); | |
| 26 | expect(parsePageFrom("https://notes--4--forge.example/", forge, apps)).toBe( | |
| 27 | "https://notes--4--forge.example/", | |
| 28 | ); | |
| 29 | }); | |
| 30 | test("a foreign host, a lookalike, plain http, credentials and a non-URL are refused", () => { | |
| 31 | for (const bad of [ | |
| 32 | "https://evil.example/x", | |
| 33 | "https://forge.example.evil.example/x", | |
| 34 | "https://a.b--forge.example/x", | |
| 35 | "http://notes--forge.example/", | |
| 36 | "https://u:[email protected]/", | |
| 37 | "javascript:alert(1)", | |
| 38 | "/alice/notes", | |
| 39 | "not a url", | |
| 40 | 42, | |
| 41 | ]) | |
| 42 | expect(parsePageFrom(bad, forge, apps)).toBeNull(); | |
| 43 | expect(parsePageFrom("https://notes--forge.example/", forge, undefined)).toBeNull(); | |
| 44 | }); | |
| 45 | }); |
new above
offline