Merge pull request #2578 from AdrianWangs/dev

feat(mcp): 添加mineru的mcp-server

projects/mcp/.env.example

+MINERU_API_BASE = "https://mineru.net"
+MINERU_API_KEY = "eyJ0eXB..."
+OUTPUT_DIR=./downloads 
+USE_LOCAL_API=false
+LOCAL_MINERU_API_BASE="http://localhost:8888"
\ No newline at end of file

projects/mcp/.gitignore

+downloads
+.env
+uv.lock
+.venv
+src/mineru/__pycache__
+dist
+.DS_Store
+.cursor
+build
+*.lock
+src/mineru_mcp.egg-info
+test
\ No newline at end of file

projects/mcp/DOCKER_README.md

+# MinerU MCP-Server Docker 部署指南
+
+## 1. 简介
+
+本文档提供了使用 Docker 部署 MinerU MCP-Server 的详细指南。通过 Docker 部署，你可以在任何支持 Docker 的环境中快速启动 MinerU MCP 服务器，无需考虑复杂的环境配置和依赖管理。
+
+Docker 部署的主要优势：
+
+- **一致的运行环境**：确保在任何平台上都有相同的运行环境
+- **简化部署流程**：一键启动，无需手动安装依赖
+- **易于扩展和迁移**：便于在不同环境间迁移和扩展服务
+- **资源隔离**：避免与宿主机其他服务产生冲突
+
+## 2. 先决条件
+
+在开始之前，请确保你的系统已安装以下软件：
+
+- [Docker](https://www.docker.com/get-started) (19.03 或更高版本)
+- [Docker Compose](https://docs.docker.com/compose/install/) (1.27.0 或更高版本)
+
+你可以通过以下命令检查它们是否已正确安装：
+
+```bash
+docker --version
+docker-compose --version
+```
+
+同时，你需要：
+
+- 从 [MinerU 官网](https://mineru.net) 获取的 API 密钥（如果需要使用远程 API）
+- 充足的硬盘空间，用于存储转换后的文件
+
+## 3. 使用 Docker Compose 部署（推荐）
+
+Docker Compose 提供了最简单的部署方式，特别适合快速开始使用或开发环境。
+
+### 3.1 准备配置文件
+
+1. 克隆仓库（如果尚未克隆）：
+
+   ```bash
+   git clone <repository-url>
+   cd mineru-mcp
+   ```
+
+2. 创建环境变量文件：
+
+   ```bash
+   cp .env.example .env
+   ```
+
+3. 编辑 `.env` 文件，设置必要的环境变量：
+
+   ```
+   MINERU_API_BASE=https://mineru.net
+   MINERU_API_KEY=你的API密钥
+   OUTPUT_DIR=./downloads
+   USE_LOCAL_API=false
+   LOCAL_MINERU_API_BASE=http://localhost:8080
+   ```
+
+   如果你计划使用本地 API，请将 `USE_LOCAL_API` 设置为 `true`，并确保 `LOCAL_MINERU_API_BASE` 指向你的本地 API 服务地址。
+
+### 3.2 启动服务
+
+在项目根目录下运行：
+
+```bash
+docker-compose up -d
+```
+
+这将会：
+- 构建 Docker 镜像（如果尚未构建）
+- 创建并启动容器
+- 在后台运行服务 (`-d` 参数)
+
+服务将在 `http://localhost:8001` 上启动。你可以通过 MCP 客户端连接此地址。
+
+### 3.3 查看日志
+
+要查看服务日志，运行：
+
+```bash
+docker-compose logs -f
+```
+
+按 `Ctrl+C` 退出日志查看。
+
+### 3.4 停止服务
+
+要停止服务，运行：
+
+```bash
+docker-compose down
+```
+
+如果你想同时删除构建的镜像，可以使用：
+
+```bash
+docker-compose down --rmi local
+```
+
+## 4. 手动构建和运行 Docker 镜像
+
+如果你需要更多的控制或自定义，你可以手动构建和运行 Docker 镜像。
+
+### 4.1 构建镜像
+
+在项目根目录下运行：
+
+```bash
+docker build -t mineru-mcp:latest .
+```
+
+这将根据 Dockerfile 构建一个名为 `mineru-mcp` 的 Docker 镜像，标签为 `latest`。
+
+### 4.2 运行容器
+
+使用环境变量文件运行容器：
+
+```bash
+docker run -p 8001:8001 --env-file .env mineru-mcp:latest
+```
+
+或者直接指定环境变量：
+
+```bash
+docker run -p 8001:8001 \
+  -e MINERU_API_BASE=https://mineru.net \
+  -e MINERU_API_KEY=你的API密钥 \
+  -e OUTPUT_DIR=/app/downloads \
+  -v $(pwd)/downloads:/app/downloads \
+  mineru-mcp:latest
+```
+
+### 4.3 挂载卷
+
+为了持久化存储转换后的文件，你应该挂载宿主机目录到容器的输出目录：
+
+```bash
+docker run -p 8001:8001 --env-file .env \
+  -v $(pwd)/downloads:/app/downloads \
+  mineru-mcp:latest
+```
+
+这将挂载当前工作目录下的 `downloads` 文件夹到容器内的 `/app/downloads` 目录。
+
+## 5. 环境变量配置
+
+Docker 环境中支持的环境变量与标准环境相同：
+
+| 环境变量 | 说明 | 默认值 |
+| ------------------------- | -------------------------------------------------------------- | ------------------------- |
+| `MINERU_API_BASE` | MinerU 远程 API 的基础 URL | `https://mineru.net` |
+| `MINERU_API_KEY` | MinerU API 密钥，需要从官网申请 | - |
+| `OUTPUT_DIR` | 转换后文件的保存路径 | `/app/downloads` |
+| `USE_LOCAL_API` | 是否使用本地 API 进行解析（仅适用于 `local_parse_pdf` 工具） | `false` |
+| `LOCAL_MINERU_API_BASE` | 本地 API 的基础 URL（当 `USE_LOCAL_API=true` 时有效） | `http://localhost:8080` |
+
+在 Docker 环境中，你可以：
+
+- 通过 `--env-file` 指定环境变量文件
+- 通过 `-e` 参数直接指定环境变量
+- 在 `docker-compose.yml` 文件中的 `environment` 部分配置环境变量

projects/mcp/Dockerfile

+FROM python:3.12-slim
+
+# Set working directory
+WORKDIR /app
+
+# Configure pip to use Alibaba Cloud mirror
+RUN pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
+
+# Install dependencies
+RUN pip install --no-cache-dir poetry
+
+# Copy project files
+COPY pyproject.toml .
+COPY README.md .
+COPY src/ ./src/
+
+# Install the package
+RUN poetry config virtualenvs.create false && \
+    poetry install
+
+# Create downloads directory
+RUN mkdir -p /app/downloads
+
+# Set environment variables
+ENV OUTPUT_DIR=/app/downloads
+# MINERU_API_KEY should be provided at runtime
+ENV MINERU_API_BASE=https://mineru.net
+ENV USE_LOCAL_API=false
+ENV LOCAL_MINERU_API_BASE=""
+
+# Expose the port that SSE will run on
+EXPOSE 8001
+
+# Set command to start the service with SSE transport
+CMD ["mineru-mcp", "--transport", "sse", "--output-dir", "/app/downloads"] 
\ No newline at end of file

projects/mcp/README.md

+# MinerU MCP-Server
+
+## 1. 概述
+
+这个项目提供了一个 **MinerU MCP 服务器** (`mineru-mcp`)，它基于 **FastMCP** 框架构建。其主要功能是作为 **MinerU API** 的接口，用于将文档转换为 Markdown格式。
+
+该服务器通过 MCP 协议公开了以下主要工具：
+
+1. `parse_documents`：统一接口，支持处理本地文件和URL，自动根据配置选择最合适的处理方式，并自动读取转换后的内容
+2. `get_ocr_languages`：获取OCR支持的语言列表
+
+这使得其他应用程序或 MCP 客户端能够轻松地集成 MinerU 的 文档 到 Markdown 转换功能。
+
+## 2. 核心功能
+
+* **文档提取**: 接收文档文件输入（单个或多个 URL、单个或多个本地路径，支持doc、ppt、pdf、图片多种格式），调用 MinerU API 进行内容提取和格式转换，最终生成 Markdown 文件。
+* **批量处理**: 支持同时处理多个文档文件（通过提供由空格、逗号或换行符分隔的 URL 列表或本地文件路径列表）。
+* **OCR 支持**: 可选启用 OCR 功能（默认不开启），以处理扫描版或图片型文档。
+* **多语言支持**: 支持多种语言的识别，可以自动检测文档语言或手动指定。
+* **自动化流程**: 自动处理与 MinerU API 的交互，包括任务提交、状态轮询、结果下载解压、结果文件读取。
+* **本地解析**: 支持调用本地部署的mineru模型直接解析文档，不依赖远程 API，适用于隐私敏感场景或离线环境。
+* **智能路径处理**: 自动识别URL和本地文件路径，根据USE_LOCAL_API配置选择最合适的处理方式。
+
+## 3. 安装
+
+在开始安装之前，请确保您的系统满足以下基本要求：
+* Python >= 3.10
+
+### 3.1 使用 pip 安装 (推荐)
+
+如果你的包已发布到 PyPI 或其他 Python 包索引，可以直接使用 pip 安装：
+
+```bash
+pip install mineru-mcp
+```
+
+这种方式适用于不需要修改源代码的普通用户。
+
+### 3.2 从源码安装
+
+如果你需要修改源代码或进行开发，可以从源码安装。
+
+克隆仓库并进入项目目录：
+
+```bash
+git clone <repository-url> # 替换为你的仓库 URL
+cd mineru-mcp
+```
+
+推荐使用 `uv` 或 `pip` 配合虚拟环境进行安装：
+
+**使用 uv (推荐):**
+
+```bash
+# 安装 uv (如果尚未安装)
+# pip install uv
+
+# 创建并激活虚拟环境
+uv venv
+
+# Linux/macOS
+source .venv/bin/activate 
+# Windows
+# .venv\\Scripts\\activate
+
+# 安装依赖和项目
+uv pip install -e .
+```
+
+**使用 pip:**
+
+```bash
+# 创建并激活虚拟环境
+python -m venv .venv
+
+# Linux/macOS
+source .venv/bin/activate 
+# Windows
+# .venv\\Scripts\\activate
+
+# 安装依赖和项目
+pip install -e .
+```
+
+## 4. 环境变量配置
+
+本项目支持通过环境变量进行配置。你可以选择直接设置系统环境变量，或者在项目根目录创建 `.env` 文件（参考 `.env.example` 模板）。
+
+### 4.1 支持的环境变量
+
+| 环境变量                  | 说明                                                            | 默认值                    |
+| ------------------------- | --------------------------------------------------------------- | ------------------------- |
+| `MINERU_API_BASE`       | MinerU 远程 API 的基础 URL                                      | `https://mineru.net`    |
+| `MINERU_API_KEY`        | MinerU API 密钥，需要从[官网](https://mineru.net)申请              | -                         |
+| `OUTPUT_DIR`            | 转换后文件的保存路径                                            | `./downloads`           |
+| `USE_LOCAL_API`         | 是否使用本地 API 进行解析                                      | `false`                 |
+| `LOCAL_MINERU_API_BASE` | 本地 API 的基础 URL（当 `USE_LOCAL_API=true` 时有效）         | `http://localhost:8080` |
+
+### 4.2 远程 API 与本地 API
+
+本项目支持两种 API 模式：
+
+* **远程 API**：默认模式，通过 MinerU 官方提供的云服务进行文档解析。优点是无需本地部署复杂的模型和环境，但需要网络连接和 API 密钥。
+* **本地 API**：在本地部署 MinerU 引擎进行文档解析，适用于对数据隐私有高要求或需要离线使用的场景。设置 `USE_LOCAL_API=true` 时生效。
+
+### 4.3 获取 API 密钥
+
+要获取 `MINERU_API_KEY`，请访问 [MinerU 官网](https://mineru.net) 注册账号并申请 API 密钥。
+
+## 5. 使用方法
+
+### 5.1 工具概览
+
+本项目通过 MCP 协议提供以下工具：
+
+1. **parse_documents**：统一接口，支持处理本地文件和URL，根据 `USE_LOCAL_API` 配置自动选择合适的处理方式，并自动读取转换后的文件内容
+2. **get_ocr_languages**：获取 OCR 支持的语言列表
+
+### 5.2 参数说明
+
+#### 5.2.1 parse_documents
+
+| 参数                | 类型    | 说明                                                                | 默认值   | 适用模式 |
+| ------------------- | ------- | ------------------------------------------------------------------- | -------- | -------- |
+| `file_sources`      | 字符串  | 文件路径或URL，多个可用逗号或换行符分隔 (支持pdf、ppt、pptx、doc、docx以及图片格式jpg、jpeg、png) | -        | 全部 |
+| `enable_ocr`        | 布尔值  | 是否启用 OCR 功能                                                   | `false`  | 全部 |
+| `language`          | 字符串  | 文档语言，默认"ch"中文，可选"en"英文等                            | `ch`     | 全部 |
+| `page_ranges`       | 字符串 (可选) | 指定页码范围，格式为逗号分隔的字符串。例如："2,4-6"：表示选取第2页、第4页至第6页；"2--2"：表示从第2页一直选取到倒数第二页。（远程API）  | `None`   | 远程API |
+
+> **注意**：
+> - 当 `USE_LOCAL_API=true` 时，如果提供了URL，这些URL会被过滤掉，只处理本地文件路径
+> - 当 `USE_LOCAL_API=false` 时，会同时处理URL和本地文件路径
+
+#### 5.2.2 get_ocr_languages
+
+无需参数
+
+## 6. MCP 客户端集成
+
+你可以在任何支持 MCP 协议的客户端中使用 MinerU MCP 服务器。
+
+### 6.1 在 Claude 中使用
+
+将 MinerU MCP 服务器配置为 Claude 的工具，即可在 Claude 中直接使用文档转 Markdown 功能。配置工具时详情请参考 MCP 工具配置文档。根据不同的安装和使用场景，你可以选择以下两种配置方式：
+
+#### 6.1.1 源码运行方式
+
+如果你是从源码安装并运行 MinerU MCP，可以使用以下配置。这种方式适合你需要修改源码或者进行开发调试的场景：
+
+```json
+{
+  "mcpServers": {
+    "mineru-mcp": {
+      "command": "uv",
+      "args": ["--directory", "/Users/adrianwang/Documents/minerU-mcp", "run", "-m", "mineru.cli"],
+      "env": {
+        "MINERU_API_BASE": "https://mineru.net",
+        "MINERU_API_KEY": "ey...",
+        "OUTPUT_DIR": "./downloads",
+        "USE_LOCAL_API": "true",
+        "LOCAL_MINERU_API_BASE": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+这种配置的特点：
+
+- 使用 `uv` 命令
+- 通过 `--directory` 参数指定源码所在目录
+- 使用 `-m mineru.cli` 运行模块
+- 适合开发调试和定制化需求
+
+#### 6.1.2 安装包运行方式
+
+如果你是通过 pip 或 uv 安装了 mineru-mcp 包，可以使用以下更简洁的配置。这种方式适合生产环境或日常使用：
+
+```json
+{
+  "mcpServers": {
+    "mineru-mcp": {
+      "command": "uvx",
+      "args": ["mineru-mcp"],
+      "env": {
+        "MINERU_API_BASE": "https://mineru.net",
+        "MINERU_API_KEY": "ey...",
+        "OUTPUT_DIR": "./downloads",
+        "USE_LOCAL_API": "true",
+        "LOCAL_MINERU_API_BASE": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+这种配置的特点：
+
+- 使用 `uvx` 命令直接运行已安装的包
+- 配置更加简洁
+- 不需要指定源码目录
+- 适合稳定的生产环境使用
+
+### 6.2 在 FastMCP 客户端中使用
+
+
+```python
+from fastmcp import FastMCP
+
+# 初始化 FastMCP 客户端
+client = FastMCP(server_url="http://localhost:8001")
+
+# 使用 parse_documents 工具处理单个文档
+result = await client.tool_call(
+    tool_name="parse_documents",
+    params={"file_sources": "/path/to/document.pdf"}
+)
+
+# 混合处理URLs和本地文件
+result = await client.tool_call(
+    tool_name="parse_documents",
+    params={"file_sources": "/path/to/file.pdf, https://example.com/document.pdf"}
+)
+
+# 启用OCR
+result = await client.tool_call(
+    tool_name="parse_documents",
+    params={"file_sources": "/path/to/file.pdf", "enable_ocr": True}
+)
+```
+
+### 6.3 直接运行服务
+
+你可以通过设置环境变量并直接运行命令的方式启动 MinerU MCP 服务器，这种方式特别适合快速测试和开发环境。
+
+#### 6.3.1 设置环境变量
+
+首先，确保设置了必要的环境变量。你可以通过创建 `.env` 文件（参考 `.env.example`）或直接在命令行中设置：
+
+```bash
+# Linux/macOS
+export MINERU_API_BASE="https://mineru.net"
+export MINERU_API_KEY="your-api-key"
+export OUTPUT_DIR="./downloads"
+export USE_LOCAL_API="true"  # 可选，如果需要本地解析
+export LOCAL_MINERU_API_BASE="http://localhost:8080"  # 可选，如果启用本地 API
+
+# Windows
+set MINERU_API_BASE=https://mineru.net
+set MINERU_API_KEY=your-api-key
+set OUTPUT_DIR=./downloads
+set USE_LOCAL_API=true
+set LOCAL_MINERU_API_BASE=http://localhost:8080
+```
+
+#### 6.3.2 启动服务
+
+使用以下命令启动 MinerU MCP 服务器，支持多种传输模式：
+
+**SSE 传输模式**：
+```bash
+uv run mineru-mcp --transport sse
+```
+
+**Streamable HTTP 传输模式**：
+```bash
+uv run mineru-mcp --transport streamable-http
+```
+
+或者，如果你使用全局安装：
+
+```bash
+mineru-mcp --transport sse
+# 或
+mineru-mcp --transport streamable-http
+```
+
+服务默认在 `http://localhost:8001` 启动，使用的传输协议取决于你指定的 `--transport` 参数。
+
+> **注意**：不同传输模式使用不同的路由路径：
+> - SSE 模式：`/sse`（例如：`http://localhost:8001/sse`）
+> - Streamable HTTP 模式：`/mcp`（例如：`http://localhost:8001/mcp`）
+
+
+## 7. Docker 部署
+
+本项目支持使用 Docker 进行部署，使你能在任何支持 Docker 的环境中快速启动 MinerU MCP 服务器。
+
+### 7.1 使用 Docker Compose
+
+1. 确保你已经安装了 Docker 和 Docker Compose
+2. 复制项目根目录中的 `.env.example` 文件为 `.env`，并根据你的需求修改环境变量
+3. 运行以下命令启动服务：
+
+```bash
+docker-compose up -d
+```
+
+服务默认会在 `http://localhost:8001` 启动。
+
+### 7.2 手动构建 Docker 镜像
+
+如果需要手动构建 Docker 镜像，可以使用以下命令：
+
+```bash
+docker build -t mineru-mcp:latest .
+```
+
+然后启动容器：
+
+```bash
+docker run -p 8001:8001 --env-file .env mineru-mcp:latest
+```
+
+更多 Docker 相关信息，请参考 `DOCKER_README.md` 文件。
+
+## 8. 常见问题
+
+### 8.1 API 密钥问题
+
+**问题**：无法连接 MinerU API 或返回 401 错误。
+**解决方案**：检查你的 API 密钥是否正确设置。在 `.env` 文件中确保 `MINERU_API_KEY` 环境变量包含有效的密钥。
+
+### 8.2 如何优雅退出服务
+
+**问题**：如何正确地停止 MinerU MCP 服务？
+**解决方案**：服务运行时，可以通过按 `Ctrl+C` 来优雅地退出。系统会自动处理正在进行的操作，并确保所有资源得到正确释放。如果一次 `Ctrl+C` 没有响应，可以再次按下 `Ctrl+C` 强制退出。
+
+### 8.3 文件路径问题
+
+**问题**：使用 `parse_documents` 工具处理本地文件时报找不到文件错误。
+**解决方案**：请确保使用绝对路径，或者相对于服务器运行目录的正确相对路径。
+
+### 8.4 MCP 服务调用超时问题
+
+**问题**：调用 `parse_documents` 工具时出现 `Error calling tool 'parse_documents': MCP error -32001: Request timed out` 错误。
+**解决方案**：这个问题常见于处理大型文档或网络不稳定的情况。在某些 MCP 客户端（如 Cursor）中，超时后可能导致无法再次调用 MCP 服务，需要重启客户端。最新版本的 Cursor 中可能会显示正在调用 MCP，但实际上没有真正调用成功。建议：
+1. **等待官方修复**：这是Cursor客户端的已知问题，建议等待Cursor官方修复
+2. **处理小文件**：尽量只处理少量小文件，避免处理大型文档导致超时
+3. **分批处理**：将多个文件分成多次请求处理，每次只处理一两个文件
+4. 增加超时时间设置（如果客户端支持）
+5. 对于超时后无法再次调用的问题，需要重启 MCP 客户端
+6. 如果反复出现超时，请检查网络连接或考虑使用本地 API 模式
+
+
+## 9. 许可证
+
+本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

projects/mcp/docker-compose.yml

+version: '3'
+
+services:
+  mineru-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8001:8001"
+    environment:
+      - MINERU_API_KEY=${MINERU_API_KEY}
+    volumes:
+      - ./downloads:/app/downloads
+    restart: unless-stopped 
\ No newline at end of file

projects/mcp/pyproject.toml

+[project]
+name = "mineru-mcp"
+version = "0.1.12"
+description = "MinerU MCP Server for PDF to Markdown conversion"
+authors = [
+    {name = "minerU",email = "OpenDataLab@pjlab.org.cn"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10,<4.0"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "fastmcp>=2.5.2",
+    "python-dotenv>=1.0.0",
+    "requests>=2.31.0",
+    "aiohttp>=3.9.0",
+    "httpx>=0.24.0",
+    "uvicorn>=0.20.0",
+    "starlette>=0.27.0",
+]
+
+[project.scripts]
+mineru-mcp = "mineru.cli:main"
+
+[tool.poetry]
+packages = [{include = "mineru", from = "src"}]
+
+[[tool.poetry.source]]
+name = "aliyun"
+url = "https://mirrors.aliyun.com/pypi/simple/"
+priority = "primary"
+
+[build-system]
+requires = ["setuptools>=42.0", "wheel"]
+build-backend = "setuptools.build_meta"

projects/mcp/src/mineru/cli.py

+"""MinerU File转Markdown服务的命令行界面。"""
+
+import sys
+import argparse
+
+from . import config
+from . import server
+
+
+def main():
+    """命令行界面的入口点。"""
+    parser = argparse.ArgumentParser(description="MinerU File转Markdown转换服务")
+
+    parser.add_argument(
+        "--output-dir", "-o", type=str, help="保存转换后文件的目录 (默认: ./downloads)"
+    )
+
+    parser.add_argument(
+        "--transport",
+        "-t",
+        type=str,
+        default="stdio",
+        help="协议类型 (默认: stdio,可选: sse,streamable-http)",
+    )
+
+    parser.add_argument(
+        "--port",
+        "-p",
+        type=int,
+        default=8001,
+        help="服务器端口 (默认: 8001, 仅在使用HTTP协议时有效)",
+    )
+
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="服务器主机地址 (默认: 127.0.0.1, 仅在使用HTTP协议时有效)",
+    )
+
+    args = parser.parse_args()
+
+    # 检查参数有效性
+    if args.transport == "stdio" and (args.host != "127.0.0.1" or args.port != 8001):
+        print("警告: 在STDIO模式下，--host和--port参数将被忽略", file=sys.stderr)
+
+    # 验证API密钥 - 移动到这里，以便 --help 等参数可以无密钥运行
+    if not config.MINERU_API_KEY:
+        print(
+            "错误: 启动服务需要 MINERU_API_KEY 环境变量。"
+            "\\n请检查是否已设置该环境变量，例如："
+            "\\n  export MINERU_API_KEY='your_actual_api_key'"
+            "\\n或者，确保在项目根目录的 `.env` 文件中定义了该变量。"
+            "\\n\\n您可以使用 --help 查看可用的命令行选项。",
+            file=sys.stderr,  # 将错误消息输出到 stderr
+        )
+        sys.exit(1)
+
+    # 如果提供了输出目录，则进行设置
+    if args.output_dir:
+        server.set_output_dir(args.output_dir)
+
+    # 打印配置信息
+    print("MinerU File转Markdown转换服务启动...")
+    if args.transport in ["sse", "streamable-http"]:
+        print(f"服务器地址: {args.host}:{args.port}")
+    print("按 Ctrl+C 可以退出服务")
+
+    server.run_server(mode=args.transport, port=args.port, host=args.host)
+
+
+if __name__ == "__main__":
+    main()

projects/mcp/src/mineru/config.py

+"""MinerU File转Markdown转换服务的配置工具。"""
+
+import os
+import logging
+from pathlib import Path
+from dotenv import load_dotenv
+
+# 从 .env 文件加载环境变量
+load_dotenv()
+
+# API 配置
+MINERU_API_BASE = os.getenv("MINERU_API_BASE", "https://mineru.net")
+MINERU_API_KEY = os.getenv("MINERU_API_KEY", "")
+
+# 本地API配置
+USE_LOCAL_API = os.getenv("USE_LOCAL_API", "").lower() in ["true", "1", "yes"]
+LOCAL_MINERU_API_BASE = os.getenv("LOCAL_MINERU_API_BASE", "http://localhost:8080")
+
+# 转换后文件的默认输出目录
+DEFAULT_OUTPUT_DIR = os.getenv("OUTPUT_DIR", "./downloads")
+
+
+# 设置日志系统
+def setup_logging():
+    """
+    设置日志系统，根据环境变量配置日志级别。
+
+    Returns:
+        logging.Logger: 配置好的日志记录器。
+    """
+    # 获取环境变量中的日志级别设置
+    log_level = os.getenv("MINERU_LOG_LEVEL", "INFO").upper()
+    debug_mode = os.getenv("MINERU_DEBUG", "").lower() in ["true", "1", "yes"]
+
+    # 如果设置了debug_mode，则覆盖log_level
+    if debug_mode:
+        log_level = "DEBUG"
+
+    # 确保log_level是有效的
+    valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+    if log_level not in valid_levels:
+        log_level = "INFO"
+
+    # 设置日志格式
+    log_format = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+    # 配置日志
+    logging.basicConfig(level=getattr(logging, log_level), format=log_format)
+
+    logger = logging.getLogger("mineru")
+    logger.setLevel(getattr(logging, log_level))
+
+    # 输出日志级别信息
+    logger.info(f"日志级别设置为: {log_level}")
+
+    return logger
+
+
+# 创建默认的日志记录器
+logger = setup_logging()
+
+
+# 如果输出目录不存在，则创建它
+def ensure_output_dir(output_dir=None):
+    """
+    确保输出目录存在。
+
+    Args:
+        output_dir: 输出目录的可选路径。如果为 None，则使用 DEFAULT_OUTPUT_DIR。
+
+    Returns:
+        表示输出目录的 Path 对象。
+    """
+    output_path = Path(output_dir or DEFAULT_OUTPUT_DIR)
+    output_path.mkdir(parents=True, exist_ok=True)
+    return output_path
+
+
+# 验证 API 配置
+def validate_api_config():
+    """
+    验证是否已设置所需的 API 配置。
+
+    Returns:
+        dict: 配置状态。
+    """
+    return {
+        "api_base": MINERU_API_BASE,
+        "api_key_set": bool(MINERU_API_KEY),
+        "output_dir": DEFAULT_OUTPUT_DIR,
+    }

projects/mcp/src/mineru/examples.py

+"""演示如何使用 MinerU File转Markdown客户端的示例。"""
+
+import os
+import asyncio
+from mcp.client import MCPClient
+
+
+async def convert_file_url_example():
+    """从 URL 转换 File 的示例。"""
+    client = MCPClient("http://localhost:8000")
+
+    # 转换单个 File URL
+    result = await client.call(
+        "convert_file_url", url="https://example.com/sample.pdf", enable_ocr=True
+    )
+    print(f"转换结果: {result}")
+
+    # 转换多个 File URL
+    urls = """
+    https://example.com/doc1.pdf
+    https://example.com/doc2.pdf
+    """
+    result = await client.call("convert_file_url", url=urls, enable_ocr=True)
+    print(f"多个转换结果: {result}")
+
+
+async def convert_file_file_example():
+    """转换本地 File 文件的示例。"""
+    client = MCPClient("http://localhost:8000")
+
+    # 获取测试 File 的绝对路径
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(os.path.dirname(os.path.dirname(script_dir)))
+    test_file_path = os.path.join(project_root, "test_files", "test.pdf")
+
+    # 转换单个 File 文件
+    result = await client.call(
+        "convert_file_file", file_path=test_file_path, enable_ocr=True
+    )
+    print(f"文件转换结果: {result}")
+
+
+async def get_api_status_example():
+    """获取 API 状态的示例。"""
+    client = MCPClient("http://localhost:8000")
+
+    # 获取 API 状态
+    status = await client.get_resource("status://api")
+    print(f"API 状态: {status}")
+
+    # 获取使用帮助
+    help_text = await client.get_resource("help://usage")
+    print(f"使用帮助: {help_text[:100]}...")  # 显示前 100 个字符
+
+
+async def main():
+    """运行所有示例。"""
+    print("运行 File 到 Markdown 转换示例...")
+
+    # 检查是否设置了 API_KEY
+    if not os.environ.get("MINERU_API_KEY"):
+        print("警告: MINERU_API_KEY 环境变量未设置。")
+        print("使用以下命令设置: export MINERU_API_KEY=your_api_key")
+        print("跳过需要 API 访问的示例...")
+
+        # 仅获取 API 状态
+        await get_api_status_example()
+    else:
+        # 运行所有示例
+        await convert_file_url_example()
+        await convert_file_file_example()
+        await get_api_status_example()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

projects/mcp/src/mineru/language.py

+"""MinerU支持的语言列表。"""
+
+from typing import Dict, List
+
+# 支持的语言列表
+LANGUAGES: List[Dict[str, str]] = [
+    {"name": "中文", "description": "Chinese & English", "code": "ch"},
+    {"name": "英文", "description": "English", "code": "en"},
+    {"name": "法文", "description": "French", "code": "fr"},
+    {"name": "德文", "description": "German", "code": "german"},
+    {"name": "日文", "description": "Japanese", "code": "japan"},
+    {"name": "韩文", "description": "Korean", "code": "korean"},
+    {"name": "中文繁体", "description": "Chinese Traditional", "code": "chinese_cht"},
+    {"name": "意大利文", "description": "Italian", "code": "it"},
+    {"name": "西班牙文", "description": "Spanish", "code": "es"},
+    {"name": "葡萄牙文", "description": "Portuguese", "code": "pt"},
+    {"name": "俄罗斯文", "description": "Russian", "code": "ru"},
+    {"name": "阿拉伯文", "description": "Arabic", "code": "ar"},
+    {"name": "印地文", "description": "Hindi", "code": "hi"},
+    {"name": "维吾尔", "description": "Uyghur", "code": "ug"},
+    {"name": "波斯文", "description": "Persian", "code": "fa"},
+    {"name": "乌尔都文", "description": "Urdu", "code": "ur"},
+    {"name": "塞尔维亚文（latin)", "description": "Serbian(latin)", "code": "rs_latin"},
+    {"name": "欧西坦文", "description": "Occitan", "code": "oc"},
+    {"name": "马拉地文", "description": "Marathi", "code": "mr"},
+    {"name": "尼泊尔文", "description": "Nepali", "code": "ne"},
+    {
+        "name": "塞尔维亚文（cyrillic)",
+        "description": "Serbian(cyrillic)",
+        "code": "rs_cyrillic",
+    },
+    {"name": "毛利文", "description": "Maori", "code": "mi"},
+    {"name": "马来文", "description": "Malay", "code": "ms"},
+    {"name": "马耳他文", "description": "Maltese", "code": "mt"},
+    {"name": "荷兰文", "description": "Dutch", "code": "nl"},
+    {"name": "挪威文", "description": "Norwegian", "code": "no"},
+    {"name": "波兰文", "description": "Polish", "code": "pl"},
+    {"name": "罗马尼亚文", "description": "Romanian", "code": "ro"},
+    {"name": "斯洛伐克文", "description": "Slovak", "code": "sk"},
+    {"name": "斯洛文尼亚文", "description": "Slovenian", "code": "sl"},
+    {"name": "阿尔巴尼亚文", "description": "Albanian", "code": "sq"},
+    {"name": "瑞典文", "description": "Swedish", "code": "sv"},
+    {"name": "西瓦希里文", "description": "Swahili", "code": "sw"},
+    {"name": "塔加洛文", "description": "Tagalog", "code": "tl"},
+    {"name": "土耳其文", "description": "Turkish", "code": "tr"},
+    {"name": "乌兹别克文", "description": "Uzbek", "code": "uz"},
+    {"name": "越南文", "description": "Vietnamese", "code": "vi"},
+    {"name": "蒙古文", "description": "Mongolian", "code": "mn"},
+    {"name": "车臣文", "description": "Chechen", "code": "che"},
+    {"name": "哈里亚纳语", "description": "Haryanvi", "code": "bgc"},
+    {"name": "保加利亚文", "description": "Bulgarian", "code": "bg"},
+    {"name": "乌克兰文", "description": "Ukranian", "code": "uk"},
+    {"name": "白俄罗斯文", "description": "Belarusian", "code": "be"},
+    {"name": "泰卢固文", "description": "Telugu", "code": "te"},
+    {"name": "阿巴扎文", "description": "Abaza", "code": "abq"},
+    {"name": "泰米尔文", "description": "Tamil", "code": "ta"},
+    {"name": "南非荷兰文", "description": "Afrikaans", "code": "af"},
+    {"name": "阿塞拜疆文", "description": "Azerbaijani", "code": "az"},
+    {"name": "波斯尼亚文", "description": "Bosnian", "code": "bs"},
+    {"name": "捷克文", "description": "Czech", "code": "cs"},
+    {"name": "威尔士文", "description": "Welsh", "code": "cy"},
+    {"name": "丹麦文", "description": "Danish", "code": "da"},
+    {"name": "爱沙尼亚文", "description": "Estonian", "code": "et"},
+    {"name": "爱尔兰文", "description": "Irish", "code": "ga"},
+    {"name": "克罗地亚文", "description": "Croatian", "code": "hr"},
+    {"name": "匈牙利文", "description": "Hungarian", "code": "hu"},
+    {"name": "印尼文", "description": "Indonesian", "code": "id"},
+    {"name": "冰岛文", "description": "Icelandic", "code": "is"},
+    {"name": "库尔德文", "description": "Kurdish", "code": "ku"},
+    {"name": "立陶宛文", "description": "Lithuanian", "code": "lt"},
+    {"name": "拉脱维亚文", "description": "Latvian", "code": "lv"},
+    {"name": "达尔瓦文", "description": "Dargwa", "code": "dar"},
+    {"name": "因古什文", "description": "Ingush", "code": "inh"},
+    {"name": "拉克文", "description": "Lak", "code": "lbe"},
+    {"name": "莱兹甘文", "description": "Lezghian", "code": "lez"},
+    {"name": "塔巴萨兰文", "description": "Tabassaran", "code": "tab"},
+    {"name": "比尔哈文", "description": "Bihari", "code": "bh"},
+    {"name": "迈蒂利文", "description": "Maithili", "code": "mai"},
+    {"name": "昂加文", "description": "Angika", "code": "ang"},
+    {"name": "孟加拉文", "description": "Bhojpuri", "code": "bho"},
+    {"name": "摩揭陀文", "description": "Magahi", "code": "mah"},
+    {"name": "那格浦尔文", "description": "Nagpur", "code": "sck"},
+    {"name": "尼瓦尔文", "description": "Newari", "code": "new"},
+    {"name": "保加利亚文", "description": "Goan Konkani", "code": "gom"},
+    {"name": "梵文", "description": "Sanskrit", "code": "sa"},
+    {"name": "阿瓦尔文", "description": "Avar", "code": "ava"},
+    {"name": "阿瓦尔文", "description": "Avar", "code": "ava"},
+    {"name": "阿迪赫文", "description": "Adyghe", "code": "ady"},
+    {"name": "巴利文", "description": "Pali", "code": "pi"},
+    {"name": "拉丁文", "description": "Latin", "code": "la"},
+]
+
+# 构建语言代码到语言信息的映射字典，便于快速查找
+LANGUAGES_DICT: Dict[str, Dict[str, str]] = {lang["code"]: lang for lang in LANGUAGES}
+
+
+def get_language_list() -> List[Dict[str, str]]:
+    """获取所有支持的语言列表。"""
+    return LANGUAGES
+
+
+def get_language_by_code(code: str) -> Dict[str, str]:
+    """根据语言代码获取语言信息。"""
+    return LANGUAGES_DICT.get(
+        code, {"name": "未知", "description": "Unknown", "code": code}
+    )