optical-context-mcp 0.1.1__tar.gz

optical_context_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Boebel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optical_context_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: optical-context-mcp
+Version: 0.1.1
+Summary: FastMCP server for compressing large OCR-heavy PDFs into dense packed images for agent workflows.
+Author: Christopher Boebel
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ChrBoebel/optical-context-mcp
+Project-URL: Issues, https://github.com/ChrBoebel/optical-context-mcp/issues
+Keywords: mcp,fastmcp,ocr,pdf,vision,document-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.1.0
+Requires-Dist: mistralai>=1.12.0
+Requires-Dist: Pillow>=12.0.0
+Requires-Dist: python-dotenv>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.chrboebel/optical-context-mcp -->
+
+<p align="center">
+  <img src="./assets/optical-context-logo.png" alt="Optical Context MCP logo" width="680">
+</p>
+
+<h1 align="center">Optical Context MCP</h1>
+
+<p align="center">
+  FastMCP server for compressing large, OCR-heavy PDFs into dense packed images for agent workflows.
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://gofastmcp.com/"><img src="https://img.shields.io/badge/MCP-FastMCP-111111.svg" alt="FastMCP"></a>
+  <a href="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml"><img src="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
+</p>
+
+Optical Context MCP is built for one specific problem: giving agents a practical way to work with **large, visually structured PDFs** without sending every page individually to a vision model.
+
+It reads a local PDF, runs OCR with Mistral, recomposes the extracted text and figures into a much smaller set of packed images, and exposes those artifacts over MCP for batch retrieval.
+
+## What It Does
+
+- reads a local PDF from the MCP host machine
+- extracts page markdown and embedded images with Mistral OCR
+- packs that content into dense PNGs that preserve visual grouping
+- stores a manifest and job artifacts for follow-up retrieval
+- lets an agent pull only the packed images it needs
+
+## Where It Fits
+
+Use it for:
+
+- operating manuals
+- scanned handbooks
+- product catalogs
+- PDF slide decks
+- visually structured OCR-heavy documents
+
+Skip it for:
+
+- tiny PDFs
+- clean text-native PDFs where normal extraction is enough
+- workflows that require exact page-faithful rendering
+- cases where OCR cost is not justified
+
+## Example Result
+
+The 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.
+
+<p align="center">
+  <img src="./assets/original-vs-packed-comparison-straight-arrow.png" alt="Side-by-side comparison of original pages and the generated packed output" width="980">
+</p>
+
+Example local run facts from the generated manifest:
+
+- source paper pages: 22
+- previewed source page range: 15 to 21
+- extracted images: 30
+- packed output images: 6
+- example packed image size: `986x1084`
+- example packed image file size: `536,697 bytes`
+
+This 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.
+
+## Install
+
+```bash
+python -m pip install "git+https://github.com/ChrBoebel/optical-context-mcp.git@v0.1.1"
+```
+
+Run directly from GitHub with `uvx`:
+
+```bash
+uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+- `MISTRAL_API_KEY` is required for `compress_pdf`
+
+## Run
+
+Default transport is `stdio`:
+
+```bash
+optical-context-mcp
+```
+
+## Claude Code
+
+Register the server in a project:
+
+```bash
+claude mcp add -s project optical-context -- uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+Typical use:
+
+1. call `compress_pdf`
+2. inspect the returned manifest
+3. fetch packed images with `get_packed_images`
+
+## MCP Tools
+
+- `compress_pdf`: run OCR plus recomposition and create a stored job
+- `get_job_manifest`: load metadata for an existing job
+- `get_packed_images`: fetch one or more packed PNGs from an existing job
+
+## How It Works
+
+```mermaid
+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"]
+```
+
+## Why Packed Images Instead Of Just OCR Text
+
+- section grouping
+- table-like layout
+- captions near figures
+- visual adjacency between text and embedded graphics
+
+For many vision-capable agents, that is a better intermediate format than a plain OCR dump.
+
+## Current Scope
+
+- depends on Mistral OCR
+- currently handles local file paths, not remote uploads
+- optimized for compression and retrieval, not final polished markdown generation
+- quality depends on OCR quality and the visual density of the source document
+
+## Roadmap
+
+- make the OCR layer provider-agnostic so different OCR backends can be swapped behind the same MCP workflow
+
+## Development
+
+```bash
+uv venv --python /opt/homebrew/bin/python3.11 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m pytest
+```

