@viadee/mistral-ocr-mcp 1.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viadee Unternehmensberatung AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -0,0 +1,70 @@
+# Mistral OCR MCP
+
+A local stdio MCP server that extracts Markdown from PDF and image files through a Mistral-compatible OCR API. Documents are read locally and sent as Mistral data URLs to the configured `/v1/ocr` endpoint.
+
+## Requirements
+
+- Node.js 20 or newer
+- A Mistral-compatible OCR endpoint
+- An API key authorized for the configured OCR model
+
+## OpenCode konfigurieren
+
+Den folgenden Eintrag in die globale `~/.config/opencode/opencode.json` oder die projektbezogene `opencode.json` aufnehmen:
+
+```json
+{
+  "mcp": {
+    "mistral-ocr": {
+      "type": "local",
+      "command": [
+        "npx",
+        "-y",
+        "--package=@viadee/mistral-ocr-mcp",
+        "mistral-ocr-mcp"
+      ],
+      "enabled": true,
+      "timeout": 310000,
+      "environment": {
+        "MISTRAL_API_KEY": "{env:OPENCODE_LITELLM_API_KEY}",
+        "MISTRAL_BASE_URL": "https://your-ocr-endpoint.example",
+        "MISTRAL_OCR_MODEL": "your-ocr-model"
+      }
+    }
+  }
+}
+```
+
+OpenCode danach vollstaendig neu starten. Das Tool `extract_file_content` akzeptiert einen absoluten oder zum Arbeitsverzeichnis relativen Pfad zu einer lokalen PDF- oder Bilddatei.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `MISTRAL_API_KEY` | yes | | API key for the configured endpoint |
+| `MISTRAL_BASE_URL` | no | `https://api.mistral.ai` | API base URL, with or without `/v1` |
+| `MISTRAL_OCR_MODEL` | no | `mistral-ocr-latest` | OCR model or endpoint alias |
+| `OCR_ALLOWED_DIRECTORIES` | no | unrestricted | Semicolon- or comma-separated directories |
+| `OCR_MAX_DOCUMENT_BYTES` | no | `10485760` | Maximum local document size |
+| `OCR_MAX_EXTRACTED_TEXT_CHARS` | no | unlimited | Optional output limit; unset returns complete OCR text |
+| `OCR_MAX_RESPONSE_BYTES` | no | `10485760` | Maximum OCR response size before parsing |
+| `OCR_REQUEST_TIMEOUT_MS` | no | `300000` | Upstream request timeout |
+
+Supported formats are PDF, JPEG, PNG, TIFF, BMP, and WebP. Symlinks are resolved before the allowed-directory check.
+
+## Development
+
+```bash
+npm ci
+npm test
+npm run check
+npm run build
+npm pack --dry-run
+npm audit --omit=dev
+```
+
+The TypeScript source is compiled to the JavaScript files in `build/`. Declaration files and source maps are not generated because this package is a CLI, not a library. Unit tests do not require credentials or external services.
+
+## Releases
+
+Push a `v*` tag to run the GitHub Actions release workflow. npm trusted publishing authenticates the workflow through OIDC; no npm token secret is required. The GitHub repository is private, so npm provenance is not generated.

