内容
# Umi-OCR MCP Server
通过 MCP 协议将 [Umi-OCR v2](https://github.com/hiroi-sora/Umi-OCR) 本地 OCR 能力暴露给 AI Agent（Hermes、Claude Code、Codex 等）。
自动拉起 Umi-OCR 进程，无需手动启动服务。
## 目录结构
```
Umi-OCR-MCP/
├── server.py # MCP 服务器（核心）
├── pyproject.toml # 依赖声明（uv run 自动安装）
├── requirements.txt # pip 依赖声明（备选）
├── config.yaml # Hermes config 接入模板
└── README.md
```
## 前置要求
| 依赖 | 说明 |
|------|------|
| Umi-OCR v2.1.5+ | 前往 [umi-ocr.com](https://umi-ocr.com/zh-CN/download) 下载 **Paddle 版（推荐）**，安装后开启 HTTP API（设置 -> 服务 -> 启用 HTTP API，默认端口 1224） |
| Python 3.11+ | 推荐通过 uv 管理 |
| uv | 包管理器，用于 `uv run` 自动安装依赖 |
## 快速开始
### 1. 确认 Umi-OCR 路径
默认路径：`YOUR_UMI_OCR_PATH\Umi-OCR.exe`
如不同，通过环境变量 `UMI_OCR_EXE` 指定。
> Windows 注意：路径中含中文/空格/特殊字符时，确保在 YAML 和环境变量中正确转义。
### 2. 测试 MCP 服务
```bash
cd YOUR_PROJECT_PATH\Umi-OCR-MCP
uv run server.py
```
首次运行 `uv run` 会自动读取 `pyproject.toml`，创建临时虚拟环境并安装 `mcp`、`requests` 依赖。
### 3. 接入 Hermes Agent
将 `config.yaml` 内容合并到 Hermes 的 `config.yaml` 的 `mcp_servers` 段：
```yaml
mcp_servers:
umi-ocr-mcp:
command: uv
args:
- run
- --directory
- YOUR_PROJECT_PATH/Umi-OCR-MCP
- YOUR_PROJECT_PATH/Umi-OCR-MCP/server.py
env:
UMI_OCR_URL: "http://127.0.0.1:1224/api/ocr"
UMI_OCR_EXE: "YOUR_UMI_OCR_PATH\\Umi-OCR.exe"
```
> 关键：`--directory` 参数告诉 uv 到哪里找 `pyproject.toml`，**不能省略**。缺了它 uv 找不到依赖，直接报 ModuleNotFoundError。
> 路径格式：推荐正斜杠 `D:/path/to/`。反斜杠在 YAML 中需转义为 `D:\\path\\to\\`。
## 工作原理
```
AI Agent -> MCP stdio -> server.py
1. 检测端口 1224 是否开放
2. 未开放 -> 自动启动 Umi-OCR.exe（指数退避等待，最长 30s）
3. 开放 -> 调用 HTTP API 识别图片
4. OCR 文本 -> 置信度过滤（>0.85）
5. 轻量后处理（常见 OCR typo 修正）
6. 返回纯文本给 Agent
```
### 服务保活
每次调用 `extract_text_umi_v2` 时自动检测端口。Umi-OCR 进程意外退出后，下一次调用会自动重新拉起，无需手动干预。
### 后处理规则
内置正则替换，修正无歧义的 OCR 常见错误（不影响 AI 理解的不修）：
| 原始 | 修正 |
|------|------|
| packspace | backspace |
| AMDV | AMD-V |
| Windows102004 | Windows 10 2004 |
| 打并 | 打开 |
| 重新新 | 重新 |
后处理仅修正**可确定**的 OCR 噪声，超出规则范围的保留原样交由 AI 阅读理解。
## 常见问题
### ModuleNotFoundError: No module named 'requests'
uv run 默认隔离环境，看不到全局包。
**解决**：项目已含 `pyproject.toml`，确保用 `uv run --directory <项目目录>` 启动，uv 会自动安装依赖。
### Umi-OCR 启动超时
- 检查 `UMI_OCR_EXE` 路径是否正确
- 首次启动 Umi-OCR 需加载 PaddleOCR 模型，较慢机器可能需 15-30 秒
- 可在 Umi-OCR 设置中开启"开机自启"或"最小化到托盘"避免每次等待
### API 返回错误码
Umi-OCR v2 API 格式：
```
POST /api/ocr
{"base64": "<base64字符串>"}
```
返回：
```json
{"code": 100, "data": [{"text":"...","score":0.99}], "msg":"success"}
```
- code=100: 成功
- code=300: Base64 解码失败（传了数组而非字符串）
- code=802: 缺少 base64 字段
### 其他电脑部署
1. 安装 uv
2. 安装 Umi-OCR（从 [umi-ocr.com](https://umi-ocr.com/zh-CN/download) 下载 Paddle 版）并开启 HTTP API（端口 1224）
3. 修改 `config.yaml` 和 `server.py` 中的默认路径
4. 确认端口 1224 未被占用
5. 首次 `uv run` 需联网自动下载依赖
## API 参考
### 工具总览
| 工具 | 用途 | 类别 | Token 特点 |
|------|------|------|-----------|
| `quick_ocr_status` | 极简服务状态 | 检查 | 仅 ~5 字符输出 |
| `check_ocr_status` | 完整服务状态 | 检查 | ~200 字符输出 |
| `extract_text_umi_v2` | 单张图片 OCR | 核心 | 标准输出 |
| `ocr_image_base64` | Base64 直接 OCR | 核心 | 免去写文件步骤 |
| `ocr_batch` | 多张图片批量 OCR | 批量 | 一次调用处理多图 |
| `ocr_directory` | 目录扫描批量 OCR | 批量 | 免去 list + 构建清单 |
| `ocr_pdf_page` | PDF 单页直接 OCR | PDF | 免去渲染 + 存文件步骤 |
### quick_ocr_status
极简状态检查，适用于高频轮询。
```
参数:
无
返回:
"running" | "stopped" | "error: ..."
```
**Token 对比**：~5 chars vs `check_ocr_status` 的 ~200 chars，省 97%。
### check_ocr_status
完整服务状态信息。
```
参数:
无
返回:
服务运行状态、监听地址、API 端点、可执行文件路径
```
### extract_text_umi_v2
OCR 提取本地图片文本。内置段落合并与置信度过滤。
```
参数:
file_path: str -- 图片绝对路径（必填）
is_handwritten: bool -- 是否手写笔记，默认 False
返回:
str -- 识别文本，或错误信息
```
### ocr_image_base64
直接从 Base64 编码的图片提取文本，省去写文件步骤。
```
参数:
image_base64: str -- Base64 编码字符串（含 data URL 前缀亦可）
is_handwritten: bool -- 是否手写笔记，默认 False
返回:
str -- 识别文本，或错误信息
```
### ocr_batch
批量 OCR 多张本地图片，一次调用返回所有结果。
```
参数:
file_paths: List[str] -- 图片绝对路径列表
is_handwritten: bool -- 是否手写笔记，默认 False
返回:
str -- 按输入顺序的分隔线分区结果
```
### ocr_directory ⭐ v1.1 新增
扫描目录下所有图片并批量 OCR。递归模式下可处理子目录。
```
参数:
directory_path: str -- 目录绝对路径（必填）
extensions: str -- 逗号分隔的扩展名，默认 "png,jpg,jpeg,bmp,webp"
recursive: bool -- 是否递归子目录，默认 False
is_handwritten: bool -- 是否手写笔记，默认 False
confidence_threshold: float -- 置信度阈值，默认 0.85
返回:
str -- 紧凑格式：[总数] + 文件名 + 文本
```
### ocr_pdf_page ⭐ v1.1 新增
直接渲染 PDF 指定页为图像并 OCR，一步到位。依赖 PyMuPDF。
```
参数:
pdf_path: str -- PDF 文件绝对路径（必填）
page_number: int -- 页码（1-based），默认 1
is_handwritten: bool -- 是否手写笔记，默认 False
dpi: int -- 渲染分辨率，默认 200
confidence_threshold: float -- 置信度阈值，默认 0.85
返回:
str -- 识别文本，或错误信息
```
### 置信度阈值说明
所有 OCR 工具内部使用 `confidence_threshold` 过滤低质量结果。
需直接控制时使用新工具暴露的参数：
| 场景 | 推荐阈值 | 说明 |
|------|---------|------|
| 清晰印刷体 | 0.90+ | 极高精度，宁缺毋滥 |
| 标准文档 | 0.85 (默认) | 精度与召回平衡 |
| 扫描版教辅 | 0.70-0.80 | 纸张质量不一，需更高包容度 |
| 手写笔记 | 0.60-0.75 | 手写体识别率天然较低 |
## MCP 固定指令（Prompts）
MCP 协议支持 **Prompts** —— 预定义的固定指令模板。
Agent 通过专用工具 `get_prompt(name)` 调取，返回标准化的分步工作流指令。
server.py 已内置 3 个 Prompt，覆盖最常用的 OCR 场景。
### 在 Hermes 中调用
重启 MCP 连接后，Hermes 会自动注册 `mcp__umi_ocr__get_prompt` 工具。
调用方式：
```
# 列出所有可用 Prompt
mcp__umi_ocr__list_prompts()
# 调取特定 Prompt
mcp__umi_ocr__get_prompt(name="ocr-workflow-quick")
```
Prompts 返回的是**指令文本**（非执行结果），Agent 读取后按步骤调用对应的 Tool 完成实际 OCR。
---
### ocr-workflow-quick
**单张图片快速 OCR 标准流程。**
| 步骤 | 操作 | 工具 |
|------|------|------|
| 1 | 确认服务在线 | `quick_ocr_status` |
| 2 | 提取文本 | `extract_text_umi_v2(file_path)` |
| 3 | 质量不足 → 降阈值重试 | `extract_text_umi_v2(..., confidence_threshold=0.65)` |
适用：截图、单张试卷照片、板书拍照。
---
### ocr-workflow-pdf
**PDF 逐页 OCR 标准流程。**
| 步骤 | 操作 | 工具 |
|------|------|------|
| 1 | 确认服务在线 | `quick_ocr_status` |
| 2 | OCR 首页试探质量 | `ocr_pdf_page(pdf_path, page_number=1)` |
| 3 | 文字模糊 → 提高 DPI 到 300 | `ocr_pdf_page(..., dpi=300)` |
| 4 | 漏字严重 → 降阈值到 0.70 | `ocr_pdf_page(..., confidence_threshold=0.70)` |
| 5 | 质量 OK → 逐页提取 | 循环 `ocr_pdf_page(pdf_path, page_number=N)` |
适用：扫描版高考真题 PDF、电子教辅、论文。
---
### ocr-workflow-batch
**整本教辅/试卷批量 OCR 标准流程。**
| 步骤 | 操作 | 工具 |
|------|------|------|
| 1 | 确认服务在线 | `quick_ocr_status` |
| 2 | 扫描目录下所有图片 | `ocr_directory(dir, recursive=true)` |
| 3 | 抽查 2-3 个结果 | 人工或 Agent 判断质量 |
| 4 | 个别失败 → 单独重试 | `extract_text_umi_v2(path, confidence_threshold=0.65)` |
| 5 | 拼接为完整文档 | 按文件名排序合并 |
适用：按页扫描后存为多张图片的整本教材、多页试卷合集。
