@2kw/ai-mcp-server 4.0.0-dev.2

package/dist/tools/schema-testing.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+import { ensureOpenAiCompatible } from "../schema-compat.js";
+/* ── helpers ─────────────────────────────────────────────────────────────── */
+function formatTestResult(result) {
+    const parts = [];
+    parts.push(`Success: ${result.success}`);
+    if (result.extractedData) {
+        parts.push(`Extracted data:\n${JSON.stringify(result.extractedData, null, 2)}`);
+    }
+    if (result.error) {
+        parts.push(`Error: ${result.error}`);
+    }
+    if (result.modelUsed) {
+        parts.push(`Model: ${result.modelUsed}`);
+    }
+    if (result.inputTokens != null || result.outputTokens != null) {
+        parts.push(`Tokens: ${result.inputTokens ?? 0} input, ${result.outputTokens ?? 0} output`);
+    }
+    if (result.processingDurationMs != null) {
+        parts.push(`Processing time: ${result.processingDurationMs}ms`);
+    }
+    return parts.join("\n");
+}
+export function register(server, client) {
+    // ── validate_schema ─────────────────────────────────────────────────────
+    server.tool("2kw_validate_schema", "Validate a JSON Schema definition without persisting it. Returns validation errors and warnings.", {
+        schemaId: z.string().describe("The schema ID"),
+        jsonSchema: z.unknown().describe("The JSON Schema to validate"),
+    }, async ({ schemaId, jsonSchema }) => {
+        try {
+            const { data } = await client.POST("/v1/schemas/{schemaId}/validate", {
+                params: { path: { schemaId } },
+                body: {
+                    jsonSchema: ensureOpenAiCompatible(jsonSchema),
+                },
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = data;
+            const parts = [];
+            parts.push(`Valid: ${result?.valid}`);
+            if (result?.errors && result.errors.length > 0) {
+                parts.push(`\nErrors:\n${result.errors.map((e) => `  - ${e}`).join("\n")}`);
+            }
+            if (result?.warnings && result.warnings.length > 0) {
+                parts.push(`\nWarnings:\n${result.warnings.map((w) => `  - ${w}`).join("\n")}`);
+            }
+            return {
+                content: [{ type: "text", text: parts.join("\n") }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── test_schema ─────────────────────────────────────────────────────────
+    server.tool("2kw_test_schema", "Test a JSON Schema against sample text using AI extraction. Returns the extraction result and token usage without creating a persistent extraction.", {
+        schemaId: z.string().describe("The schema ID"),
+        jsonSchema: z.unknown().describe("The JSON Schema to test"),
+        sampleText: z.string().describe("Sample text to extract data from"),
+        model: z.string().describe("AI model in 'provider/model' format (e.g. 'openai/gpt-4o')"),
+    }, async ({ schemaId, jsonSchema, sampleText, model }) => {
+        try {
+            // Create a temporary version with this schema content, then test
+            await client.POST("/v1/schemas/{schemaId}/versions", {
+                params: { path: { schemaId } },
+                body: {
+                    jsonSchema: ensureOpenAiCompatible(jsonSchema),
+                    changeDescription: "Test version",
+                },
+            });
+            const { data } = await client.POST("/v1/schemas/{schemaId}/test", {
+                params: { path: { schemaId } },
+                body: {
+                    jsonSchema: ensureOpenAiCompatible(jsonSchema),
+                    sampleText,
+                    model,
+                },
+            });
+            const result = data;
+            return {
+                content: [{ type: "text", text: formatTestResult(result) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=schema-testing.js.map

package/dist/tools/schema-versions.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=schema-versions.d.ts.map

package/dist/tools/schema-versions.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+import { ensureOpenAiCompatible } from "../schema-compat.js";
+export function register(server, client) {
+    // ── create_schema_version ───────────────────────────────────────────────
+    server.tool("2kw_create_schema_version", "Create a new version for a schema. The new version becomes the active one.", {
+        schemaId: z.string().describe("The schema ID"),
+        jsonSchema: z.unknown().describe("The JSON Schema definition for this version"),
+        changeDescription: z
+            .string()
+            .optional()
+            .describe("Description of what changed in this version"),
+    }, async ({ schemaId, jsonSchema, changeDescription }) => {
+        try {
+            const { data } = await client.POST("/v1/schemas/{schemaId}/versions", {
+                params: { path: { schemaId } },
+                body: {
+                    jsonSchema: ensureOpenAiCompatible(jsonSchema),
+                    ...(changeDescription && { changeDescription }),
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_schema_versions ────────────────────────────────────────────────
+    server.tool("2kw_list_schema_versions", "List all versions of a schema with pagination.", {
+        schemaId: z.string().describe("The schema ID"),
+        page: z.number().optional().default(0).describe("Page number (0-based)"),
+        size: z.number().optional().default(20).describe("Page size"),
+    }, async ({ schemaId, page, size }) => {
+        try {
+            const { data } = await client.GET("/v1/schemas/{schemaId}/versions", {
+                params: {
+                    path: { schemaId },
+                    query: { pageable: { page, size } },
+                },
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = data;
+            const lines = (result?.content ?? []).map(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (v) => `- v${v.versionNumber} (id: ${v.id}) ${v.isActive ? "[ACTIVE]" : "[inactive]"}${v.changeDescription ? ` — ${v.changeDescription}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Schema 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,
+            };
+        }
+    });
+    // ── get_schema_version ──────────────────────────────────────────────────
+    server.tool("2kw_get_schema_version", "Get a specific schema version by its ID.", {
+        schemaId: z.string().describe("The schema ID"),
+        versionId: z.string().describe("The version ID"),
+    }, async ({ schemaId, versionId }) => {
+        try {
+            const { data } = await client.GET("/v1/schemas/{schemaId}/versions/{versionId}", {
+                params: { path: { schemaId, versionId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_latest_schema_version ───────────────────────────────────────────
+    server.tool("2kw_get_latest_schema_version", "Get the latest active version of a schema.", {
+        schemaId: z.string().describe("The schema ID"),
+    }, async ({ schemaId }) => {
+        try {
+            const { data } = await client.GET("/v1/schemas/{schemaId}/versions/latest", {
+                params: { path: { schemaId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── activate_schema_version ─────────────────────────────────────────────
+    server.tool("2kw_activate_schema_version", "Re-activate a historical schema version by creating a copy as the newest active version.", {
+        schemaId: z.string().describe("The schema ID"),
+        versionId: z.string().describe("The version ID to activate"),
+    }, async ({ schemaId, versionId }) => {
+        try {
+            const { data } = await client.PUT("/v1/schemas/{schemaId}/versions/{versionId}/activate", {
+                params: { path: { schemaId, versionId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=schema-versions.js.map

package/dist/tools/schemas.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=schemas.d.ts.map

package/dist/tools/schemas.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    // ── list_schemas ────────────────────────────────────────────────────────
+    server.tool("2kw_list_schemas", "List schemas in the organization with optional search and pagination.", {
+        search: z.string().optional().describe("Filter schemas 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/schemas", {
+                params: {
+                    query: {
+                        search,
+                        pageable: {
+                            page,
+                            size,
+                            sort: sort ? [sort] : undefined,
+                        },
+                    },
+                },
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = data;
+            const lines = (result?.content ?? []).map(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (s) => `- ${s.name} (id: ${s.id})${s.description ? ` — ${s.description}` : ""}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Schemas (${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_schema ──────────────────────────────────────────────────────────
+    server.tool("2kw_get_schema", "Get a schema by its ID.", {
+        schemaId: z.string().describe("The schema ID"),
+    }, async ({ schemaId }) => {
+        try {
+            const { data } = await client.GET("/v1/schemas/{id}", {
+                params: { path: { id: schemaId } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── create_schema ───────────────────────────────────────────────────────
+    server.tool("2kw_create_schema", "Create a new schema in the organization.", {
+        name: z.string().min(1).describe("Schema name"),
+        description: z.string().optional().describe("Schema description"),
+    }, async ({ name, description }) => {
+        try {
+            const { data } = await client.POST("/v1/schemas", {
+                body: {
+                    name,
+                    ...(description !== undefined && { description }),
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── update_schema ───────────────────────────────────────────────────────
+    server.tool("2kw_update_schema", "Update an existing schema.", {
+        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;
+            const { data } = await client.PUT("/v1/schemas/{id}", {
+                params: { path: { id: schemaId } },
+                body: body,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── delete_schema ───────────────────────────────────────────────────────
+    server.tool("2kw_delete_schema", "Delete a schema and all its versions. This action is irreversible.", {
+        schemaId: z.string().describe("The schema ID to delete"),
+    }, async ({ schemaId }) => {
+        try {
+            await client.DELETE("/v1/schemas/{id}", {
+                params: { path: { id: schemaId } },
+            });
+            return {
+                content: [
+                    { type: "text", text: `Schema ${schemaId} deleted successfully.` },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=schemas.js.map

package/dist/tools/scores.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=scores.d.ts.map

package/dist/tools/scores.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    server.tool("2kw_record_human_score", "Record a human score for an experiment run result. Upserts by (runResultId, evaluatorId, annotatorId) — a reviewer calling this again replaces their own score, not anyone else's. Score must be between 0.0 and 1.0.", {
+        runResultId: z.string().describe("Run result id"),
+        evaluatorId: z
+            .string()
+            .describe("Evaluator identifier (e.g. 'helpfulness' or a template id)"),
+        score: z.number().min(0).max(1).describe("Score between 0.0 and 1.0"),
+        label: z
+            .string()
+            .optional()
+            .describe("Short label (e.g. 'pass', 'fail', 'good')"),
+        comment: z.string().optional().describe("Optional reviewer note"),
+    }, async (params) => {
+        try {
+            const { data } = await client.POST("/v1/evaluation-scores/human", {
+                body: {
+                    runResultId: params.runResultId,
+                    evaluatorId: params.evaluatorId,
+                    score: params.score,
+                    label: params.label,
+                    comment: params.comment,
+                },
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Human score recorded.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=scores.js.map

package/dist/tools/tracing.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=tracing.d.ts.map

package/dist/tools/tracing.js

@@ -0,0 +1,124 @@
+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 () => {
+        try {
+            const { data } = await client.GET("/v1/tracing/settings");
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    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.", {
+        includePrompts: z
+            .boolean()
+            .optional()
+            .describe("Retain prompt content on ingested spans (default false)"),
+        includeCompletions: z
+            .boolean()
+            .optional()
+            .describe("Retain completion content on ingested spans (default false)"),
+    }, 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,
+            };
+            const { data } = await client.PUT("/v1/tracing/settings", {
+                body: merged,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Tracing settings updated.\n\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── traces ──────────────────────────────────────────────────────────────
+    server.tool("2kw_list_traces", "List recent traces in the org. Traces are aggregated by trace_id across all spans. Optional filters: source service, status code (OK/ERROR/UNSET, CSV for multiple), free-text search across trace id + span name + service + backbone.operation.", {
+        sourceService: z.string().optional().describe("Filter by source_service"),
+        statusCode: z
+            .string()
+            .optional()
+            .describe("Filter by status (OK, ERROR, UNSET — comma-separated for multiple)"),
+        search: z
+            .string()
+            .optional()
+            .describe("Free-text search across trace id / span name / service / operation"),
+        page: z.number().int().min(0).optional().describe("Page index (0-based)"),
+        size: z.number().int().min(1).max(100).optional().describe("Page size"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/traces", {
+                params: {
+                    query: {
+                        sourceService: params.sourceService,
+                        statusCode: params.statusCode,
+                        search: params.search,
+                        page: params.page ?? 0,
+                        size: params.size ?? 20,
+                    },
+                },
+            });
+            const result = data;
+            const lines = (result.content ?? []).map((t) => {
+                const services = Array.isArray(t.sourceServices)
+                    ? t.sourceServices.join(", ")
+                    : "";
+                return `- ${t.traceId} [${t.statusCode ?? "UNSET"}] ${t.rootSpanName ?? "(unnamed)"} · ${t.durationMs}ms · ${t.spanCount} spans · ${services}`;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Traces (${result.totalElements ?? 0} total, page ${(result.number ?? 0) + 1}/${result.totalPages ?? 1}):\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_get_trace", "Get every span of a specific trace. Returns a flat array of spans sorted by start time — reconstruct the parent/child tree from parent_id.", {
+        traceId: z.string().describe("Trace id (32-char hex)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/traces/{traceId}", {
+                params: { path: { traceId: params.traceId } },
+            });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tools/transcription.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=transcription.d.ts.map

package/dist/tools/transcription.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { formatErrorForMcp } from "../errors.js";
+import { getMimeType } from "../mime.js";
+export function register(server, client) {
+    server.tool("2kw_transcribe_audio", "Transcribe an audio file using Backbone's transcription API. Supports flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Reads local files automatically.", {
+        filePath: z.string().describe("Local path to the audio file"),
+        model: z
+            .string()
+            .describe("Transcription model in 'provider/model' format (e.g. 'openai/whisper-1')"),
+        language: z
+            .string()
+            .optional()
+            .describe("ISO-639-1 language code (e.g. 'en', 'de')"),
+        prompt: z
+            .string()
+            .optional()
+            .describe("Text to guide the transcription style/context"),
+        responseFormat: z
+            .enum(["json", "text", "srt", "verbose_json", "vtt"])
+            .optional()
+            .describe("Response format (default: json)"),
+        temperature: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Sampling temperature (0-1)"),
+    }, async ({ filePath, model, language, prompt, responseFormat, temperature }) => {
+        try {
+            const fileBuffer = await readFile(filePath);
+            const filename = basename(filePath);
+            const mimeType = getMimeType(filename);
+            const formData = new FormData();
+            formData.append("file", new Blob([fileBuffer], { type: mimeType }), filename);
+            formData.append("model", model);
+            if (language)
+                formData.append("language", language);
+            if (prompt)
+                formData.append("prompt", prompt);
+            if (responseFormat)
+                formData.append("response_format", responseFormat);
+            if (temperature !== undefined)
+                formData.append("temperature", String(temperature));
+            const { data } = await client.POST("/v1/audio/transcriptions", {
+                // Provide placeholder body for type checking; actual payload comes from bodySerializer
+                body: { file: "", model },
+                bodySerializer: () => formData,
+            });
+            const result = data;
+            const parts = [];
+            parts.push({ type: "text", text: result.text });
+            if (result.language) {
+                parts.push({
+                    type: "text",
+                    text: `[Language: ${result.language}]`,
+                });
+            }
+            if (result.duration !== undefined) {
+                parts.push({
+                    type: "text",
+                    text: `[Duration: ${result.duration}s]`,
+                });
+            }
+            return { content: parts };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=transcription.js.map