ocular

ocular

コーディングエージェントのためのビジョン。

ocular は、OpenAI 互換のビジョンモデルを通じて、テキスト中心のコーディングエージェントがスクリーンショット、UI モックアップ、ターミナルのエラー、ドキュメント、表、グラフを分析できるようにする MCP サーバーです。

ローカルの stdio 利用とリモートの HTTP デプロイの両方を想定して設計されています。リモートエージェントでは、画像データをバイナリアップロード用のサイドチャネルで送信し、MCP ツール呼び出しでは軽量な file_id のみを渡すことで、大きなインライン Base64 ペイロードを避けられます。

プロジェクトの状況： 初期段階にあり、活発に開発が進められています。フィードバック、バグ報告、インテグレーション、実際の利用に関する報告を歓迎します。

ocular を選ぶ理由

コーディングエージェントはソースコードを読むのは得意ですが、重要な証拠が視覚的なものである場合、つまりレイアウトの崩れ、ターミナルのスクリーンショット、エラーダイアログ、グラフ、デザインの参考画像などでは、文脈を見失いがちです。

ocular は、こうした視覚的な入力を、エージェントが推論に利用できる構造化データに変換します。

• エージェント向けの出力 — ツールは文章だけの説明ではなく、構造化 JSON を返します。
• 目的別に特化した 8 つのビジョンツール — 一般分析、OCR、UI 検査、エラー診断、UI 比較、表の抽出、グラフ分析、アップロードのオーケストレーション。
• OpenAI 互換のプロバイダーインターフェース — ocular の接続先として、互換性のあるマルチモーダルエンドポイントとモデルを指定できます。再現可能なテスト済みの構成は、プロバイダーの互換性で管理されています。
• リモート利用に適したアップロード — 大きな画像にはバイナリの PUT /upload フローを使用し、コンテンツアドレス指定の file_id 参照を利用できます。
• ローカルまたはリモートの MCP — ローカルクライアントには stdio、ホスト型またはプライベートなデプロイには HTTP を使用します。
• キャッシュと永続化 — 重複するアップロードを排除し、エージェントのワークフローで結果を再利用できるようキャッシュします。

仕組み

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

アップロードとキャッシュのモデルについては、アーキテクチャを参照してください。

デモ

スクリーンショットからコーディングエージェント向けの証拠が得られるまでの一連の流れをご覧になりたい場合は、エンドツーエンドのデモをお読みください。

リモート画像のアップロード、diagnose_error_screenshot の呼び出し、エージェントに返される構造化フィールド、およびその証拠をリポジトリのコンテキストと組み合わせる方法を紹介します。モデル出力の例は、ベンチマークとしてではなく、代表例として明示されています。

クイックスタート

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 キーをシェルの履歴に直接保存しないでください。利用可能な場合は、クライアントの環境変数またはシークレット管理機能を使用してください。

汎用 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 のセットアップを参照してください。

ワークフローの例

スクリーンショットを診断する

コーディングエージェントにエラーのスクリーンショットを調べさせ、正確なメッセージ、考えられる原因、次に確認すべき項目を抽出させます。

{
  "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 と実際の UI を比較する

compare_ui_screenshots に参照スクリーンショットと実装のスクリーンショットを渡すと、リグレッションやレイアウトの違いを特定できます。

Screenshot debugging の例を参照してください。

ツール

ツール	目的
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 を返します。MCP 経由で大きな base64 文字列を送る代わりに、その ID をビジョンツールに渡してください。

リバースプロキシと systemd の例については、デプロイを参照してください。

設定

一般的な変数：

変数	目的
OCULAR_BASE_URL	OpenAI 互換 API のベース URL
OCULAR_API_KEY	プロバイダーの API キー
OCULAR_MODEL	ビジョン機能に対応するモデル名
OCULAR_HEADERS	JSON 形式の任意のカスタムプロバイダーヘッダー
OCULAR_TEMPERATURE	生成時の温度
OCULAR_MAX_TOKENS	生成されるトークンの最大数
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 クライアントとの統合および利用レポート
• プロバイダー／モデルの互換性検証
• 実際のエンドポイントから取得したフィクスチャベースのベンチマーク結果の公開
• コミュニティ主導のツールおよびプロンプトの改善

実際のワークフローで ocular を使用している場合は、クライアント、プロバイダー／モデル、ユースケースを記載した Usage report の issue を作成してください。問題が何もない場合でも、公開レポートは役立ち、互換性や導入状況に関する主張を実際の利用状況に基づいたものにする助けとなります。

貢献

貢献を歓迎します。CONTRIBUTING.md を確認し、PR を作成する前に npm run check を実行してください。動作の変更を含む場合は、再現手順も記載してください。

リリースとレジストリ

npm パッケージは ocular-mcp、インストールされる CLI は ocular です。リリースの自動化には、長期有効なリポジトリトークンではなく、npm Trusted Publishing を使用しています。Publishing をご覧ください。

ocular は、公式 MCP Registry に io.github.xyun1996/ocular として公開されています。現在の ID とリリースの流れについては、MCP Registry をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。

エージェントのワークフローで ocular が役立った場合は、GitHub でスターを付けると、ほかの開発者がこのプロジェクトを見つけやすくなります。