# paddle-ocr-mcp-server

PaddleOCR PP-OCRv6 的 **FastMCP server**：把云端 PaddleOCR 识别能力封装为标准 MCP 工具，任何 MCP 客户端（Claude Code 等）都能通过协议直接调用图片/截图/扫描件里的文字识别。

## 特性

- **一个工具搞定 OCR**：`paddle_ocr(image)`，传入本地路径或 URL，返回识别文本行 + 置信度（JSON）。
- **零第三方依赖的客户端**：`ocr_client.py` 仅用 Python 标准库（urllib / json / base64）实现「提交 → 轮询 → 拉取结果」全流程，可独立复用。
- **可测**：解析逻辑抽成纯函数 `parse_jsonl`，6 个单测覆盖正常 / 空输入 / 异常路径，不联网、不依赖 token。
- **token 走环境变量**：`PADDLEOCR_TOKEN`（已写入 `~/.zshrc`），密钥不进代码不进仓库。

## 快速开始

```bash
cd ~/Code/paddle-ocr-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

# token 从环境变量读取（若新 shell 未继承，先 source ~/.zshrc 或 export）
```

## 运行 / 验证

```bash
# 1) 直接跑 server（stdio，Claude Code 默认传输）
.venv/bin/paddle-ocr-mcp

# 2) 单测（不联网、不依赖 token）
.venv/bin/python -m pytest -q

# 3) 用 MCP inspector 调试（可选）
npx @modelcontextprotocol/inspector .venv/bin/paddle-ocr-mcp
```

## 接入 Claude Code

```bash
claude mcp add paddle-ocr -- .venv/bin/paddle-ocr-mcp
```

之后在 Claude Code 里直接说「识别这张图 xxx.png 里的字」，模型会自动调用 `paddle_ocr` 工具。

## 工具

- `paddle_ocr(image: str) -> str`
  - `image`：图片**本地路径**或 **URL**
  - 返回 JSON 数组 `[{"text": "...", "confidence": 0.99}, ...]`

## 项目结构

```
src/paddle_ocr_mcp/
├── ocr_client.py   # OCR 客户端（提交/轮询/解析），零第三方依赖，纯函数可测
└── server.py       # FastMCP server + @mcp.tool paddle_ocr
tests/              # ocr_client 纯函数单测（不联网）
```

## 开发

```bash
.venv/bin/python -m pytest -v     # 跑测试
.venv/bin/paddle-ocr-mcp --transport sse   # 需要 HTTP 传输时
```