# Vision-OCR-MCP

本项目提供一个 MCP OCR 服务，工具名为 `ocr_image`，用于识别本地图片文字。

新增 `ocr_region_by_description`，支持按文本描述在大图/PDF 页面中定位局部区域并 OCR。

新增 `ocr_region_by_bbox`，支持通过对角坐标直接框选区域 OCR。

## 1. 运行要求

- Python 3.10+
- 可用的多模态模型 API（支持 `zhipu` 或 `openai_compatible`）
- 支持图片格式：`.jpg` `.jpeg` `.png` `.webp`
- 区域 OCR 额外支持：`.bmp` `.tif` `.tiff` `.gif` `.pdf`

## 2. 安装步骤

在项目根目录执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

## 3. 配置模型提供方

默认读取项目根目录 `.env.example`，也支持同名环境变量。

### 方式 A：zhipu（示例）

```text
OCR_PROVIDER=zhipu
ZHIPUAI_API_KEY=<YOUR_ZHIPUAI_API_KEY>
ZHIPUAI_MODEL=glm-4v-flash
```

### 方式 B：openai_compatible

```text
OCR_PROVIDER=openai_compatible
OCR_API_KEY=<YOUR_API_KEY>
OCR_BASE_URL=https://your-provider.example/v1
OCR_MODEL=<YOUR_VISION_MODEL>
```

### 缓存配置（可选）

```text
OCR_CACHE_TARGET_KB=300
OCR_CACHE_MAX_ITEMS=30
OCR_CACHE_DIR=.ocr_cache
OCR_CACHE_AGE_COMPRESS=true
OCR_CACHE_AGE_STEP_DAYS=7
OCR_CACHE_AGE_DECAY=0.12
OCR_CACHE_AGE_MIN_RATIO=0.35
```

- `OCR_CACHE_TARGET_KB`：缓存帧压缩目标大小（KB，上限目标值）。
- `OCR_CACHE_MAX_ITEMS`：缓存队列最多保留帧数，超出后自动淘汰最旧帧。
- `OCR_CACHE_DIR`：缓存目录。
- `OCR_CACHE_AGE_COMPRESS`：是否启用按时间衰减压缩。
- `OCR_CACHE_AGE_STEP_DAYS`：每经过多少天降低一个压缩档位。
- `OCR_CACHE_AGE_DECAY`：每个档位的目标大小衰减比例（例如 `0.12` 表示每档再缩小 12%）。
- `OCR_CACHE_AGE_MIN_RATIO`：压缩目标最小比例，避免过度压缩。

如果 `.env.example` 中未配置，则回退读取环境变量。

### 环境变量方式（可选）

当前终端临时生效：

```powershell
$env:OCR_PROVIDER="zhipu"
$env:ZHIPUAI_API_KEY="<YOUR_ZHIPUAI_API_KEY>"
```

持久化到用户环境变量（新终端生效）：

```powershell
setx OCR_PROVIDER "zhipu"
setx ZHIPUAI_API_KEY "<YOUR_ZHIPUAI_API_KEY>"
```

## 4. 本地启动 MCP 服务

```powershell
python server.py
```

或使用：

```powershell
run.bat
```

## 5. 接入 Claude Desktop

编辑配置文件：

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

示例（Windows 路径按实际修改）：

```json
{
   "mcpServers": {
      "VisionOCR": {
         "command": "python",
         "args": ["D:\\Projects\\mcp\\Vision-OCR-mcp-server\\server.py"],
         "env": {
            "OCR_PROVIDER": "zhipu",
            "ZHIPUAI_API_KEY": "<YOUR_ZHIPUAI_API_KEY>"
         }
      }
   }
}
```

保存后重启 Claude Desktop。

## 6. 使用方式

在支持 MCP 的客户端调用以下工具：

| 工具名 | 参数 | 说明 | 调用示例 |
| --- | --- | --- | --- |
| `ocr_image` | `image_path: str \| list[str]` | 对单图或多图执行全文 OCR。 | `ocr_image("D:/images/a.png")`<br>`ocr_image(["D:/images/a.png", "D:/images/b.png"])` |
| `ocr_region_by_description` | `file_path: str, region_description: str, page_number: int = 1` | 根据文本描述先定位区域，再进行局部 OCR，支持图片和 PDF。 | `ocr_region_by_description("D:/images/large.png", "左上角标题区域")`<br>`ocr_region_by_description("D:/docs/report.pdf", "第3段结论框", 2)` |
| `ocr_region_by_bbox` | `file_path: str, x1: int, y1: int, x2: int, y2: int, page_number: int = 1` | 通过对角坐标直接框选区域 OCR，支持图片和 PDF。 | `ocr_region_by_bbox("D:/images/large.png", 120, 80, 920, 460)`<br>`ocr_region_by_bbox("D:/docs/report.pdf", 100, 120, 430, 280, 2)` |
| `ocr_cached_frames_summary` | `max_frames: int = 0` | 对缓存帧逐个重新 OCR，结合来源路径、缓存时间、上次 OCR 时间生成统一调查提示词。`0` 表示处理全部缓存帧。 | `ocr_cached_frames_summary()`<br>`ocr_cached_frames_summary(10)` |
| `what_have_you_seen` | `max_frames: int = 10` | 面向自然问法的高触发入口（如“你看见过什么”），内部调用缓存汇总并返回调查提示词。 | `what_have_you_seen()`<br>`what_have_you_seen(20)` |

## 6.1 让模型更容易调用 MCP

优先使用明确的“调用工具”表达，模型命中率更高：

- `请调用 what_have_you_seen，告诉我你看见过什么。`
- `请调用 ocr_cached_frames_summary(20)，整理历史 OCR 证据。`
- `请调用 ocr_region_by_description，对这个 PDF 找标题区域并识别。`

## 7. 已实现能力与限制

- 支持单图/多图 OCR
- 超过 5MB 自动压缩后再上传
- 支持图片格式自动转换后识别（bmp/tiff/gif -> jpeg）
- 支持基于文本描述的区域 OCR（先低分辨率定位，再对局部高分辨率识别）
- 支持对角坐标框选区域 OCR（支持任意两点顺序，自动归一化）
- 历史 OCR 帧自动压缩入缓存，并支持队列淘汰
- 缓存支持按时间分级压缩（越旧压缩越强）
- 支持批量回放缓存帧并生成调查汇总提示词
- 单张本地读取上限 30MB
- 单次最多 10 张图片

## 8. 常见问题

- 报错 `未读取到 ... API_KEY`：检查 `.env.example` 或环境变量中的 key 是否存在。
- 报错 `不支持的文件格式`：仅支持 `.jpg` `.jpeg` `.png` `.webp`。
- 报错 `图片压缩后仍超过 5MB`：请先手动裁剪或降低分辨率。