optical_context_mcp-0.1.1/README.md

@@ -0,0 +1,148 @@
+<!-- mcp-name: io.github.chrboebel/optical-context-mcp -->
+
+<p align="center">
+  <img src="./assets/optical-context-logo.png" alt="Optical Context MCP logo" width="680">
+</p>
+
+<h1 align="center">Optical Context MCP</h1>
+
+<p align="center">
+  FastMCP server for compressing large, OCR-heavy PDFs into dense packed images for agent workflows.
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://gofastmcp.com/"><img src="https://img.shields.io/badge/MCP-FastMCP-111111.svg" alt="FastMCP"></a>
+  <a href="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml"><img src="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
+</p>
+
+Optical Context MCP is built for one specific problem: giving agents a practical way to work with **large, visually structured PDFs** without sending every page individually to a vision model.
+
+It reads a local PDF, runs OCR with Mistral, recomposes the extracted text and figures into a much smaller set of packed images, and exposes those artifacts over MCP for batch retrieval.
+
+## What It Does
+
+- reads a local PDF from the MCP host machine
+- extracts page markdown and embedded images with Mistral OCR
+- packs that content into dense PNGs that preserve visual grouping
+- stores a manifest and job artifacts for follow-up retrieval
+- lets an agent pull only the packed images it needs
+
+## Where It Fits
+
+Use it for:
+
+- operating manuals
+- scanned handbooks
+- product catalogs
+- PDF slide decks
+- visually structured OCR-heavy documents
+
+Skip it for:
+
+- tiny PDFs
+- clean text-native PDFs where normal extraction is enough
+- workflows that require exact page-faithful rendering
+- cases where OCR cost is not justified
+
+## Example Result
+
+The 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.
+
+<p align="center">
+  <img src="./assets/original-vs-packed-comparison-straight-arrow.png" alt="Side-by-side comparison of original pages and the generated packed output" width="980">
+</p>
+
+Example local run facts from the generated manifest:
+
+- source paper pages: 22
+- previewed source page range: 15 to 21
+- extracted images: 30
+- packed output images: 6
+- example packed image size: `986x1084`
+- example packed image file size: `536,697 bytes`
+
+This 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.
+
+## Install
+
+```bash
+python -m pip install "git+https://github.com/ChrBoebel/optical-context-mcp.git@v0.1.1"
+```
+
+Run directly from GitHub with `uvx`:
+
+```bash
+uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+- `MISTRAL_API_KEY` is required for `compress_pdf`
+
+## Run
+
+Default transport is `stdio`:
+
+```bash
+optical-context-mcp
+```
+
+## Claude Code
+
+Register the server in a project:
+
+```bash
+claude mcp add -s project optical-context -- uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+Typical use:
+
+1. call `compress_pdf`
+2. inspect the returned manifest
+3. fetch packed images with `get_packed_images`
+
+## MCP Tools
+
+- `compress_pdf`: run OCR plus recomposition and create a stored job
+- `get_job_manifest`: load metadata for an existing job
+- `get_packed_images`: fetch one or more packed PNGs from an existing job
+
+## How It Works
+
+```mermaid
+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"]
+```
+
+## Why Packed Images Instead Of Just OCR Text
+
+- section grouping
+- table-like layout
+- captions near figures
+- visual adjacency between text and embedded graphics
+
+For many vision-capable agents, that is a better intermediate format than a plain OCR dump.
+
+## Current Scope
+
+- depends on Mistral OCR
+- currently handles local file paths, not remote uploads
+- optimized for compression and retrieval, not final polished markdown generation
+- quality depends on OCR quality and the visual density of the source document
+
+## Roadmap
+
+- make the OCR layer provider-agnostic so different OCR backends can be swapped behind the same MCP workflow
+
+## Development
+
+```bash
+uv venv --python /opt/homebrew/bin/python3.11 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m pytest
+```

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: optical-context-mcp
+Version: 0.1.1
+Summary: FastMCP server for compressing large OCR-heavy PDFs into dense packed images for agent workflows.
+Author: Christopher Boebel
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ChrBoebel/optical-context-mcp
+Project-URL: Issues, https://github.com/ChrBoebel/optical-context-mcp/issues
+Keywords: mcp,fastmcp,ocr,pdf,vision,document-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.1.0
+Requires-Dist: mistralai>=1.12.0
+Requires-Dist: Pillow>=12.0.0
+Requires-Dist: python-dotenv>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.chrboebel/optical-context-mcp -->
+
+<p align="center">
+  <img src="./assets/optical-context-logo.png" alt="Optical Context MCP logo" width="680">
+</p>
+
+<h1 align="center">Optical Context MCP</h1>
+
+<p align="center">
+  FastMCP server for compressing large, OCR-heavy PDFs into dense packed images for agent workflows.
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"></a>
+  <a href="https://gofastmcp.com/"><img src="https://img.shields.io/badge/MCP-FastMCP-111111.svg" alt="FastMCP"></a>
+  <a href="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml"><img src="https://github.com/ChrBoebel/optical-context-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
+</p>
+
+Optical Context MCP is built for one specific problem: giving agents a practical way to work with **large, visually structured PDFs** without sending every page individually to a vision model.
+
+It reads a local PDF, runs OCR with Mistral, recomposes the extracted text and figures into a much smaller set of packed images, and exposes those artifacts over MCP for batch retrieval.
+
+## What It Does
+
+- reads a local PDF from the MCP host machine
+- extracts page markdown and embedded images with Mistral OCR
+- packs that content into dense PNGs that preserve visual grouping
+- stores a manifest and job artifacts for follow-up retrieval
+- lets an agent pull only the packed images it needs
+
+## Where It Fits
+
+Use it for:
+
+- operating manuals
+- scanned handbooks
+- product catalogs
+- PDF slide decks
+- visually structured OCR-heavy documents
+
+Skip it for:
+
+- tiny PDFs
+- clean text-native PDFs where normal extraction is enough
+- workflows that require exact page-faithful rendering
+- cases where OCR cost is not justified
+
+## Example Result
+
+The 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.
+
+<p align="center">
+  <img src="./assets/original-vs-packed-comparison-straight-arrow.png" alt="Side-by-side comparison of original pages and the generated packed output" width="980">
+</p>
+
+Example local run facts from the generated manifest:
+
+- source paper pages: 22
+- previewed source page range: 15 to 21
+- extracted images: 30
+- packed output images: 6
+- example packed image size: `986x1084`
+- example packed image file size: `536,697 bytes`
+
+This 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.
+
+## Install
+
+```bash
+python -m pip install "git+https://github.com/ChrBoebel/optical-context-mcp.git@v0.1.1"
+```
+
+Run directly from GitHub with `uvx`:
+
+```bash
+uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+- `MISTRAL_API_KEY` is required for `compress_pdf`
+
+## Run
+
+Default transport is `stdio`:
+
+```bash
+optical-context-mcp
+```
+
+## Claude Code
+
+Register the server in a project:
+
+```bash
+claude mcp add -s project optical-context -- uvx --from git+https://github.com/ChrBoebel/optical-context-mcp@v0.1.1 optical-context-mcp
+```
+
+Typical use:
+
+1. call `compress_pdf`
+2. inspect the returned manifest
+3. fetch packed images with `get_packed_images`
+
+## MCP Tools
+
+- `compress_pdf`: run OCR plus recomposition and create a stored job
+- `get_job_manifest`: load metadata for an existing job
+- `get_packed_images`: fetch one or more packed PNGs from an existing job
+
+## How It Works
+
+```mermaid
+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"]
+```
+
+## Why Packed Images Instead Of Just OCR Text
+
+- section grouping
+- table-like layout
+- captions near figures
+- visual adjacency between text and embedded graphics
+
+For many vision-capable agents, that is a better intermediate format than a plain OCR dump.
+
+## Current Scope
+
+- depends on Mistral OCR
+- currently handles local file paths, not remote uploads
+- optimized for compression and retrieval, not final polished markdown generation
+- quality depends on OCR quality and the visual density of the source document
+
+## Roadmap
+
+- make the OCR layer provider-agnostic so different OCR backends can be swapped behind the same MCP workflow
+
+## Development
+
+```bash
+uv venv --python /opt/homebrew/bin/python3.11 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+.venv/bin/python -m pytest
+```

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+optical_context_mcp.egg-info/PKG-INFO
+optical_context_mcp.egg-info/SOURCES.txt
+optical_context_mcp.egg-info/dependency_links.txt
+optical_context_mcp.egg-info/entry_points.txt
+optical_context_mcp.egg-info/requires.txt
+optical_context_mcp.egg-info/top_level.txt
+optical_mcp/__init__.py
+optical_mcp/__main__.py
+optical_mcp/mistral_client.py
+optical_mcp/models.py
+optical_mcp/recomposition.py
+optical_mcp/server.py
+optical_mcp/service.py
+optical_mcp/storage.py
+tests/test_server_tools.py
+tests/test_storage.py

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+optical-context-mcp = optical_mcp.server:main

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/requires.txt

@@ -0,0 +1,7 @@
+fastmcp>=3.1.0
+mistralai>=1.12.0
+Pillow>=12.0.0
+python-dotenv>=1.2.0
+
+[dev]
+pytest>=8.0.0

optical_context_mcp-0.1.1/optical_context_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+optical_mcp

optical_context_mcp-0.1.1/optical_mcp/__init__.py

@@ -0,0 +1 @@
+"""Optical Context MCP package."""

optical_context_mcp-0.1.1/optical_mcp/__main__.py

@@ -0,0 +1,5 @@
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

optical_context_mcp-0.1.1/optical_mcp/mistral_client.py

@@ -0,0 +1,60 @@
+"""
+Mistral OCR client for document extraction.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+from mistralai import Mistral
+
+
+class MistralOCRClient:
+    """Client for the Mistral OCR API."""
+
+    def __init__(self, api_key: str):
+        if not api_key:
+            raise ValueError("Mistral API key not provided")
+        self.client = Mistral(api_key=api_key)
+        self.model = "mistral-ocr-latest"
+
+    def extract_pdf(self, pdf_path: Path | str):
+        """Extract text and images from a PDF."""
+        path = Path(pdf_path)
+        with open(path, "rb") as handle:
+            pdf_data = base64.b64encode(handle.read()).decode("utf-8")
+
+        return self.client.ocr.process(
+            model=self.model,
+            document={
+                "type": "document_url",
+                "document_url": f"data:application/pdf;base64,{pdf_data}",
+            },
+            include_image_base64=True,
+        )
+
+    def extract_image(self, image_path: Path | str):
+        """Extract text and elements from a single image."""
+        path = Path(image_path)
+        suffix = path.suffix.lower()
+        mime_map = {
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".jpeg": "image/jpeg",
+            ".gif": "image/gif",
+            ".webp": "image/webp",
+        }
+        mime_type = mime_map.get(suffix, "image/png")
+
+        with open(path, "rb") as handle:
+            image_data = base64.b64encode(handle.read()).decode("utf-8")
+
+        return self.client.ocr.process(
+            model=self.model,
+            document={
+                "type": "image_url",
+                "image_url": f"data:{mime_type};base64,{image_data}",
+            },
+            include_image_base64=True,
+        )

optical_context_mcp-0.1.1/optical_mcp/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+
+@dataclass(slots=True)
+class PackedImageArtifact:
+    index: int
+    path: str
+    width: int
+    height: int
+    size_bytes: int
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class CompressionJobManifest:
+    job_id: str
+    source_pdf: str
+    output_dir: str
+    created_at: str
+    chars_per_image: int
+    page_count: int
+    extracted_image_count: int
+    packed_image_count: int
+    ocr_markdown_path: str
+    packed_images: list[PackedImageArtifact]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "job_id": self.job_id,
+            "source_pdf": self.source_pdf,
+            "output_dir": self.output_dir,
+            "created_at": self.created_at,
+            "chars_per_image": self.chars_per_image,
+            "page_count": self.page_count,
+            "extracted_image_count": self.extracted_image_count,
+            "packed_image_count": self.packed_image_count,
+            "ocr_markdown_path": self.ocr_markdown_path,
+            "packed_images": [image.to_dict() for image in self.packed_images],
+        }