# macOS OCR MCP Server
## 项目愿景
提供 macOS 原生 OCR 功能的 MCP 服务器，支持读取图片文本和文本布局分析，为 LLM 应用提供高质量的离线 OCR 能力。利用 macOS 内置的强大 Vision 框架，实现高精度的中文、英文及中英混排识别，无需上传云端或 API Key。
## 架构总览
```mermaid
graph TD
A["(根) macOS OCR MCP Server"] --> B["src"];
B --> C["server.py<br/>MCP 服务器与工具注册"];
B --> D["ocr.py<br/>OCR 核心算法与布局分析"];
B --> E["__init__.py<br/>模块初始化"];
A --> F["requirements.txt<br/>依赖定义"];
A --> G["pyproject.toml<br/>项目配置"];
A --> H["README.md<br/>使用文档"];
A --> I["skills/macos-ocr-helper<br/>Claude Skill 定义"];
click C "./src/server.py" "查看 MCP 服务器实现"
click D "./src/ocr.py" "查看 OCR 核心逻辑"
click E "./src/__init__.py" "查看模块初始化"
click F "./requirements.txt" "查看依赖定义"
click G "./pyproject.toml" "查看项目配置"
click H "./readme.md" "查看使用文档"
click I "./skills/macos-ocr-helper/SKILL.md" "查看 Claude Skill 定义"
```
### 核心技术栈
- **MCP 框架**: FastMCP
- **OCR 引擎**: macOS Vision Framework (VNRecognizeTextRequest)
- **图像处理**: Pillow + NumPy
- **PDF 处理**: Quartz (CGPDFDocument)
- **Python 版本**: >= 3.10
### 系统架构
```
Claude / MCP Client
|
v
[FastMCP Server] (src/server.py)
|
+-- read_image_text()
| |
| v
| [OCR Engine] (src/ocr.py)
| |
| +-- Vision Framework (OCR)
| +-- Block Clustering (布局分析)
| +-- Text Merging (智能合并)
|
+-- read_image_layout()
|
+-- Vision Framework (OCR)
+-- Block Clustering (布局分析)
+-- Style Analysis (样式分析)
```
## 模块索引
| 模块 | 职责 | 语言 | 入口文件 | 扫描状态 |
|------|------|------|----------|----------|
| src | 项目核心代码 - MCP 服务器、OCR 识别、布局分析 | Python | src/server.py | 完整 |
| skills/macos-ocr-helper | | Claude Skill | | 完整 |
## 运行与开发
### 环境要求
- macOS 10.15+ (Catalina) 或更高版本
- Python 3.10+
- 已安装 [uv](https://github.com/astral-sh/uv) (`brew install uv`)
### 安装与使用
#### 快速开始 (使用 uvx)
无需克隆代码仓库，直接通过 `uvx` 运行：
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"macos-ocr": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/wenjiazhu/macos-ocr-mcp.git",
"macos-ocr"
]
}
}
}
```
如需强制更新到最新版本，在 `args` 列表中添加 `"--refresh"` 参数。
#### 本地开发
1. 克隆仓库：
```bash
git clone https://github.com/wenjiazhu/macos-ocr-mcp.git
cd macos-ocr-mcp
```
2. 运行：
```bash
# 运行测试脚本 (输出纯文本)
uv run src/ocr.py path/to/image.png
# 运行 MCP 服务器
uv run src/server.py
```
## 测试策略
项目使用 macOS 内置的 Vision 框架进行 OCR，测试通常通过以下方式：
### 功能测试
1. **直接运行 OCR 测试**：
```bash
uv run src/ocr.py path/to/image.png
```
输出结果：
- 纯文本模式：识别后的文本内容
- 布局模式（默认）：JSON 格式的结构化数据
2. **集成测试**：
- 将服务器配置到 Claude Desktop 中
- 使用提示词示例进行实际场景测试
- 测试不同格式（图片、PDF）
### 测试场景
- 纯文本提取（中文、英文、混合）
- 图片转 Markdown
- 表格提取转 CSV
- 发票/收据结构化提取
- 代码截图识别
- 长文档分析
## 编码规范
项目采用标准 Python 编码规范：
- PEP 8 风格
- 类型提示（Type Hints）
- 使用 uv 进行依赖管理
- 清晰的函数注释
## AI 使用指引
### 工具列表 (Tools)
#### `read_image_text`
识别并提取图片或 PDF 中的纯文本。会自动进行段落合并和表格优化。
- **输入**: `image_path` (图片或 PDF 的绝对路径)
- **输出**: 文本字符串
#### `read_image_layout`
提取结构化的版面信息，专为 LLM 重建文档设计。
- **输入**: `image_path` (图片或 PDF 的绝对路径)
- **输出**: JSON 字符串，包含多个 "Block" 对象。每个 Block 包含：
- `text`: 合并纠错后的语义文本。
- `bbox`: 文本块的归一化坐标 (x, y, w, h)，用于还原排版。
- `type`: 样式类型（"print" 或 "emphasized"）。
- `lines`: 构成该块的原始行信息。
### 提示词示例
#### 1) 快速提取纯文本
```text
请调用 macos-ocr 的 read_image_text 读取以下文件并输出识别结果：
image_path=/绝对路径/xxx.png
要求：
1. 只输出 OCR 文本本身，不要添加解释、标题或多余前后缀。
2. 尽量保留原有换行与段落；不要翻译，不要总结。
```
#### 2) 图片/PDF → Markdown
```text
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/xxx.pdf
然后将返回的 blocks 按 bbox 近似还原为 Markdown：
- 标题/小标题、段落、列表分别用合适的 Markdown 语法表示
- 识别出表格时输出为 Markdown 表格（必要时补齐空单元格）
- 多页内容用清晰的分页分隔（例如：--- Page 1 ---）
只输出最终 Markdown，不要输出中间 JSON。
```
#### 3) 扫描表格 → CSV
```text
请调用 macos-ocr 的 read_image_layout 读取以下文件：
image_path=/绝对路径/table.png
目标：把图片中的"表格"转换成 CSV。
要求：
1. 只输出 CSV（逗号分隔），不要额外解释。
2. 保留表头；不要丢列或丢行；空单元格也要保留为空。
3. 如果存在合并单元格：优先用空值或重复值保证列数一致，并在 CSV 末尾另起一行用 NOTE: 简要说明处理方式。
```
#### 4) 发票/收据 → 结构化 JSON
```text
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/receipt.jpg
请将识别内容抽取为严格 JSON（只输出 JSON）：
{
"merchant": string|null,
"date": "YYYY-MM-DD"|null,
"currency": string|null,
"total": number|null,
"tax": number|null,
"items": [{"name": string, "qty": number|null, "unit_price": number|null, "amount": number|null}],
"payment_method": string|null,
"invoice_no": string|null
}
规则：金额统一用数字；无法确认就填 null；不要编造。
```
#### 5) 代码/终端截图 → 可复制代码块
```text
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/code.png
把结果整理成一个 Markdown 代码块输出：
1. 去掉行号、提示符（如 $、>>>）等无关字符
2. 修正常见 OCR 错误（如 0/O、1/l/I、:;、引号、括号配对）
3. 保持原有缩进
只输出代码块（例如 ```python ... ```），不要额外解释。
```
#### 6) 论文/合同扫描件 → 结构化提纲
```text
请调用 macos-ocr 的 read_image_text 读取以下文件：
image_path=/绝对路径/doc.png
基于 OCR 文本输出：
1) 结构化提纲（H1/H2/H3）
2) "关键点"列表（最多 10 条）
3) "需要人工确认的疑点/缺失"列表（例如数字不清、条款编号断裂）
要求：不要杜撰；引用原文时用原句；输出用中文。
```
### 工具选择指南
- **使用 `read_image_text`**：
- 只需要纯文本内容
- 快速提取可复制文本
- 进行文本搜索、内容分析或总结
- **使用 `read_image_layout`**：
- 需要保留或重建文档布局
- 处理复杂文档（表格、多栏）
- 需要定位文本位置
- 转换为结构化格式（CSV、Markdown）
## 变更记录 (Changelog)
### 2026-01-18
- 完成项目架构扫描与文档生成
- 识别出核心模块：src/server.py 和 src/ocr.py
- 文档涵盖项目愿景、架构、运行说明、AI 使用指引等内容
- 更新 src 模块文档，补充核心算法说明
### 之前的变更
- 2025年12月：为 OCR 文本块添加样式分析，以区分印刷体和强调文本，并引入 Pillow 和 NumPy 依赖
- 实现智能区块聚合，优化表格和段落识别
- 支持多语言识别（中文简繁/英文）
- 集成 macOS Vision 框架实现离线 OCR
