mineru-mcp 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# mineru-mcp
+
+MCP server for [MinerU](https://mineru.net) document parsing API - optimized for Claude Code.
+
+## Features
+
+- **4 optimized tools** with concise descriptions (~73% token reduction vs alternatives)
+- **VLM model support** (90%+ accuracy) and pipeline mode (faster)
+- **Page range selection** - parse specific pages only
+- **Batch processing** - up to 200 documents at once
+- **Pagination** - efficient handling of large batch results
+- **109 language OCR** support
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add mineru-mcp -e MINERU_API_KEY=your-api-key -- npx mineru-mcp
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "mineru": {
+      "command": "npx",
+      "args": ["-y", "mineru-mcp"],
+      "env": {
+        "MINERU_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `MINERU_API_KEY` | (required) | Your MinerU API Bearer token |
+| `MINERU_BASE_URL` | `https://mineru.net/api/v4` | API base URL |
+| `MINERU_DEFAULT_MODEL` | `pipeline` | Default model: `pipeline` or `vlm` |
+
+Get your API key at [mineru.net](https://mineru.net)
+
+## Tools
+
+### `mineru_parse`
+
+Parse a single document URL.
+
+```typescript
+mineru_parse({
+  url: "https://example.com/document.pdf",
+  model: "vlm",        // optional: "pipeline" (default) or "vlm" (90% accuracy)
+  pages: "1-10,15",    // optional: page ranges
+  ocr: true,           // optional: enable OCR (pipeline only)
+  formula: true,       // optional: formula recognition
+  table: true,         // optional: table recognition
+  language: "en",      // optional: language code
+  formats: ["html"]    // optional: extra export formats
+})
+```
+
+### `mineru_status`
+
+Check task progress and get download URL.
+
+```typescript
+mineru_status({
+  task_id: "abc-123",
+  format: "concise"    // optional: "concise" (default) or "detailed"
+})
+```
+
+**Concise output**: `done | abc-123 | https://cdn-mineru.../result.zip`
+
+### `mineru_batch`
+
+Parse multiple documents in one batch (max 200).
+
+```typescript
+mineru_batch({
+  urls: ["https://example.com/doc1.pdf", "https://example.com/doc2.pdf"],
+  model: "vlm"
+})
+```
+
+### `mineru_batch_status`
+
+Get batch results with pagination.
+
+```typescript
+mineru_batch_status({
+  batch_id: "batch-123",
+  limit: 10,           // optional: max results (default: 10)
+  offset: 0,           // optional: skip first N results
+  format: "concise"    // optional: "concise" or "detailed"
+})
+```
+
+## Supported Formats
+
+- PDF, DOC, DOCX, PPT, PPTX
+- PNG, JPG, JPEG
+
+## Limits
+
+- Single file: 200MB max, 600 pages max
+- Daily quota: 2000 pages at high priority
+- Batch: max 200 URLs per request
+
+## License
+
+MIT
+
+## Links
+
+- [MinerU](https://mineru.net) - Document parsing service
+- [MinerU GitHub](https://github.com/opendatalab/MinerU) - Open source version
+- [MCP Specification](https://modelcontextprotocol.io) - Model Context Protocol

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,233 @@
+#!/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 axios, { AxiosError } from "axios";
+// Configuration from environment
+const config = {
+    apiKey: process.env.MINERU_API_KEY || "",
+    baseUrl: process.env.MINERU_BASE_URL || "https://mineru.net/api/v4",
+    defaultModel: (process.env.MINERU_DEFAULT_MODEL || "pipeline"),
+};
+// Error codes with actionable messages
+const ERROR_MESSAGES = {
+    "A0202": "Token error. Check your API key.",
+    "A0211": "Token expired. Get a new API key.",
+    "-60002": "Invalid file format. Use: pdf, doc, docx, ppt, pptx, png, jpg, jpeg",
+    "-60005": "File too large. Max 200MB.",
+    "-60006": "Too many pages. Max 600 per file. Split the document.",
+    "-60008": "URL timeout. Check the URL is accessible.",
+    "-60009": "Queue full. Try again later.",
+    "-60012": "Task not found. Check task_id is valid.",
+    "-60013": "Access denied. You can only access your own tasks.",
+};
+// API client
+async function mineruRequest(endpoint, method = "GET", data) {
+    if (!config.apiKey) {
+        throw new Error("MINERU_API_KEY not set. Add it to your environment.");
+    }
+    try {
+        const response = await axios({
+            method,
+            url: `${config.baseUrl}${endpoint}`,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+            data,
+        });
+        const result = response.data;
+        if (result.code !== 0) {
+            const code = String(result.code);
+            const msg = ERROR_MESSAGES[code] || result.msg || "Unknown error";
+            throw new Error(`MinerU error ${code}: ${msg}`);
+        }
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof AxiosError) {
+            const code = error.response?.data?.code;
+            if (code) {
+                const msg = ERROR_MESSAGES[String(code)] || error.response?.data?.msg;
+                throw new Error(`MinerU error ${code}: ${msg}`);
+            }
+            throw new Error(`HTTP ${error.response?.status}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+// Format helpers
+function formatConciseStatus(status) {
+    const parts = [status.state, status.task_id];
+    if (status.state === "done" && status.full_zip_url) {
+        parts.push(status.full_zip_url);
+    }
+    else if (status.state === "running" && status.extract_progress) {
+        const p = status.extract_progress;
+        parts.push(`${p.extracted_pages}/${p.total_pages} pages`);
+    }
+    else if (status.state === "failed" && status.err_msg) {
+        parts.push(status.err_msg);
+    }
+    return parts.join(" | ");
+}
+function formatDetailedStatus(status) {
+    return JSON.stringify(status, null, 2);
+}
+function formatConciseBatch(batch, limit, offset) {
+    const results = batch.extract_result.slice(offset, offset + limit);
+    const total = batch.extract_result.length;
+    const done = batch.extract_result.filter((r) => r.state === "done").length;
+    const lines = [`Batch ${batch.batch_id}: ${done}/${total} done`];
+    for (const r of results) {
+        let line = `- ${r.file_name}: ${r.state}`;
+        if (r.state === "done" && r.full_zip_url) {
+            line += ` ${r.full_zip_url}`;
+        }
+        else if (r.state === "running" && r.extract_progress) {
+            line += ` (${r.extract_progress.extracted_pages}/${r.extract_progress.total_pages})`;
+        }
+        lines.push(line);
+    }
+    if (offset + limit < total) {
+        lines.push(`[+${total - offset - limit} more, use offset=${offset + limit}]`);
+    }
+    return lines.join("\n");
+}
+// Create MCP server
+const server = new McpServer({
+    name: "mineru",
+    version: "1.0.0",
+});
+// Tool 1: mineru_parse
+server.tool("mineru_parse", "Parse a document URL. Returns task_id to check status.", {
+    url: z.string().describe("Document URL (PDF, DOC, PPT, images)"),
+    model: z
+        .enum(["pipeline", "vlm"])
+        .optional()
+        .describe("pipeline=fast, vlm=90% accuracy"),
+    pages: z.string().optional().describe("Page range: 1-10,15 or 2--2"),
+    ocr: z.boolean().optional().describe("Enable OCR (pipeline only)"),
+    formula: z.boolean().optional().describe("Formula recognition"),
+    table: z.boolean().optional().describe("Table recognition"),
+    language: z.string().optional().describe("Language code: ch, en, etc"),
+    formats: z
+        .array(z.enum(["docx", "html", "latex"]))
+        .optional()
+        .describe("Extra export formats"),
+}, async (params) => {
+    const requestData = {
+        url: params.url,
+        model_version: params.model || config.defaultModel,
+    };
+    if (params.pages)
+        requestData.page_ranges = params.pages;
+    if (params.ocr !== undefined)
+        requestData.is_ocr = params.ocr;
+    if (params.formula !== undefined)
+        requestData.enable_formula = params.formula;
+    if (params.table !== undefined)
+        requestData.enable_table = params.table;
+    if (params.language)
+        requestData.language = params.language;
+    if (params.formats?.length)
+        requestData.extra_formats = params.formats;
+    const result = await mineruRequest("/extract/task", "POST", requestData);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Task created: ${result.task_id}\nUse mineru_status to check progress.`,
+            },
+        ],
+    };
+});
+// Tool 2: mineru_status
+server.tool("mineru_status", "Check task progress. Returns download URL when done.", {
+    task_id: z.string().describe("Task ID from mineru_parse"),
+    format: z
+        .enum(["concise", "detailed"])
+        .optional()
+        .default("concise")
+        .describe("Output format"),
+}, async (params) => {
+    const status = await mineruRequest(`/extract/task/${params.task_id}`);
+    const text = params.format === "detailed"
+        ? formatDetailedStatus(status)
+        : formatConciseStatus(status);
+    return {
+        content: [{ type: "text", text }],
+    };
+});
+// Tool 3: mineru_batch
+server.tool("mineru_batch", "Parse multiple URLs in one batch (max 200).", {
+    urls: z.array(z.string()).describe("Array of document URLs"),
+    model: z
+        .enum(["pipeline", "vlm"])
+        .optional()
+        .describe("pipeline=fast, vlm=90% accuracy"),
+    ocr: z.boolean().optional().describe("Enable OCR (pipeline only)"),
+    formula: z.boolean().optional().describe("Formula recognition"),
+    table: z.boolean().optional().describe("Table recognition"),
+    language: z.string().optional().describe("Language code: ch, en, etc"),
+    formats: z
+        .array(z.enum(["docx", "html", "latex"]))
+        .optional()
+        .describe("Extra export formats"),
+}, async (params) => {
+    if (params.urls.length > 200) {
+        throw new Error("Max 200 URLs per batch. Split into smaller batches.");
+    }
+    const requestData = {
+        files: params.urls.map((url) => ({ url })),
+        model_version: params.model || config.defaultModel,
+    };
+    if (params.ocr !== undefined)
+        requestData.is_ocr = params.ocr;
+    if (params.formula !== undefined)
+        requestData.enable_formula = params.formula;
+    if (params.table !== undefined)
+        requestData.enable_table = params.table;
+    if (params.language)
+        requestData.language = params.language;
+    if (params.formats?.length)
+        requestData.extra_formats = params.formats;
+    const result = await mineruRequest("/extract/task/batch", "POST", requestData);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Batch created: ${result.batch_id}\n${params.urls.length} files queued.\nUse mineru_batch_status to check progress.`,
+            },
+        ],
+    };
+});
+// Tool 4: mineru_batch_status
+server.tool("mineru_batch_status", "Get batch results. Supports pagination for large batches.", {
+    batch_id: z.string().describe("Batch ID from mineru_batch"),
+    limit: z.number().optional().default(10).describe("Max results to return"),
+    offset: z.number().optional().default(0).describe("Skip first N results"),
+    format: z
+        .enum(["concise", "detailed"])
+        .optional()
+        .default("concise")
+        .describe("Output format"),
+}, async (params) => {
+    const batch = await mineruRequest(`/extract-results/batch/${params.batch_id}`);
+    const text = params.format === "detailed"
+        ? JSON.stringify(batch, null, 2)
+        : formatConciseBatch(batch, params.limit ?? 10, params.offset ?? 0);
+    return {
+        content: [{ type: "text", text }],
+    };
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MinerU MCP server running");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "mineru-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for MinerU document parsing API - optimized for Claude Code with 73% token reduction",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mineru-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mineru",
+    "pdf",
+    "document-parsing",
+    "ocr",
+    "claude",
+    "claude-code",
+    "anthropic",
+    "ai",
+    "llm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/claude-code"
+  },
+  "homepage": "https://mineru.net",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.7.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}