ocular

ocular

为编码 Agent 提供视觉能力。

ocular 是一个 MCP 服务，可让以文本为主的编码 Agent 通过兼容 OpenAI 的视觉模型分析屏幕截图、UI 线框图、终端错误、文档、表格和图表。

它既适用于本地 stdio 使用，也适用于远程 HTTP 部署。对于远程 Agent，图像字节可以通过二进制上传旁路传输，而 MCP 工具调用只需携带轻量的 file_id，避免大型内联 base64 负载。

项目状态： 处于早期阶段，仍在积极迭代。欢迎提供反馈、报告错误、分享集成方案和真实使用体验。

为什么选择 ocular？

编码 Agent 擅长读取源代码，但当重要证据以视觉形式呈现时，往往会丢失上下文：例如布局损坏、终端截图、错误对话框、图表或设计参考。

ocular 会将这些视觉输入转换为结构化数据，供 Agent 推理。

• 面向 Agent 的输出——工具返回结构化 JSON，而非仅用文字描述。
• 8 个专注于视觉的工具——通用分析、OCR、UI 检查、错误诊断、UI 对比、表格提取、图表分析和上传编排。
• 兼容 OpenAI 的提供方接口——将 ocular 指向兼容的多模态端点和模型；可复现测试过的配置记录在提供方兼容性中。
• 适用于远程场景的上传——通过二进制 PUT /upload 流程上传大型图像，并使用内容寻址的 file_id 引用。
• 本地或远程 MCP——本地客户端使用 stdio，托管或私有部署使用 HTTP。
• 缓存与持久化——上传去重，并为重复的 Agent 工作流缓存结果。

工作原理

flowchart LR
    A[Coding agent] -->|MCP tool call| B[ocular]
    C[Image / screenshot] -->|binary upload or base64| B
    B -->|OpenAI-compatible request| D[Vision model]
    D -->|multimodal response| B
    B -->|structured JSON| A

对于远程 HTTP 部署，推荐采用以下路径：

image bytes -> PUT /upload -> file_id -> MCP vision tool -> structured result

请参阅架构，了解上传和缓存模型。

演示

想了解从屏幕截图到编码 Agent 获取证据的完整流程？请阅读端到端演示。

演示介绍了远程图像上传、diagnose_error_screenshot 调用、返回给 Agent 的结构化字段，以及如何将这些证据与代码库上下文结合。示例模型输出明确标注为代表性示例，而非基准测试结果。

快速开始

1. 安装

已发布的 npm 包是 ocular-mcp。它会安装 CLI 命令 ocular。

全局安装：

npm install -g ocular-mcp

也可以不进行全局安装，直接运行：

npx -y ocular-mcp

如需从源代码构建：

git clone https://github.com/xyun1996/ocular.git
cd ocular
npm install
npm run build

2. 配置视觉提供方

ocular 需要兼容 OpenAI 的多模态端点、API 密钥和模型名称：

OCULAR_BASE_URL=https://your-openai-compatible-endpoint.example/v1
OCULAR_API_KEY=your_api_key
OCULAR_MODEL=your_vision_model

对于本地兼容端点，请使用该服务的基础 URL 和支持视觉能力的模型名称。兼容性取决于端点与模型的组合；请参阅提供方兼容性，了解可复现的冒烟测试流程和已验证配置。

3. 以 stdio 模式运行

全局安装后：

ocular

或者：

npx -y ocular-mcp

服务通过 stdio 通信，因此直接启动时可能会看起来处于空闲状态。正常使用时，MCP 客户端会启动该服务，并通过 stdin/stdout 交换协议消息。

4. 连接 MCP 客户端

Claude Code 示例：

claude mcp add ocular \
  -e OCULAR_BASE_URL=https://your-openai-compatible-endpoint.example/v1 \
  -e OCULAR_MODEL=your_vision_model \
  -e OCULAR_API_KEY=your_api_key \
  -- npx -y ocular-mcp

在共享机器上，避免将长期有效的 API 密钥直接写入 shell 历史记录。请尽可能使用客户端的环境变量或密钥管理机制。

对于通用 MCP 客户端：

{
  "mcpServers": {
    "ocular": {
      "command": "npx",
      "args": ["-y", "ocular-mcp"],
      "env": {
        "OCULAR_BASE_URL": "https://your-openai-compatible-endpoint.example/v1",
        "OCULAR_MODEL": "your_vision_model",
        "OCULAR_API_KEY": "your_api_key"
      }
    }
  }
}

如需更完整的操作指南，请参阅 Claude Code 设置。

示例工作流

诊断屏幕截图

请编码 Agent 检查错误屏幕截图，并提取准确的错误消息、可能的原因以及接下来要进行的检查。

