Merge remote-tracking branch 'origin/dev' into dev

.github/workflows/cli.yml

@@ -31,9 +31,9 @@ jobs:
         conda env list
         pip show coverage
         cd $GITHUB_WORKSPACE && sh tests/retry_env.sh
-        cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
-        cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
-        cd $GITHUB_WORKSPACE && python tests/get_coverage.py
+        # cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
+        # cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
+        # cd $GITHUB_WORKSPACE && python tests/get_coverage.py
         cd $GITHUB_WORKSPACE && pytest -m P0 -s -v tests/test_cli/test_cli_sdk.py
 
   notify_to_feishu:

.github/workflows/huigui.yml

@@ -30,9 +30,9 @@ jobs:
         conda env list
         pip show coverage
         cd $GITHUB_WORKSPACE && sh tests/retry_env.sh
-        cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
-        cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
-        cd $GITHUB_WORKSPACE && python tests/get_coverage.py
+        # cd $GITHUB_WORKSPACE && python tests/clean_coverage.py      
+        # cd $GITHUB_WORKSPACE && coverage run -m pytest tests/unittest/ --cov=magic_pdf/  --cov-report html --cov-report term-missing
+        # cd $GITHUB_WORKSPACE && python tests/get_coverage.py
         cd $GITHUB_WORKSPACE && pytest -s -v tests/test_cli/test_cli_sdk.py
 
   notify_to_feishu:

.github/workflows/python-package.yml

@@ -82,7 +82,7 @@ jobs:
     - name: Install mineru
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[all]
+        pip install -e .[core]
 
   build:
     needs: [ check-install ]

SECURITY.md

+# Security Policy
+
+## Supported Versions
+
+latest
+
+## Reporting a Vulnerability
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+Instead, please report them at https://github.com/opendatalab/MinerU/security.
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+## Preferred Languages
+
+We prefer all communications to be in English and Chinese.
+
+## Policy
+
+We will fix security issues in the project's own code as quickly as possible. Before the project completes the fix, you must not disclose the vulnerability information to any public platform.

mineru/cli/models_download.py

@@ -42,9 +42,8 @@ def download_and_modify_json(url, local_filename, modifications):
 
 def configure_model(model_dir, model_type):
     """配置模型"""
-    # json_url = 'https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/mineru.template.json'
-    json_url = 'https://gcore.jsdelivr.net/gh/myhloli/Magic-PDF@dev/mineru.template.json'
-    config_file_name = 'mineru.json'
+    json_url = 'https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/mineru.template.json'
+    config_file_name = os.getenv('MINERU_TOOLS_CONFIG_JSON', 'mineru.json')
     home_dir = os.path.expanduser('~')
     config_file = os.path.join(home_dir, config_file_name)
 
@@ -120,13 +119,13 @@ def download_models(model_source, model_type):
             click.echo(f"Downloading model: {model_path}")
             download_finish_path = auto_download_and_get_model_root_path(model_path, repo_mode='pipeline')
         click.echo(f"Pipeline models downloaded successfully to: {download_finish_path}")
-        configure_model(download_finish_path, model_type)
+        configure_model(download_finish_path, "pipeline")
 
     def download_vlm_models():
         """下载VLM模型"""
         download_finish_path = auto_download_and_get_model_root_path("/", repo_mode='vlm')
         click.echo(f"VLM models downloaded successfully to: {download_finish_path}")
-        configure_model(download_finish_path, model_type)
+        configure_model(download_finish_path, "vlm")
 
     try:
         if model_type == 'pipeline':

mineru/version.py

-__version__ = "2.0.0"
\ No newline at end of file
+__version__ = "2.0.1"

projects/README.md

@@ -8,4 +8,4 @@
 - Projects not yet compatible with version 2.0:
   - [web_api](./web_api/README.md): Web API based on FastAPI
   - [multi_gpu](./multi_gpu/README.md): Multi-GPU parallel processing based on LitServe
-
+  - [mcp](./mcp/README.md): MCP server based on the official API

projects/README_zh-CN.md

@@ -8,3 +8,4 @@
 - 未兼容2.0版本的项目列表
   - [web_api](./web_api/README.md): 基于 FastAPI 的 Web API 
   - [multi_gpu](./multi_gpu/README.md): 基于 LitServe 的多 GPU 并行处理
+  - [mcp](./mcp/README.md): 基于官方api的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==1.0.0
+```
+
+目前版本：1.0.0
+
+这种方式适用于不需要修改源代码的普通用户。
+
+### 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 模式
+

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 = "1.0.0"
+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,
+    }