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

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025-present Manfred Kunze Dev
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of the Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+the copyright holder.
+
+The Software is provided "as is", without warranty of any kind, express or implied,
+including but not limited to the warranties of merchantability, fitness for a
+particular purpose, and noninfringement. In no event shall the authors or copyright
+holders be liable for any claim, damages, or other liability, whether in an action
+of contract, tort, or otherwise, arising from, out of, or in connection with the
+Software or the use or other dealings in the Software.
+
+Usage of this Software is permitted only in accordance with the terms and conditions
+set forth by Manfred Kunze Dev.

package/README.md

@@ -0,0 +1,123 @@
+# Backbone MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI coding assistants direct access to the [Backbone AI](https://backbone.manfred-kunze.dev) platform — manage schemas, run extractions, convert documents, and more from your IDE.
+
+## Installation
+
+```bash
+npm install -g @manfred-kunze-dev/backbone-mcp-server
+```
+
+Or run directly with `npx` (no install needed):
+
+```bash
+npx @manfred-kunze-dev/backbone-mcp-server
+```
+
+## Quick Start
+
+1. Create an API key in the Backbone dashboard under **API Keys**
+2. Add the server to your IDE's MCP configuration (see below)
+3. Start asking your AI assistant to manage your Backbone resources
+
+## IDE Configuration
+
+### Claude Code
+
+Add to `.claude/settings.local.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `.windsurf/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "sk_your_api_key"
+      }
+    }
+  }
+}
+```
+
+Works with any MCP-compatible client using the same configuration pattern.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BACKBONE_API_KEY` | Yes | — | API key for authenticating with the Backbone backend |
+| `BACKBONE_BASE_URL` | No | `https://backbone.manfred-kunze.dev/api` | Base URL of your Backbone instance |
+| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_HTTP_PORT` | No | `3100` | Port for HTTP transport |
+
+## Available Tools
+
+| Category | Tools |
+|----------|-------|
+| **Schemas** | CRUD operations, version management, validation, testing |
+| **Extractions** | Create extractions (sync/async), estimate tokens, re-run |
+| **Document Conversion** | Convert PDFs, DOCX, images to Markdown/text/HTML/JSON |
+| **Transcription** | Transcribe audio files (flac, mp3, mp4, ogg, wav, webm) |
+| **AI Gateway** | Chat completions, list available models |
+| **API Docs** | Browse API documentation by section |
+
+For full tool documentation, see the [Backbone docs](https://backbone.manfred-kunze.dev).
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE) for details.

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import createClient from "openapi-fetch";
+import type { paths } from "./generated/openapi.js";
+export type ApiClient = ReturnType<typeof createClient<paths>> & {
+    /** Exposed config for raw fetch calls (e.g. multipart uploads). */
+    _config: {
+        baseUrl: string;
+        apiKey: string;
+    };
+};
+/**
+ * Create a typed openapi-fetch client with Bearer auth and error middleware.
+ */
+export declare function createApiClient(baseUrl: string, apiKey: string): ApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,46 @@
+import createClient from "openapi-fetch";
+import { BackboneApiError } from "./errors.js";
+/**
+ * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ */
+const errorMiddleware = {
+    async onResponse({ response }) {
+        if (response.ok)
+            return undefined;
+        let body;
+        try {
+            body = await response.clone().json();
+        }
+        catch {
+            body = {
+                error: response.statusText,
+                message: `HTTP ${response.status}: ${response.statusText}`,
+                status: response.status,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        throw new BackboneApiError({
+            status: body.status ?? response.status,
+            error: body.title ?? body.error ?? response.statusText,
+            message: body.detail ?? body.message ?? `HTTP ${response.status}: ${response.statusText}`,
+            timestamp: body.timestamp ?? new Date().toISOString(),
+        });
+    },
+};
+/**
+ * Create a typed openapi-fetch client with Bearer auth and error middleware.
+ */
+export function createApiClient(baseUrl, apiKey) {
+    const client = createClient({
+        baseUrl: baseUrl.replace(/\/+$/, ""),
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    client.use(errorMiddleware);
+    // Expose config for raw fetch calls (multipart uploads)
+    const enriched = client;
+    enriched._config = { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };
+    return enriched;
+}
+//# sourceMappingURL=client.js.map

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+interface ApiErrorBody {
+    error: string;
+    message: string;
+    status: number;
+    timestamp: string;
+}
+export declare class BackboneApiError extends Error {
+    readonly status: number;
+    readonly errorType: string;
+    readonly timestamp: string;
+    constructor(apiError: ApiErrorBody);
+}
+export declare function formatErrorForMcp(error: unknown): string;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,22 @@
+export class BackboneApiError extends Error {
+    status;
+    errorType;
+    timestamp;
+    constructor(apiError) {
+        super(apiError.message);
+        this.name = "BackboneApiError";
+        this.status = apiError.status;
+        this.errorType = apiError.error;
+        this.timestamp = apiError.timestamp;
+    }
+}
+export function formatErrorForMcp(error) {
+    if (error instanceof BackboneApiError) {
+        return `API Error (${error.status}): ${error.message}`;
+    }
+    if (error instanceof Error) {
+        return `Error: ${error.message}`;
+    }
+    return `Unknown error: ${String(error)}`;
+}
+//# sourceMappingURL=errors.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createServer } from "node:http";
+import { createApiClient } from "./client.js";
+import * as conversion from "./tools/conversion.js";
+import * as extraction from "./tools/extraction.js";
+import * as aiGateway from "./tools/ai-gateway.js";
+import * as transcription from "./tools/transcription.js";
+import * as schemas from "./tools/schemas.js";
+import * as schemaLabels from "./tools/schema-labels.js";
+import * as schemaVersions from "./tools/schema-versions.js";
+import * as schemaTesting from "./tools/schema-testing.js";
+import * as datasets from "./tools/datasets.js";
+import * as experiments from "./tools/experiments.js";
+import * as evaluators from "./tools/evaluators.js";
+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 tracing from "./tools/tracing.js";
+import * as analytics from "./tools/analytics.js";
+import * as docs from "./tools/docs.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.
+let legacyEnvWarned = false;
+function readEnv(canonical, legacy) {
+    const v = process.env[canonical];
+    if (v)
+        return v;
+    const legacyV = process.env[legacy];
+    if (legacyV) {
+        if (!legacyEnvWarned) {
+            legacyEnvWarned = true;
+            console.error(`[deprecation] ${legacy} is read for backwards compatibility. ` +
+                `Switch to ${canonical} — the BACKBONE_* names will be removed ` +
+                `in a future release.`);
+        }
+        return legacyV;
+    }
+    return undefined;
+}
+function requireEnv(canonical, legacy) {
+    const v = readEnv(canonical, legacy);
+    if (!v) {
+        console.error(`Missing required environment variable: ${canonical} (legacy: ${legacy})`);
+        process.exit(1);
+    }
+    return v;
+}
+const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
+    process.env.BACKBONE_DEFAULT_BASE_URL ??
+    "https://backbone.manfred-kunze.dev/api";
+async function main() {
+    const apiKey = requireEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY");
+    const baseUrl = readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL") ?? DEFAULT_BASE_URL;
+    const transport = process.env.MCP_TRANSPORT ?? "stdio";
+    const httpPort = parseInt(process.env.MCP_HTTP_PORT ?? "3100", 10);
+    const client = createApiClient(baseUrl, apiKey);
+    const server = new McpServer({
+        name: "backbone",
+        version: "1.0.0",
+    });
+    // Register all tool groups
+    conversion.register(server, client);
+    extraction.register(server, client);
+    aiGateway.register(server, client);
+    transcription.register(server, client);
+    schemas.register(server, client);
+    schemaLabels.register(server, client);
+    schemaVersions.register(server, client);
+    schemaTesting.register(server, client);
+    datasets.register(server, client);
+    experiments.register(server, client);
+    evaluators.register(server, client);
+    prompts.register(server, client);
+    providers.register(server, client);
+    billing.register(server, client);
+    scores.register(server, client);
+    tracing.register(server, client);
+    analytics.register(server, client);
+    docs.register(server, client, baseUrl, apiKey);
+    if (transport === "http") {
+        const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        const httpServer = createServer(async (req, res) => {
+            const url = new URL(req.url ?? "/", `http://localhost:${httpPort}`);
+            if (url.pathname === "/mcp") {
+                await httpTransport.handleRequest(req, res);
+            }
+            else if (url.pathname === "/health") {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ status: "ok" }));
+            }
+            else {
+                res.writeHead(404);
+                res.end("Not found");
+            }
+        });
+        await server.connect(httpTransport);
+        httpServer.listen(httpPort, () => {
+            console.error(`Backbone MCP server listening on http://localhost:${httpPort}/mcp`);
+        });
+    }
+    else {
+        const stdioTransport = new StdioServerTransport();
+        await server.connect(stdioTransport);
+        console.error("Backbone MCP server running on stdio");
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/mime.d.ts

@@ -0,0 +1,2 @@
+export declare function getMimeType(filename: string): string;
+//# sourceMappingURL=mime.d.ts.map

package/dist/mime.js

@@ -0,0 +1,56 @@
+const MIME_TYPES = {
+    // Documents
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".odt": "application/vnd.oasis.opendocument.text",
+    ".ods": "application/vnd.oasis.opendocument.spreadsheet",
+    ".odp": "application/vnd.oasis.opendocument.presentation",
+    ".rtf": "application/rtf",
+    ".csv": "text/csv",
+    ".tsv": "text/tab-separated-values",
+    // Text
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".xml": "application/xml",
+    ".json": "application/json",
+    ".yaml": "application/x-yaml",
+    ".yml": "application/x-yaml",
+    // Images
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".bmp": "image/bmp",
+    ".tiff": "image/tiff",
+    ".tif": "image/tiff",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    // CAD
+    ".dxf": "image/vnd.dxf",
+    ".geo": "application/vnd.trumpf.geo",
+    // Email
+    ".eml": "message/rfc822",
+    ".msg": "application/vnd.ms-outlook",
+    // Audio
+    ".flac": "audio/flac",
+    ".mp3": "audio/mpeg",
+    ".mp4": "audio/mp4",
+    ".mpeg": "audio/mpeg",
+    ".mpga": "audio/mpeg",
+    ".m4a": "audio/mp4",
+    ".ogg": "audio/ogg",
+    ".wav": "audio/wav",
+    ".webm": "audio/webm",
+};
+export function getMimeType(filename) {
+    const ext = filename.slice(filename.lastIndexOf(".")).toLowerCase();
+    return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+//# sourceMappingURL=mime.js.map

package/dist/schema-compat.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Sanitize a JSON Schema to be compatible with OpenAI's structured output requirements.
+ *
+ * OpenAI requires:
+ * - Every object type must have `additionalProperties: false`
+ * - Every object must list all properties in `required`
+ *
+ * This function recursively walks the schema and applies these constraints.
+ */
+export declare function ensureOpenAiCompatible(schema: unknown): unknown;
+//# sourceMappingURL=schema-compat.d.ts.map

package/dist/schema-compat.js

@@ -0,0 +1,51 @@
+/**
+ * Sanitize a JSON Schema to be compatible with OpenAI's structured output requirements.
+ *
+ * OpenAI requires:
+ * - Every object type must have `additionalProperties: false`
+ * - Every object must list all properties in `required`
+ *
+ * This function recursively walks the schema and applies these constraints.
+ */
+export function ensureOpenAiCompatible(schema) {
+    if (schema === null || schema === undefined || typeof schema !== "object") {
+        return schema;
+    }
+    if (Array.isArray(schema)) {
+        return schema.map(ensureOpenAiCompatible);
+    }
+    const obj = schema;
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === "properties" && typeof value === "object" && value !== null) {
+            // Recurse into each property definition
+            const props = {};
+            for (const [propName, propValue] of Object.entries(value)) {
+                props[propName] = ensureOpenAiCompatible(propValue);
+            }
+            result[key] = props;
+        }
+        else if (key === "items") {
+            // Recurse into array items
+            result[key] = ensureOpenAiCompatible(value);
+        }
+        else if (key === "anyOf" || key === "oneOf" || key === "allOf") {
+            // Recurse into combinators
+            result[key] = Array.isArray(value) ? value.map(ensureOpenAiCompatible) : value;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    // If this node is an object type with properties, enforce OpenAI constraints
+    if (obj.type === "object" && obj.properties && typeof obj.properties === "object") {
+        result.additionalProperties = false;
+        // Ensure all properties are in required
+        const propNames = Object.keys(obj.properties);
+        const existing = Array.isArray(obj.required) ? obj.required : [];
+        const merged = [...new Set([...existing, ...propNames])];
+        result.required = merged;
+    }
+    return result;
+}
+//# sourceMappingURL=schema-compat.js.map

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

package/dist/tools/ai-gateway.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+export function register(server, client) {
+    // ── chat ────────────────────────────────────────────────────────────────
+    server.tool("2kw_chat", "Send a chat completion request through Backbone's OpenAI-compatible AI gateway. Supports multiple providers (OpenAI, Anthropic, Azure, Vertex AI, etc.). Model format: 'provider/model' (e.g. 'openai/gpt-4o', 'anthropic/claude-sonnet-4-5-20250929'). Always non-streaming.", {
+        model: z.string().describe("Model identifier in 'provider/model' format"),
+        messages: z
+            .array(z.object({
+            role: z.enum(["system", "user", "assistant", "tool"]),
+            content: z.string().nullable(),
+            name: z.string().optional(),
+            tool_call_id: z.string().optional(),
+        }))
+            .describe("Chat messages array"),
+        temperature: z.number().min(0).max(2).optional().describe("Sampling temperature (0-2)"),
+        max_tokens: z.number().optional().describe("Maximum tokens to generate"),
+        top_p: z.number().optional().describe("Top-p (nucleus) sampling"),
+        frequency_penalty: z.number().optional(),
+        presence_penalty: z.number().optional(),
+        stop: z.array(z.string()).optional().describe("Stop sequences"),
+        response_format: z
+            .object({ type: z.enum(["text", "json_object"]) })
+            .optional()
+            .describe("Response format constraint"),
+        tools: z.array(z.unknown()).optional().describe("Tool definitions for function calling"),
+        tool_choice: z.unknown().optional().describe("Tool choice: 'auto', 'none', 'required', or object"),
+    }, async (params) => {
+        try {
+            // Build the spec-compliant body, then add non-spec OpenAI-compatible fields
+            const body = {
+                model: params.model,
+                messages: params.messages,
+                stream: false,
+                ...(params.temperature !== undefined && { temperature: params.temperature }),
+                ...(params.max_tokens !== undefined && { max_tokens: params.max_tokens }),
+                ...(params.top_p !== undefined && { top_p: params.top_p }),
+                ...(params.frequency_penalty !== undefined && {
+                    frequency_penalty: params.frequency_penalty,
+                }),
+                ...(params.presence_penalty !== undefined && {
+                    presence_penalty: params.presence_penalty,
+                }),
+                ...(params.stop && { stop: params.stop }),
+                ...(params.response_format && { response_format: params.response_format }),
+                ...(params.tools && { tools: params.tools }),
+                ...(params.tool_choice !== undefined && { tool_choice: params.tool_choice }),
+            };
+            const { data } = await client.POST("/v1/chat/completions", {
+                body: body,
+            });
+            const result = data;
+            const parts = [];
+            const choices = result.choices;
+            if (choices) {
+                for (const choice of choices) {
+                    const msg = choice.message;
+                    if (msg.content) {
+                        parts.push({ type: "text", text: msg.content });
+                    }
+                    if (msg.tool_calls?.length) {
+                        parts.push({
+                            type: "text",
+                            text: `Tool calls:\n${JSON.stringify(msg.tool_calls, null, 2)}`,
+                        });
+                    }
+                }
+            }
+            const usage = result.usage;
+            if (usage) {
+                parts.push({
+                    type: "text",
+                    text: `\n[Usage: ${usage.prompt_tokens} prompt + ${usage.completion_tokens} completion = ${usage.total_tokens} total tokens]`,
+                });
+            }
+            return { content: parts };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── list_models ─────────────────────────────────────────────────────────
+    server.tool("2kw_list_models", "List available AI models and providers accessible through the Backbone AI gateway.", {}, async () => {
+        try {
+            const { data } = await client.GET("/v1/models");
+            const result = data;
+            const lines = (result.data ?? []).map((m) => `${m.id} (${m.owned_by})`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Available models:\n${lines.join("\n")}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=ai-gateway.js.map

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