neuron-mcp-server 1.0.1 → 1.1.0

package/src/tools/conversations.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+/**
+ * Register conversation-related MCP tools
+ */
+export function registerConversationTools(server: McpServer): void {
+  // List conversations for a bot
+  server.registerTool(
+    "neuron_list_conversations",
+    {
+      title: "List Conversations",
+      description: "Retrieve a paginated list of conversations for a specific bot, with optional filtering by status.",
+      inputSchema: z.object({
+        botId: z.string().describe("Unique identifier (UUID) of the bot whose conversations to list"),
+        status: z.string().optional().describe("Filter by conversation status (e.g., 'active', 'closed')"),
+        cursor: z.string().optional().describe("Opaque pagination cursor from a previous response for retrieving the next page"),
+        limit: z.number().int().positive().optional().describe("Maximum number of conversations to return per page"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `conversations/bot/${params.botId}`, undefined, {
+          status: params.status,
+          cursor: params.cursor,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Get a specific conversation
+  server.registerTool(
+    "neuron_get_conversation",
+    {
+      title: "Get Conversation",
+      description: "Retrieve detailed information about a specific conversation, including its status, participants, and metadata.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `conversations/${params.id}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Get messages from a conversation
+  server.registerTool(
+    "neuron_get_messages",
+    {
+      title: "Get Conversation Messages",
+      description: "Retrieve messages from a specific conversation in chronological order, with optional cursor-based pagination.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation"),
+        cursor: z.string().optional().describe("Opaque pagination cursor from a previous response for retrieving the next page"),
+        limit: z.number().int().positive().optional().describe("Maximum number of messages to return per page"),
+      }),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("GET", `conversations/${params.id}/messages`, undefined, {
+          cursor: params.cursor,
+          limit: params.limit,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Takeover a conversation
+  server.registerTool(
+    "neuron_takeover_conversation",
+    {
+      title: "Takeover Conversation",
+      description: "Transfer control of a conversation from the bot to a human agent. The bot will stop auto-responding until the conversation is released.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation to take over"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `conversations/${params.id}/takeover`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Release a conversation
+  server.registerTool(
+    "neuron_release_conversation",
+    {
+      title: "Release Conversation",
+      description: "Release a conversation back to the bot, returning control from a human agent. The bot will resume auto-responding.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation to release"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `conversations/${params.id}/release`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Send a message to a conversation
+  server.registerTool(
+    "neuron_send_message",
+    {
+      title: "Send Message",
+      description: "Send a message to an existing conversation. Supports text, image, and document message types with optional media attachments.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation"),
+        content: z.string().describe("Message content to send"),
+        messageType: z.string().optional().describe("Type of message: 'text' (default), 'image', or 'document'"),
+        mediaUrl: z.string().optional().describe("URL of media to attach (required for image/document message types)"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const body: Record<string, unknown> = { content: params.content };
+        if (params.messageType) body.messageType = params.messageType;
+        if (params.mediaUrl) body.mediaUrl = params.mediaUrl;
+        const result = await api("POST", `conversations/${params.id}/send`, body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Compose a new message (start new conversation)
+  server.registerTool(
+    "neuron_compose_message",
+    {
+      title: "Compose Message",
+      description: "Compose and send a new message to a phone number via a specific channel. Automatically creates a new conversation if one does not exist.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        channelId: z.string().describe("Unique identifier (UUID) of the WhatsApp channel to send through"),
+        to: z.string().describe("Recipient phone number (E.164 format, e.g., '2348012345678')"),
+        text: z.string().describe("Message text content"),
+        messageType: z.string().optional().describe("Type of message: 'text' (default), 'image', or 'document'"),
+        mediaUrl: z.string().optional().describe("URL of media to attach (required for non-text message types)"),
+        contactName: z.string().optional().describe("Display name for the recipient contact"),
+        sendAt: z.string().optional().describe("ISO 8601 date-time for scheduled delivery (e.g., '2025-12-31T10:00:00Z'). Message sends immediately if omitted."),
+      }),
+    },
+    async (params) => {
+      try {
+        const body: Record<string, unknown> = {
+          channelId: params.channelId,
+          to: params.to,
+          text: params.text,
+        };
+        if (params.messageType) body.messageType = params.messageType;
+        if (params.mediaUrl) body.mediaUrl = params.mediaUrl;
+        if (params.contactName) body.contactName = params.contactName;
+        if (params.sendAt) body.sendAt = params.sendAt;
+        const result = await api("POST", "conversations/compose", body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Simple WhatsApp send — auto-resolves channel
+  server.registerTool(
+    "neuron_send_whatsapp",
+    {
+      title: "Send WhatsApp Message",
+      description:
+        "Send a WhatsApp message to a phone number or group. Auto-resolves which channel to use " +
+        "(org default > first connected). Supports text, image, audio, video, and document types.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        to: z.string().describe("Recipient: phone number (e.g., '2348012345678') or group JID (e.g., '120363XXX@g.us')"),
+        text: z.string().describe("Message text content"),
+        messageType: z.string().optional().describe("Message type: 'text' (default), 'image', 'audio', 'video', or 'document'"),
+        mediaUrl: z.string().optional().describe("URL of media to attach (required for non-text message types)"),
+        channelId: z.string().optional().describe("Unique identifier (UUID) of a specific channel to override auto-resolution"),
+        contactName: z.string().optional().describe("Display name for the recipient contact"),
+        sendAt: z.string().optional().describe("ISO 8601 date-time for scheduled delivery (e.g., '2025-12-31T10:00:00Z'). Message sends immediately if omitted."),
+      }),
+    },
+    async (params) => {
+      try {
+        const body: Record<string, unknown> = {
+          to: params.to,
+          text: params.text,
+        };
+        if (params.messageType) body.messageType = params.messageType;
+        if (params.mediaUrl) body.mediaUrl = params.mediaUrl;
+        if (params.channelId) body.channelId = params.channelId;
+        if (params.contactName) body.contactName = params.contactName;
+        if (params.sendAt) body.sendAt = params.sendAt;
+        const result = await api("POST", "conversations/send-message", body);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Edit a message
+  server.registerTool(
+    "neuron_edit_message",
+    {
+      title: "Edit Message",
+      description: "Edit the content of a previously sent message in a conversation. Only the message sender can edit their messages.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation"),
+        msgId: z.string().describe("Unique identifier (UUID) of the message to edit"),
+        content: z.string().describe("New text content to replace the existing message"),
+      }),
+    },
+    async (params) => {
+      try {
+        const result = await api("PUT", `conversations/${params.id}/messages/${params.msgId}`, {
+          content: params.content,
+        });
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Delete a message
+  server.registerTool(
+    "neuron_delete_message",
+    {
+      title: "Delete Message",
+      description: "Permanently delete a specific message from a conversation. This action cannot be undone.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation"),
+        msgId: z.string().describe("Unique identifier (UUID) of the message to delete"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("DELETE", `conversations/${params.id}/messages/${params.msgId}`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  // Close a conversation
+  server.registerTool(
+    "neuron_close_conversation",
+    {
+      title: "Close Conversation",
+      description: "Close an active conversation, marking it as completed. The bot will stop responding and the conversation is archived.",
+      inputSchema: z.object({
+        id: z.string().describe("Unique identifier (UUID) of the conversation to close"),
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+    },
+    async (params) => {
+      try {
+        const result = await api("POST", `conversations/${params.id}/close`);
+        return jsonResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+}

package/src/tools/flows.ts

@@ -0,0 +1,298 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { api, jsonResult, errorResult } from "../client.js";
+
+const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const DELETE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+
+/* ── Shared schemas ────────────────────────────────────────────────── */
+
+const nodeSchema = z.object({
+  id: z.string().describe("Stable node id unique within the flow, e.g. 'n_a1b2' or 't_msg'."),
+  type: z.string().describe("Registry key — e.g. 'trigger.message_received', 'logic.branch', 'action.send_message'. Use neuron_get_flow_catalog to see all available types."),
+  config: z.record(z.unknown()).default({}).describe("Node-specific configuration. Values may contain {{…}} templates resolved at runtime against trigger, vars, and nodes."),
+  position: z.object({ x: z.number(), y: z.number() }).optional().describe("Canvas position (UI layout). Use x=300 as center, space nodes ~160px apart vertically."),
+  label: z.string().optional().describe("Human label overriding the registry default."),
+});
+
+const edgeSchema = z.object({
+  id: z.string().describe("Unique edge id, e.g. 'e_msg_reply'."),
+  source: z.string().describe("Source node id."),
+  target: z.string().describe("Target node id."),
+  sourceHandle: z.string().optional().describe("Which output port of the source node this edge leaves from. Branch nodes use 'true'/'false', switch/router use case ids, wait nodes use 'default'/'timeout', lookup uses 'found'/'not_found'. Defaults to 'default'."),
+});
+
+const graphSchema = z.object({
+  nodes: z.array(nodeSchema).describe("Array of flow nodes."),
+  edges: z.array(edgeSchema).describe("Array of edges connecting nodes. Each edge fires when its source node emits on the matching sourceHandle."),
+});
+
+/* ── Registration ──────────────────────────────────────────────────── */
+
+export function registerFlowTools(server: McpServer): void {
+  /* ── Catalog ─────────────────────────────────────────────────────── */
+
+  server.registerTool(
+    "neuron_get_flow_catalog",
+    {
+      title: "Get Flow Node Catalog",
+      description:
+        "Retrieve the COMPLETE catalog for authoring flows. ALWAYS call this first when building or editing a flow — do not rely on memory, the full node set changes. The response has two parts:\n" +
+        "  • `data`: every node type (all triggers, logic, and actions) with its config `fields` (including `options` enums and `required`), output `handles`, and `dynamicHandles`.\n" +
+        "  • `reference`: the authoring guide you need for anything non-trivial —\n" +
+        "      - `conditions`: the ConditionGroup JSON shape + the full operator vocabulary (used by branch/filter/switch/loop and trigger filters). Note: on LOGIC nodes a rule's `field` is a {{template}}; on a TRIGGER's config.conditions it is a raw payload path.\n" +
+        "      - `compositeFields`: the exact JSON for field kinds the flat schema can't express — `cases` (switch), `assignments` (set_fields), `weekdays`, and the delay amount/unit note.\n" +
+        "      - `triggerConditions`: every trigger also accepts an optional config.conditions AND/OR filter over the raw event payload.\n" +
+        "      - `templating`, `errorHandling` (__errorHandling), `handles` (wiring map), and `examples` (simple, branching AND/OR, and complex switch+set_fields+expression graphs to imitate).\n" +
+        "The catalog is grouped by kind: trigger (entry points), logic (routing/waits/data), action (side effects). There are dozens of node types — read `data` for the authoritative list rather than assuming.",
+      inputSchema: z.object({}),
+      annotations: READ,
+    },
+    async () => {
+      try {
+        return jsonResult(await api("GET", "/flows/catalog"));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  /* ── CRUD ────────────────────────────────────────────────────────── */
+
+  server.registerTool(
+    "neuron_list_flows",
+    {
+      title: "List Flows",
+      description: "List all automation flows in the organization. Returns each flow's id, name, description, enabled status, trigger events, run count, and last run time.",
+      inputSchema: z.object({}),
+      annotations: READ,
+    },
+    async () => {
+      try {
+        return jsonResult(await api("GET", "/flows"));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_create_flow",
+    {
+      title: "Create Flow",
+      description:
+        "Create a new automation flow. A flow is a directed graph of nodes connected by edges. " +
+        "The graph MUST start with at least one trigger node (entry point). Edges connect nodes via output handles.\n\n" +
+        "BEFORE BUILDING: call neuron_get_flow_catalog and read its `reference` — it carries the JSON shapes you cannot guess: the ConditionGroup + operator list for branch/filter/switch conditions, the `cases`/`assignments`/`weekdays` composite shapes, the handle wiring map, and copy-ready `examples`. Condition `field` on a logic node must be a {{template}} (e.g. '{{trigger.text}}'); on a trigger's config.conditions it is a raw payload path (e.g. 'text').\n\n" +
+        "AFTER SAVING: the flow always saves, but the response includes a `warnings` array flagging likely bugs (unknown node type, missing required field, malformed conditions/cases/assignments, edges wired to a handle a node never emits, missing trigger). Always check it and fix any warnings — a warning means that part will silently no-op at run time.\n\n" +
+        "TEMPLATE RESOLUTION: Node config values support {{…}} templates resolved at runtime:\n" +
+        "  {{trigger.text}} — the triggering message text\n" +
+        "  {{trigger.contactPhone}} — the sender's phone\n" +
+        "  {{trigger.senderName}} — the sender's name\n" +
+        "  {{vars.myVar}} — a variable set by logic.set_variable\n" +
+        "  {{nodes.n_abc.output.text}} — output from a previous node\n" +
+        "  {{= amount * 1.1 }} — inline expression (arithmetic, comparisons, ternary)\n\n" +
+        "ERROR HANDLING: Any node's config can include __errorHandling: { continueOnFail: true, retryCount: 3, retryDelayMs: 1000 } " +
+        "to retry on failure with exponential backoff and/or continue on the 'error' handle instead of failing the run.\n\n" +
+        "WIRING RULES:\n" +
+        "  - logic.branch: 'true' and 'false' handles\n" +
+        "  - logic.switch / logic.ai_router: one handle per case id, plus 'default'\n" +
+        "  - logic.wait_for_reply: 'default' (replied) and 'timeout'\n" +
+        "  - logic.wait_for_approval: 'approved', 'rejected', 'timeout'\n" +
+        "  - logic.wait_first_of: 'reply', 'event', 'timeout'\n" +
+        "  - logic.loop: 'loop' (body) and 'done'\n" +
+        "  - action.lookup_contact: 'found' and 'not_found'\n" +
+        "  - action.call_flow: 'default' (returned), 'timeout', 'error'\n" +
+        "  - All other nodes: 'default' handle (or 'error' when continueOnFail is on)",
+      inputSchema: z.object({
+        name: z.string().describe("Human-readable name for the flow."),
+        description: z.string().optional().describe("Optional description of what the flow does."),
+        graph: graphSchema.optional().describe("The flow graph — nodes and edges. Omit to create an empty flow (edit later in the UI)."),
+        enabled: z.boolean().optional().describe("Whether the flow should be active immediately (default: false)."),
+      }),
+      annotations: WRITE,
+    },
+    async ({ name, ...rest }) => {
+      try {
+        return jsonResult(await api("POST", "/flows", { name, ...rest }));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_get_flow",
+    {
+      title: "Get Flow",
+      description: "Retrieve a single flow by id, including its full graph (nodes and edges), enabled status, and run stats.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow."),
+      }),
+      annotations: READ,
+    },
+    async ({ id }) => {
+      try {
+        return jsonResult(await api("GET", `/flows/${id}`));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_update_flow",
+    {
+      title: "Update Flow",
+      description:
+        "Update a flow's name, description, graph, or enabled state. Only provided fields are changed. " +
+        "When updating the graph, provide the COMPLETE graph (all nodes and edges) — it replaces the existing graph entirely. " +
+        "When a graph is supplied the response includes a non-blocking `warnings` array (same checks as create_flow) — check it and fix any flagged issues.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow to update."),
+        name: z.string().optional().describe("New name."),
+        description: z.string().nullable().optional().describe("New description (null to clear)."),
+        graph: graphSchema.optional().describe("Complete replacement graph. Provide ALL nodes and edges."),
+        enabled: z.boolean().optional().describe("Enable or disable the flow."),
+      }),
+      annotations: WRITE,
+    },
+    async ({ id, ...body }) => {
+      try {
+        return jsonResult(await api("PUT", `/flows/${id}`, body));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_delete_flow",
+    {
+      title: "Delete Flow",
+      description: "Soft-delete a flow. It stops running but can be restored. Running executions are not cancelled.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow to delete."),
+      }),
+      annotations: DELETE,
+    },
+    async ({ id }) => {
+      try {
+        return jsonResult(await api("DELETE", `/flows/${id}`));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_toggle_flow",
+    {
+      title: "Toggle Flow",
+      description: "Enable or disable a flow. Disabled flows stop receiving events but retain their graph.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow."),
+        enabled: z.boolean().describe("true to enable, false to disable."),
+      }),
+      annotations: WRITE,
+    },
+    async ({ id, enabled }) => {
+      try {
+        return jsonResult(await api("POST", `/flows/${id}/toggle`, { enabled }));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  /* ── Execution ───────────────────────────────────────────────────── */
+
+  server.registerTool(
+    "neuron_run_flow",
+    {
+      title: "Run Flow",
+      description:
+        "Manually trigger a flow run for testing. Starts at the 'trigger.manual' node if present, otherwise the first trigger node. " +
+        "Optionally provide a payload object that becomes {{trigger.*}} in the flow.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow to run."),
+        payload: z.record(z.unknown()).optional().describe("Test payload available as {{trigger.*}} in the flow — e.g. { text: 'hello', contactPhone: '2348012345678', senderName: 'Test User' }."),
+        nodeId: z.string().optional().describe("Specific trigger node id to start from (for flows with multiple triggers)."),
+      }),
+      annotations: WRITE,
+    },
+    async ({ id, ...body }) => {
+      try {
+        return jsonResult(await api("POST", `/flows/${id}/run`, body));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_list_flow_runs",
+    {
+      title: "List Flow Runs",
+      description: "List execution runs for a flow, newest first. Each run shows status (running/waiting/completed/failed/cancelled), trigger type, step count, and timing.",
+      inputSchema: z.object({
+        id: z.string().describe("UUID of the flow."),
+        page: z.number().int().optional().describe("Page number (default: 1)."),
+        limit: z.number().int().optional().describe("Items per page (default: 20, max: 100)."),
+      }),
+      annotations: READ,
+    },
+    async ({ id, page, limit }) => {
+      try {
+        const params = new URLSearchParams();
+        if (page) params.set("page", String(page));
+        if (limit) params.set("limit", String(limit));
+        const qs = params.toString();
+        return jsonResult(await api("GET", `/flows/${id}/runs${qs ? `?${qs}` : ""}`));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_get_flow_run",
+    {
+      title: "Get Flow Run",
+      description:
+        "Get a single flow run with its full step-by-step execution trace. Each step shows the node type, input/output, status (ok/error/skipped/wait), duration, and which handle fired. " +
+        "Use this to debug flows — see exactly what happened at each step.",
+      inputSchema: z.object({
+        runId: z.string().describe("UUID of the run."),
+      }),
+      annotations: READ,
+    },
+    async ({ runId }) => {
+      try {
+        return jsonResult(await api("GET", `/flows/runs/${runId}`));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+
+  server.registerTool(
+    "neuron_cancel_flow_run",
+    {
+      title: "Cancel Flow Run",
+      description: "Cancel a running or waiting flow execution. Steps already completed are not rolled back.",
+      inputSchema: z.object({
+        runId: z.string().describe("UUID of the run to cancel."),
+      }),
+      annotations: WRITE,
+    },
+    async ({ runId }) => {
+      try {
+        return jsonResult(await api("POST", `/flows/runs/${runId}/cancel`));
+      } catch (error) {
+        return errorResult(error);
+      }
+    },
+  );
+}