Optical Context MCP

Optical Context MCP

Compress OCR-heavy PDFs into dense packed images so agents can work with long visual documents.

光学上下文MCP是为一项特定任务而构建的：车削 大型、视觉结构化的PDF 转换为一组较小的可检索打包图像，用于代理工作流。

它读取本地PDF，使用Mistral运行OCR，将提取的文本和图形重新组合成密集的PNG，并通过MCP公开这些伪影以进行批量检索。

它的作用

• 从MCP主机读取本地PDF
• 使用Mistral OCR提取页面标记和嵌入图像
• 将内容打包成密集的PNG，以保持视觉分组
• 可选择使用捆绑的技术文档模型来调整嵌入图形的大小
• 存储清单和临时作业工件以供后续检索
• 让代理只提取它需要的打包图像

它适合哪里

将其用于：

• 操作手册
• 扫描手册
• 产品目录
• PDF幻灯片
• 视觉结构化OCR重型文档

跳过它：

• 小PDF
• 纯文本原生PDF，正常提取就足够了
• 需要精确页面忠实渲染的工作流
• OCR成本不合理的情况

示例结果

下图显示了一篇公共研究论文的真实本地验证运行，其中包含密集的文本、数字、图表和页面级视觉结构。右侧的打包图像整合了左侧显示的七个源页面。

生成的清单中的本地运行事实示例：

• 源论文页数：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

• MISTRAL_API_KEY 是必需的 compress_pdf
• 打包的图像始终存储在系统临时目录下的本地
• 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.4 optical-context-mcp

跑

默认传输方式为 stdio:

optical-context-mcp

克劳德代码

在项目中注册服务器：

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文本

• 区段分组
• 表格式布局
• 数字旁边的标题
• 文本与嵌入式图形的视觉邻接

对于许多具有视觉能力的代理来说，这是一种比普通OCR转储更好的中间格式。

当前范围

• 取决于Mistral OCR
• 当前处理本地文件路径，而不是远程上传
• 默认情况下，将工件存储在本地系统临时目录中
• 针对压缩和检索进行了优化，而不是最终的抛光标记生成
• 质量取决于OCR质量和源文档的视觉密度
• 当ML运行时不存在时，自适应大小安全地回落到固定的中等图像大小

路线图

• 使OCR层提供者不可知，这样不同的OCR后端就可以在同一MCP工作流后交换

发展

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