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

package/dist/tools/analytics.js

@@ -0,0 +1,163 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+const dateRange = {
+    startDate: z.string().optional().describe("Start date (YYYY-MM-DD)"),
+    endDate: z.string().optional().describe("End date (YYYY-MM-DD)"),
+};
+export function register(server, client) {
+    server.tool("2kw_analytics_summary", "Cross-surface summary for the org: total operations, spend, p95 duration, and per-surface breakdown (extractions, conversions, chat, transcription, experiments). Default range is the trailing 30 days.", dateRange, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/summary", {
+                params: { query: { startDate: params.startDate, endDate: params.endDate } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_time_series", "Operations count grouped by date bucket and surface. Useful for charting activity over time.", {
+        ...dateRange,
+        groupBy: z
+            .enum(["day", "week", "month"])
+            .optional()
+            .describe("Bucket size (default: day)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/time-series", {
+                params: {
+                    query: {
+                        startDate: params.startDate,
+                        endDate: params.endDate,
+                        groupBy: params.groupBy ?? "day",
+                    },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_schemas", "Top schemas by extraction count with success rate, token usage, and cost (extraction surface only).", {
+        ...dateRange,
+        limit: z.number().int().min(1).max(100).optional().describe("Max rows (default 10)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/schemas", {
+                params: {
+                    query: {
+                        startDate: params.startDate,
+                        endDate: params.endDate,
+                        limit: params.limit ?? 10,
+                    },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_providers", "Provider usage breakdown (extraction surface only): counts, success rate, tokens, cost, avg duration.", dateRange, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/providers", {
+                params: { query: { startDate: params.startDate, endDate: params.endDate } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_errors", "Top failures across all surfaces, grouped by (surface, error message), with count and last occurrence.", {
+        ...dateRange,
+        limit: z.number().int().min(1).max(100).optional().describe("Max rows (default 10)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/errors", {
+                params: {
+                    query: {
+                        startDate: params.startDate,
+                        endDate: params.endDate,
+                        limit: params.limit ?? 10,
+                    },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_quality", "Total experiment runs in range + average evaluator score. Snapshot of overall quality signal.", dateRange, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/quality", {
+                params: { query: { startDate: params.startDate, endDate: params.endDate } },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_analytics_quality_trend", "Average evaluator score over time, bucketed by day/week/month.", {
+        ...dateRange,
+        groupBy: z
+            .enum(["day", "week", "month"])
+            .optional()
+            .describe("Bucket size (default: day)"),
+    }, async (params) => {
+        try {
+            const { data } = await client.GET("/v1/analytics/quality/trend", {
+                params: {
+                    query: {
+                        startDate: params.startDate,
+                        endDate: params.endDate,
+                        groupBy: params.groupBy ?? "day",
+                    },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=analytics.js.map

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

package/dist/tools/billing.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    server.tool("2kw_get_billing_tier", "Show the org's current subscription tier and its feature flags.", {}, async () => {
+        try {
+            const { data } = await client.GET("/v1/billing/tier");
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_list_billing_tiers", "List every available subscription tier with its limits (for comparison or upgrade guidance).", {}, async () => {
+        try {
+            const { data } = await client.GET("/v1/billing/tiers");
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_get_billing_limits", "Current usage vs. tier limits across resources (schemas, prompts, team members, etc.) plus period window and feature flags.", {}, async () => {
+        try {
+            const { data } = await client.GET("/v1/billing/limits");
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("2kw_billing_check", "Check whether the org can create another resource of the given type before attempting it. Returns a single boolean answer.", {
+        resource: z
+            .enum(["schema", "prompt", "team-member"])
+            .describe("Resource type to check"),
+    }, async (params) => {
+        try {
+            let data;
+            switch (params.resource) {
+                case "schema":
+                    ({ data } = await client.GET("/v1/billing/can-create-schema"));
+                    break;
+                case "prompt":
+                    ({ data } = await client.GET("/v1/billing/can-create-prompt"));
+                    break;
+                case "team-member":
+                    ({ data } = await client.GET("/v1/billing/can-add-team-member"));
+                    break;
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=billing.js.map

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

package/dist/tools/conversion.js

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { BackboneApiError, formatErrorForMcp } from "../errors.js";
+import { getMimeType } from "../mime.js";
+/**
+ * Map user-friendly format names to backend OutputFormat enum values.
+ */
+function mapOutputFormat(format) {
+    const map = {
+        markdown: "MD", md: "MD",
+        text: "TEXT", txt: "TEXT",
+        json: "JSON",
+        html: "HTML",
+    };
+    return map[format.toLowerCase()] ?? format.toUpperCase();
+}
+/**
+ * Extract content from an ExportDocument that uses per-format content fields.
+ */
+function formatExportDocument(doc) {
+    const parts = [];
+    if (doc.mdContent)
+        parts.push({ type: "text", text: `<document filename="${doc.filename}" format="markdown">\n${doc.mdContent}\n</document>` });
+    if (doc.textContent)
+        parts.push({ type: "text", text: `<document filename="${doc.filename}" format="text">\n${doc.textContent}\n</document>` });
+    if (doc.htmlContent)
+        parts.push({ type: "text", text: `<document filename="${doc.filename}" format="html">\n${doc.htmlContent}\n</document>` });
+    if (doc.jsonContent)
+        parts.push({ type: "text", text: JSON.stringify(doc.jsonContent, null, 2) });
+    return parts;
+}
+const TERMINAL_STATUSES = new Set(["SUCCESS", "PARTIAL_SUCCESS", "FAILURE", "COMPLETED", "FAILED"]);
+/**
+ * Poll an async task until terminal status, then fetch and return the result.
+ */
+async function waitForTask(client, taskId, pollSeconds = 30) {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        const { data } = await client.GET("/v1/convert/tasks/{taskId}", {
+            params: { path: { taskId }, query: { wait: pollSeconds } },
+        });
+        const status = data?.taskStatus;
+        if (status && TERMINAL_STATUSES.has(status.toUpperCase()))
+            break;
+    }
+    const { data } = await client.GET("/v1/convert/tasks/{taskId}/result", {
+        params: { path: { taskId } },
+    });
+    return data;
+}
+/**
+ * Format a ConvertResponse into MCP text content parts.
+ */
+function formatConvertResponse(result) {
+    const parts = [];
+    if (result.documents?.length) {
+        for (const doc of result.documents) {
+            parts.push(...formatExportDocument(doc));
+        }
+    }
+    if (result.errors?.length) {
+        parts.push({
+            type: "text",
+            text: `Errors:\n${result.errors.map((e) => `- ${e.filename ?? "unknown"}: ${e.errorMessage}`).join("\n")}`,
+        });
+    }
+    if (parts.length === 0) {
+        parts.push({ type: "text", text: `Conversion completed with status: ${result.status}` });
+    }
+    return parts;
+}
+export function register(server, client) {
+    // ── convert_document ────────────────────────────────────────────────────
+    server.tool("2kw_convert_document", "Convert documents (PDF, DOCX, XLSX, images, etc.) to Markdown, text, HTML, or JSON. Accepts URLs, base64 data, or local file paths. Local files are automatically read and base64-encoded. Use this to convert binary files before passing them to 2kw_create_extraction. Pipeline options: 'fast' (default, fast text extraction), 'ocr' (OCR with layout analysis), or 'vlm' (vision language model for image-heavy/complex layouts). Set async=true with waitForCompletion=true for long-running pipelines like VLM — this submits asynchronously and automatically polls until the result is ready.", {
+        sources: z
+            .array(z.object({
+            type: z.enum(["url", "base64", "file"]).describe("Source type: 'url' for HTTP URLs, 'base64' for base64-encoded data, 'file' for local file paths"),
+            url: z.string().optional().describe("URL of the document (when type='url')"),
+            data: z.string().optional().describe("Base64-encoded document data (when type='base64')"),
+            filename: z.string().optional().describe("Filename (required for base64/file types)"),
+            path: z.string().optional().describe("Local file path (when type='file')"),
+        }))
+            .describe("List of document sources to convert"),
+        pipeline: z
+            .string()
+            .optional()
+            .describe("Processing pipeline: 'fast' (default, fast text extraction), 'ocr' (OCR with layout analysis), or 'vlm' (vision language model for image-heavy documents)"),
+        options: z
+            .object({
+            outputFormats: z.array(z.string()).optional().describe("Output formats, e.g. ['md', 'text', 'html', 'json']. Only relevant for ocr/vlm pipelines."),
+            ocrEngine: z.string().optional().describe("OCR engine (e.g. 'easyocr', 'tesseract')"),
+            ocrLanguages: z.array(z.string()).optional().describe("OCR languages (e.g. ['en', 'de'])"),
+            pdfBackend: z.string().optional().describe("PDF backend (e.g. 'dlparser', 'pypdfium2')"),
+            tableStructure: z.boolean().optional().describe("Enable table structure detection"),
+            maxPages: z.number().optional().describe("Maximum number of pages to process"),
+            imageExportMode: z.string().optional().describe("Image export mode (e.g. 'placeholder', 'embedded')"),
+            imagesScale: z.number().optional().describe("Scale factor for exported images"),
+            pictureClassification: z.boolean().optional().describe("Enable picture classification"),
+        })
+            .optional()
+            .describe("Options for ocr/vlm pipelines. Ignored when pipeline is 'fast'."),
+        async: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, submit as async task. Combine with waitForCompletion=true to get the final result in a single call."),
+        waitForCompletion: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When async=true, automatically poll until done and return the final result instead of a task ID. Recommended for VLM pipeline."),
+    }, async ({ sources, pipeline, options: pipelineOptions, async: isAsync, waitForCompletion }) => {
+        try {
+            // Separate file sources (use multipart) from url/base64 sources (use JSON)
+            const fileSources = [];
+            const apiSources = [];
+            for (const src of sources) {
+                if (src.type === "url") {
+                    if (!src.url)
+                        throw new Error("url is required for type='url'");
+                    apiSources.push({ kind: "http", url: src.url });
+                }
+                else if (src.type === "base64") {
+                    if (!src.data || !src.filename)
+                        throw new Error("data and filename are required for type='base64'");
+                    apiSources.push({ kind: "base64", content: src.data, filename: src.filename, mimeType: getMimeType(src.filename) });
+                }
+                else if (src.type === "file") {
+                    const filePath = src.path ?? src.filename;
+                    if (!filePath)
+                        throw new Error("path or filename is required for type='file'");
+                    const name = src.filename ?? basename(filePath);
+                    fileSources.push({ path: filePath, filename: name });
+                }
+            }
+            // Build pipeline options
+            const nestedOpts = {};
+            if (pipelineOptions) {
+                if (pipelineOptions.outputFormats)
+                    nestedOpts.outputFormats = pipelineOptions.outputFormats.map(mapOutputFormat);
+                if (pipelineOptions.ocrEngine)
+                    nestedOpts.ocrEngine = pipelineOptions.ocrEngine;
+                if (pipelineOptions.ocrLanguages)
+                    nestedOpts.ocrLanguages = pipelineOptions.ocrLanguages;
+                if (pipelineOptions.pdfBackend)
+                    nestedOpts.pdfBackend = pipelineOptions.pdfBackend;
+                if (pipelineOptions.tableStructure !== undefined)
+                    nestedOpts.tableStructure = pipelineOptions.tableStructure;
+                if (pipelineOptions.maxPages !== undefined)
+                    nestedOpts.maxPages = pipelineOptions.maxPages;
+                if (pipelineOptions.imageExportMode)
+                    nestedOpts.imageExportMode = pipelineOptions.imageExportMode;
+                if (pipelineOptions.imagesScale !== undefined)
+                    nestedOpts.imagesScale = pipelineOptions.imagesScale;
+                if (pipelineOptions.pictureClassification !== undefined)
+                    nestedOpts.pictureClassification = pipelineOptions.pictureClassification;
+            }
+            // Use multipart upload for file sources (avoids base64 33% size overhead)
+            if (fileSources.length > 0 && apiSources.length === 0) {
+                const formData = new FormData();
+                for (const f of fileSources) {
+                    const buffer = await readFile(f.path);
+                    const blob = new Blob([buffer], { type: getMimeType(f.filename) });
+                    formData.append("files", blob, f.filename);
+                }
+                if (Object.keys(nestedOpts).length > 0) {
+                    formData.append("options", new Blob([JSON.stringify(nestedOpts)], { type: "application/json" }));
+                }
+                const { baseUrl, apiKey } = client._config;
+                const endpoint = isAsync ? "/v1/convert/file/async" : "/v1/convert/file";
+                const url = pipeline
+                    ? `${baseUrl}${endpoint}?pipeline=${encodeURIComponent(pipeline)}`
+                    : `${baseUrl}${endpoint}`;
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${apiKey}` },
+                    body: 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();
+                if (isAsync) {
+                    const taskId = data?.taskId;
+                    if (waitForCompletion && taskId) {
+                        const result = await waitForTask(client, taskId);
+                        return { content: formatConvertResponse(result) };
+                    }
+                    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+                }
+                return { content: formatConvertResponse(data) };
+            }
+            // Fall back to JSON body for url/base64 sources (or mixed)
+            // For mixed sources with files, base64-encode as before (rare case)
+            for (const f of fileSources) {
+                const fileBuffer = await readFile(f.path);
+                apiSources.push({ kind: "base64", content: fileBuffer.toString("base64"), filename: f.filename, mimeType: getMimeType(f.filename) });
+            }
+            const opts = {};
+            if (pipeline)
+                opts.pipeline = pipeline;
+            if (Object.keys(nestedOpts).length > 0)
+                opts.options = nestedOpts;
+            const body = {
+                sources: apiSources,
+                options: Object.keys(opts).length > 0 ? opts : undefined,
+            };
+            if (isAsync) {
+                const { data } = await client.POST("/v1/convert/source/async", { body });
+                const taskId = data?.taskId;
+                if (waitForCompletion && taskId) {
+                    const result = await waitForTask(client, taskId);
+                    return { content: formatConvertResponse(result) };
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+                };
+            }
+            const { data } = await client.POST("/v1/convert/source", { body });
+            return { content: formatConvertResponse(data) };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_task_status ─────────────────────────────────────────────────────
+    server.tool("2kw_get_task_status", "Check the status of an async conversion task. Supports long polling with the wait parameter.", {
+        taskId: z.string().describe("The async task ID returned by convert_document"),
+        wait: z
+            .number()
+            .optional()
+            .describe("Long-poll timeout in seconds (max 60)"),
+    }, async ({ taskId, wait }) => {
+        try {
+            const { data } = await client.GET("/v1/convert/tasks/{taskId}", {
+                params: {
+                    path: { taskId },
+                    query: { wait },
+                },
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_task_result ─────────────────────────────────────────────────────
+    server.tool("2kw_get_task_result", "Get the result of a completed async conversion task.", {
+        taskId: z.string().describe("The async task ID"),
+    }, async ({ taskId }) => {
+        try {
+            const { data } = await client.GET("/v1/convert/tasks/{taskId}/result", {
+                params: { path: { taskId } },
+            });
+            return { content: formatConvertResponse(data) };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=conversion.js.map

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