@anchrd/intel 0.59.0

package/dist/mcp/mcp.js

@@ -0,0 +1,1292 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { GetPromptRequestSchema, ListPromptsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { AuditListRequest } from "../contract/audit.js";
+import { BoardAssigneeSearchInput, BoardGetInput, BoardTaskCreateInput, BoardTaskUpdateInput, BoardUpdateInput, DirectoryResolveInput, } from "../contract/board.js";
+import { IdempotencyKey, IntelId } from "../contract/contract.js";
+import { FeedListRequest } from "../contract/feed.js";
+import { ArchiveFlowInput, CreateFlowInput, GetFlowInput, GetFlowVersionInput, ListFlowsInput, PreviewFlowPublishInput, PublishFlowInput, PurgeFlowInput, RelationGraphInput, SaveFlowVersionInput, UnpublishFlowInput, UpdateFlowInput, } from "../contract/flow.js";
+import { CancelFlowRunInput, CompleteFlowRunStepInput, GetFlowRunInput, ListFlowRunsInput, StartFlowRunInput, } from "../contract/flow-run.js";
+import { ArchiveNodeInput, CreateNodeInput, GetAttachmentInput, GetNodeInput, GetNodeVersionInput, ListNodesInput, NodeGraphInput, PurgeNodeInput, PurgeNodePreviewInput, ResolveNodeLinksInput, SaveAttachmentInput, SaveNodeVersionInput, SearchInput, UpdateNodeInput, } from "../contract/node.js";
+import { ListEffectiveAccessInput, ListFlowEffectiveAccessInput, ListFlowGrantsInput, ListGrantsInput, RevokeFlowGrantInput, RevokeGrantInput, ShareFlowInput, ShareInput, } from "../contract/share.js";
+import { AppendTableRowsInput, DefineTableInput, DeleteTableRowsInput, GetTableInput, RedefineTableInput, UpdateTableRowsInput, } from "../contract/table.js";
+import { ExecuteToolInput, TestToolInput } from "../contract/tool.js";
+import { permits } from "../shared/gate-authorization/gate-authorization.js";
+import { IntelError } from "../shared/intel-error/intel-error.js";
+function text(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }], isError: false };
+}
+/**
+ * ⚠️ The one thing a tool error loses on its way out, and the whole reason this `catch` exists
+ * (#597).
+ *
+ * A thrown `IntelError` is turned into a tool error by the SDK's `createToolError`, which keeps
+ * `error instanceof Error ? error.message : String(error)` and nothing else — so `callers`, the
+ * structured half of a refusal that NAMES flows (#448, #593), never reaches a model over MCP.
+ *
+ * It arrives here as a SECOND content block. The first one is the sentence, byte for byte what the
+ * SDK would have sent, so a reader that only takes text loses nothing: the machine-readable half
+ * stands beside the prose rather than instead of it.
+ *
+ * ⚠️ It wraps the handlers whose service can refuse WITH data — `node_grant_revoke` and
+ * `flow_purge` today — and deliberately NOT all sixty. For every other refusal there is nothing to
+ * carry, and turning each of their errors into JSON would change every tool for the sake of two.
+ * What keeps that from becoming a place to forget is where the rule is written down: at the field
+ * itself (`IntelError.callers`), in `packages/intel/CLAUDE.md`, and as two tests in `mcp.e2e.ts` —
+ * whoever attaches `callers` to a new refusal wraps its handler here.
+ */
+async function refusing(run) {
+    try {
+        return text(await run());
+    }
+    catch (error) {
+        if (!(error instanceof IntelError) || !error.callers)
+            throw error;
+        return {
+            content: [
+                { type: "text", text: error.message },
+                {
+                    type: "text",
+                    text: JSON.stringify({ code: error.code, callers: error.callers }),
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * ⚠️ One name per tool, and the second one is gone for good (#149).
+ *
+ * Every tool here carried a `knowledge_*` alias beside its name from #125 until today. The alias
+ * was never politeness: a tool name lives in somebody else's configuration — a portal endpoint, an
+ * agent definition, a saved prompt — so renaming it here alone breaks them at the moment we deploy
+ * rather than at a moment they chose. ADR-0005 §8 therefore kept both, **for a transition**.
+ *
+ * A transition without an end date is not a transition, it is a second permanent name — and two
+ * names for one tool is exactly the friction #125 removed. It ends here. What follows for anybody
+ * writing a tool: there is one name, and a rename is a breaking change that needs its own ticket
+ * and its own notice, not a quiet second entry.
+ */
+// MCP returns resource payloads inline as base64, so an attachment cannot be streamed to the client
+// and must fit in Worker memory twice over. Refuse oversized attachments instead of losing the
+// isolate; HTTP still serves them as a stream.
+const AttachmentInlineLimit = 10 * 1024 * 1024;
+async function base64(stream) {
+    const bytes = new Uint8Array(await new Response(stream).arrayBuffer());
+    const chunkSize = 24_576;
+    let encoded = "";
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        let binary = "";
+        for (const byte of bytes.subarray(offset, offset + chunkSize)) {
+            binary += String.fromCharCode(byte);
+        }
+        encoded += btoa(binary);
+    }
+    return encoded;
+}
+export async function handleMcp(request, deps) {
+    const actor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        isAdmin: deps.authorization.can("intel", "admin"),
+    };
+    const toolActor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        canExecute: permits(deps.authorization, "tools", "execute"),
+    };
+    const flowActor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        canRun: permits(deps.authorization, "flows", "run"),
+        isAdmin: deps.authorization.can("intel", "admin"),
+    };
+    const bundleActor = {
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        isAdmin: deps.authorization.can("intel", "admin"),
+        canReadFlows: permits(deps.authorization, "flows", "read"),
+        canCreateFlows: permits(deps.authorization, "flows", "create"),
+    };
+    const server = new McpServer({ name: "intel", version: "0.1.0" });
+    const EmptyInput = z.strictObject({});
+    // `null` is the root: the whole tree as this caller may read it. The field is required rather
+    // than defaulted so "everything" is always said, never fallen into.
+    const ExportManifestInput = z.strictObject({
+        nodeId: IntelId.nullable().describe('Folder or node to plan the export of, or `null` for the whole tree as this caller may read it. Required rather than defaulted, so "everything" is always said and never fallen into.'),
+    });
+    // The zip travels inline as base64, which is MCP's one way of carrying bytes. ~14M characters is
+    // ~10 MB of zip — the same order as the attachment inline limit, and for the same isolate-memory
+    // reason. Bigger bundles take the HTTP door, which streams.
+    const ImportBundleInput = z.strictObject({
+        nodeId: IntelId.nullable().describe("Folder the bundle lands under, or `null` for the top level. The bundle's own structure is kept beneath it."),
+        zipBase64: z
+            .string()
+            .min(1)
+            .max(14_000_000)
+            .describe("The zip bundle, base64-encoded. Around 10 MB of zip; a bigger bundle takes the HTTP door, which streams instead of holding it in memory."),
+        idempotencyKey: IdempotencyKey,
+    });
+    function decodeZipBase64(value) {
+        if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+            throw new IntelError(400, "import_invalid_bundle", "zipBase64 is not valid base64");
+        }
+        try {
+            return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+        }
+        catch {
+            throw new IntelError(400, "import_invalid_bundle", "zipBase64 is not valid base64");
+        }
+    }
+    // The caller's own identity (#148): the MCP twin of `GET /session`, and like it behind no
+    // capability at all — the answer is the token's own subject, and an agent that may connect may
+    // ask who it is connected as. Deliberately id, email, and name and nothing else: no
+    // capabilities, no token, nothing a caller could mistake for a permission.
+    server.registerTool("session_get", {
+        title: "Get session identity",
+        description: "Get the identity this connection acts as: user id, email, and display name. The MCP counterpart of GET /session; it answers from the token's own subject and never lists permissions.",
+        inputSchema: EmptyInput,
+        annotations: {
+            title: "Get session identity",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => text({
+        id: deps.authorization.identity.id,
+        email: deps.authorization.identity.email,
+        name: deps.authorization.identity.name ?? null,
+    }));
+    // The change journal, read forward from a stable position (#620). It is what makes Intel the
+    // simplest of all signal sources: a consumer keeps its own cursor and asks what happened since,
+    // and Intel never learns that the consumer exists. That is the D24 test passed rather than
+    // argued — remove every reader and nothing piles up here.
+    //
+    // ⚠️ **The capability follows the KIND asked for** (#774), which is why this tool stands outside
+    // both capability blocks rather than inside one. An audit row says the same thing its resource
+    // says, so the journal asks what reading that resource asks — `nodes/read` for `node`,
+    // `flows/read` for `flow` and `flow-run`. A capability of its own would be a second answer to one
+    // question and the two would drift; `nodes/read` for all three would drop the first of the three
+    // checks for exactly the two kinds #774 opened.
+    //
+    // ⚠️ **Offered on EITHER capability, decided per call.** Registration is per connection and the
+    // kind arrives per call, so the two cannot be the same gate. Holding one of the two is what makes
+    // the tool worth listing at all; which of the three journals it then answers is the handler's
+    // question. Same shape, same order, same refusal as `GET /audit` — one business layer, three thin
+    // surfaces.
+    if (permits(deps.authorization, "nodes", "read") ||
+        permits(deps.authorization, "flows", "read")) {
+        server.registerTool("audit_list", {
+            title: "List change events",
+            description: "Read the change journal forward from a stable position: what happened to the resources you may read, oldest first. `resourceType` picks which of the three journals to read — `node`, `flow` or `flow-run` — and each has its own cursor; do not carry one over to another. Pass `nextCursor` back as `after` to continue where you stopped — it says WHERE YOU GOT TO and comes back on the last page as well. Whether another page may follow is `hasMore`; a null `nextCursor` means nothing was returned, not that you have caught up. Events about permanently deleted nodes and flows are never returned, to anybody.",
+            inputSchema: AuditListRequest,
+            annotations: {
+                title: "List change events",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => {
+            // ⚠️ Before the service, so a refusal costs no journal read. A 403 that arrived after the
+            // rows were read is a 403 that already read them.
+            if (!permits(deps.authorization, input.resourceType === "node" ? "nodes" : "flows", "read")) {
+                throw new IntelError(403, "permission_required", "Permission required");
+            }
+            return text(await deps.audit.list(actor, input));
+        });
+    }
+    if (permits(deps.authorization, "nodes", "read")) {
+        // The board as one answer (#648). Four tools, not five: a move is an update of `status` and
+        // `position`, and deleting a task is `node_archive` — nothing here removes a `nodes` row.
+        server.registerTool("board_get", {
+            title: "Read a board",
+            description: "Read one board in a single answer: its columns and every card you may see, without the card bodies. Filter by column, assignee, due date or what a card waits for — each filter narrows the query itself. Open a card's text with node_version_get.",
+            inputSchema: BoardGetInput,
+            annotations: {
+                title: "Read a board",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.get(actor, input)));
+        // ⚠️ Two tools rather than one, because they answer two questions that differ in exactly one
+        // way: `board_assignee_list` offers whom a card MAY be given to and is narrowed to this board
+        // (D70); `directory_resolve` names people who are ALREADY on cards and is not narrowed,
+        // because somebody whose access was withdrawn is still who the card belongs to.
+        //
+        // ⚠️ `list`, NOT `search`, although a query narrows it. `search` is the ONE bare verb at the
+        // root of this surface (Jack's decision 2026-08-09, `packages/intel/CLAUDE.md`), and a second one
+        // behind a domain would make that exception look like a pattern. The verb for "reads many" is
+        // `list`, and a filter does not change which verb a call is.
+        server.registerTool("board_assignee_list", {
+            title: "Who a card on this board can be given to",
+            description: "Find the people you may set as assignee on a card of this board. Only people who can actually open THIS board are offered, so the same query against two boards can give two different answers. Leave the query EMPTY to get up to three of them without searching, plus a count of how many more there are. One character answers empty rather than everybody; from two on it filters. Use directory_resolve to name somebody already on a card.",
+            inputSchema: BoardAssigneeSearchInput,
+            annotations: {
+                title: "Who a card on this board can be given to",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                // ⚠️ The answer comes from gate, not from this database, and it changes when an account
+                // or a grant does. `false` would promise a stability nothing here controls.
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.boards.searchAssignees(actor, input)));
+        server.registerTool("directory_resolve", {
+            title: "What the people on these cards are called",
+            description: "Turn assignee ids into names, so a card can say who it belongs to instead of showing an identifier. Ids that cannot be named are absent from the answer rather than reported as missing. Not narrowed to a board: somebody whose access was withdrawn is still who the card belongs to.",
+            inputSchema: DirectoryResolveInput,
+            annotations: {
+                title: "What the people on these cards are called",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.boards.resolveNames(actor, input)));
+        server.registerTool("board_task_create", {
+            title: "Add a card to a board",
+            description: "File a new card on a board. Omit the status to put it in the first column. Name a parent task to make it a subtask — it lands on the same board, and moving an existing card under another one is `node_update` with a new parent. The card is a node like any other: its own address, its own permissions, its own history — and its own body. This call answers with the BOARD rather than the new card, so to write that body, make the card with `node_create` under the board instead: it answers with the node itself, files it on the board just the same, and hands you the id `node_version_create` asks for.",
+            inputSchema: BoardTaskCreateInput,
+            annotations: {
+                title: "Add a card to a board",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.createTask(actor, input)));
+        server.registerTool("board_task_update", {
+            title: "Change a card",
+            description: "Change a card's column, order, assignee, labels or dates. Moving a card is this call with a new status — send a position to place it, or leave it out to put it at the end of the column. An absent field is left alone; null clears one. Rename a card with node_update. To move a card UNDER another card, use `node_update` with the other card as its parent — this tool changes what a card is, not where it hangs.",
+            inputSchema: BoardTaskUpdateInput,
+            annotations: {
+                title: "Change a card",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.updateTask(actor, input)));
+        server.registerTool("board_update", {
+            title: "Set a board's columns",
+            description: "Replace a board's column list, in order. Columns are replaced rather than merged, so send the complete list. A column marked terminal is one where a card counts as finished.",
+            inputSchema: BoardUpdateInput,
+            annotations: {
+                title: "Set a board's columns",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.boards.update(actor, input)));
+        server.registerTool("feed_list", {
+            title: "List recent activity",
+            description: "Read the change journal backwards: what most recently happened to the nodes you may read, newest first, one entry per event. Each entry carries the node's current title and the folders above it, and only the folders you may open. Pass `nextCursor` back as `before` to keep going further into the past; a null `nextCursor` means you have reached the beginning. Pass `actor` to see one person's or one agent's work alone. This is the human-facing view — for catching up on everything in order, use audit_list, and do not mix the two cursors.",
+            inputSchema: FeedListRequest,
+            annotations: {
+                title: "List recent activity",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.feed.list(actor, input)));
+        server.registerTool("node_list", {
+            title: "List nodes",
+            description: "List authorized folders, documents, attachments, and tables under one parent.",
+            inputSchema: ListNodesInput,
+            annotations: {
+                title: "List nodes",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.list(actor, input)));
+        server.registerTool("node_get", {
+            title: "Get node",
+            description: "Get one authorized node and its current immutable content version.",
+            inputSchema: GetNodeInput,
+            annotations: {
+                title: "Get node",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.get(actor, input.nodeId)));
+        server.registerTool("node_version_list", {
+            title: "List node versions",
+            description: "List immutable versions of one authorized node.",
+            inputSchema: GetNodeInput,
+            annotations: {
+                title: "List node versions",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listVersions(actor, input.nodeId)));
+        // The content behind one row of the version list (#147): what a version-pinned search citation
+        // points at. No `knowledge_*` alias — the tool is new under the post-#125 naming and never
+        // carried the old prefix.
+        server.registerTool("node_version_get", {
+            title: "Get node version content",
+            description: "Read one pinned immutable version of an authorized node, content included — the version a search citation names, whether or not it is current. For an attachment the answer is its metadata without the bytes. A version that does not belong to the node is not found.",
+            inputSchema: GetNodeVersionInput,
+            annotations: {
+                title: "Get node version content",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.getVersion(actor, input.nodeId, input.versionId)));
+        server.registerTool("node_attachment_get", {
+            title: "Get node attachment",
+            description: "Get authorized immutable attachment metadata, and with includeContent the file itself. " +
+                "The resourceUri in the answer is this server's own address; a portal that aggregates " +
+                "several servers prefixes it, so read the file through includeContent unless the URI " +
+                "came from resources/list.",
+            inputSchema: GetAttachmentInput,
+            annotations: {
+                title: "Get node attachment",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, 
+        /**
+         * ⚠️ The size is checked BEFORE the stream is opened, which the resource handler below cannot
+         * do — it is handed the body by the SDK and has to cancel it. Here the metadata read is its
+         * own call, so an oversized attachment costs no R2 read at all.
+         *
+         * ⚠️ The bytes go out as an embedded RESOURCE block, never as text. A base64 string in a text
+         * block is something a model will try to read; a resource block is a file to a client that
+         * understands one, and the metadata stays in the first block either way (#773).
+         */
+        async (input) => {
+            const metadata = await deps.nodes.getAttachment(actor, input.nodeId);
+            if (!input.includeContent)
+                return text(metadata);
+            if (metadata.version.size > AttachmentInlineLimit) {
+                throw new IntelError(413, "attachment_too_large", "Attachment is too large to inline; read it over HTTP instead");
+            }
+            const { attachment, body } = await deps.nodes.readAttachment(actor, input.nodeId);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(attachment) },
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: `intel://nodes/${attachment.node.id}/attachment`,
+                            mimeType: attachment.version.mediaType,
+                            blob: await base64(body),
+                        },
+                    },
+                ],
+                isError: false,
+            };
+        });
+        server.registerResource("node-attachment", 
+        /**
+         * ⚠️ `list` is what makes the attachments findable at all, and it was `undefined` until #773.
+         * A client that cannot enumerate them has to GUESS the URI — and the one place it could copy
+         * one from, `node_attachment_get`, answers this server's own address, which a portal that
+         * aggregates several servers prefixes. Measured on 2026-08-24: the URI out of that tool was
+         * refused as `Resource not found` while the prefixed spelling delivered the file.
+         *
+         * ⚠️ The listing is COMPLETE, and the loop below is why it has to be. `ListResourcesCallback`
+         * takes `RequestHandlerExtra` and nothing else — the SDK hands a template's list callback no
+         * cursor (checked against the 1.30.0 type: `(extra) => ListResourcesResult`), so a
+         * `nextCursor` in the answer is one nothing would ever send back. That leaves two honest
+         * options and one dishonest one: answer everything, refuse, or cut the list at some limit and
+         * let it read as complete. The cut is the one that is out — a reader would never learn which
+         * of their files are missing.
+         *
+         * The paging is therefore INTERNAL: D1 is asked in pages so one statement never has to carry
+         * the whole set, and the loop ends when the service stops handing back a cursor.
+         */
+        new ResourceTemplate("intel://nodes/{nodeId}/attachment", {
+            list: async () => {
+                const resources = [];
+                let after = null;
+                do {
+                    const page = await deps.nodes.listAttachments(actor, { limit: 100, after });
+                    resources.push(...page.items.map((node) => ({
+                        uri: `intel://nodes/${node.id}/attachment`,
+                        name: node.title,
+                        // ⚠️ No `mimeType`: it lives on the VERSION, so answering one would cost a version
+                        // read per row. The read itself carries the real one.
+                        description: node.description ?? undefined,
+                    })));
+                    after = page.nextCursor;
+                } while (after !== null);
+                return { resources };
+            },
+        }), { title: "Intel node attachment" }, async (uri, variables) => {
+            const { attachment, body } = await deps.nodes.readAttachment(actor, String(variables.nodeId));
+            if (attachment.version.size > AttachmentInlineLimit) {
+                await body.cancel();
+                throw new IntelError(413, "attachment_too_large", "Attachment is too large to inline; read it over HTTP instead");
+            }
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: attachment.version.mediaType,
+                        blob: await base64(body),
+                    },
+                ],
+            };
+        });
+        server.registerResource("node-document", new ResourceTemplate("intel://nodes/{nodeId}", { list: undefined }), { title: "Intel node document", mimeType: "application/json" }, async (uri, variables) => {
+            const document = await deps.nodes.get(actor, String(variables.nodeId));
+            return {
+                contents: [
+                    { uri: uri.href, mimeType: "application/json", text: JSON.stringify(document) },
+                ],
+            };
+        });
+        server.registerTool("search", {
+            title: "Search nodes",
+            description: "Search only authorized indexed nodes and return version-pinned citations. Pass scopeId " +
+                "with a folder node id to search that folder and everything beneath it instead of " +
+                "everything readable.",
+            inputSchema: SearchInput,
+            annotations: {
+                title: "Search nodes",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.search(actor, input)));
+        server.registerTool("node_table_get", {
+            title: "Get node table",
+            description: "Read one authorized table as column names and rows.",
+            inputSchema: GetTableInput,
+            annotations: {
+                title: "Get node table",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.getTable(actor, input.nodeId)));
+        server.registerTool("node_link_list", {
+            title: "List node links",
+            description: "List authorized outgoing links and backlinks for one node.",
+            inputSchema: GetNodeInput,
+            annotations: {
+                title: "List node links",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listLinks(actor, input.nodeId)));
+        // The reader's half of a document link (#41): the titles of the linked documents this caller
+        // may see. There is no tool to create or delete a link — a relationship is written in the text
+        // and `node_version_create` is what records it, so there is only one way to make one.
+        //
+        // ⚠️ A target this caller may not reach, or one that is gone, is simply absent from the answer.
+        // The two are indistinguishable on purpose: telling them apart would confirm that a document
+        // exists somewhere they cannot look.
+        server.registerTool("node_link_resolve", {
+            title: "Resolve node links",
+            description: "Resolve document link targets to the titles this caller is authorized to see. Targets that are unreachable or deleted are absent from the result.",
+            inputSchema: ResolveNodeLinksInput,
+            annotations: {
+                title: "Resolve node links",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.resolveLinks(actor, input)));
+        server.registerTool("node_graph", {
+            title: "Get node graph",
+            description: "Get the authorized nodes and explicit relationships for discovery.",
+            inputSchema: NodeGraphInput,
+            annotations: {
+                title: "Get node graph",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.graph(actor, input)));
+        // The export as MCP offers it (#136): the manifest — every readable entry with its bundle path
+        // and media type. The contents behind the paths are read one by one through `node_get`,
+        // `node_table_get`, and `node_attachment_get`. ⚠️ Deliberately no binary zip over MCP: a
+        // resource payload travels inline as base64 and would have to fit in Worker memory twice, the
+        // same limit that caps `node_attachment_get` at 10 MB — a whole subtree is the case that limit
+        // exists for. HTTP `GET /nodes/:nodeId/export` streams the real archive.
+        server.registerTool("node_export", {
+            title: "Export nodes",
+            description: "Plan a bundle export: the manifest of one authorized subtree (or the whole tree when nodeId is null) with each entry's bundle path, kind, and media type. Content bytes are fetched per node; the binary zip is served over HTTP.",
+            inputSchema: ExportManifestInput,
+            annotations: {
+                title: "Export nodes",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.bundle.manifest(bundleActor, input.nodeId)));
+    }
+    if (deps.authorization.can("intel", "admin")) {
+        server.registerTool("node_reindex", {
+            title: "Reindex nodes",
+            description: "Queue every current canonical node version for derived index rebuild.",
+            inputSchema: EmptyInput,
+            annotations: {
+                title: "Reindex nodes",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async () => text(await deps.nodes.reindex(actor)));
+    }
+    if (permits(deps.authorization, "nodes", "create")) {
+        server.registerTool("node_create", {
+            title: "Create node",
+            description: "Create a governed node: a folder, a board, a document, a card, an attachment or a table. A card made under a board lands on that board, and the answer carries the new node's id — which is what `node_version_create` needs to give it a body. ⚠️ `index` is a reserved name inside a folder (`index`, `Index` and `index.md` alike): a document called that IS the text of the folder it sits in. The browser shows it in the folder's details instead of as a row beneath it, so a folder gets described by writing one. Here nothing is hidden — it is listed and read like any other document.",
+            inputSchema: CreateNodeInput,
+            annotations: {
+                title: "Create node",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.create(actor, input)));
+    }
+    if (permits(deps.authorization, "nodes", "write")) {
+        server.registerTool("node_version_create", {
+            title: "Create node version",
+            description: "Append an immutable content version using an optimistic base version. Documents and board cards both take one — writing a card here is how a ticket gets a body instead of only a title.",
+            inputSchema: SaveNodeVersionInput,
+            annotations: {
+                title: "Create node version",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.save(actor, input)));
+        server.registerTool("node_attachment_create", {
+            title: "Create node attachment version",
+            description: "Append immutable base64 file bytes to an attachment node.",
+            inputSchema: SaveAttachmentInput,
+            annotations: {
+                title: "Create node attachment version",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.saveAttachment(actor, input)));
+        // The import half of the bundle round trip (#137). At minimum the manifest way: a zip made by
+        // the export — or a naked zipped folder — lands as a new subtree under the target. Same
+        // service as HTTP, so authorization, limits, remapping, and the all-or-nothing write cannot
+        // differ by surface; only the transport differs (inline base64 here, a streamed body there).
+        server.registerTool("node_import", {
+            title: "Import nodes",
+            description: "Import a zip bundle (base64) as a new subtree under an authorized target folder — null files at the root. Kinds come from manifest.json when present, from file extensions otherwise. Always creates new nodes; links and flow references between bundled entries are rewritten to the new IDs. Bundles beyond ~10 MB take the streaming HTTP route POST /nodes/:nodeId/import.",
+            inputSchema: ImportBundleInput,
+            annotations: {
+                title: "Import nodes",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.bundle.importBundle(bundleActor, {
+            targetNodeId: input.nodeId,
+            zip: decodeZipBase64(input.zipBase64),
+            idempotencyKey: input.idempotencyKey,
+        })));
+        server.registerTool("node_table_create", {
+            title: "Create node table columns",
+            description: "Write the column names of an empty table. The header is the contract every append is checked against and cannot be rewritten.",
+            inputSchema: DefineTableInput,
+            annotations: {
+                title: "Create node table columns",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.defineTable(actor, input)));
+        // The tool #40 exists for: an agent collecting findings on a schedule appends them without
+        // reading or resending what is already there, and two agents appending at once lose nothing.
+        server.registerTool("node_table_row_create", {
+            title: "Create node table rows",
+            description: "Append rows to a table without reading or resending its existing content. Each row must have exactly as many cells as the table has columns; a row that does not is rejected and nothing is written.",
+            inputSchema: AppendTableRowsInput,
+            annotations: {
+                title: "Create node table rows",
+                readOnlyHint: false,
+                destructiveHint: false,
+                // The idempotency key makes a repeat of the same call a no-op; without one, appending
+                // twice appends twice, which is what appending means.
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.appendTableRows(actor, input)));
+        // The other half of #135: an agent that wrote a wrong finding can correct it. Positions address
+        // rows — they carry no IDs on purpose — so every mutation names the version the positions were
+        // read from and is refused with `version_conflict` when the table moved on. No `knowledge_*`
+        // alias: these tools are new under the post-#125 naming and never carried the old prefix.
+        server.registerTool("node_table_row_update", {
+            title: "Update node table rows",
+            description: "Replace rows at the given zero-based positions. Requires the baseVersionId the positions were read from (see node_table_get); answers version_conflict and writes nothing when the table has changed since. Each replacement row must match the column count.",
+            inputSchema: UpdateTableRowsInput,
+            annotations: {
+                title: "Update node table rows",
+                readOnlyHint: false,
+                // Replacing a cell discards what stood there; the history keeps it, the table does not.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.updateTableRows(actor, input)));
+        server.registerTool("node_table_row_delete", {
+            title: "Delete node table rows",
+            description: "Remove rows at the given zero-based positions. Requires the baseVersionId the positions were read from; answers version_conflict and writes nothing when the table has changed since.",
+            inputSchema: DeleteTableRowsInput,
+            annotations: {
+                title: "Delete node table rows",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.deleteTableRows(actor, input)));
+        server.registerTool("node_table_update", {
+            title: "Update node table columns",
+            description: "Change the header of a defined table through an explicit column mapping: each new column names the current column that fills it (rename or keep), names none to start empty (add), and a current column no entry names is removed with its cells. Requires the baseVersionId the mapping was read from. Defining over an existing header without a mapping stays refused.",
+            inputSchema: RedefineTableInput,
+            annotations: {
+                title: "Update node table columns",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.redefineTable(actor, input)));
+        server.registerTool("node_update", {
+            title: "Update node",
+            description: "Rename, move, or describe a node.",
+            inputSchema: UpdateNodeInput,
+            annotations: {
+                title: "Update node",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.update(actor, input)));
+        server.registerTool("node_archive", {
+            title: "Archive node",
+            description: "Archive or restore one node. Archiving hides it from listings and search and takes its vectors out of the index; nothing is deleted and every version stays readable, so restoring is the same call with `archived: false`.",
+            inputSchema: ArchiveNodeInput,
+            annotations: {
+                title: "Archive node",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                // ⚠️ `true` until #418, and the reason is worth keeping: archiving an agent used to
+                // switch its Gate Application off (#182), which was the one node mutation that reached
+                // outside. With the agents parked nothing here leaves the installation — and an
+                // openWorldHint that is wrong in the cautious direction is still wrong, because it is
+                // the field a client decides on.
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.archive(actor, input)));
+        /**
+         * ⚠️ The look before the irreversible step, and it is on this surface because the step itself
+         * is (#586). `node_purge` has stood here since #457 for the reason #436 states — a way only the
+         * interface has is a way an agent goes around — but until now the COUNT did not, so an agent
+         * could delete for good without being able to see first what went with it. A person in the
+         * interface is shown both numbers and then confirms.
+         *
+         * That is exactly the state `.claude/rules/destructive.md` refuses in its own words: a cascade
+         * turns one confirmed click into an unknown number of deletions, and "the question can no
+         * longer name what disappears". Here the question could not be ASKED, which is the same gap one
+         * step earlier — and the half that was missing was the safe half.
+         *
+         * ⚠️ It answers about a tree, not about one row: `totalItems` counts the nodes AND the flows
+         * beneath it, the same two tables the purge itself walks. `inboundLinks` is the other kind of
+         * consequence — mentions elsewhere that will break and are deliberately not refused.
+         */
+        server.registerTool("node_purge_preview", {
+            title: "Preview a permanent deletion",
+            description: "Ask before node_purge, afterwards there is no row left to count. Names and counts what deleting one ARCHIVED node for good would take with it: the nodes and flows in its subtree with their titles, capped at fifty with the total beside it, plus how many documents link to it from outside. Changes nothing.",
+            inputSchema: PurgeNodePreviewInput,
+            annotations: {
+                title: "Preview a permanent deletion",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.purgePreview(actor, input)));
+        // ⚠️ It exists on this surface for the reason #436 states: a way only the interface has is a way
+        // an agent goes around, by looking for the row in the database. What it may do is bounded by the
+        // same rules the interface obeys — only an archived node, only an empty folder, never one a flow
+        // still uses.
+        server.registerTool("node_purge", {
+            title: "Delete node for good",
+            description: "Delete one ARCHIVED node and everything belonging to it — every version, its content, its grants and its entries in the search index. This cannot be undone. A living node is refused: archive it first. A folder is refused while it still holds anything, and so is a node a published flow uses as a step; documents that merely LINK to it are not, and their links break.",
+            inputSchema: PurgeNodeInput,
+            annotations: {
+                title: "Delete node for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // ⚠️ NOT idempotent, and that is the honest answer rather than a missing flag: calling it
+                // twice deletes once and then answers 404. A client that repeated it on a timeout would
+                // otherwise read the second answer as "already done" when it may mean "somebody else's
+                // node with that id is gone".
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.purge(actor, input)));
+    }
+    if (permits(deps.authorization, "nodes", "share")) {
+        server.registerTool("node_grant_list", {
+            title: "List node grants",
+            description: "List direct grants for nodes the caller is allowed to manage.",
+            inputSchema: ListGrantsInput,
+            annotations: {
+                title: "List node grants",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listGrants(actor, input.resourceId)));
+        /**
+         * ⚠️ The neighbour above answers a NARROWER question, and that is why this one has to be here
+         * (#586). `node_grant_list` reads the rows on this node; this resolves the inheritance — every
+         * grant along the folders above plus the owners, who reach it without a grant row existing at
+         * all. On the everyday node, whose access comes from the folder it sits in, the first answer is
+         * empty and this one is not.
+         *
+         * Two queries with similar names are two different questions, and `.claude/rules/destructive.md`
+         * records what it costs to confuse them: in #457 a refusal asked the one that sounded right and
+         * never fired. Here the cost is the same shape and lands on the sharing path — an agent asked
+         * "who can see this" reaches for the only name it has, is answered `[]`, and reports that
+         * nobody can, about a document the whole organization opens. Silence would not be a missing
+         * answer here, it would be a confident wrong one.
+         *
+         * ⚠️ The list is for reading, never for revoking: only the entries whose `resourceId` is this
+         * node can be revoked here, the rest belong to the folder that granted them.
+         */
+        server.registerTool("node_effective_access_list", {
+            title: "List effective node access",
+            description: "List everybody who reaches one node once inheritance is resolved: the grants on it AND on every folder above it, plus the owners, who need no grant. node_grant_list answers the narrower question — the rows sitting on this node alone — and on a node that inherits its access that answer is empty while this one is not. An entry whose resourceId is another node was granted there and can only be revoked there.",
+            inputSchema: ListEffectiveAccessInput,
+            annotations: {
+                title: "List effective node access",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.listEffectiveAccess(actor, input.resourceId)));
+        server.registerTool("node_grant_create", {
+            title: "Grant node access",
+            description: "Grant inherited node access to a Gate user, verified email, or the organization.",
+            inputSchema: ShareInput,
+            annotations: {
+                title: "Grant node access",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.nodes.share(actor, input)));
+        server.registerTool("node_grant_revoke", {
+            title: "Revoke node grant",
+            description: "Revoke one direct node grant by ID.",
+            inputSchema: RevokeGrantInput,
+            annotations: {
+                title: "Revoke node grant",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => await refusing(() => deps.nodes.revokeGrant(actor, input)));
+    }
+    if (permits(deps.authorization, "flows", "read")) {
+        server.registerTool("flow_list", {
+            title: "List flows",
+            description: "List authorized flows, either all of them or the ones filed in one folder of the shared tree.",
+            inputSchema: ListFlowsInput,
+            annotations: {
+                title: "List flows",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.list(flowActor, input)));
+        server.registerTool("flow_get", {
+            title: "Get flow",
+            description: "Load one authorized flow and its current immutable graph on demand.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "Get flow",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.get(flowActor, input.flowId)));
+        // Named like `knowledge_versions_list`, because it is the same question about the other kind of
+        // thing in the tree. This pair is what turns the `versionId` that `flow_publish` and
+        // `flow_publish_preview` demand into something an MCP client can actually obtain (#144).
+        server.registerTool("flow_version_list", {
+            title: "List flow versions",
+            description: "List the immutable versions of one authorized flow, oldest first, marking which of them is published. Metadata only; flow_version_get loads a version's graph.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List flow versions",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listVersions(flowActor, input.flowId)));
+        server.registerTool("flow_version_get", {
+            title: "Get flow version",
+            description: "Get one immutable version of an authorized flow, including its graph.",
+            inputSchema: GetFlowVersionInput,
+            annotations: {
+                title: "Get flow version",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.getVersion(flowActor, input)));
+        server.registerTool("flow_call_list", {
+            title: "List called flows",
+            description: "List the flows one flow calls, read out of its graph rather than out of where it is filed.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List called flows",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listCalls(flowActor, input.flowId)));
+        // ⚠️ Only nodes the requesting user may see are in the answer, placeholders included: an edge to
+        // a grey box would already say that something is there. The same rule the screen follows,
+        // because it is the same service (#19).
+        server.registerTool("flow_graph", {
+            title: "Read the relation graph",
+            description: "Read what accesses what for one folder or one flow: which flow reads which document and which flow calls which flow.",
+            inputSchema: RelationGraphInput,
+            annotations: {
+                title: "Read the relation graph",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.relationGraph(flowActor, input)));
+        server.registerTool("flow_validate", {
+            title: "Check whether a flow would start",
+            description: "Check whether this flow would start for the calling user right now, and name every reason it would not. Answers rather than acts: no run is created. The answer is a snapshot for this user at this moment, because tool reachability is a live query with their own portal token.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "Check whether a flow would start",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.validate(flowActor, input.flowId)));
+        server.registerTool("flow_requirement_list", {
+            title: "List what a flow needs",
+            description: "List the documents and MCP tools one flow's graph names. Documents the calling user cannot see are counted rather than named, and no claim is made about whether anyone may reach them: for tools that cannot be known in advance, because the catalog is a live query with each user's own portal token.",
+            inputSchema: GetFlowInput,
+            annotations: {
+                title: "List what a flow needs",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listRequirements(flowActor, input.flowId)));
+        server.registerTool("flow_run_get", {
+            title: "Get flow run",
+            description: "Get durable run state and the next node an AI or person must handle.",
+            inputSchema: GetFlowRunInput,
+            annotations: {
+                title: "Get flow run",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.getRun(flowActor, input.runId)));
+        // ⚠️ Model context like every other tool result: what a run did, never what it produced. The run
+        // input and output are absent because a run reaches nodes and tools with the rights of
+        // whoever started it, and only their own runs are the calling user's to read out that way.
+        server.registerTool("flow_run_list", {
+            title: "List flow runs",
+            description: 'List flow runs, newest first, with status, start, duration, what triggered them, and for a failed run the step that ended it. Name a `flowId` for one flow, or leave it out for the runs of every flow you may read — which is the way to answer "did anything run at all" without knowing a flow first. Optionally only the failed ones. Runs the calling user may not see are absent, and a failure inside a called flow they may not see is named by the calling step alone.',
+            inputSchema: ListFlowRunsInput,
+            annotations: {
+                title: "List flow runs",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listRuns(flowActor, input)));
+        server.registerTool("flow_run_step_list", {
+            title: "List flow run steps",
+            description: "List every completed step of one run, oldest first, with its outcome, branch, and the reason a failed step gives, plus the call chain the run belongs to.",
+            inputSchema: GetFlowRunInput,
+            annotations: {
+                title: "List flow run steps",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listRunSteps(flowActor, input.runId)));
+    }
+    // The flow's own sharing (#530), named by the same grammar as the node tools: domain singular,
+    // the way narrowing left to right, the verb last.
+    if (permits(deps.authorization, "flows", "share")) {
+        server.registerTool("flow_grant_list", {
+            title: "List flow grants",
+            description: "List the grants sitting on one flow. What the folder it is filed in passes down is not listed here.",
+            inputSchema: ListFlowGrantsInput,
+            annotations: {
+                title: "List flow grants",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listGrants(flowActor, input.flowId)));
+        // ⚠️ The flow half of the node tool three groups up, and it is a SECOND tool rather than a
+        // widened one because it is a second question (#586): the answer is assembled from `flow_grants`
+        // and from the node grants of the folders above, and the owners come from the flow itself as
+        // well as from those folders. One tool over a `resourceId` that means either would have to guess
+        // which table to ask, and a caller passing the wrong kind would be answered "nobody" instead of
+        // being told.
+        server.registerTool("flow_effective_access_list", {
+            title: "List effective flow access",
+            description: "List everybody who reaches one flow once inheritance is resolved: the grants on the flow AND on the folders it is filed under, plus the owners, who need no grant. flow_grant_list answers the narrower question — the rows sitting on the flow itself — and for a flow whose access comes from its folder that answer is empty while this one is not. An entry whose resourceId is a folder was granted there and can only be revoked there.",
+            inputSchema: ListFlowEffectiveAccessInput,
+            annotations: {
+                title: "List effective flow access",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.listEffectiveAccess(flowActor, input.flowId)));
+        server.registerTool("flow_grant_create", {
+            title: "Grant flow access",
+            description: "Grant access to one flow for a Gate user, verified email, or the organization. The grant reaches this flow alone — not the folder it is filed in, and not the flows it calls; the answer names what it does not cover.",
+            inputSchema: ShareFlowInput,
+            annotations: {
+                title: "Grant flow access",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.share(flowActor, input)));
+        server.registerTool("flow_grant_revoke", {
+            title: "Revoke flow grant",
+            description: "Revoke one grant sitting on a flow by ID.",
+            inputSchema: RevokeFlowGrantInput,
+            annotations: {
+                title: "Revoke flow grant",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.revokeGrant(flowActor, input)));
+    }
+    if (permits(deps.authorization, "flows", "create")) {
+        server.registerTool("flow_create", {
+            title: "Create flow",
+            description: "Create governed flow metadata before adding an immutable graph version.",
+            inputSchema: CreateFlowInput,
+            annotations: {
+                title: "Create flow",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.create(flowActor, input)));
+    }
+    if (permits(deps.authorization, "flows", "write")) {
+        server.registerTool("flow_update", {
+            title: "Rename or move flow",
+            description: "Rename a flow, change its description, or move it to another folder of the shared tree. Never changes what the flow does.",
+            inputSchema: UpdateFlowInput,
+            annotations: {
+                title: "Rename or move flow",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.update(flowActor, input)));
+        server.registerTool("flow_archive", {
+            title: "Archive flow",
+            description: "Archive or restore one flow using optimistic concurrency. An archived flow keeps its versions but can no longer be opened, started, or called by another flow.",
+            inputSchema: ArchiveFlowInput,
+            annotations: {
+                title: "Archive flow",
+                readOnlyHint: false,
+                // What it takes away is reach, not content: nothing is deleted and `archived: false` puts
+                // it back. Destructive all the same, because a flow another flow calls stops resolving.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.archive(flowActor, input)));
+        // ⚠️ On this surface because a way only the UI has is a way an agent works around (#436). Its
+        // limits are the same as the UI's.
+        server.registerTool("flow_purge", {
+            title: "Delete flow for good",
+            description: "Delete one ARCHIVED flow together with every version and the record of every run it had. This cannot be undone. A living flow is refused: archive it first. So is a flow another published flow still calls, and one whose runs started runs of other flows.",
+            inputSchema: PurgeFlowInput,
+            annotations: {
+                title: "Delete flow for good",
+                readOnlyHint: false,
+                destructiveHint: true,
+                // Not idempotent, and that is the honest answer: twice deletes once and then answers 404.
+                idempotentHint: false,
+                openWorldHint: false,
+            },
+        }, async (input) => await refusing(() => deps.flows.purge(flowActor, input)));
+        server.registerTool("flow_version_create", {
+            title: "Create flow version",
+            description: "Append a validated immutable flow graph version with optimistic concurrency.",
+            inputSchema: SaveFlowVersionInput,
+            annotations: {
+                title: "Create flow version",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.save(flowActor, input)));
+    }
+    if (permits(deps.authorization, "flows", "publish")) {
+        // The same answer the screen shows the author before publishing. Every user-visible capability
+        // has its MCP equivalent, and a freeze nobody could inspect from here would be one behavior
+        // through two doors.
+        server.registerTool("flow_publish_preview", {
+            title: "Preview flow publication",
+            description: "Show which version each sub-flow call will take and which of them publishing freezes.",
+            inputSchema: PreviewFlowPublishInput,
+            annotations: {
+                title: "Preview flow publication",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.previewPublish(flowActor, input)));
+        server.registerTool("flow_publish", {
+            title: "Publish flow",
+            description: "Publish a version after resolving its authorized node and tool references.",
+            inputSchema: PublishFlowInput,
+            annotations: {
+                title: "Publish flow",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.publish(flowActor, input)));
+        server.registerTool("flow_unpublish", {
+            title: "Unpublish flow",
+            description: "Withdraw a flow's published version. Versions are kept and can be republished; new runs and calls from other flows stop resolving, runs in flight finish on the version they took.",
+            inputSchema: UnpublishFlowInput,
+            annotations: {
+                title: "Unpublish flow",
+                readOnlyHint: false,
+                // Nothing is deleted and republishing is one publish away — destructive all the same,
+                // because a flow another flow calls stops resolving, like flow_archive.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.unpublish(flowActor, input)));
+    }
+    if (permits(deps.authorization, "flows", "run")) {
+        server.registerTool("flow_run_start", {
+            title: "Start flow run",
+            description: "Start a durable run of the published graph and return its first actionable node.",
+            inputSchema: StartFlowRunInput,
+            annotations: {
+                title: "Start flow run",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.start(flowActor, input)));
+        server.registerTool("flow_run_step_complete", {
+            title: "Complete flow step",
+            description: "Submit a node result or semantic branch to advance a durable run without persisting credentials.",
+            inputSchema: CompleteFlowRunStepInput,
+            annotations: {
+                title: "Complete flow step",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.flows.completeStep(flowActor, input)));
+        server.registerTool("flow_run_cancel", {
+            title: "Cancel flow run",
+            description: "Cancel a running flow run without recording a step failure. Running child runs it called are cancelled with it; a run that is already terminal is refused unchanged.",
+            inputSchema: CancelFlowRunInput,
+            annotations: {
+                title: "Cancel flow run",
+                readOnlyHint: false,
+                // Nothing is deleted, but work in flight is ended for the run and its children — a
+                // client deciding whether to ask first has to be told that.
+                destructiveHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.cancelRun(flowActor, input)));
+    }
+    if (permits(deps.authorization, "tools", "read")) {
+        server.registerTool("tool_list", {
+            title: "List tools",
+            description: "List the MCP tools the calling user can reach through the portal, live rather than cached.",
+            inputSchema: EmptyInput,
+            annotations: {
+                title: "List tools",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async () => text(await deps.tools.catalog(toolActor)));
+        // The servers behind the same live list (D30), as the portal itself names them.
+        server.registerTool("tool_server_list", {
+            title: "List tool servers",
+            description: "List the MCP servers the calling user reaches through the portal, as the portal itself names them. The handle is the prefix on every tool name from that server, which is how tool_execute is routed.",
+            inputSchema: EmptyInput,
+            annotations: {
+                title: "List tool servers",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async () => text(await deps.tools.servers(toolActor)));
+    }
+    if (permits(deps.authorization, "tools", "test")) {
+        server.registerTool("tool_test", {
+            title: "Test tool",
+            description: "Validate input and execute one explicitly read-only cached MCP tool with the caller's Gate connection.",
+            inputSchema: TestToolInput,
+            annotations: {
+                title: "Test tool",
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.tools.test(toolActor, input)));
+    }
+    if (permits(deps.authorization, "tools", "execute")) {
+        server.registerTool("tool_execute", {
+            title: "Execute tool",
+            description: "Validate and execute a discovered MCP tool with the caller's just-in-time Gate connection.",
+            inputSchema: ExecuteToolInput,
+            annotations: {
+                title: "Execute tool",
+                readOnlyHint: false,
+                destructiveHint: true,
+                idempotentHint: false,
+                openWorldHint: true,
+            },
+        }, async (input) => text(await deps.tools.execute(toolActor, input)));
+    }
+    /**
+     * The slash-command surface (#775). A prompt is the one thing on this server the HUMAN chooses:
+     * a tool is called when the model thinks of it, a prompt when somebody types `/name`.
+     *
+     * ⚠️ **Registered through the low-level handlers rather than `registerPrompt`, and the cost is
+     * the reason.** `registerPrompt` takes one name at a time, so a catalogue that lives in D1 would
+     * have to be read and registered while the server is being built — on EVERY request, including
+     * every `tools/call` that will never look at a prompt. These two handlers run the queries only
+     * when a client actually asks for prompts.
+     *
+     * ⚠️ **The capability is declared here because nothing else declares it.** Without
+     * `registerCapabilities` the SDK would answer `prompts/list` while telling clients during
+     * initialization that this server has no prompts, and a client that believes the handshake never
+     * asks. `listChanged: false` is the truthful value: the catalogue changes when somebody edits a
+     * document, and this server sends no notification about it.
+     *
+     * ⚠️ **Offered on EITHER capability, decided per call** — the shape `audit_list` uses one screen
+     * up, for the same reason. Holding one of the two is what makes the surface worth offering at
+     * all; which half of the catalogue it then answers is `listOffered`'s question, and it asks it
+     * per row against the resource ACL underneath.
+     */
+    if (permits(deps.authorization, "nodes", "read") ||
+        permits(deps.authorization, "flows", "read")) {
+        const promptActor = {
+            ...actor,
+            canReadNodes: permits(deps.authorization, "nodes", "read"),
+            canReadFlows: permits(deps.authorization, "flows", "read"),
+        };
+        server.server.registerCapabilities({ prompts: { listChanged: false } });
+        server.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: (await deps.prompts.list(promptActor)).map((entry) => ({
+                name: entry.name,
+                title: entry.title,
+                // ⚠️ No `arguments`, and that is a decision rather than a gap (#775). A prompt without
+                // arguments is completely usable — it is an instruction somebody wrote down — and the
+                // obvious source of an argument schema, a flow's requirements, is a round of its own.
+                // Declaring an empty `arguments` array would tell a client the question was asked and
+                // answered "none", which is a different claim.
+                ...(entry.description === null ? {} : { description: entry.description }),
+            })),
+        }));
+        server.server.setRequestHandler(GetPromptRequestSchema, async (promptRequest) => {
+            const { entry, text } = await deps.prompts.get(promptActor, promptRequest.params.name);
+            return {
+                ...(entry.description === null ? {} : { description: entry.description }),
+                messages: [{ role: "user", content: { type: "text", text } }],
+            };
+        });
+    }
+    const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+    await server.connect(transport);
+    return await transport.handleRequest(request);
+}