zh-ocr-mcp

# ZH OCR MCP-Server ## 1. 概述 这个项目提供了一个 **ZH OCR MCP 服务器** (`zh-ocr-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 zh-ocr-mcp==1.0.0 ``` 目前版本：1.0.0 这种方式适用于不需要修改源代码的普通用户。 ### 3.2 从源码安装 如果你需要修改源代码或进行开发，可以从源码安装。 克隆仓库并进入项目目录： ```bash git clone <repository-url> # 替换为你的仓库 URL cd zh-ocr-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 密…