@2kw/ai-mcp-server 7.0.0 → 7.1.0-dev.14

package/README.md

@@ -1,6 +1,6 @@
 # 2kw.ai MCP Server
 
-An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [2kw.ai](https://2kw.ai) — the EU-hosted AI integration platform. It gives AI coding assistants like Claude Code, Cursor, and Windsurf direct access to an [OpenAI-compatible LLM gateway](https://2kw.ai/gateway), [schema-driven document extraction](https://2kw.ai/extraction), audio transcription, custom agents with a knowledge base, and [cost observability](https://2kw.ai/observability) — 158 tools, straight from your editor.
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [2kw.ai](https://2kw.ai) — the EU-hosted AI integration platform. It gives AI coding assistants like Claude Code, Cursor, and Windsurf direct access to an [OpenAI-compatible LLM gateway](https://2kw.ai/gateway), [schema-driven document extraction](https://2kw.ai/extraction), audio transcription, custom agents with a knowledge base, and [cost observability](https://2kw.ai/observability) — 199 tools, straight from your editor.
 
 Typical prompts once installed: *"extract the line items from this invoice PDF"*, *"create a schema for purchase orders and test it against these samples"*, *"transcribe this call recording"*, *"what did our extraction traffic cost this week?"*.
 

package/dist/client.js

@@ -31,6 +31,8 @@ const errorMiddleware = {
                 body.error?.message ??
                 `HTTP ${response.status}: ${response.statusText}`,
             timestamp: body.timestamp ?? new Date().toISOString(),
+            // A background run's 409 names its newest response, so the caller can poll it.
+            headResponseId: typeof body.error?.head_response_id === "string" ? body.error.head_response_id : undefined,
         });
     },
 };

package/dist/errors.d.ts

@@ -3,11 +3,14 @@ interface ApiErrorBody {
     message: string;
     status: number;
     timestamp: string;
+    /** The background run's newest response, named by a 409 the run's state answers. */
+    headResponseId?: string;
 }
 export declare class BackboneApiError extends Error {
     readonly status: number;
     readonly errorType: string;
     readonly timestamp: string;
+    readonly headResponseId?: string;
     constructor(apiError: ApiErrorBody);
 }
 export declare function formatErrorForMcp(error: unknown): string;

package/dist/errors.js

