@2kw/ai-mcp-server 6.2.0-dev.14 → 6.2.0-dev.30

package/dist/client.js

@@ -2,6 +2,8 @@ import createClient from "openapi-fetch";
 import { BackboneApiError } from "./errors.js";
 /**
  * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ * The api-key filter now returns the OpenAI envelope (#658); the surface
+ * filter still sends the flat shape, so both are normalized here.
  */
 const errorMiddleware = {
     async onResponse({ response }) {
@@ -21,8 +23,13 @@ const errorMiddleware = {
         }
         throw new BackboneApiError({
             status: body.status ?? response.status,
-            error: body.title ?? body.error ?? response.statusText,
-            message: body.detail ?? body.message ?? `HTTP ${response.status}: ${response.statusText}`,
+            error: typeof body.error === "string"
+                ? body.error
+                : (body.error?.code ?? body.error?.type ?? body.title ?? response.statusText),
+            message: body.detail ??
+                body.message ??
+                body.error?.message ??
+                `HTTP ${response.status}: ${response.statusText}`,
             timestamp: body.timestamp ?? new Date().toISOString(),
         });
     },

package/dist/tools/agents.d.ts

@@ -1,4 +1,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ApiClient } from "../client.js";
+/**
+ * The `model`/`models` pair of an agent write (#626, spec #591 §3.3). The backend owns the
+ * rules (derivation, uniqueness, existence); this only refuses the two shapes a caller can
+ * get wrong locally, so the error names the tool's own parameters instead of a 400.
+ */
+export declare function modelFields(model: string | undefined, models: string[] | undefined, required: boolean): {
+    model?: string;
+    models?: string[];
+};
+/** `model: a` for a single-model agent, `models: a (default), b` otherwise. */
+export declare function describeModels(row: {
+    model?: string;
+    models?: string[];
+}): string;
 export declare function register(server: McpServer, client: ApiClient): void;
 //# sourceMappingURL=agents.d.ts.map

package/dist/tools/agents.js

