Optical Context MCP

Optical Context MCP

将 OCR 内容繁多的 PDF 压缩为密集拼接图像，方便 Agent 处理篇幅较长的视觉文档。

Optical Context MCP 专为一项任务打造：将篇幅较长、视觉结构丰富的 PDF转换成一组更精简、可检索的拼接图像，供 Agent 工作流使用。

它会读取本地 PDF，使用 Mistral 执行 OCR，将提取的文本和图表重新编排为密集的 PNG 图像，并通过 MCP 提供这些内容，以便批量检索。

功能

• 从 MCP 主机读取本地 PDF
• 使用 Mistral OCR 提取页面 Markdown 和嵌入图像
• 将这些内容拼接成密集的 PNG 图像，同时保留视觉分组
• 可选地使用随附的技术文档模型调整嵌入图表的尺寸
• 保存清单和临时任务文件，供后续检索
• 让 Agent 仅提取所需的拼接图像

适用场景

适用于：

• 操作手册
• 扫描版手册
• 产品目录
• PDF 幻灯片
• 视觉结构丰富、OCR 内容繁多的文档

不适用于：

• 篇幅很短的 PDF
• 可直接提取文本、无需其他处理的 PDF
• 需要严格忠实于原始页面的工作流
• OCR 成本不划算的场景

示例结果

下图展示了对一篇公开研究论文进行的真实本地验证运行。论文包含大量文本、图表和页面级视觉结构。右侧的拼接图像汇总了左侧显示的 7 个原始页面。

生成的清单中记录了以下本地运行示例信息：

• 源论文页数：22
• 预览的源页面范围：15 至 21
• 提取的图像：30
• 拼接输出图像：6
• 拼接图像示例尺寸：986x1084
• 拼接图像示例文件大小：536,697 bytes

此示例展示了预期的工作流：将篇幅较长、视觉结构丰富的 PDF 压缩为一组更精简、可检索的拼接图像，同时保留源文档的视觉结构。

安装

python -m pip install optical-context-mcp

安装并启用自适应尺寸调整运行时：

python -m pip install "optical-context-mcp[ml]"

无需安装即可运行：

uvx optical-context-mcp

• compress_pdf 需要设置 MISTRAL_API_KEY
• 拼接图像始终保存在系统临时目录下的本地位置
• 默认情况下，compress_pdf 会以内联形式返回最多 30 张拼接图像
• 自适应尺寸调整检查点随软件包提供
• 当 torch 和 torchvision 可用时，会自动启用自适应尺寸调整
• 设置 OPTICAL_CONTEXT_DISABLE_ADAPTIVE_SIZING=1 可强制使用旧版固定尺寸调整
• 设置 OPTICAL_CONTEXT_ADAPTIVE_MODEL_PATH=/path/to/model.pt 可覆盖随软件包提供的检查点

对于固定版本的共享环境：

uvx --from optical-context-mcp==0.1.5 optical-context-mcp

运行

默认传输方式为 stdio：

optical-context-mcp

Claude Code

在项目中注册服务：

claude mcp add -s project optical-context -- uvx optical-context-mcp

典型用法：

1. 调用 compress_pdf
2. 检查返回的清单
3. 使用 get_packed_images 获取拼接图像

MCP 工具

• compress_pdf：运行 OCR 并重新组合，创建一个已存储的作业
• get_job_manifest：加载现有作业的元数据
• get_packed_images：从现有作业中获取一个或多个打包后的 PNG

工作原理

flowchart LR
    A["Local PDF"] --> B["Mistral OCR"]
    B --> C["Page markdown + embedded images"]
    C --> D["Recomposition engine"]
    D --> E["Dense packed PNG images"]
    E --> F["Stored job artifacts"]
    F --> G["Agent fetches manifest or image batches over MCP"]

为什么使用打包图像，而不只是 OCR 文本

• 分节分组
• 类似表格的布局
• 图注靠近图表
• 文本与嵌入图形之间的视觉邻接关系

对于许多具备视觉能力的 Agent 来说，与纯 OCR 文本相比，这是一种更好的中间格式。

当前范围

• 依赖 Mistral OCR
• 目前处理本地文件路径，不处理远程上传
• 默认将生成内容存储在本地系统临时目录中
• 针对压缩和检索进行优化，而非生成最终润色后的 Markdown
• 效果取决于 OCR 质量和源文档的视觉密集程度
• 如果 ML 运行时不可用，自适应尺寸调整会安全地回退到固定的中等图像尺寸

路线图

• 使 OCR 层与提供商无关，从而能够在同一 MCP 工作流中替换不同的 OCR 后端

反馈

在文档工作流中尝试过 Optical Context 吗？你可以通过反馈表单自愿分享哪些方面有用、哪些方面遇到了问题。 请注明软件包版本、MCP 客户端，并简要描述文档类型。请勿附上私人 PDF 或 API 密钥。反馈会公开显示在 GitHub 上。

有关已发布版本之间的变更，请参阅变更日志。

开发

uv venv --python /opt/homebrew/bin/python3.11 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest

发布

确保 pyproject.toml 和 server.json 中的两个版本保持同步。在经过审核的发布提交上运行 Publish PyPI 工作流。该工作流会检查 wheel、针对已安装的发行包运行测试、发布到 PyPI，然后将相同版本发布到 MCP Registry。这两项操作都使用 GitHub OIDC；无需本地发布令牌。如果只有注册表任务失败，请重新运行失败的任务，而不要重新发布不可变的 PyPI 版本。 如果需要修正工作流并重新运行，请选择 registry_only，以重试注册表发布，而不再次上传现有的 PyPI 版本。

从同一提交创建对应的 GitHub Release，并附上工作流的 python-distributions 工件。