@2kw/ai-mcp-server 6.1.0-dev.8 → 6.1.1

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, and [cost observability](https://2kw.ai/observability) — 88 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) — 158 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?"*.
 
@@ -56,6 +56,10 @@ Get an API key from your [2kw.ai dashboard](https://2kw.ai) — paid plans start
 | **Schemas** | CRUD, versioning, labels, validation, and testing against sample documents |
 | **Prompts** | Versioned prompt management, labels, compilation, testing |
 | **Datasets & experiments** | Build datasets, run experiments, manage evaluators, record scores |
+| **Agents** | CRUD, versioning, labels, tool-approval history, and tool-catalog sync history |
+| **Conversations** | Create/inspect/delete conversations and replay their items for the responses API |
+| **Knowledge base** | CRUD, document upload/attach/versioning, hybrid search, and citation resolution |
+| **Files** | Upload, list, download, and delete files (agent input or knowledge documents) |
 | **Observability** | Analytics (spend, quality, providers, errors), traces, billing limits |
 | **API docs** | Browse the platform API documentation by section |
 

package/dist/index.js

@@ -21,9 +21,14 @@ import * as prompts from "./tools/prompts.js";
 import * as providers from "./tools/providers.js";
 import * as billing from "./tools/billing.js";
 import * as scores from "./tools/scores.js";
+import * as annotationQueues from "./tools/annotation-queues.js";
 import * as tracing from "./tools/tracing.js";
 import * as analytics from "./tools/analytics.js";
 import * as docs from "./tools/docs.js";
+import * as agents from "./tools/agents.js";
+import * as conversations from "./tools/conversations.js";
+import * as knowledge from "./tools/knowledge.js";
+import * as files from "./tools/files.js";
 // Read the canonical KW_* env var; fall back to legacy BACKBONE_* for
 // backwards compatibility. Warn once on stderr when the legacy name supplied
 // the value.
@@ -81,9 +86,14 @@ async function main() {
     providers.register(server, client);
     billing.register(server, client);
     scores.register(server, client);
+    annotationQueues.register(server, client);
     tracing.register(server, client);
     analytics.register(server, client);
     docs.register(server, client, baseUrl, apiKey);
+    agents.register(server, client);
+    conversations.register(server, client);
+    knowledge.register(server, client);
+    files.register(server, client);
     if (transport === "http") {
         const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         const httpServer = createServer(async (req, res) => {

package/dist/tools/agents.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=agents.d.ts.map

package/dist/tools/agents.js

@@ -0,0 +1,434 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    // ── list_agents ─────────────────────────────────────────────────────────
+    server.tool("2kw_list_agents", "List agents in the organization with optional search and pagination.", {
+        search: z.string().optional().describe("Filter agents by name"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+        sort: z.string().optional().describe("Sort field and direction"),
+    }, async ({ search, page, size, sort }) => {
+        try {
+            const { data } = await client.GET("/v1/agents", {
+                params: {
+                    query: {
+                        search,
+                        pageable: { page, size, sort: sort ? [sort] : undefined },
+                    },
+                },
+            });
+            const result = data;
+            const lines = (result.content ?? []).map((a) => `- ${a.name} (id: ${a.id}, model: ${a.model})${a.description ? ` — ${a.description}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Agents (${result.totalElements} total, page ${(result.number ?? 0) + 1}/${result.totalPages}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_agent ───────────────────────────────────────────────────────────
+    server.tool("2kw_get_agent", "Get an agent by its ID.", { agentId: z.string().describe("The agent ID") }, async ({ agentId }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{id}", {
+                params: { path: { id: agentId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── create_agent ────────────────────────────────────────────────────────
+    server.tool("2kw_create_agent", "Create a new agent for the organization.", {
+        name: z.string().min(1).describe("Agent name"),
+        model: z.string().min(1).describe("Model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+        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 }) => {
+        try {
+            const body = { name, model };
+            if (description !== undefined)
+                body.description = description;
+            if (instructions !== undefined)
+                body.instructions = instructions;
+            if (options !== undefined)
+                body.options = options;
+            if (tools !== undefined)
+                body.tools = tools;
+            if (skills !== undefined)
+                body.skills = skills;
+            if (hitlPolicy !== undefined)
+                body.hitlPolicy = hitlPolicy;
+            const { data } = await client.POST("/v1/agents", {
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── 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.", {
+        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')"),
+        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 }) => {
+        try {
+            const body = { name, model };
+            if (description !== undefined)
+                body.description = description;
+            if (instructions !== undefined)
+                body.instructions = instructions;
+            if (options !== undefined)
+                body.options = options;
+            if (tools !== undefined)
+                body.tools = tools;
+            if (skills !== undefined)
+                body.skills = skills;
+            if (hitlPolicy !== undefined)
+                body.hitlPolicy = hitlPolicy;
+            const { data } = await client.PUT("/v1/agents/{id}", {
+                params: { path: { id: agentId } },
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_agent ────────────────────────────────────────────────────────
+    server.tool("2kw_delete_agent", "Delete an agent and cascade-delete its versions and labels. This action is irreversible.", { agentId: z.string().describe("The agent ID to delete") }, async ({ agentId }) => {
+        try {
+            await client.DELETE("/v1/agents/{id}", {
+                params: { path: { id: agentId } },
+            });
+            return {
+                content: [{ type: "text", text: `Agent ${agentId} deleted successfully.` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_agent_versions ─────────────────────────────────────────────────
+    server.tool("2kw_list_agent_versions", "List version history for an agent, with pagination.", {
+        agentId: z.string().describe("The agent ID"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ agentId, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/versions", {
+                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}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Agent versions (${result.totalElements} total, page ${(result.number ?? 0) + 1}/${result.totalPages}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── create_agent_version ────────────────────────────────────────────────
+    server.tool("2kw_create_agent_version", "Create a new version of an agent. Auto-updates the 'latest' label.", {
+        agentId: z.string().describe("The agent ID"),
+        model: z.string().min(1).describe("Model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+        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 }) => {
+        try {
+            const body = { model };
+            if (changeDescription !== undefined)
+                body.changeDescription = changeDescription;
+            if (instructions !== undefined)
+                body.instructions = instructions;
+            if (options !== undefined)
+                body.options = options;
+            if (tools !== undefined)
+                body.tools = tools;
+            if (skills !== undefined)
+                body.skills = skills;
+            if (hitlPolicy !== undefined)
+                body.hitlPolicy = hitlPolicy;
+            const { data } = await client.POST("/v1/agents/{agentId}/versions", {
+                params: { path: { agentId } },
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_latest_agent_version ────────────────────────────────────────────
+    server.tool("2kw_get_latest_agent_version", "Retrieve the most recent version of an agent.", { agentId: z.string().describe("The agent ID") }, async ({ agentId }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/versions/latest", {
+                params: { path: { agentId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_agent_version ───────────────────────────────────────────────────
+    server.tool("2kw_get_agent_version", "Retrieve a specific version of an agent.", {
+        agentId: z.string().describe("The agent ID"),
+        versionId: z.string().describe("The version ID"),
+    }, async ({ agentId, versionId }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/versions/{versionId}", {
+                params: { path: { agentId, versionId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── deactivate_agent_version ────────────────────────────────────────────
+    server.tool("2kw_deactivate_agent_version", "Soft-delete an agent version.", {
+        agentId: z.string().describe("The agent ID"),
+        versionId: z.string().describe("The version ID to deactivate"),
+    }, async ({ agentId, versionId }) => {
+        try {
+            await client.DELETE("/v1/agents/{agentId}/versions/{versionId}", {
+                params: { path: { agentId, versionId } },
+            });
+            return {
+                content: [
+                    { type: "text", text: `Agent version ${versionId} deactivated.` },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── activate_agent_version ──────────────────────────────────────────────
+    server.tool("2kw_activate_agent_version", "Re-activate a historical agent version by creating a copy at the head.", {
+        agentId: z.string().describe("The agent ID"),
+        versionId: z.string().describe("The version ID to activate"),
+    }, async ({ agentId, versionId }) => {
+        try {
+            const { data } = await client.PUT("/v1/agents/{agentId}/versions/{versionId}/activate", { params: { path: { agentId, versionId } } });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_agent_labels ───────────────────────────────────────────────────
+    server.tool("2kw_list_agent_labels", "List labels defined on an agent (e.g. production, staging) and which version each points to.", { agentId: z.string().describe("The agent ID") }, async ({ agentId }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/labels", {
+                params: { path: { agentId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── create_agent_label ──────────────────────────────────────────────────
+    server.tool("2kw_create_agent_label", "Label an agent version (e.g. tag as 'production'). Labels are unique per agent. The 'latest' label is system-managed and cannot be created manually.", {
+        agentId: z.string().describe("The agent ID"),
+        name: z.string().describe("Label name"),
+        agentVersionId: z.string().describe("Version id the label should point to"),
+    }, async ({ agentId, name, agentVersionId }) => {
+        try {
+            const { data } = await client.POST("/v1/agents/{agentId}/labels", {
+                params: { path: { agentId } },
+                body: { name, agentVersionId },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_agent_label ──────────────────────────────────────────────────
+    server.tool("2kw_update_agent_label", "Repoint an existing agent label to a different version — typical release cutover. The 'latest' label is system-managed and cannot be updated manually.", {
+        agentId: z.string().describe("The agent ID"),
+        labelName: z.string().describe("The label name"),
+        agentVersionId: z.string().describe("Version id the label should now point to"),
+    }, async ({ agentId, labelName, agentVersionId }) => {
+        try {
+            const { data } = await client.PUT("/v1/agents/{agentId}/labels/{labelName}", {
+                params: { path: { agentId, labelName } },
+                body: { agentVersionId },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_agent_label ──────────────────────────────────────────────────
+    server.tool("2kw_delete_agent_label", "Delete a label from an agent. The 'latest' label cannot be deleted.", {
+        agentId: z.string().describe("The agent ID"),
+        labelName: z.string().describe("The label name"),
+    }, async ({ agentId, labelName }) => {
+        try {
+            await client.DELETE("/v1/agents/{agentId}/labels/{labelName}", {
+                params: { path: { agentId, labelName } },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Label "${labelName}" deleted from agent ${agentId}.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_agent_approvals ────────────────────────────────────────────────
+    server.tool("2kw_list_agent_approvals", "List human-in-the-loop tool approvals raised by an agent, newest first. Filter with status=pending|approved|rejected|cancelled. A surface principal sees only their own.", {
+        agentId: z.string().describe("The agent ID"),
+        status: z.string().optional().describe("Filter by approval status"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ agentId, status, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/approvals", {
+                params: {
+                    path: { agentId },
+                    query: { status, pageable: { page, size } },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_agent_tool_catalogs ─────────────────────────────────────────────
+    server.tool("2kw_list_agent_tool_catalogs", "List an agent's tool-catalog sync history, newest first. Optionally narrow to one installation. The signed bytes and their signature are never returned.", {
+        agentId: z.string().describe("The agent ID"),
+        installationId: z.string().optional().describe("Narrow to a single installation"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ agentId, installationId, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/tool-catalogs", {
+                params: {
+                    path: { agentId },
+                    query: { installationId, pageable: { page, size } },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=agents.js.map

package/dist/tools/annotation-queues.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=annotation-queues.d.ts.map