{
  "file_id": "e21ba723...",
  "task": "Extract the exact error and suggest the next debugging checks",
  "project_context": "Node.js TypeScript project"
}

审查 UI 实现

使用 analyze_ui_screenshot 将屏幕截图转化为面向实现的观察结果，涵盖层级、对齐、间距、排版、对比度和可能的视觉缺陷。

比较预期与实际 UI

使用 compare_ui_screenshots，通过参考屏幕截图和实现截图找出回归问题和布局差异。

请参阅屏幕截图调试示例。

工具

工具	用途
analyze_image	通用结构化图像分析
extract_text_from_image	具备阅读顺序和布局感知能力的 OCR
analyze_ui_screenshot	UI 层级、间距、排版和无障碍审查
diagnose_error_screenshot	提取并诊断终端、浏览器或构建错误
compare_ui_screenshots	比较参考屏幕截图和实现截图
extract_table_from_image	将表格数据提取为结构化输出
analyze_chart_image	分析图表标签、数值、趋势和不确定性
create_upload_session	为远程客户端返回上传端点和说明

每个视觉工具都接受 file_id；在适用情况下，本地工作流也可以使用内联 image_base64。

远程部署

设置 HTTP 传输和身份验证：

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp
MCP_AUTH_TOKEN=replace_with_a_long_random_token
MCP_AUTH_HEADER=authorization
MCP_AUTH_SCHEME=Bearer

上传原始字节：

curl --request PUT \
  --data-binary @/path/to/image.png \
  "https://your.host/upload" \
  -H "Content-Type: image/png" \
  -H "Authorization: Bearer your_mcp_auth_token"

服务会返回一个内容寻址的 file_id；请将该 id 传递给视觉工具，而不是通过 MCP 发送很大的 base64 字符串。

有关反向代理和 systemd 示例，请参阅部署。

配置

常用变量：

变量	用途
OCULAR_BASE_URL	OpenAI 兼容的 API 基础 URL
OCULAR_API_KEY	提供商 API 密钥
OCULAR_MODEL	支持视觉功能的模型名称
OCULAR_HEADERS	可选的自定义提供商标头，格式为 JSON
OCULAR_TEMPERATURE	生成温度
OCULAR_MAX_TOKENS	生成的最大 token 数
OCULAR_TIMEOUT_MS	提供商超时时间
OCULAR_MAX_IMAGE_MB	最大图像大小
OCULAR_CACHE_ENABLED	启用结果缓存
OCULAR_CACHE_DIR	缓存目录
OCULAR_UPLOADS_DIR	持久化上传目录
OCULAR_UPLOAD_URL_BASE	上传说明中使用的公共基础 URL

完整配置项请参阅 .env.example。

验证与基准测试

提供商兼容性声明基于对真实端点和模型进行的冒烟测试，而非仅凭 API 名称判断。请参阅提供商兼容性。

该代码库还包含可重复使用且可再分发的合成视觉测试样例，用于进行可重复的项目级测量。请参阅基准测试样例。基准测试会测量执行情况、结构化 JSON 输出和耗时；它并非旨在广泛评比模型质量。

开发

npm install
npm run build
npm test
npm run check
npm run dev

该代码库包含针对身份验证、缓存、图像处理、MCP 服务行为、提供商负载、工具执行、npm 打包、Registry 元数据一致性和发布冒烟检查的测试。

安全与隐私

请勿提交提供商 API 密钥或 MCP 身份验证令牌。公共 HTTP 部署应置于 HTTPS 和反向代理之后；Node 进程通常应绑定到私有接口。

有关漏洞报告指南，请参阅 SECURITY.md。

路线图

近期欢迎贡献的方向：

• 真实场景下的 MCP 客户端集成和使用报告
• 提供方／模型兼容性验证
• 基于真实端点发布的 fixture 基准测试结果
• 由社区推动的工具和提示词改进

如果你在真实工作流中使用 ocular，请提交一个 使用报告 issue，说明客户端、提供方／模型和使用场景。即使没有出现问题，公开报告也很有帮助，有助于确保兼容性和采用情况的说法有真实使用作为依据。

贡献

欢迎贡献。请先阅读 CONTRIBUTING.md，在提交 PR 前运行 npm run check，并在行为变更时附上复现详情。

发布和注册表

npm 包名为 ocular-mcp；安装后的 CLI 为 ocular。发布自动化使用 npm Trusted Publishing，而不是长期有效的仓库令牌。请参阅 发布。

ocular 已作为 io.github.xyun1996/ocular 发布到官方 MCP Registry。请参阅 MCP Registry，了解当前身份和发布流程。

许可证

MIT —— 请参阅 LICENSE。

如果 ocular 对你的 Agent 工作流有帮助，请在 GitHub 上点个星，帮助其他开发者发现这个项目。