Optical Context MCP

Optical Context MCP

OCR が多用されている PDF を高密度のパック画像に圧縮し、エージェントが長いビジュアル文書を扱えるようにします。

Optical Context MCP は、大規模で視覚的に構造化された PDF を、エージェントのワークフローで取得できる、より少数のパック画像に変換するという特定の用途に特化しています。

ローカルの PDF を読み込み、Mistral で OCR を実行し、抽出したテキストと図表を高密度の PNG に再構成して、MCP 経由でこれらのアーティファクトをまとめて取得できるようにします。

機能

• MCP ホストマシン上のローカル PDF を読み込みます
• Mistral OCR でページの Markdown と埋め込み画像を抽出します
• 視覚的なまとまりを保ったまま、コンテンツを高密度の PNG にまとめます
• バンドルされた技術文書用モデルを使って、埋め込み図表のサイズを調整できます
• 後続の取得に備えて、マニフェストと一時ジョブアーティファクトを保存します
• 必要なパック画像だけをエージェントが取得できるようにします

適した用途

次の用途に使用できます。

• 操作マニュアル
• スキャンされたハンドブック
• 製品カタログ
• PDF のスライド資料
• 視覚的に構造化された、OCR が多用されている文書

次の用途には適していません。

• 小さな PDF
• 通常の抽出で十分な、テキストベースのきれいな PDF
• ページの見た目を正確に再現する必要があるワークフロー
• OCR のコストに見合わないケース

出力例

下の画像は、テキスト、図、グラフ、ページ単位の視覚的な構造が豊富な公開研究論文を使った、実際のローカル検証結果です。右側のパック画像は、左側に示された元の 7 ページをまとめたものです。

生成されたマニフェストに記録されたローカル実行の例：

• 元の論文のページ数：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

• compress_pdf の使用には MISTRAL_API_KEY が必要です
• パック画像は常にシステムの一時ディレクトリ下にローカル保存されます
• 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.5 optical-context-mcp

実行

デフォルトのトランスポートは stdio です。

optical-context-mcp

Claude Code

プロジェクトにサーバーを登録します。

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：既存のジョブから 1 つ以上のパック済み 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 に依存しています
• 現在はローカルのファイルパスに対応しており、リモートアップロードには対応していません
• デフォルトでは、アーティファクトをローカルシステムの一時ディレクトリに保存します
• 最終的な、洗練された Markdown の生成ではなく、圧縮と取得に最適化されています
• 品質は OCR の精度とソース文書の視覚的な密度に依存します
• ML ランタイムがない場合、適応型サイズ調整は安全に固定の中サイズ画像へフォールバックします

ロードマップ

• OCR レイヤーをプロバイダーに依存しない設計にし、同じ MCP ワークフローの背後で異なる OCR バックエンドを切り替えられるようにします

フィードバック

文書のワークフローで Optical Context を試しましたか？フィードバックフォームから、うまくいった点や問題になった点を任意で共有できます。 パッケージのバージョン、MCP クライアント、文書の種類についての簡単な説明を含めてください。 非公開の PDF や API キーは添付しないでください。フィードバックは GitHub 上で公開されます。

公開済みバージョン間の変更については、変更履歴をご覧ください。

開発

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

公開

pyproject.toml と server.json 内の両方のバージョンを同期させてください。レビュー済みのリリースコミットで Publish PyPI ワークフローを実行します。このワークフローは、wheel を検証し、インストール済みの配布物を使ってテストを実行した後、PyPI に公開し、続いて同じバージョンを MCP Registry に公開します。どちらも GitHub OIDC を使用するため、ローカルの公開トークンは不要です。レジストリーのジョブだけが失敗した場合は、変更不可の PyPI バージョンを再公開するのではなく、失敗したジョブを再実行してください。 ワークフローの修正により新たな実行が必要な場合は、既存の PyPI バージョンを再アップロードせずにレジストリーへの公開を再試行するため、registry_only を選択してください。

同じコミットから対応する GitHub リリースを作成し、ワークフローの python-distributions アーティファクトを添付してください。