Scan MCP

🚀 scan - mcp

スキャナーキャプチャ（ADF/両面/用紙サイズ）、バッチ処理、およびマルチページ組み立て用の最小限のMCPサーバーです。

🚀 クイックスタート

ローカルstdio（デフォルト）

MCPクライアント構成にサーバーエントリを追加します：

{
  "mcpServers": {
    "scan": {
      "command": "npx",
      "args": [
        "-y",
        "scan - mcp"
      ],
      "env": {
        "INBOX_DIR": "~/Documents/scanned_documents/inbox"
      }
    }
  }
}

• この呼び出しは、プライバシーを重視した単一マシンのセットアップでstdioを介して実行されます。
• device_idを指定せずにstart_scan_jobを呼び出すと、スキャナーが自動選択され、スキャンが開始されます。
• 成果物は、各ジョブごとにINBOX_DIRの下に書き込まれます：job - */page_*.tiff、doc_*.tiff、manifest.json、events.jsonl。

ストリーム可能なHTTPトランスポート

スキャナーをネットワーク上の別のマシンに接続したい場合、scan - mcpはストリーム可能なHTTPトランスポートもサポートしています：

scan - mcp --http

• デフォルトのポートは3001です。MCP_HTTP_PORTを設定して上書きできます（例：MCP_HTTP_PORT = 3333 scan - mcp --http）。
• HTTPレスポンスは、ツールの出力をストリーミングするためにサーバー送信イベント（SSE）を使用します。Claude DesktopやWindsurfなどのクライアントはこのトランスポートをサポートしています。
• 現在、認証はありません。これは内部LANネットワーク用に意図されています。

✨ 主な機能

• デバイス検出とスキャンジョブのツールを公開する小型で型付けされたMCPサーバー
• JSONスキーマで検証された入力と決定論的で型付けされた出力
• スマートなデバイス選択（ADF/両面を優先し、カメラバックエンドを避ける）、堅牢なデフォルト設定
• ローカル優先のトランスポート：すべてをデバイス上に保持するためにデフォルトでstdio、独自のネットワーク展開用にオプションのHTTP

⚠️ 重要提示

このパッケージはNode 22とLinux SANEバックエンド（scanimage）を対象としています。

📦 インストール

• npxで実行：npx scan - mcp（推奨）
  • CLIは、Node 22以上と必要なスキャナー/画像ツールのクイック事前チェックを実行し、不足しているものがあればインストールヒントを表示します。
  • 上記の推奨サーバー構成を参照してください。
• 別のマシンで実行する場合、npx scan - mcp --httpを使用してストリーム可能なHTTPトランスポートを起動します。
• CLIヘルプ：scan - mcp --help
• ソースから（開発用）：
  • npm install
  • npm run build
• Clineセットアップやその他の自動化されたエージェント型インストールについては、[llms - install.md](llms - install.md)を参照してください。

🔧 技術詳細

システム要件

• SANEユーティリティがインストールされたLinux：scanimage（オプションでscanadf）
• TIFFツール：tiffcp（推奨）またはImageMagickのconvert

環境変数

API

ツール

• list_devices

  • 接続されたスキャナーをバックエンドの詳細とともに検出します。
  • 入力：なし。

• get_device_options

  • 特定のデバイスのSANEオプションを取得します。
  • 入力：
    • device_id（文字列）：対象デバイスの識別子。

• start_scan_job

  • スキャンジョブを開始します。device_idを省略すると、自動選択とデフォルトオプションが適用されます。
  • 入力（特に指定がない限りすべてオプション）：
    • device_id（文字列）
    • resolution_dpi（整数、50 - 1200）
    • color_mode（Color | Gray | Lineart）
    • source（Flatbed | ADF | ADF Duplex）
    • duplex（ブール値）
    • page_size（Letter | A4 | Legal | Custom）
    • custom_size_mm { width, height }
    • doc_break_policy { type, blank_threshold, page_count, timer_ms, barcode_values }
    • output_format（文字列、デフォルトtiff）
    • tmp_dir（文字列）

• get_job_status

  • ジョブの状態と成果物の数を調べます。
  • 入力：
    • job_id（文字列）

• cancel_job

  • ジョブのキャンセルを要求します。スキャンループ中は最善の努力で実行されます。
  • 入力：
    • job_id（文字列）

• list_jobs

  • 受信トレイディレクトリから最近のジョブを一覧表示します。
  • 入力（オプション）：
    • limit（整数、最大100）
    • state（running | completed | cancelled | error | unknown）

• get_manifest

  • ジョブのmanifest.jsonを取得します。
  • 入力：
    • job_id（文字列）

• get_events

  • ジョブのevents.jsonlログを取得します。
  • 入力：
    • job_id（文字列）

schemas/のJSONスキーマを参照して、入力の形式を確認してください。テストはこれらの契約に対して実行されます。

選択とデフォルトの仕組み

デフォルトでは、300dpi、適切なカラーモード、および利用可能な場合はADF/両面を目指しています。スコアリングとフォールバックの詳細はドキュメントに記載されています：

• 選択とデフォルト：docs/SELECTION.md

プロジェクト構成

• src/mcp.ts — MCPサーバーのエントリポイントとツールの登録
• src/services/* — ハードウェアインターフェイスとジョブオーケストレーション
• schemas/ — 検証とテストに使用されるJSONスキーマ
• docs/ — アーキテクチャ、規約、および詳細な解説

開発

• npm run dev（stdio MCPサーバー）、npm run dev:http（HTTPトランスポート）
• make verifyでリント、型チェック、およびテストを実行します。
• 規約：docs/CONVENTIONS.mdおよびアーキテクチャはdocs/BLUEPRINT.mdに記載されています。

ロードマップ

アイデアと将来の改善点はdocs/ROADMAP.mdに記載されています。