@2kw/ai-mcp-server 6.2.2 → 6.3.0-dev.106

package/dist/tools/experiments.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 export function register(server, client) {
     // ── list_experiments ────────────────────────────────────────────
     server.tool("2kw_list_experiments", "List experiments in the organization with optional search, status filter, and pagination.", {
@@ -99,7 +100,7 @@ export function register(server, client) {
         }
     });
     // ── update_experiment ───────────────────────────────────────────
-    server.tool("2kw_update_experiment", "Update an existing experiment's details.", {
+    server.tool("2kw_update_experiment", "Update an existing experiment's details. Omitted fields keep their current values (the tool reads the experiment first).", {
         experimentId: z.string().describe("The experiment ID"),
         name: z.string().optional().describe("New name"),
         description: z.string().optional().describe("New description"),
@@ -108,20 +109,16 @@ export function register(server, client) {
         metadata: z.unknown().optional().describe("Arbitrary metadata (JSON object)"),
     }, async ({ experimentId, name, description, type, datasetVersionId, metadata }) => {
         try {
-            const body = {};
-            if (name !== undefined)
-                body.name = name;
-            if (description !== undefined)
-                body.description = description;
-            if (type !== undefined)
-                body.type = type;
-            if (datasetVersionId !== undefined)
-                body.datasetVersionId = datasetVersionId;
-            if (metadata !== undefined)
-                body.metadata = metadata;
+            assertNameNotBlank(name);
+            // PUT /v1/experiments/{id} replaces the whole experiment, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/experiments/{id}", {
+                params: { path: { id: experimentId } },
+            });
+            if (!current)
+                throw new Error(`Experiment ${experimentId} could not be read.`);
             const { data } = await client.PUT("/v1/experiments/{id}", {
                 params: { path: { id: experimentId } },
-                body: body,
+                body: overlay(current, { name, description, type, datasetVersionId, metadata }),
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -157,7 +154,7 @@ export function register(server, client) {
     server.tool("2kw_add_variant", "Add a variant to an experiment with a task type and configuration.", {
         experimentId: z.string().describe("The experiment ID"),
         name: z.string().min(1).describe("Variant name"),
-        taskType: z.string().min(1).describe("Task type (e.g., EXTRACTION, CLASSIFICATION)"),
+        taskType: z.string().min(1).describe("Task type: extraction or agent"),
         configuration: z.unknown().describe("Variant configuration (JSON object)"),
         description: z.string().optional().describe("Variant description"),
         sortOrder: z.number().optional().describe("Sort order for display"),
@@ -210,30 +207,29 @@ export function register(server, client) {
         }
     });
     // ── update_variant ──────────────────────────────────────────────
-    server.tool("2kw_update_variant", "Update an existing variant's details.", {
+    server.tool("2kw_update_variant", "Update an existing variant's details. Omitted fields keep their current values (the tool reads the variant first).", {
         experimentId: z.string().describe("The experiment ID"),
         variantId: z.string().describe("The variant ID"),
         name: z.string().optional().describe("New variant name"),
-        taskType: z.string().optional().describe("New task type"),
+        taskType: z.string().optional().describe("Task type; must equal the variant's current one (it cannot change)"),
         configuration: z.unknown().optional().describe("New variant configuration (JSON object)"),
         description: z.string().optional().describe("New variant description"),
         sortOrder: z.number().optional().describe("New sort order for display"),
     }, async ({ experimentId, variantId, name, taskType, configuration, description, sortOrder }) => {
         try {
-            const body = {};
-            if (name !== undefined)
-                body.name = name;
-            if (taskType !== undefined)
-                body.taskType = taskType;
-            if (configuration !== undefined)
-                body.configuration = configuration;
-            if (description !== undefined)
-                body.description = description;
-            if (sortOrder !== undefined)
-                body.sortOrder = sortOrder;
+            assertNameNotBlank(name);
+            // PUT .../variants/{variantId} writes name, description and configuration as sent, so an
+            // omitted one would be cleared. There is no single-variant GET: read it from the list. The
+            // read's version goes back with the body, so a change made since is refused with 409.
+            const { data: variants } = await client.GET("/v1/experiments/{id}/variants", {
+                params: { path: { id: experimentId } },
+            });
+            const current = variants?.find((v) => v.id === variantId);
+            if (!current)
+                throw new Error(`Variant ${variantId} is not a variant of experiment ${experimentId}.`);
             const { data } = await client.PUT("/v1/experiments/{id}/variants/{variantId}", {
                 params: { path: { id: experimentId, variantId } },
-                body: body,
+                body: overlay(current, { name, taskType, configuration, description, sortOrder }),
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],

package/dist/tools/index.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+export interface ToolDeps {
+    client: ApiClient;
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * One tool module. `id` is its file name under src/tools; `title` and `summary` head its table on
+ * the public docs page, which `npm run docs:tools` generates from this list (#1148).
+ */
+export interface ToolGroup {
+    id: string;
+    title: string;
+    summary: string;
+    register(server: McpServer, deps: ToolDeps): void;
+}
+/** Every tool module, in the order the docs page lists them. A new module must be added here. */
+export declare const TOOL_GROUPS: readonly ToolGroup[];
+export declare function registerAllTools(server: McpServer, deps: ToolDeps): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,190 @@
+import * as agents from "./agents.js";
+import * as aiGateway from "./ai-gateway.js";
+import * as analytics from "./analytics.js";
+import * as annotationQueues from "./annotation-queues.js";
+import * as billing from "./billing.js";
+import * as conversations from "./conversations.js";
+import * as conversion from "./conversion.js";
+import * as datasets from "./datasets.js";
+import * as docs from "./docs.js";
+import * as evaluators from "./evaluators.js";
+import * as experiments from "./experiments.js";
+import * as extraction from "./extraction.js";
+import * as files from "./files.js";
+import * as knowledge from "./knowledge.js";
+import * as memory from "./memory.js";
+import * as plugins from "./plugins.js";
+import * as prompts from "./prompts.js";
+import * as providers from "./providers.js";
+import * as schemaLabels from "./schema-labels.js";
+import * as schemaTesting from "./schema-testing.js";
+import * as schemaVersions from "./schema-versions.js";
+import * as schemas from "./schemas.js";
+import * as scores from "./scores.js";
+import * as skills from "./skills.js";
+import * as tracing from "./tracing.js";
+import * as transcription from "./transcription.js";
+/** Every tool module, in the order the docs page lists them. A new module must be added here. */
+export const TOOL_GROUPS = [
+    {
+        id: "ai-gateway",
+        title: "AI Gateway",
+        summary: "Call models through the gateway — chat completions, the Responses endpoint (including stored agents) and the model list.",
+        register: (s, d) => aiGateway.register(s, d.client),
+    },
+    {
+        id: "agents",
+        title: "Agents",
+        summary: "Manage agents, their versions, labels and tool catalogs, and decide paused approvals. See [Running agents](#running-agents).",
+        register: (s, d) => agents.register(s, d.client),
+    },
+    {
+        id: "conversations",
+        title: "Conversations",
+        summary: "Create, read, rename and delete conversations, list their items and cancel a running turn.",
+        register: (s, d) => conversations.register(s, d.client),
+    },
+    {
+        id: "memory",
+        title: "Memory",
+        summary: "Read and edit your own agent memory, and see or erase a member's memory as an admin.",
+        register: (s, d) => memory.register(s, d.client),
+    },
+    {
+        id: "knowledge",
+        title: "Knowledge Bases",
+        summary: "Manage knowledge bases and their documents, search them and resolve citations.",
+        register: (s, d) => knowledge.register(s, d.client),
+    },
+    {
+        id: "files",
+        title: "Files",
+        summary: "Upload, list, download and delete files.",
+        register: (s, d) => files.register(s, d.client),
+    },
+    {
+        id: "skills",
+        title: "Skills",
+        summary: "Import, read, resolve and delete skills, with their versions and labels.",
+        register: (s, d) => skills.register(s, d.client),
+    },
+    {
+        id: "plugins",
+        title: "Plugins",
+        summary: "Install, sync, update and remove plugins.",
+        register: (s, d) => plugins.register(s, d.client),
+    },
+    {
+        id: "prompts",
+        title: "Prompts",
+        summary: "Manage prompts, their versions and labels, and resolve, compile or test them.",
+        register: (s, d) => prompts.register(s, d.client),
+    },
+    {
+        id: "schemas",
+        title: "Schemas",
+        summary: "Define extraction schemas within your organization.",
+        register: (s, d) => schemas.register(s, d.client),
+    },
+    {
+        id: "schema-versions",
+        title: "Schema Versions",
+        summary: "Manage versioned snapshots of schema definitions.",
+        register: (s, d) => schemaVersions.register(s, d.client),
+    },
+    {
+        id: "schema-labels",
+        title: "Schema Labels",
+        summary: "Point named labels at schema versions.",
+        register: (s, d) => schemaLabels.register(s, d.client),
+    },
+    {
+        id: "schema-testing",
+        title: "Schema Testing",
+        summary: "Validate schemas and test extractions without persisting data.",
+        register: (s, d) => schemaTesting.register(s, d.client),
+    },
+    {
+        id: "extraction",
+        title: "Extractions",
+        summary: "Extract structured data from text using schemas and AI models.",
+        register: (s, d) => extraction.register(s, d.client),
+    },
+    {
+        id: "conversion",
+        title: "Document Conversion",
+        summary: "Convert documents (PDF, DOCX and more) to Markdown, text, HTML or JSON.",
+        register: (s, d) => conversion.register(s, d.client),
+    },
+    {
+        id: "transcription",
+        title: "Audio Transcription",
+        summary: "Transcribe audio files using AI models.",
+        register: (s, d) => transcription.register(s, d.client),
+    },
+    {
+        id: "datasets",
+        title: "Datasets",
+        summary: "Manage evaluation datasets, their versions and items.",
+        register: (s, d) => datasets.register(s, d.client),
+    },
+    {
+        id: "experiments",
+        title: "Experiments",
+        summary: "Run experiments over datasets, compare variants and track regressions against a baseline.",
+        register: (s, d) => experiments.register(s, d.client),
+    },
+    {
+        id: "evaluators",
+        title: "Evaluators",
+        summary: "List evaluator types and manage evaluator templates.",
+        register: (s, d) => evaluators.register(s, d.client),
+    },
+    {
+        id: "scores",
+        title: "Scores",
+        summary: "Record and list human scores.",
+        register: (s, d) => scores.register(s, d.client),
+    },
+    {
+        id: "annotation-queues",
+        title: "Annotation Queues",
+        summary: "Manage annotation queues and work through their items.",
+        register: (s, d) => annotationQueues.register(s, d.client),
+    },
+    {
+        id: "tracing",
+        title: "Tracing",
+        summary: "Read traces and trace sessions, and change the tracing settings.",
+        register: (s, d) => tracing.register(s, d.client),
+    },
+    {
+        id: "analytics",
+        title: "Analytics",
+        summary: "Usage, error and quality analytics for your organization.",
+        register: (s, d) => analytics.register(s, d.client),
+    },
+    {
+        id: "providers",
+        title: "Providers",
+        summary: "Manage AI providers and list their models.",
+        register: (s, d) => providers.register(s, d.client),
+    },
+    {
+        id: "billing",
+        title: "Billing",
+        summary: "Read your billing tier and limits, and check available budget.",
+        register: (s, d) => billing.register(s, d.client),
+    },
+    {
+        id: "docs",
+        title: "API Documentation",
+        summary: "Browse the backend's OpenAPI documentation by section.",
+        register: (s, d) => docs.register(s, d.client, d.baseUrl, d.apiKey),
+    },
+];
+export function registerAllTools(server, deps) {
+    for (const group of TOOL_GROUPS)
+        group.register(server, deps);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/knowledge.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { BackboneApiError, formatErrorForMcp } from "../errors.js";
+import { formatErrorForMcp } from "../errors.js";
 import { getMimeType } from "../mime.js";
 const ChunkingStrategy = z.enum(["AUTO", "FIXED", "HIERARCHICAL", "CUSTOM"]);
 const DocumentStatus = z.enum(["PENDING", "PARSING", "CHUNKING", "EMBEDDING", "READY", "ERROR"]);
@@ -203,29 +203,13 @@ export function register(server, client) {
                 const filename = basename(filePath);
                 formData.append("files", new Blob([buffer], { type: getMimeType(filename) }), filename);
             }
-            const { baseUrl, apiKey } = client._config;
-            const res = await fetch(`${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${apiKey}` },
-                body: formData,
+            const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+                params: { path: { knowledgeBaseId } },
+                // Provide placeholder body for type checking; actual payload comes from bodySerializer
+                body: { files: [] },
+                bodySerializer: () => formData,
             });
-            if (!res.ok) {
-                let body;
-                try {
-                    body = await res.json();
-                }
-                catch {
-                    body = {
-                        error: res.statusText,
-                        message: `HTTP ${res.status}: ${res.statusText}`,
-                        status: res.status,
-                        timestamp: new Date().toISOString(),
-                    };
-                }
-                throw new BackboneApiError(body);
-            }
-            const data = (await res.json());
-            const lines = data.map((r) => r.error
+            const lines = (data ?? []).map((r) => r.error
                 ? `- ${r.filename}: rejected — ${r.error}`
                 : `- ${r.filename}: accepted, documentId=${r.upload?.document?.id}, versionId=${r.upload?.acceptedVersion?.id}, status=${r.upload?.acceptedVersion?.status}`);
             return {

package/dist/tools/memory.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+/**
+ * Agent memory of organization members (agent memory spec §7.1, §7.4). The "my" tools act on
+ * the API key owner's own memory; the member tools are for ADMIN and OWNER keys and never
+ * show paths or content.
+ */
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/tools/memory.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+async function reply(action) {
+    try {
+        const data = await action();
+        return {
+            content: [{ type: "text", text: data === undefined ? "Done." : JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+    }
+}
+const path = z.string().min(1).describe("Memory path, /memories or below, e.g. /memories/preferences.md");
+/**
+ * Agent memory of organization members (agent memory spec §7.1, §7.4). The "my" tools act on
+ * the API key owner's own memory; the member tools are for ADMIN and OWNER keys and never
+ * show paths or content.
+ */
+export function register(server, client) {
+    server.tool("2kw_list_my_memory_files", "List the files in your agent memory (the API key owner's), ordered by path, without content.", {}, async () => reply(async () => (await client.GET("/v1/memories/me/files")).data));
+    server.tool("2kw_read_my_memory_file", "Read one of your agent memory files: the raw content, its version (for ifMatchVersion) and which agent wrote it last.", { path }, async ({ path }) => reply(async () => (await client.GET("/v1/memories/me/file", { params: { query: { path } } })).data));
+    server.tool("2kw_write_my_memory_file", "Create or replace one of your agent memory files with the complete content. Pass ifMatchVersion (the version from 2kw_read_my_memory_file) to refuse the write if the file changed since. Credentials are refused; files are limited to 32 KB.", {
+        path,
+        content: z.string().describe("The complete UTF-8 text content of the file"),
+        ifMatchVersion: z.number().int().min(0).optional().describe("Only replace the file if it still has this version"),
+    }, async ({ path, content, ifMatchVersion }) => reply(async () => (await client.PUT("/v1/memories/me/file", {
+        params: { query: { path } },
+        body: { content },
+        headers: ifMatchVersion === undefined ? undefined : { "If-Match": `"${ifMatchVersion}"` },
+    })).data));
+    server.tool("2kw_delete_my_memory_file", "Delete one of your agent memory files, or a directory with everything below it. Irreversible.", { path }, async ({ path }) => reply(async () => {
+        await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+    }));
+    server.tool("2kw_forget_my_memory", "Delete your whole agent memory. Irreversible: confirm with the user before calling.", {}, async () => reply(async () => {
+        await client.DELETE("/v1/memories/me");
+    }));
+    server.tool("2kw_list_member_memory_usage", "Agent memory totals per organization member: file count, total bytes and last write. Never paths or content. Needs an ADMIN or OWNER key.", {}, async () => reply(async () => (await client.GET("/v1/memories/users")).data));
+    server.tool("2kw_erase_member_memory", "Erase one member's whole agent memory in this organization. Irreversible: confirm with the user before calling. Needs an ADMIN or OWNER key.", { userId: z.string().min(1).describe("The member's user id, from 2kw_list_member_memory_usage") }, async ({ userId }) => reply(async () => {
+        await client.DELETE("/v1/memories/users/{userId}", { params: { path: { userId } } });
+    }));
+}
+//# sourceMappingURL=memory.js.map

package/dist/tools/prompts.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 export function register(server, client) {
     // ── prompts ─────────────────────────────────────────────────────────────
     server.tool("2kw_list_prompts", "List org prompts with optional name/type filter and pagination.", {
@@ -74,23 +75,23 @@ export function register(server, client) {
             };
         }
     });
-    server.tool("2kw_update_prompt", "Update prompt metadata (name, description, type).", {
+    server.tool("2kw_update_prompt", "Update prompt metadata (name, description, type). Omitted fields keep their current values (the tool reads the prompt first).", {
         promptId: z.string(),
         name: z.string().optional(),
         description: z.string().optional(),
         type: z.enum(["TEXT", "CHAT"]).optional(),
     }, async (params) => {
         try {
-            const body = {};
-            if (params.name !== undefined)
-                body.name = params.name;
-            if (params.description !== undefined)
-                body.description = params.description;
-            if (params.type !== undefined)
-                body.type = params.type;
+            assertNameNotBlank(params.name);
+            // PUT /v1/prompts/{id} replaces the whole prompt, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/prompts/{id}", {
+                params: { path: { id: params.promptId } },
+            });
+            if (!current)
+                throw new Error(`Prompt ${params.promptId} could not be read.`);
             const { data } = await client.PUT("/v1/prompts/{id}", {
                 params: { path: { id: params.promptId } },
-                body: body,
+                body: overlay(current, { name: params.name, description: params.description, type: params.type }),
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],

package/dist/tools/schemas.js

@@ -85,20 +85,27 @@ export function register(server, client) {
         }
     });
     // ── update_schema ───────────────────────────────────────────────────────
-    server.tool("2kw_update_schema", "Update an existing schema.", {
+    server.tool("2kw_update_schema", "Update an existing schema. Omitted fields keep their current values (the tool reads the schema first).", {
         schemaId: z.string().describe("The schema ID"),
         name: z.string().optional().describe("New schema name"),
         description: z.string().optional().describe("New schema description"),
     }, async ({ schemaId, name, description }) => {
         try {
-            const body = {};
-            if (name !== undefined)
-                body.name = name;
-            if (description !== undefined)
-                body.description = description;
+            if (name !== undefined && !name.trim())
+                throw new Error("name must not be empty.");
+            // PUT /v1/schemas/{id} replaces the whole schema, so an omitted field would be stored as null.
+            if (name === undefined || description === undefined) {
+                const { data: current } = await client.GET("/v1/schemas/{id}", {
+                    params: { path: { id: schemaId } },
+                });
+                if (!current)
+                    throw new Error(`Schema ${schemaId} could not be read.`);
+                name ??= current.name;
+                description ??= current.description;
+            }
             const { data } = await client.PUT("/v1/schemas/{id}", {
                 params: { path: { id: schemaId } },
-                body: body,
+                body: { name, description },
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],

package/dist/tools/tracing.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
 export function register(server, client) {
     // ── settings ────────────────────────────────────────────────────────────
-    server.tool("2kw_get_tracing_settings", "Return the org's tracing settings (includePrompts / includeCompletions). These control whether raw prompt and completion content are persisted on ingested spans. Defaults are false for both.", {}, async () => {
+    server.tool("2kw_get_tracing_settings", "Return the org's tracing settings: includePrompts / includeCompletions (whether raw prompt and completion content are persisted on ingested spans; false by default) and trace retention: retentionDays (the org's choice, null = follow the plan), planRetentionDays and effectiveRetentionDays.", {}, async () => {
         try {
             const { data } = await client.GET("/v1/tracing/settings");
             return {
@@ -16,7 +16,7 @@ export function register(server, client) {
             };
         }
     });
-    server.tool("2kw_update_tracing_settings", "Update the org's tracing settings. Admin-only. Omit a field to leave it at its current value — the tool reads the current setting first and merges.", {
+    server.tool("2kw_update_tracing_settings", "Update the org's tracing settings. Admin-only. Omit a field to leave it at its current value — the tool reads the current setting first and merges. Shortening retentionDays deletes older traces at the next daily sweep.", {
         includePrompts: z
             .boolean()
             .optional()
@@ -25,12 +25,20 @@ export function register(server, client) {
             .boolean()
             .optional()
             .describe("Retain completion content on ingested spans (default false)"),
+        retentionDays: z
+            .number()
+            .int()
+            .min(1)
+            .nullable()
+            .optional()
+            .describe("Trace retention in days, at most the plan's limit (planRetentionDays). null follows the plan. Shortening deletes older traces at the next daily sweep."),
     }, async (params) => {
         try {
             const { data: current } = await client.GET("/v1/tracing/settings");
             const merged = {
                 includePrompts: params.includePrompts ?? current?.includePrompts ?? false,
                 includeCompletions: params.includeCompletions ?? current?.includeCompletions ?? false,
+                retentionDays: params.retentionDays !== undefined ? params.retentionDays : (current?.retentionDays ?? null),
             };
             const { data } = await client.PUT("/v1/tracing/settings", {
                 body: merged,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "6.2.2",
+  "version": "6.3.0-dev.106",
   "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,8 @@
     "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",
+    "docs:tools": "tsx scripts/tool-docs.ts",
+    "check:tool-docs": "tsx scripts/tool-docs.ts --check",
     "test": "tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit"
   },