@@ -1,5 +1,39 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+const modelSchema = z
+    .string()
+    .min(1)
+    .describe("Default model in 'provider/model' format (e.g. 'openai/gpt-4o') or a bare platform model name. Shorthand for a one-entry `models` list; if both are given it must equal models[0].");
+const modelsSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .max(10)
+    .describe("Ordered model list, 1-10 unique entries. The first entry is the default the agent runs on; the others are the models a single request may switch to with `agent/<ref>#<model>` (see 2kw_create_response `agentModel`).");
+/**
+ * The `model`/`models` pair of an agent write (#626, spec #591 §3.3). The backend owns the
+ * rules (derivation, uniqueness, existence); this only refuses the two shapes a caller can
+ * get wrong locally, so the error names the tool's own parameters instead of a 400.
+ */
+export function modelFields(model, models, required) {
+    if (models !== undefined && models.length > 0) {
+        if (model !== undefined && model !== models[0]) {
+            throw new Error(`\`model\` ('${model}') must equal the first entry of \`models\` ('${models[0]}'), which is the default. Omit \`model\` when sending \`models\`.`);
+        }
+        return model !== undefined ? { model, models } : { models };
+    }
+    if (model !== undefined)
+        return { model };
+    if (required)
+        throw new Error("Either `model` or `models` is required.");
+    return {};
+}
+/** `model: a` for a single-model agent, `models: a (default), b` otherwise. */
+export function describeModels(row) {
+    const models = row.models && row.models.length > 0 ? row.models : row.model ? [row.model] : [];
+    if (models.length <= 1)
+        return `model: ${models[0] ?? row.model ?? "?"}`;
+    return `models: ${models[0]} (default), ${models.slice(1).join(", ")}`;
+}
 export function register(server, client) {
     // ── list_agents ─────────────────────────────────────────────────────────
     server.tool("2kw_list_agents", "List agents in the organization with optional search and pagination.", {
@@ -18,7 +52,7 @@ export function register(server, client) {
                 },
             });
             const result = data;
-            const lines = (result.content ?? []).map((a) => `- ${a.name} (id: ${a.id}, model: ${a.model})${a.description ? ` — ${a.description}` : ""}`);
+            const lines = (result.content ?? []).map((a) => `- ${a.name} (id: ${a.id}, ${describeModels(a)})${a.description ? ` — ${a.description}` : ""}`);
             return {
                 content: [
                     {
@@ -53,18 +87,19 @@ export function register(server, client) {
         }
     });
     // ── create_agent ────────────────────────────────────────────────────────
-    server.tool("2kw_create_agent", "Create a new agent for the organization.", {
+    server.tool("2kw_create_agent", "Create a new agent for the organization. Give its model as `model` (one model) or `models` (an ordered list whose first entry is the default); one of the two is required.", {
         name: z.string().min(1).describe("Agent name"),
-        model: z.string().min(1).describe("Model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+        model: modelSchema.optional(),
+        models: modelsSchema.optional(),
         description: z.string().optional().describe("Agent description"),
         instructions: z.string().optional().describe("System instructions for the agent"),
         options: z.unknown().optional().describe("Arbitrary model options (JSON object)"),
         tools: z.unknown().optional().describe("Tool configuration (JSON object)"),
         skills: z.unknown().optional().describe("Skill configuration (JSON object)"),
         hitlPolicy: z.unknown().optional().describe("Human-in-the-loop approval policy (JSON object)"),
-    }, async ({ name, model, description, instructions, options, tools, skills, hitlPolicy }) => {
+    }, async ({ name, model, models, description, instructions, options, tools, skills, hitlPolicy }) => {
         try {
-            const body = { name, model };
+            const body = { name, ...modelFields(model, models, true) };
             if (description !== undefined)
                 body.description = description;
             if (instructions !== undefined)
@@ -92,19 +127,20 @@ export function register(server, client) {
         }
     });
     // ── update_agent ────────────────────────────────────────────────────────
-    server.tool("2kw_update_agent", "Update an agent's metadata and configuration. name and model are required on every update — the backend treats this as a full replace of those fields.", {
+    server.tool("2kw_update_agent", "Update an agent's metadata and configuration. name is required on every update. `model` or `models` replaces the stored model list (a shorter list leaves no tail); omit both to keep the current models. Does not create a version.", {
         agentId: z.string().describe("The agent ID"),
         name: z.string().min(1).describe("Agent name"),
-        model: z.string().min(1).describe("Model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+        model: modelSchema.optional(),
+        models: modelsSchema.optional(),
         description: z.string().optional().describe("Agent description"),
         instructions: z.string().optional().describe("System instructions for the agent"),
         options: z.unknown().optional().describe("Arbitrary model options (JSON object)"),
         tools: z.unknown().optional().describe("Tool configuration (JSON object)"),
         skills: z.unknown().optional().describe("Skill configuration (JSON object)"),
         hitlPolicy: z.unknown().optional().describe("Human-in-the-loop approval policy (JSON object)"),
-    }, async ({ agentId, name, model, description, instructions, options, tools, skills, hitlPolicy }) => {
+    }, async ({ agentId, name, model, models, description, instructions, options, tools, skills, hitlPolicy }) => {
         try {
-            const body = { name, model };
+            const body = { name, ...modelFields(model, models, false) };
             if (description !== undefined)
                 body.description = description;
             if (instructions !== undefined)
@@ -160,7 +196,7 @@ export function register(server, client) {
                 params: { path: { agentId }, query: { pageable: { page, size } } },
             });
             const result = data;
-            const lines = (result.content ?? []).map((v) => `- v${v.versionNumber} (id: ${v.id})${v.changeDescription ? ` — ${v.changeDescription}` : ""}`);
+            const lines = (result.content ?? []).map((v) => `- v${v.versionNumber} (id: ${v.id}, ${describeModels(v)})${v.changeDescription ? ` — ${v.changeDescription}` : ""}`);
             return {
                 content: [
                     {
@@ -178,18 +214,19 @@ export function register(server, client) {
         }
     });
     // ── create_agent_version ────────────────────────────────────────────────
-    server.tool("2kw_create_agent_version", "Create a new version of an agent. Auto-updates the 'latest' label.", {
+    server.tool("2kw_create_agent_version", "Create a new version of an agent. Auto-updates the 'latest' label. Give its model as `model` (one model) or `models` (an ordered list whose first entry is the default); one of the two is required.", {
         agentId: z.string().describe("The agent ID"),
-        model: z.string().min(1).describe("Model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+        model: modelSchema.optional(),
+        models: modelsSchema.optional(),
         changeDescription: z.string().optional().describe("Description of what changed in this version"),
         instructions: z.string().optional().describe("System instructions for the agent"),
         options: z.unknown().optional().describe("Arbitrary model options (JSON object)"),
         tools: z.unknown().optional().describe("Tool configuration (JSON object)"),
         skills: z.unknown().optional().describe("Skill configuration (JSON object)"),
         hitlPolicy: z.unknown().optional().describe("Human-in-the-loop approval policy (JSON object)"),
-    }, async ({ agentId, model, changeDescription, instructions, options, tools, skills, hitlPolicy }) => {
+    }, async ({ agentId, model, models, changeDescription, instructions, options, tools, skills, hitlPolicy }) => {
         try {
-            const body = { model };
+            const body = { ...modelFields(model, models, true) };
             if (changeDescription !== undefined)
                 body.changeDescription = changeDescription;
             if (instructions !== undefined)

package/dist/tools/ai-gateway.d.ts

@@ -1,4 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ApiClient } from "../client.js";
+/**
+ * The `model` value for an agent run: `agent/<ref>[@<label>]`, plus `#<model>` when the
+ * request switches to another entry of the version's `models` list (#626, spec #591 §4.1).
+ * Returns undefined when no agent is given.
+ */
+export declare function agentModelReference(agent: string | undefined, agentModel?: string): string | undefined;
 export declare function register(server: McpServer, client: ApiClient): void;
 //# sourceMappingURL=ai-gateway.d.ts.map

package/dist/tools/ai-gateway.js

@@ -1,8 +1,18 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+/**
+ * The `model` value for an agent run: `agent/<ref>[@<label>]`, plus `#<model>` when the
+ * request switches to another entry of the version's `models` list (#626, spec #591 §4.1).
+ * Returns undefined when no agent is given.
+ */
+export function agentModelReference(agent, agentModel) {
+    if (!agent)
+        return undefined;
+    return agentModel ? `agent/${agent}#${agentModel}` : `agent/${agent}`;
+}
 export function register(server, client) {
     // ── chat ────────────────────────────────────────────────────────────────
-    server.tool("2kw_chat", "Send a chat completion request through Backbone's OpenAI-compatible AI gateway. Supports multiple providers (OpenAI, Anthropic, Azure, Vertex AI, etc.). Model format: 'provider/model' (e.g. 'openai/gpt-4o', 'anthropic/claude-sonnet-4-5-20250929'). Always non-streaming.", {
+    server.tool("2kw_chat", "Send a chat completion request through Backbone's OpenAI-compatible AI gateway. Supports OpenAI, Azure OpenAI, Anthropic, xAI, Mistral and Ollama. Model format: 'provider/model' (e.g. 'openai/gpt-4o', 'anthropic/claude-sonnet-4-5-20250929'). Always non-streaming.", {
         model: z.string().describe("Model identifier in 'provider/model' format"),
         messages: z
             .array(z.object({
@@ -82,18 +92,23 @@ export function register(server, client) {
         }
     });
     // ── 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'). Always non-streaming.", {
+    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. The reply ends with the model that answered. Always non-streaming.", {
         input: z.string().min(1).describe("The input text (sent as a single user message)"),
         agent: z
             .string()
             .optional()
             .describe("Stored agent id or name to invoke, optionally 'ref@label'. Mutually exclusive with `model`."),
+        agentModel: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Only with `agent`: run this request on this model instead of the agent's default. Must be one of the resolved version's `models`; sent as 'agent/<ref>#<model>'."),
         model: z
             .string()
             .optional()
             .describe("Model identifier in 'provider/model' format. Mutually exclusive with `agent`."),
         conversation: z.string().optional().describe("Conversation ID this response belongs to"),
-    }, async ({ input, agent, model, conversation }) => {
+    }, async ({ input, agent, agentModel, model, conversation }) => {
         try {
             if (agent && model) {
                 throw new Error("Use either `agent` or `model`, not both.");
@@ -101,7 +116,13 @@ export function register(server, client) {
             if (!agent && !model) {
                 throw new Error("Either `agent` or `model` is required.");
             }
-            const resolvedModel = agent ? `agent/${agent}` : model;
+            if (agentModel !== undefined && !agent) {
+                throw new Error("`agentModel` switches a stored agent's model; it needs `agent`.");
+            }
+            if (agentModel !== undefined && agent?.includes("#")) {
+                throw new Error("Give the model switch once: either 'ref#model' in `agent` or `agentModel`.");
+            }
+            const resolvedModel = agentModelReference(agent, agentModel) ?? model;
             const body = {
                 model: resolvedModel,
                 // The wire `input` field also accepts a bare string (shorthand for
@@ -141,6 +162,11 @@ export function register(server, client) {
             if (parts.length === 0) {
                 parts.push({ type: "text", text: JSON.stringify(result, null, 2) });
             }
+            // The response echoes the model that answered: for an agent run
+            // 'agent/<name>@<version>', plus '#<model>' when the request switched it (#591).
+            if (agent && typeof result.model === "string") {
+                parts.push({ type: "text", text: `[model: ${result.model}]` });
+            }
             return { content: parts };
         }
         catch (error) {

package/dist/tools/providers.js

@@ -1,12 +1,12 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+// The API enum also has VERTEX_AI, but the gateway cannot build a model for it yet (#118).
 const ProviderType = z.enum([
     "OPENAI",
     "AZURE_OPENAI",
     "ANTHROPIC",
     "XAI",
     "MISTRAL",
-    "VERTEX_AI",
     "OLLAMA",
 ]);
 export function register(server, client) {

package/dist/tools/skills.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ApiClient } from "../client.js";
-/** Register skill read and import tools (#642). */
+/** Register skill read, import and delete tools (#642, #683). */
 export declare function register(server: McpServer, client: ApiClient): void;
 //# sourceMappingURL=skills.d.ts.map

package/dist/tools/skills.js

@@ -10,7 +10,7 @@ function paginationParams(params) {
         sort: params.sort ? [params.sort] : undefined,
     };
 }
-/** Register skill read and import tools (#642). */
+/** Register skill read, import and delete tools (#642, #683). */
 export function register(server, client) {
     server.tool("2kw_list_skills", "List org skills with optional name/status filter and pagination.", {
         search: z.string().optional().describe("Filter by name"),
@@ -131,6 +131,20 @@ export function register(server, client) {
             };
         }
     });
+    server.tool("2kw_delete_skill", "Delete a skill and all its versions. Refused with 409 while an agent version binds it; the message names the agents.", { skillId: z.string() }, async (params) => {
+        try {
+            await client.DELETE("/v1/skills/{id}", { params: { path: { id: params.skillId } } });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ deleted: params.skillId }, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     server.tool("2kw_import_skill", "Import a local SKILL.md or .zip file. Returns outcome, version, renamedFrom and skipped files. Zip directories before importing.", { filePath: z.string().min(1).describe("Local path to SKILL.md or a .zip archive") }, async (params) => {
         try {
             const info = await stat(params.filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "6.2.0-dev.14",
+  "version": "6.2.0-dev.30",
   "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.",
   "mcpName": "ai.2kw/mcp-server",
   "keywords": [
@@ -41,6 +41,7 @@
     "check:generated": "tsx openapi/scripts/check-generated.ts",
     "fix:generated": "tsx openapi/scripts/check-generated.ts --write",
     "check:coverage": "tsx ../cli/openapi/scripts/check-coverage.ts",
+    "test": "tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {