{ "markdown": "\n\n

\n \"Optical\n

\n\n

Optical Context MCP

\n\n

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

\n\n

\n \"PyPI\n \"Python\n \"FastMCP\"\n \"CI\"\n \"MIT\n

\n\nOptical Context MCP is built for one specific job: turning **large, visually structured PDFs** into a smaller set of retrievable packed images for agent workflows.\n\nIt reads a local PDF, runs OCR with Mistral, recomposes the extracted text and figures into dense PNGs, and exposes those artifacts over MCP for batch retrieval.\n\n## What It Does\n\n- reads a local PDF from the MCP host machine\n- extracts page markdown and embedded images with Mistral OCR\n- packs that content into dense PNGs that preserve visual grouping\n- optionally sizes embedded figures with a bundled technical-document model\n- stores a manifest and temp job artifacts for follow-up retrieval\n- lets an agent pull only the packed images it needs\n\n## Where It Fits\n\nUse it for:\n\n- operating manuals\n- scanned handbooks\n- product catalogs\n- PDF slide decks\n- visually structured OCR-heavy documents\n\nSkip it for:\n\n- tiny PDFs\n- clean text-native PDFs where normal extraction is enough\n- workflows that require exact page-faithful rendering\n- cases where OCR cost is not justified\n\n## Example Result\n\nThe image below shows a real local validation run on a public research paper with dense text, figures, charts, and page-level visual structure. The packed image on the right consolidates the seven source pages shown on the left.\n\n

\n \"Side-by-side\n

\n\nExample local run facts from the generated manifest:\n\n- source paper pages: 22\n- previewed source page range: 15 to 21\n- extracted images: 30\n- packed output images: 6\n- example packed image size: `986x1084`\n- example packed image file size: `536,697 bytes`\n\nThis example shows the intended workflow: take a long, visually structured PDF and compress it into a smaller set of retrievable packed images that still preserve the visual structure of the source.\n\n## Install\n\n```bash\npython -m pip install optical-context-mcp\n```\n\nInstall with the adaptive sizing runtime:\n\n```bash\npython -m pip install \"optical-context-mcp[ml]\"\n```\n\nRun without installing:\n\n```bash\nuvx optical-context-mcp\n```\n\n- `MISTRAL_API_KEY` is required for `compress_pdf`\n- packed images are always stored locally under the system temp directory\n- `compress_pdf` returns up to `30` packed images inline by default\n- the adaptive sizing checkpoint is bundled with the package\n- adaptive sizing activates automatically when `torch` and `torchvision` are available\n- set `OPTICAL_CONTEXT_DISABLE_ADAPTIVE_SIZING=1` to force the legacy fixed sizing\n- set `OPTICAL_CONTEXT_ADAPTIVE_MODEL_PATH=/path/to/model.pt` to override the bundled checkpoint\n\nFor pinned shared setups:\n\n```bash\nuvx --from optical-context-mcp==0.1.4 optical-context-mcp\n```\n\n## Run\n\nDefault transport is `stdio`:\n\n```bash\noptical-context-mcp\n```\n\n## Claude Code\n\nRegister the server in a project:\n\n```bash\nclaude mcp add -s project optical-context -- uvx optical-context-mcp\n```\n\nTypical use:\n\n1. call `compress_pdf`\n2. inspect the returned manifest\n3. fetch packed images with `get_packed_images`\n\n## MCP Tools\n\n- `compress_pdf`: run OCR plus recomposition and create a stored job\n- `get_job_manifest`: load metadata for an existing job\n- `get_packed_images`: fetch one or more packed PNGs from an existing job\n\n## How It Works\n\n```mermaid\nflowchart LR\n A[\"Local PDF\"] --> B[\"Mistral OCR\"]\n B --> C[\"Page markdown + embedded images\"]\n C --> D[\"Recomposition engine\"]\n D --> E[\"Dense packed PNG images\"]\n E --> F[\"Stored job artifacts\"]\n F --> G[\"Agent fetches manifest or image batches over MCP\"]\n```\n\n## Why Packed Images Instead Of Just OCR Text\n\n- section grouping\n- table-like layout\n- captions near figures\n- visual adjacency between text and embedded graphics\n\nFor many vision-capable agents, that is a better intermediate format than a plain OCR dump.\n\n## Current Scope\n\n- depends on Mistral OCR\n- currently handles local file paths, not remote uploads\n- stores artifacts in the local system temp directory by default\n- optimized for compression and retrieval, not final polished markdown generation\n- quality depends on OCR quality and the visual density of the source document\n- adaptive sizing falls back safely to fixed medium image sizing when the ML runtime is absent\n\n## Roadmap\n\n- make the OCR layer provider-agnostic so different OCR backends can be swapped behind the same MCP workflow\n\n## Development\n\n```bash\nuv venv --python /opt/homebrew/bin/python3.11 .venv\nuv pip install --python .venv/bin/python -e \".[dev]\"\n.venv/bin/python -m pytest\n```\n", "bytes": 5666, "sha": "1732ae6c9cce393336638959f24f496bf34af974bc70b93e7d0578c79186350d", "repo_slug": "chrboebel/optical-context-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_chrboebel_optical_context_mcp_5efa2acc/readme" }