内容
# Mistral OCR MCP 服务器
本 MCP 服务器为本地文件和公共 URL 提供 Mistral OCR 服务。
## 工具列表
| 工具 | 用途 |
| --- | --- |
| `health_check` | 验证密钥、网络访问、模型名称和输出目录。 |
| `set_api_key` | 为当前 MCP 进程设置一个运行时密钥。 |
| `set_api_keys` | 为自动故障转移设置多个运行时密钥。 |
| `list_pages` | 检查本地文件并返回可用的 PDF 页数。 |
| `ocr_from_file` | 对本地文件进行 OCR 并返回 Markdown 内联。适用于短测试。 |
| `ocr_from_url` | 对公共 URL 进行 OCR 并返回 Markdown 内联。适用于短测试。 |
| `ocr_to_markdown_file` | 对本地文件进行 OCR 并将 Markdown 保存到磁盘。适用于 PDF。 |
| `ocr_url_to_markdown_file` | 对公共 URL 进行 OCR 并将 Markdown 保存到磁盘。 |
## 配置
优先使用多个密钥，以便服务器可以在一个密钥被授权、速率限制或暂时失败时自动切换。
```toml
[mcp_servers.mistral-ocr]
type = "stdio"
command = "uv"
args = ["--directory", 'D:\34728\play\OCR\mistral-ocr-mcp', "run", "server.py"]
[mcp_servers.mistral-ocr.env]
MISTRAL_API_KEYS = "key1,key2,key3"
MISTRAL_OCR_OUTPUT_DIR = 'D:\34728\play\OCR\outputs'
```
单密钥兼容性仍然受支持：
```toml
MISTRAL_API_KEY = "key1"
```
编辑 Codex 配置后，重启 Codex 或重新加载 MCP 工具，以便新的服务器进程看到环境变量。
## 推荐的代理工作流程
1. 调用 `health_check`。
2. 对于本地 PDF，调用 `list_pages`。
3. 对于快速样本，使用 `pages="0"` 调用 `ocr_from_file`。
4. 对于实际工作，调用 `ocr_to_markdown_file` 并读取生成的 `.md`。
示例：
```text
health_check()
list_pages(file_path="D:\docs\paper.pdf")
ocr_to_markdown_file(file_path="D:\docs\paper.pdf", pages="0-3")
```
要保留提取的 PDF 图片，请传递 `include_images=true`。
```text
ocr_to_markdown_file(
file_path="D:\docs\paper.pdf",
pages="0-5",
include_images=true,
image_limit=50,
image_min_size=64
)
```
Markdown 文件将包含相对图片链接，图片文件将保存在名为 `paper_hash_assets/` 的 sibling 文件夹中。
## 本地烟雾测试
```powershell
cd D:\34728\play\OCR\mistral-ocr-mcp
uv sync
$env:MISTRAL_API_KEYS="key1,key2"
.\.venv\Scripts\python.exe -m py_compile server.py test_ocr.py
.\.venv\Scripts\python.exe test_ocr.py "https://arxiv.org/pdf/2201.04234"
```
## 注意事项
- `MISTRAL_API_KEYS` 接受逗号、分号或换行符分隔的密钥。
- HTTP `401`、`403`、`429`、选定的暂时失败和 `5xx` 响应会触发切换到下一个密钥。
- HTTP `400` 通常意味着错误的请求或不支持的文件有效载体，不会触发密钥轮换。
- 保存的 Markdown 使用 UTF-8 编码，并写入 `MISTRAL_OCR_OUTPUT_DIR` 或 `outputs/`（位于 `server.py` 旁边）。
- 缓存文件名包括内容/选项哈希。重新运行相同的 OCR 任务会返回缓存的 Markdown 路径，除非 `use_cache=false`。
- Mistral OCR 单独返回图片和 Markdown。没有 `include_images=true`，服务器只保存文本/表格。有 `include_images=true`，服务器请求 `include_image_base64`，写入图片资产，并重写 Markdown 占位符，例如 `` 为本地相对路径。