@@ -2,17 +2,20 @@ export class BackboneApiError extends Error {
     status;
     errorType;
     timestamp;
+    headResponseId;
     constructor(apiError) {
         super(apiError.message);
         this.name = "BackboneApiError";
         this.status = apiError.status;
         this.errorType = apiError.error;
         this.timestamp = apiError.timestamp;
+        this.headResponseId = apiError.headResponseId;
     }
 }
 export function formatErrorForMcp(error) {
     if (error instanceof BackboneApiError) {
-        return `API Error (${error.status}): ${error.message}`;
+        const head = error.headResponseId ? ` (newest response: ${error.headResponseId})` : "";
+        return `API Error (${error.status}): ${error.message}${head}`;
     }
     if (error instanceof Error) {
         return `Error: ${error.message}`;

package/dist/lib/agent-run.js

@@ -78,7 +78,8 @@ function parseArguments(raw) {
 /**
  * A connector tool's open approval, decoded from the standard `mcp_approval_request` item (#949). The item
  * is the MCP twin of `backbone:approval_request` (#805): it names the server and the tool, carries no call
- * id, policy class or status, and exists only while the decision is open, so its id doubles as the call id
+ * id or status (its policy class is an optional extension, #1084; "unknown" without it), and exists only
+ * while the decision is open, so its id doubles as the call id
  * and the tool is named as the approval row stores it, `mcp__<server_label>__<tool>`.
  */
 function connectorApproval(i) {
@@ -87,7 +88,7 @@ function connectorApproval(i) {
         callId: String(i.id),
         tool: `mcp__${String(i.server_label)}__${String(i.name)}`,
         arguments: parseArguments(i.arguments),
-        policyClass: "unknown",
+        policyClass: typeof i.policy_class === "string" ? i.policy_class : "unknown",
         reason: null,
         preview: null,
     };
@@ -274,15 +275,12 @@ export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
     }
     else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingToolCalls.length === 0 && responseId) {
         // A connector-only pause (no relayed call, so 2kw_decide_agent_approvals has nothing to decide,
-        // spec M11) has no tool here to continue it by id, and a connect pause cannot be continued by
-        // conversation (the gateway answers 400), so the honest ways on are a fresh request or a client
-        // that continues by response id (#1254 review: continueWithDecisions does send previous_response_id
-        // for every other pause this server can decide).
+        // spec M11) is continued by id with 2kw_create_response `previousResponseId` (#1065); a connect
+        // pause cannot be continued by conversation (the gateway answers 400).
         next =
             `Tell the user to ${connectionsPhrase(pendingConnections)} in ${chatUrl}/connectors. ` +
-                `This server cannot continue response ${JSON.stringify(responseId)}: once they have connected, send the request again ` +
-                "with 2kw_create_response without `conversation` (a connect pause cannot be continued by conversation), " +
-                "or continue the response by its id from n8n (Previous Response ID) or any client that sends previous_response_id.";
+                `Once they have connected, call 2kw_create_response with agent ${JSON.stringify(ref)} and previousResponseId ` +
+                `${JSON.stringify(responseId)} and an empty input (not \`conversation\`: a connect pause cannot be continued by conversation).`;
     }
     else if (status === "requires_tool_output" && pendingConnections.length === 0 && pendingToolCalls.length === 0 && responseId) {
         // Paused on nothing the envelope decodes: say so, rather than hand back a pause with no way on.

package/dist/tools/ai-gateway.js

@@ -92,9 +92,23 @@ export function register(server, client) {
             };
         }
     });
+    // An empty input resumes a paused response (#1065): the wire takes `[]`, not an empty message.
+    const requestInput = (input, mode) => {
+        const message = input === "" ? [] : [{ type: "message", role: "user", content: input }];
+        if (mode)
+            return [...message, modeItem(mode)];
+        return input === "" ? [] : input;
+    };
     // ── create_response ─────────────────────────────────────────────────────
-    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer an approval pause with 2kw_decide_agent_approvals. A run paused on a relayed (client-side) tool call comes back with status requires_tool_output and `pendingToolCalls`; answer it with 2kw_decide_agent_approvals `outputs`. A run that needs the user's own sign-in to a connector pauses with status requires_tool_output and `pendingConnections` (label, host, reason): no tool here can answer that; tell the user to connect it in chat.2kw.ai → Connectors, as the envelope's `next` says. A run where a connector asks the user a question pauses with status requires_tool_output and `pendingInputs` (label, tool, mode, answerUrl): the user answers it in chat at `answerUrl`, not here. Always non-streaming. " + MODE_RULE, {
-        input: z.string().min(1).describe("The input text (sent as a single user message)"),
+    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer an approval pause with 2kw_decide_agent_approvals. A run paused on a relayed (client-side) tool call comes back with status requires_tool_output and `pendingToolCalls`; answer it with 2kw_decide_agent_approvals `outputs`. A run that needs the user's own sign-in to a connector pauses with status requires_tool_output and `pendingConnections` (label, host, reason): no tool here can answer that; tell the user to connect it in chat.2kw.ai → Connectors, as the envelope's `next` says; once they have, resume it with 2kw_create_response `previousResponseId` (and an empty `input`). A run where a connector asks the user a question pauses with status requires_tool_output and `pendingInputs` (label, tool, mode, answerUrl): the user answers it in chat at `answerUrl`, not here. Always non-streaming. " + MODE_RULE, {
+        input: z
+            .string()
+            .describe("The input text (sent as a single user message). May be empty only with `previousResponseId`, to resume a paused response without a new message."),
+        previousResponseId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Resume this paused response (sent as previous_response_id), e.g. after the user connected a connector in chat.2kw.ai → Connectors. Use the `responseId` from the pause envelope."),
         agent: z
             .string()
             .optional()
