unlimited-ocr-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

把百度的 Unlimited-OCR 模型封装成 MCP 工具，让 Claude Code 能识别任意图片中的文字。本地推理、无调用配额、无 API 费用。整套链路必须在本机 GPU 上运行。 我在Windows 11 + RTX5070TI LAPTOP，使用Python 3.12.3，CUDA13.2，测试成功。 官网推荐是Python3.12.3 + CUDA12.9。如果使用其他版本，建议看看测试效果。

常用命令

服务必须在 conda 环境 uocr 中运行（Python 3.12.3 + PyTorch/CUDA）。

conda activate uocr

# 1. 启动 OCR 服务(关键,必须常驻。首次下载模型需设镜像)
$env:HF_ENDPOINT = "https://hf-mirror.com"   # PowerShell; bash 用 export
$env:HF_HOME = "your/path/hf/cache" # PowerShell; bash 用 export。换成你自己的缓存目录(如 D:/hf/cache)
python serve_ocr.py

# 2. 验证服务在线(MCP 能用的前提)
curl http://127.0.0.1:10000/v1/models

# 3. 测试 HTTP API(默认图 inputs/test.jpg; --image 指定图; --stream 测流式)
python test_api.py --image inputs/1.jpg

# 4. 命令行直接推理(脱离 MCP,单进程内加载模型并跑一次)
python run_ocr.py --mode single -i inputs/1.jpg -o outputs
python run_ocr.py --mode multi  -i inputs/p1.png inputs/p2.png -o outputs
python run_ocr.py --mode pdf    -i inputs/doc.pdf -o outputs --dpi 300

# 5. 调试脚本:探测 model.infer 的真实返回值类型
python probe_infer.py

MCP server（ocr_mcp_server.py）无需手动启动——Claude Code 通过 .mcp.json 自动拉起。

本项目没有自动化测试框架。test_api.py / probe_infer.py 是手动 smoke-test 脚本,不是 pytest 用例。

架构:两层解耦(改代码前必读)

Claude Code ──MCP(stdio)──> ocr_mcp_server.py ──HTTP /v1/chat/completions──> serve_ocr.py ──> 模型

层	文件	职责
模型服务	serve_ocr.py	启动时一次性加载模型进显存,FastAPI 暴露 OpenAI 兼容 HTTP API(:10000),常驻进程
MCP 网关	ocr_mcp_server.py	把 HTTP API 包装成 MCP 工具 ocr_image / ocr_multi,被 Claude Code 经 stdio 调用

为什么分两层:模型加载耗时数十~上百秒。拆开后模型只在 serve_ocr.py 启动时加载一次,Claude Code / MCP server 重启都不重载模型。这是整个设计的核心不变量,改动时不能破坏。

两个推理分支(参数不同,别混用)

serve_ocr.py 的 run_inference() 按图片数量走不同模型方法:

• 单图 → model.infer(),走 gundam 配置(base_size=1024, image_size=640, crop_mode=True),适合大图切片
• 多图 → model.infer_multi()(image_size=1024),保留跨页上下文