@manfred-kunze-dev/backbone-mcp-server 2.6.0-dev.4

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,311 @@
+# Backbone MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes the Backbone AI platform as tools for LLMs. It lets AI assistants manage projects, define schemas, run extractions, convert documents, transcribe audio, and more — all through a standardized tool interface.
+
+## Setup
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0
+- **Backbone backend** running and accessible (local or remote)
+- A valid **API key** for the Backbone backend
+
+### Install Dependencies
+
+```bash
+cd mcp
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+This compiles TypeScript from `src/` into `dist/`.
+
+### 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 the Backbone backend including the API prefix. Override for local development (e.g. `http://localhost:8080/api`) |
+| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
+| `MCP_HTTP_PORT` | No | `3100` | Port for the HTTP transport (only used when `MCP_TRANSPORT=http`) |
+
+### Running the Server
+
+**Stdio transport** (default — for use with Claude Code, Cursor, etc.):
+
+```bash
+BACKBONE_API_KEY=your-key BACKBONE_BASE_URL=http://localhost:8080/api npm start
+```
+
+**HTTP transport** (for network-accessible deployments):
+
+```bash
+BACKBONE_API_KEY=your-key BACKBONE_BASE_URL=http://localhost:8080/api MCP_TRANSPORT=http npm start
+```
+
+The HTTP server exposes:
+- `POST /mcp` — MCP Streamable HTTP endpoint
+- `GET /health` — Health check
+
+**Development mode** (auto-recompile on changes):
+
+```bash
+npm run dev
+```
+
+### Connecting to Claude Code
+
+Add the server to your Claude Code MCP configuration (`.claude/settings.local.json` or similar):
+
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "your-api-key",
+        "BACKBONE_BASE_URL": "http://localhost:8080/api"
+      }
+    }
+  }
+}
+```
+
+### Connecting to Cursor
+
+Add to your `.cursor/mcp.json`:
+u
+```json
+{
+  "mcpServers": {
+    "backbone": {
+      "command": "npx",
+      "args": ["@manfred-kunze-dev/backbone-mcp-server"],
+      "env": {
+        "BACKBONE_API_KEY": "your-api-key",
+        "BACKBONE_BASE_URL": "http://localhost:8080/api"
+      }
+    }
+  }
+}
+```
+
+> **Installing from the GitLab registry:** Configure npm to use the GitLab registry for the `@manfred-kunze-dev` scope by adding this to your `.npmrc`:
+> ```
+> @manfred-kunze-dev:registry=https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/
+> //gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/:_authToken=<YOUR_TOKEN>
+> ```
+
+---
+
+## Available Tools
+
+### Projects
+
+Manage projects within your organization.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_list_projects` | List projects with optional search and pagination | `search?`, `page?`, `size?`, `sort?` |
+| `backbone_get_project` | Get a project by ID | `projectId` |
+| `backbone_create_project` | Create a new project | `name`, `description?` |
+| `backbone_update_project` | Update a project | `projectId`, `name?`, `description?` |
+| `backbone_delete_project` | Delete a project and all its data (irreversible) | `projectId` |
+
+### Schemas
+
+Define extraction schemas within projects. Schemas describe the structure of data to extract.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_list_schemas` | List schemas in a project | `projectId`, `search?`, `page?`, `size?`, `sort?` |
+| `backbone_get_schema` | Get a schema by ID | `projectId`, `schemaId` |
+| `backbone_create_schema` | Create a new schema | `projectId`, `name`, `description?`, `content?` |
+| `backbone_update_schema` | Update a schema | `projectId`, `schemaId`, `name?`, `description?`, `content?` |
+| `backbone_delete_schema` | Delete a schema and all its versions (irreversible) | `projectId`, `schemaId` |
+
+### Schema Versions
+
+Manage versioned snapshots of schema definitions.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_create_schema_version` | Create a new version (becomes active) | `projectId`, `schemaId`, `jsonSchema`, `changeDescription?` |
+| `backbone_list_schema_versions` | List all versions of a schema | `projectId`, `schemaId`, `page?`, `size?` |
+| `backbone_get_schema_version` | Get a specific version | `projectId`, `schemaId`, `versionId` |
+| `backbone_get_latest_schema_version` | Get the latest active version | `projectId`, `schemaId` |
+| `backbone_activate_schema_version` | Re-activate a historical version | `projectId`, `schemaId`, `versionId` |
+
+### Schema Testing
+
+Validate schemas and test extractions without persisting data.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_validate_schema` | Validate a JSON Schema definition | `projectId`, `schemaId`, `jsonSchema` |
+| `backbone_test_schema` | Test a schema against sample text with AI extraction | `projectId`, `schemaId`, `jsonSchema`, `sampleText`, `model` |
+
+### Extractions
+
+Extract structured data from text using schemas and AI models.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_create_extraction` | Extract data from text (sync or async) | `projectId`, `schemaId`, `inputText`, `model`, `schemaVersionId?`, `async?` |
+| `backbone_get_extraction` | Get an extraction by ID (check status or retrieve results) | `projectId`, `extractionId` |
+| `backbone_list_extractions` | List extractions with filtering | `projectId`, `status?`, `schemaVersionId?`, `search?`, `page?`, `size?`, `sort?` |
+| `backbone_estimate_tokens` | Estimate token usage without executing | `projectId`, `schemaId`, `inputText`, `schemaVersionId?` |
+| `backbone_rerun_extraction` | Re-run an existing extraction | `projectId`, `extractionId` |
+
+### Document Conversion
+
+Convert documents (PDF, DOCX, etc.) to Markdown, text, HTML, or JSON.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_convert_document` | Convert documents from URLs, base64, or local files | `sources[]` (type, url/data/path, filename), `outputFormats?`, `pageRange?`, `async?` |
+| `backbone_get_task_status` | Check status of an async conversion task | `taskId`, `wait?` |
+| `backbone_get_task_result` | Get the result of a completed conversion | `taskId` |
+
+Each source in `sources` can be:
+- **`url`** — fetch from a URL
+- **`base64`** — provide raw base64 data with a filename
+- **`file`** — provide a local file path (automatically read and encoded)
+
+### Audio Transcription
+
+Transcribe audio files using AI models.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_transcribe_audio` | Transcribe an audio file | `filePath`, `model`, `language?`, `prompt?`, `responseFormat?`, `temperature?` |
+
+Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.
+
+### AI Gateway
+
+Access multiple AI providers through a unified OpenAI-compatible interface.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_chat` | Send a chat completion request | `model`, `messages[]`, `temperature?`, `max_tokens?`, `top_p?`, `frequency_penalty?`, `presence_penalty?`, `stop?`, `response_format?`, `tools?`, `tool_choice?` |
+| `backbone_list_models` | List available AI models and providers | *(none)* |
+
+Models use the format `provider/model` (e.g. `openai/gpt-4o`, `anthropic/claude-sonnet-4-5-20250929`).
+
+### API Documentation
+
+Browse the backend's OpenAPI documentation by section. Useful for understanding endpoint details, request/response shapes, and parameter constraints.
+
+| Tool | Description | Parameters |
+|---|---|---|
+| `backbone_list_api_doc_sections` | List available doc sections (tags) with endpoint counts | *(none)* |
+| `backbone_get_api_docs` | Fetch filtered docs for a specific section | `tag` |
+
+> **Note:** Requires `SPRINGDOC_ENABLED=true` on the backend. If docs are disabled, these tools return an informative error message.
+
+The `get_api_docs` tool returns only the endpoints and schemas relevant to the requested tag, keeping context usage minimal. The OpenAPI spec is cached in memory after the first fetch.
+
+---
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Dev mode (watch + auto-recompile)
+npm run dev
+
+# Start
+npm start
+
+# Type-check without emitting
+npm run typecheck
+
+# Debug with MCP Inspector
+npm run inspect
+```
+
+### OpenAPI Type Generation
+
+Types are generated from the backend's OpenAPI spec using `openapi-typescript`. This ensures that all API calls are type-checked at compile time — if the backend renames a field, the MCP server won't compile until updated.
+
+**Prerequisites:**
+- A running Backbone backend at `http://localhost:8080` (or pass a custom URL as argument)
+- `BACKBONE_API_KEY` set — either in a `.env` file or as an environment variable
+
+```bash
+# Set up your .env (one-time)
+cp .env.example .env
+# Then edit .env with your API key
+
+# Full pipeline: fetch spec from backend + generate TypeScript types
+npm run generate
+
+# Individual steps:
+npm run generate:spec    # Fetch spec → openapi/openapi.json
+npm run generate:types   # Generate types → src/generated/openapi.d.ts
+
+# CI drift check: compare committed spec against live backend
+npm run check:spec
+```
+
+> **Note:** `generate:types` does not need the API key — it reads from the committed `openapi/openapi.json` file. The `.env` file is loaded automatically by the `generate:spec` and `check:spec` scripts.
+
+**When to regenerate:**
+- After any backend API change (new endpoints, renamed fields, changed DTOs)
+- The `check:spec` script can be used in CI to detect stale types automatically
+
+**How it works:**
+
+1. `generate:spec` — Fetches the OpenAPI spec from the backend's `/v3/api-docs` endpoint and saves it to `openapi/openapi.json`
+2. `generate:types` — Runs `openapi-typescript` to convert `openapi.json` into TypeScript type definitions at `src/generated/openapi.d.ts`
+3. `check:spec` — CI guard that compares the committed `openapi.json` against the live backend. Exits non-zero if they differ.
+
+Both `mcp/` and `cli/` share the same backend spec and generated types.
+
+### Project Structure
+
+```
+mcp/
+├── openapi/
+│   ├── openapi.json             # Committed OpenAPI spec (generated)
+│   └── scripts/
+│       ├── fetch-spec.ts        # Downloads spec from running backend
+│       └── check-drift.ts       # CI guard for spec drift detection
+├── src/
+│   ├── index.ts                 # Entry point, transport setup, tool registration
+│   ├── client.ts                # openapi-fetch client factory with error middleware
+│   ├── errors.ts                # Error types and MCP error formatting
+│   ├── mime.ts                  # MIME type detection for file uploads
+│   ├── schema-compat.ts         # OpenAI-compatible schema enforcement
+│   ├── generated/
+│   │   └── openapi.d.ts         # Auto-generated TypeScript types (do not edit)
+│   └── tools/
+│       ├── ai-gateway.ts        # Chat completions & model listing
+│       ├── conversion.ts        # Document conversion
+│       ├── docs.ts              # API documentation browsing
+│       ├── extraction.ts        # Data extraction
+│       ├── projects.ts          # Project CRUD
+│       ├── schema-testing.ts    # Schema validation & testing
+│       ├── schema-versions.ts   # Schema version management
+│       ├── schemas.ts           # Schema CRUD
+│       └── transcription.ts     # Audio transcription
+├── dist/                        # Compiled output (generated)
+├── package.json
+└── tsconfig.json
+```
+
+### Adding New Tools
+
+1. Create a new file in `src/tools/` following the existing pattern
+2. Export a `register(server: McpServer, client: ApiClient): void` function
+3. Import and call `register()` in `src/index.ts`
+4. Rebuild with `npm run build`

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+import createClient from "openapi-fetch";
+import type { paths } from "./generated/openapi.js";
+export type ApiClient = ReturnType<typeof createClient<paths>>;
+/**
+ * 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,38 @@
+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(body);
+    },
+};
+/**
+ * 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);
+    return client;
+}
+//# 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,75 @@
+#!/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 projects from "./tools/projects.js";
+import * as schemas from "./tools/schemas.js";
+import * as schemaVersions from "./tools/schema-versions.js";
+import * as schemaTesting from "./tools/schema-testing.js";
+import * as docs from "./tools/docs.js";
+function requiredEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        console.error(`Missing required environment variable: ${name}`);
+        process.exit(1);
+    }
+    return value;
+}
+async function main() {
+    const apiKey = requiredEnv("BACKBONE_API_KEY");
+    const baseUrl = process.env.BACKBONE_BASE_URL ?? "https://backbone.manfred-kunze.dev/api";
+    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);
+    projects.register(server, client);
+    schemas.register(server, client);
+    schemaVersions.register(server, client);
+    schemaTesting.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,53 @@
+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",
+    // 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