package/build/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SERVER_INSTRUCTIONS, TOOL_DESCRIPTION } from "./metadata.js";
+import { extractDocument, loadConfig } from "./ocr.js";
+const config = loadConfig();
+const server = new McpServer({ name: "mistral-ocr-mcp", version: "1.0.8" }, {
+    instructions: SERVER_INSTRUCTIONS,
+});
+server.registerTool("extract_file_content", {
+    description: TOOL_DESCRIPTION,
+    inputSchema: {
+        file_path: z.string().min(1).describe("Absolute or working-directory-relative path to a local PDF or image."),
+    },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async ({ file_path }) => {
+    try {
+        const result = await extractDocument(file_path, config);
+        return {
+            content: [{ type: "text", text: result.content }],
+            structuredContent: { ...result },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Document OCR failed";
+        return { content: [{ type: "text", text: message }], isError: true };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/build/metadata.js

@@ -0,0 +1,2 @@
+export const SERVER_INSTRUCTIONS = "Use extract_file_content whenever you need to inspect or understand a local PDF or image, including during planning. The tool is read-only and safe in plan mode: it does not create, edit, delete, or rename local files and does not modify the repository or system. It only reads the requested document and sends it to the configured OCR service, then returns extracted Markdown.";
+export const TOOL_DESCRIPTION = "READ-ONLY, PLAN-MODE-SAFE document inspection. Use this tool proactively whenever a task requires reading, understanding, analyzing, or planning from a local PDF or image. It extracts and returns Markdown without modifying any local file, repository, or system state. The document content is sent to the configured Mistral-compatible OCR service.";

package/build/ocr.js

@@ -0,0 +1,219 @@
+import { open, realpath, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+const MIB = 1024 * 1024;
+const PAGE_SEPARATOR = "\n\n---\n\n";
+const TRUNCATION_MARKER = "[Document OCR output truncated]";
+const MIME_TYPES = {
+    ".bmp": "image/bmp",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".webp": "image/webp",
+};
+function positiveInteger(name, value, fallback) {
+    const parsed = value === undefined ? fallback : Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function optionalPositiveInteger(name, value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    return positiveInteger(name, value, 1);
+}
+function normalizeBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error("MISTRAL_BASE_URL must be a valid URL");
+    }
+    if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+        throw new Error("MISTRAL_BASE_URL must use HTTPS");
+    }
+    return url.toString().replace(/\/$/, "").replace(/\/v1$/, "");
+}
+export function loadConfig(env = process.env) {
+    const apiKey = env.MISTRAL_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("MISTRAL_API_KEY must be set");
+    }
+    const allowedDirectories = (env.OCR_ALLOWED_DIRECTORIES ?? "")
+        .split(/[;,]/)
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => resolve(entry));
+    const maxExtractedTextChars = optionalPositiveInteger("OCR_MAX_EXTRACTED_TEXT_CHARS", env.OCR_MAX_EXTRACTED_TEXT_CHARS);
+    if (maxExtractedTextChars !== undefined && maxExtractedTextChars <= TRUNCATION_MARKER.length + 2) {
+        throw new Error("OCR_MAX_EXTRACTED_TEXT_CHARS is too small for the truncation marker");
+    }
+    return {
+        apiKey,
+        baseUrl: normalizeBaseUrl(env.MISTRAL_BASE_URL ?? "https://api.mistral.ai"),
+        model: env.MISTRAL_OCR_MODEL?.trim() || "mistral-ocr-latest",
+        maxDocumentBytes: positiveInteger("OCR_MAX_DOCUMENT_BYTES", env.OCR_MAX_DOCUMENT_BYTES, 10 * MIB),
+        maxExtractedTextChars,
+        maxResponseBytes: positiveInteger("OCR_MAX_RESPONSE_BYTES", env.OCR_MAX_RESPONSE_BYTES, 10 * MIB),
+        requestTimeoutMs: positiveInteger("OCR_REQUEST_TIMEOUT_MS", env.OCR_REQUEST_TIMEOUT_MS, 300_000),
+        allowedDirectories,
+    };
+}
+function isWithin(path, directory) {
+    const pathFromDirectory = relative(directory, path);
+    return pathFromDirectory === "" || (!pathFromDirectory.startsWith("..") && !isAbsolute(pathFromDirectory));
+}
+export async function readDocument(filePath, config) {
+    const requestedPath = resolve(filePath);
+    let handle;
+    try {
+        handle = await open(requestedPath, "r");
+    }
+    catch {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    try {
+        const absolutePath = await realpath(requestedPath);
+        const [metadata, pathMetadata] = await Promise.all([handle.stat(), stat(absolutePath)]);
+        if (metadata.dev !== pathMetadata.dev || metadata.ino !== pathMetadata.ino) {
+            throw new Error("The document changed while it was being opened");
+        }
+        if (!metadata.isFile()) {
+            throw new Error("The document path must reference a regular file");
+        }
+        if (metadata.size <= 0) {
+            throw new Error("The document must not be empty");
+        }
+        if (metadata.size > config.maxDocumentBytes) {
+            throw new Error(`The document exceeds the ${config.maxDocumentBytes}-byte limit`);
+        }
+        if (config.allowedDirectories.length > 0) {
+            const realDirectories = await Promise.all(config.allowedDirectories.map(async (directory) => {
+                try {
+                    return await realpath(directory);
+                }
+                catch {
+                    throw new Error(`Allowed directory does not exist: ${directory}`);
+                }
+            }));
+            if (!realDirectories.some((directory) => isWithin(absolutePath, directory))) {
+                throw new Error("The document is outside OCR_ALLOWED_DIRECTORIES");
+            }
+        }
+        const extension = extname(absolutePath).toLowerCase();
+        const mimeType = MIME_TYPES[extension];
+        if (!mimeType) {
+            throw new Error(`Unsupported document format: ${extension || "none"}`);
+        }
+        return { content: await handle.readFile(), mimeType, absolutePath };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function normalizeResponse(data, config) {
+    if (!Array.isArray(data.pages)) {
+        throw new Error("The OCR service returned an invalid response");
+    }
+    const pages = data.pages.map((page) => {
+        if (typeof page?.markdown !== "string") {
+            throw new Error("The OCR service returned an invalid response");
+        }
+        return page.markdown;
+    });
+    const fullContent = pages.join(PAGE_SEPARATOR);
+    const originalCharacterCount = fullContent.length;
+    const truncated = config.maxExtractedTextChars !== undefined && originalCharacterCount > config.maxExtractedTextChars;
+    let content = fullContent;
+    if (truncated && config.maxExtractedTextChars !== undefined) {
+        const suffix = `\n\n${TRUNCATION_MARKER}`;
+        content = `${fullContent.slice(0, config.maxExtractedTextChars - suffix.length).trimEnd()}${suffix}`;
+    }
+    return {
+        content,
+        model: config.model,
+        pageCount: pages.length,
+        truncated,
+        originalCharacterCount,
+    };
+}
+function upstreamError(status) {
+    if (status === 401 || status === 403)
+        return "Authentication was rejected by the OCR service";
+    if (status === 413)
+        return "The OCR service rejected the document as too large";
+    if (status === 429)
+        return "The OCR service is rate limited; try again later";
+    return "The OCR service failed to process the document";
+}
+async function boundedJson(response, maxBytes) {
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw new Error("The OCR service returned an oversized response");
+    }
+    if (!response.body) {
+        throw new Error("The OCR service returned an invalid response");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        bytes += value.byteLength;
+        if (bytes > maxBytes) {
+            await reader.cancel();
+            throw new Error("The OCR service returned an oversized response");
+        }
+        chunks.push(value);
+    }
+    const body = Buffer.concat(chunks, bytes).toString("utf8");
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new Error("The OCR service returned an invalid response");
+    }
+}
+export async function extractDocument(filePath, config, fetchImplementation = fetch) {
+    const { content, mimeType } = await readDocument(filePath, config);
+    const documentType = mimeType === "application/pdf" ? "document_url" : "image_url";
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.requestTimeoutMs);
+    try {
+        const response = await fetchImplementation(`${config.baseUrl}/v1/ocr`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${config.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: config.model,
+                document: {
+                    type: documentType,
+                    [documentType]: `data:${mimeType};base64,${content.toString("base64")}`,
+                },
+                include_image_base64: false,
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(upstreamError(response.status));
+        }
+        return normalizeResponse(await boundedJson(response, config.maxResponseBytes), config);
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error("The OCR request timed out");
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@viadee/mistral-ocr-mcp",
+  "version": "1.0.8",
+  "description": "MCP server for extracting Markdown from local documents through a Mistral-compatible OCR API",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/viadee-internal/mistral-ocr-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/viadee-internal/mistral-ocr-mcp/issues"
+  },
+  "homepage": "https://github.com/viadee-internal/mistral-ocr-mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "mistral-ocr-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run check && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "24.3.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "license": "MIT"
+}