{
  "markdown": "# ocular\n\n[![CI](https://github.com/xyun1996/ocular/actions/workflows/ci.yml/badge.svg)](https://github.com/xyun1996/ocular/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/ocular-mcp.svg)](https://www.npmjs.com/package/ocular-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://modelcontextprotocol.io/)\n\n**Vision for coding agents.**\n\n`ocular` is an MCP server that lets text-first coding agents analyze screenshots, UI mockups, terminal errors, documents, tables, and charts through OpenAI-compatible vision models.\n\nIt is designed for both local stdio use and remote HTTP deployments. For remote agents, image bytes can travel through a binary upload side channel while MCP tool calls carry only a lightweight `file_id`, avoiding large inline base64 payloads.\n\n> **Project status:** early-stage and actively evolving. Feedback, bug reports, integrations, and real-world usage reports are welcome.\n\n## Why ocular?\n\nCoding agents are good at reading source code but often lose context when the important evidence is visual: a broken layout, a terminal screenshot, an error dialog, a chart, or a design reference.\n\n`ocular` turns those visual inputs into structured data an agent can reason about.\n\n- **Agent-oriented output** — tools return structured JSON instead of prose-only descriptions.\n- **8 focused vision tools** — general analysis, OCR, UI inspection, error diagnosis, UI comparison, table extraction, chart analysis, and upload orchestration.\n- **OpenAI-compatible provider interface** — point ocular at a compatible multimodal endpoint and model; reproducibly tested configurations are tracked in [Provider compatibility](docs/provider-compatibility.md).\n- **Remote-friendly uploads** — binary `PUT /upload` flow for large images with content-addressed `file_id` references.\n- **Local or remote MCP** — stdio for local clients, HTTP for hosted/private deployments.\n- **Caching and persistence** — deduplicated uploads plus result caching for repeated agent workflows.\n\n## How it works\n\n```mermaid\nflowchart LR\n    A[Coding agent] -->|MCP tool call| B[ocular]\n    C[Image / screenshot] -->|binary upload or base64| B\n    B -->|OpenAI-compatible request| D[Vision model]\n    D -->|multimodal response| B\n    B -->|structured JSON| A\n```\n\nFor remote HTTP deployments, the recommended path is:\n\n```text\nimage bytes -> PUT /upload -> file_id -> MCP vision tool -> structured result\n```\n\nSee [Architecture](docs/architecture.md) for the upload and caching model.\n\n## Demo\n\nWant to see the full handoff from screenshot to coding-agent evidence? Read the [end-to-end demo](docs/demo.md).\n\nIt walks through a remote image upload, a `diagnose_error_screenshot` call, the structured fields returned to the agent, and how that evidence is combined with repository context. Example model output is explicitly marked representative rather than presented as a benchmark.\n\n## Quick start\n\n### 1. Install\n\nThe published npm package is [`ocular-mcp`](https://www.npmjs.com/package/ocular-mcp). It installs the CLI command `ocular`.\n\nGlobal install:\n\n```bash\nnpm install -g ocular-mcp\n```\n\nOr run it without a global install:\n\n```bash\nnpx -y ocular-mcp\n```\n\nTo build from source instead:\n\n```bash\ngit clone https://github.com/xyun1996/ocular.git\ncd ocular\nnpm install\nnpm run build\n```\n\n### 2. Configure a vision provider\n\n`ocular` requires an OpenAI-compatible multimodal endpoint, API key, and model name:\n\n```env\nOCULAR_BASE_URL=https://your-openai-compatible-endpoint.example/v1\nOCULAR_API_KEY=your_api_key\nOCULAR_MODEL=your_vision_model\n```\n\nFor a local compatible endpoint, use that server's base URL and vision-capable model name. Compatibility depends on the endpoint/model combination; see [Provider compatibility](docs/provider-compatibility.md) for the reproducible smoke-test procedure and verified configurations.\n\n### 3. Run in stdio mode\n\nWith a global install:\n\n```bash\nocular\n```\n\nOr:\n\n```bash\nnpx -y ocular-mcp\n```\n\nThe server communicates over stdio, so it may appear idle when started directly. In normal use an MCP client launches it and exchanges protocol messages over stdin/stdout.\n\n### 4. Connect an MCP client\n\nClaude Code example:\n\n```bash\nclaude mcp add ocular \\\n  -e OCULAR_BASE_URL=https://your-openai-compatible-endpoint.example/v1 \\\n  -e OCULAR_MODEL=your_vision_model \\\n  -e OCULAR_API_KEY=your_api_key \\\n  -- npx -y ocular-mcp\n```\n\nAvoid putting long-lived API keys directly in shell history on shared machines. Use your client's environment/secret-management mechanism when available.\n\nFor a generic MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"ocular\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ocular-mcp\"],\n      \"env\": {\n        \"OCULAR_BASE_URL\": \"https://your-openai-compatible-endpoint.example/v1\",\n        \"OCULAR_MODEL\": \"your_vision_model\",\n        \"OCULAR_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\nSee [Claude Code setup](examples/claude-code.md) for a fuller walkthrough.\n\n## Example workflows\n\n### Diagnose a screenshot\n\nAsk your coding agent to inspect an error screenshot and extract the exact message, likely cause, and next checks.\n\n```json\n{\n  \"file_id\": \"e21ba723...\",\n  \"task\": \"Extract the exact error and suggest the next debugging checks\",\n  \"project_context\": \"Node.js TypeScript project\"\n}\n```\n\n### Review a UI implementation\n\nUse `analyze_ui_screenshot` to turn a screenshot into implementation-oriented observations about hierarchy, alignment, spacing, typography, contrast, and likely visual defects.\n\n### Compare expected vs actual UI\n\nUse `compare_ui_screenshots` with a reference screenshot and an implementation screenshot to identify regressions and layout differences.\n\nSee [Screenshot debugging example](examples/screenshot-debugging.md).\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `analyze_image` | General structured image analysis |\n| `extract_text_from_image` | OCR with reading-order/layout awareness |\n| `analyze_ui_screenshot` | UI hierarchy, spacing, typography and accessibility review |\n| `diagnose_error_screenshot` | Extract and diagnose terminal/browser/build errors |\n| `compare_ui_screenshots` | Compare reference and implementation screenshots |\n| `extract_table_from_image` | Extract table data into structured output |\n| `analyze_chart_image` | Analyze chart labels, values, trends and uncertainty |\n| `create_upload_session` | Return upload endpoint and instructions for remote clients |\n\nEvery vision tool accepts `file_id`; local workflows can also use inline `image_base64` where appropriate.\n\n## Remote deployment\n\nSet HTTP transport and authentication:\n\n```env\nMCP_TRANSPORT=http\nMCP_HTTP_HOST=127.0.0.1\nMCP_HTTP_PORT=3000\nMCP_HTTP_PATH=/mcp\nMCP_AUTH_TOKEN=replace_with_a_long_random_token\nMCP_AUTH_HEADER=authorization\nMCP_AUTH_SCHEME=Bearer\n```\n\nUpload raw bytes:\n\n```bash\ncurl --request PUT \\\n  --data-binary @/path/to/image.png \\\n  \"https://your.host/upload\" \\\n  -H \"Content-Type: image/png\" \\\n  -H \"Authorization: Bearer your_mcp_auth_token\"\n```\n\nThe server returns a content-addressed `file_id`; pass that id to a vision tool instead of sending a large base64 string through MCP.\n\nFor reverse proxy and systemd examples, see [Deployment](docs/deployment.md).\n\n## Configuration\n\nCommon variables:\n\n| Variable | Purpose |\n|---|---|\n| `OCULAR_BASE_URL` | OpenAI-compatible API base URL |\n| `OCULAR_API_KEY` | Provider API key |\n| `OCULAR_MODEL` | Vision-capable model name |\n| `OCULAR_HEADERS` | Optional custom provider headers as JSON |\n| `OCULAR_TEMPERATURE` | Generation temperature |\n| `OCULAR_MAX_TOKENS` | Maximum generated tokens |\n| `OCULAR_TIMEOUT_MS` | Provider timeout |\n| `OCULAR_MAX_IMAGE_MB` | Maximum image size |\n| `OCULAR_CACHE_ENABLED` | Enable result cache |\n| `OCULAR_CACHE_DIR` | Cache directory |\n| `OCULAR_UPLOADS_DIR` | Persistent upload directory |\n| `OCULAR_UPLOAD_URL_BASE` | Public base URL used in upload instructions |\n\nSee [.env.example](.env.example) for the full configuration surface.\n\n## Verification and benchmarks\n\nProvider compatibility claims are based on real endpoint/model smoke tests, not on API naming alone. See [Provider compatibility](docs/provider-compatibility.md).\n\nThe repository also includes synthetic, redistributable visual fixtures for repeatable project-level measurements. See [Benchmark fixtures](bench/README.md). The benchmark measures execution, structural JSON output, and timing; it is not presented as a broad model-quality ranking.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\nnpm run check\nnpm run dev\n```\n\nThe repository includes tests for authentication, caching, image handling, MCP server behavior, provider payloads, tool execution, npm packaging, Registry metadata consistency, and release smoke checks.\n\n## Security and privacy\n\nDo not commit provider API keys or MCP authentication tokens. Public HTTP deployments should sit behind HTTPS and a reverse proxy; the Node process should generally bind to a private interface.\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting guidance.\n\n## Roadmap\n\nNear-term areas where contributions are useful:\n\n- Real-world MCP client integration and usage reports\n- Provider/model compatibility verification\n- Published fixture-based benchmark results from real endpoints\n- Community-driven tool and prompt improvements\n\nIf you are using `ocular` in a real workflow, open a **Usage report** issue describing the client, provider/model, and use case. Public reports are useful even when nothing is broken and help keep compatibility/adoption claims grounded in real usage.\n\n## Contributing\n\nContributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), run `npm run check` before opening a PR, and include reproduction details for behavior changes.\n\n## Release and registry\n\nThe npm package is `ocular-mcp`; the installed CLI is `ocular`. Release automation uses npm Trusted Publishing rather than a long-lived repository token. See [Publishing](docs/publishing.md).\n\n`ocular` is published in the official MCP Registry as [`io.github.xyun1996/ocular`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.xyun1996%2Focular). See [MCP Registry](docs/mcp-registry.md) for the live identity and release flow.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nIf `ocular` is useful in your agent workflow, a GitHub star helps other developers discover the project.\n",
  "bytes": 10635,
  "sha": "0f19b57ab849ea8ec111b7987a339f01669d57d5194666124534a8e7d410fcdc",
  "repo_slug": "xyun1996/ocular",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xyun1996_ocular_e2ad6170/readme"
}