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

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("backbone_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("backbone_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/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,197 @@
+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";
+/**
+ * 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: `--- ${doc.filename} (markdown) ---\n${doc.mdContent}` });
+    if (doc.textContent)
+        parts.push({ type: "text", text: `--- ${doc.filename} (text) ---\n${doc.textContent}` });
+    if (doc.htmlContent)
+        parts.push({ type: "text", text: `--- ${doc.filename} (html) ---\n${doc.htmlContent}` });
+    if (doc.jsonContent)
+        parts.push({ type: "text", text: `--- ${doc.filename} (json) ---\n${JSON.stringify(doc.jsonContent, null, 2)}` });
+    return parts;
+}
+export function register(server, client) {
+    // ── convert_document ────────────────────────────────────────────────────
+    server.tool("backbone_convert_document", "Convert documents to Markdown, text, HTML, or JSON. Accepts URLs, base64 data, or local file paths. Local files are automatically read and base64-encoded. Use async mode for large documents.", {
+        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"),
+        outputFormats: z
+            .array(z.string())
+            .optional()
+            .describe("Output formats, e.g. ['markdown', 'text', 'html', 'json']"),
+        pageRange: z
+            .string()
+            .optional()
+            .describe("Page range to convert, e.g. '1-5'"),
+        pipeline: z
+            .string()
+            .optional()
+            .describe("Processing pipeline: 'standard' (default) or 'vlm' (vision language model for image-heavy documents)"),
+        async: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("If true, submit as async task and return task ID for polling"),
+    }, async ({ sources, outputFormats, pageRange, pipeline, async: isAsync }) => {
+        try {
+            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: "HttpSource", 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: "Base64Source", 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 fileBuffer = await readFile(filePath);
+                    const b64 = fileBuffer.toString("base64");
+                    const name = src.filename ?? basename(filePath);
+                    apiSources.push({ kind: "Base64Source", content: b64, filename: name, mimeType: getMimeType(name) });
+                }
+            }
+            const body = {
+                sources: apiSources,
+                options: {
+                    ...(outputFormats ? { toFormats: outputFormats.map(mapOutputFormat) } : {}),
+                    ...(pageRange ? { pageRange } : {}),
+                    ...(pipeline ? { pipeline } : {}),
+                },
+            };
+            if (isAsync) {
+                const { data } = await client.POST("/v1/convert/source/async", { body });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(data, null, 2),
+                        },
+                    ],
+                };
+            }
+            const { data } = await client.POST("/v1/convert/source", { body });
+            const convertResult = data;
+            const parts = [];
+            if (convertResult.documents?.length) {
+                for (const doc of convertResult.documents) {
+                    parts.push(...formatExportDocument(doc));
+                }
+            }
+            if (convertResult.errors?.length) {
+                parts.push({
+                    type: "text",
+                    text: `Errors:\n${convertResult.errors.map((e) => `- ${e.filename ?? "unknown"}: ${e.errorMessage}`).join("\n")}`,
+                });
+            }
+            if (parts.length === 0) {
+                parts.push({
+                    type: "text",
+                    text: `Conversion completed with status: ${convertResult.status}`,
+                });
+            }
+            return { content: parts };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_task_status ─────────────────────────────────────────────────────
+    server.tool("backbone_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("backbone_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 } },
+            });
+            const result = data;
+            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: `Task result status: ${result.status}`,
+                });
+            }
+            return { content: parts };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=conversion.js.map

package/dist/tools/docs.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, baseUrl: string, apiKey: string): void;
+//# sourceMappingURL=docs.d.ts.map

package/dist/tools/docs.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+/* eslint-enable @typescript-eslint/no-explicit-any */
+let specCache = null;
+async function fetchSpec(baseUrl, apiKey) {
+    if (specCache)
+        return specCache;
+    const specUrl = `${baseUrl.replace(/\/+$/, "")}/v3/api-docs`;
+    const res = await fetch(specUrl, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) {
+        if (res.status === 404 || res.status === 403) {
+            throw new Error("API documentation is not available. Enable it by setting SPRINGDOC_ENABLED=true on the backend.");
+        }
+        throw new Error(`Failed to fetch API docs: ${res.status} ${res.statusText}`);
+    }
+    specCache = await res.json();
+    return specCache;
+}
+/**
+ * Collect all $ref strings from an object tree.
+ */
+function collectRefs(obj, refs) {
+    if (obj === null || obj === undefined || typeof obj !== "object")
+        return;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            collectRefs(item, refs);
+        return;
+    }
+    const record = obj;
+    if (typeof record["$ref"] === "string") {
+        refs.add(record["$ref"]);
+    }
+    for (const value of Object.values(record)) {
+        collectRefs(value, refs);
+    }
+}
+/**
+ * Recursively resolve schema refs — the initial set plus any schemas they reference.
+ */
+function resolveSchemas(refPaths, allSchemas) {
+    const resolved = {};
+    const queue = [...refPaths];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const ref = queue.pop();
+        if (visited.has(ref))
+            continue;
+        visited.add(ref);
+        const prefix = "#/components/schemas/";
+        if (!ref.startsWith(prefix))
+            continue;
+        const name = ref.slice(prefix.length);
+        const schema = allSchemas[name];
+        if (!schema)
+            continue;
+        resolved[name] = schema;
+        // Find nested refs in this schema
+        const nested = new Set();
+        collectRefs(schema, nested);
+        for (const n of nested) {
+            if (!visited.has(n))
+                queue.push(n);
+        }
+    }
+    return resolved;
+}
+export function register(server, _client, baseUrl, apiKey) {
+    // ── list_api_doc_sections ───────────────────────────────────────────────
+    server.tool("backbone_list_api_doc_sections", "List available API documentation sections (tags) from the OpenAPI spec. Use this to discover which sections you can fetch detailed docs for.", {}, async () => {
+        try {
+            const spec = await fetchSpec(baseUrl, apiKey);
+            const tags = spec.tags ?? [];
+            const paths = spec.paths ?? {};
+            // Count endpoints per tag
+            const tagCounts = new Map();
+            for (const methods of Object.values(paths)) {
+                for (const operation of Object.values(methods)) {
+                    if (operation?.tags) {
+                        for (const tag of operation.tags) {
+                            tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+                        }
+                    }
+                }
+            }
+            const lines = tags.map((t) => {
+                const count = tagCounts.get(t.name) ?? 0;
+                const desc = t.description ? ` — ${t.description}` : "";
+                return `- ${t.name} (${count} endpoint${count !== 1 ? "s" : ""})${desc}`;
+            });
+            const info = spec.info ?? {};
+            const header = `${info.title ?? "API"} v${info.version ?? "?"}`;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${header}\n\nAvailable sections:\n${lines.join("\n") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+    // ── get_api_docs ────────────────────────────────────────────────────────
+    server.tool("backbone_get_api_docs", "Fetch API documentation for a specific section (tag). Returns the filtered endpoints and their referenced schemas. Use backbone_list_api_doc_sections first to see available tags.", {
+        tag: z.string().describe("The tag/section name to filter by (e.g. 'Projects', 'Extractions')"),
+    }, async ({ tag }) => {
+        try {
+            const spec = await fetchSpec(baseUrl, apiKey);
+            const allTags = spec.tags ?? [];
+            const tagNames = allTags.map((t) => t.name);
+            if (!tagNames.includes(tag)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Tag "${tag}" not found. Available tags: ${tagNames.join(", ")}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const allPaths = spec.paths ?? {};
+            const allSchemas = spec.components?.schemas ?? {};
+            // Filter paths to only operations matching the requested tag
+            const filteredPaths = {};
+            const refs = new Set();
+            for (const [path, methods] of Object.entries(allPaths)) {
+                const filteredMethods = {};
+                for (const [method, operation] of Object.entries(methods)) {
+                    const op = operation;
+                    if (op?.tags?.includes(tag)) {
+                        filteredMethods[method] = operation;
+                        collectRefs(operation, refs);
+                    }
+                }
+                if (Object.keys(filteredMethods).length > 0) {
+                    filteredPaths[path] = filteredMethods;
+                }
+            }
+            // Resolve referenced schemas (including transitive refs)
+            const referencedSchemas = resolveSchemas(refs, allSchemas);
+            const result = {
+                paths: filteredPaths,
+                schemas: referencedSchemas,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=docs.js.map

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