@@ -113,8 +127,14 @@ export function register(server, client) {
             .enum(["plan", "ask", "auto"])
             .optional()
             .describe("Only with `agent`: the conversation mode for this and later turns (plan, ask or auto). Only on the user's explicit request."),
-    }, async ({ input, agent, agentModel, model, conversation, mode }) => {
+    }, async ({ input, previousResponseId, agent, agentModel, model, conversation, mode }) => {
         try {
+            if (input === "" && previousResponseId === undefined) {
+                throw new Error("`input` is empty; it may only be empty with `previousResponseId`.");
+            }
+            if (input === "" && mode !== undefined) {
+                throw new Error("`mode` needs a non-empty `input`: an empty input only resumes a paused response.");
+            }
             if (agent && model) {
                 throw new Error("Use either `agent` or `model`, not both.");
             }
@@ -136,8 +156,9 @@ export function register(server, client) {
                 // Without `mode` the wire `input` is the bare string (shorthand for one user message; see
                 // ResponseItemInputDeserializer). With it, the backbone:mode item follows the message (#656);
                 // that literal item array is what the cast below is for.
-                input: mode ? [{ type: "message", role: "user", content: input }, modeItem(mode)] : input,
+                input: requestInput(input, mode),
                 stream: false,
+                ...(previousResponseId !== undefined && { previous_response_id: previousResponseId }),
                 ...(conversation !== undefined && { conversation }),
             };
             const { data } = await client.POST("/v1/responses", {
@@ -190,6 +211,39 @@ export function register(server, client) {
             };
         }
     });
+    // ── background responses ────────────────────────────────────────────────
+    server.tool("2kw_get_response", "Read a background response (one created with background: true) as it stands now. Its status is queued, in_progress, requires_action, completed, incomplete, failed or cancelled. Its output stays empty while it is queued or in_progress and is filled once the run completes or pauses. Poll it until it leaves queued and in_progress. Only background responses can be read by id; a synchronous one is refused, and an id the caller cannot see answers not found.", {
+        responseId: z.string().min(1).describe("The background response id (resp_...)"),
+    }, async ({ responseId }) => {
+        try {
+            const { data } = await client.GET("/v1/responses/{responseId}", {
+                params: { path: { responseId } },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_cancel_response", "Cancel the background run whose newest response this is. A queued or paused run is cancelled at once and answers status cancelled; a running one stops at its next step and answers in_progress until it does. Only the caller that started the run can cancel it. An older response of the run is refused with a conflict that names the newest response; a run that already ended is refused the same way.", {
+        responseId: z.string().min(1).describe("The run's newest background response id (resp_...)"),
+    }, async ({ responseId }) => {
+        try {
+            const { data } = await client.POST("/v1/responses/{responseId}/cancel", {
+                params: { path: { responseId } },
+            });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     // ── list_models ─────────────────────────────────────────────────────────
     server.tool("2kw_list_models", "List available AI models and providers accessible through the Backbone AI gateway.", {}, async () => {
         try {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "7.0.0",
-  "description": "MCP server for 2kw.ai — EU-hosted AI platform: OpenAI-compatible LLM gateway, schema-driven document extraction, transcription, agents with a knowledge base, and cost observability. 158 tools for Claude Code, Cursor, and Windsurf.",
+  "version": "7.1.0-dev.14",
+  "description": "MCP server for 2kw.ai — EU-hosted AI platform: OpenAI-compatible LLM gateway, schema-driven document extraction, transcription, agents with a knowledge base, and cost observability. 199 tools for Claude Code, Cursor, and Windsurf.",
   "mcpName": "ai.2kw/mcp-server",
   "keywords": [
     "mcp",