scan-mcp

scan-mcp

スキャナーでの読み取り（ADF／両面／ページサイズ）、バッチ処理、複数ページの組み立てに対応する、最小構成の MCP サーバーです。

特長

• デバイスの検出とスキャンジョブ用のツールを提供する、小規模で型定義された MCP サーバー
• zod で入力を検証します。schemas/ 内の JSON スキーマで仕様を定義し、契約テストを実施しています
• デバイスをスマートに選択します（ADF／両面対応を優先し、カメラバックエンドを回避）。堅牢なデフォルト設定を備えています
• ローカル優先のトランスポートに対応します。デフォルトでは stdio を使用してすべての処理をデバイス上に保ち、独自のネットワーク環境にデプロイする場合は HTTP も選択できます

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

クイックスタート（ローカル 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。crop_carrier_sheets が設定され、キャリアシートが検出された場合は、該当する各ページについて page_*.cropped.tiff も派生ファイルとして書き込まれます。

ストリーミング可能な HTTP トランスポート

ネットワーク上の別のマシンにスキャナーを接続したい場合は、scan-mcp でストリーミング可能な HTTP トランスポートも利用できます。

scan-mcp --http

• デフォルトのポートは 3001 です。変更するには MCP_HTTP_PORT を設定します（例：MCP_HTTP_PORT=3333 scan-mcp --http）。
• デフォルトでは 127.0.0.1 にバインドします。他のインターフェースで公開するには MCP_HTTP_HOST を設定します（例：すべてのインターフェースを対象にする場合は MCP_HTTP_HOST=::、または LAN アドレス）。サーバーには認証機能がないため、信頼できるネットワークでのみ公開してください。
• HTTP レスポンスでは、ツール出力のストリーミングにサーバー送信イベント（SSE）を使用します。Claude Desktop や Windsurf などのクライアントがこのトランスポートに対応しています。
• 現時点では認証機能がありません。バインドアドレスを広げるのは、信頼できる内部ネットワーク上に限ってください。

インストール

• 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 を参照してください

システム要件

• SANE ユーティリティのある Linux：scanimage
• TIFF ツール：tiffcp（複数ページの組み立て）および ImageMagick の convert（キャリアシートの検出と切り抜き）。事前チェックでは両方が必要です

環境変数

• SCAN_MOCK（デフォルト：false）：SANE 呼び出しをモックし、テスト用の偽の TIFF を生成します。
• INBOX_DIR（デフォルト：scanned_documents/inbox）：ジョブの実行データと成果物の保存先ディレクトリです。
• SCANIMAGE_BIN（デフォルト：scanimage）：バイナリのパスを上書きします。
• TIFFCP_BIN／IM_CONVERT_BIN（デフォルト：tiffcp／convert）：複数ページの組み立てと画像解析に使用するツールです。
• SCAN_EXCLUDE_BACKENDS（CSV）：除外するバックエンド（例：v4l）。
• SCAN_PREFER_BACKENDS（CSV）：優先するバックエンド（例：epjitsu,epson2）。
• PERSIST_LAST_USED_DEVICE（デフォルト：true）：最後に使用したデバイスを保存し、わずかに優先します。
• LOG_LEVEL（デフォルト：info）：pino のログレベルです。
• MCP_HTTP_PORT（デフォルト：3001）：HTTP トランスポート用の TCP ポートです。
• MCP_HTTP_HOST（デフォルト：127.0.0.1）：HTTP トランスポートのバインドアドレスです。

API

ツール

• list_devices

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

• get_device_options

  • 指定したデバイスの SANE オプションを取得します。
  • 入力：
    • device_id (string)：対象デバイスの識別子。

• start_scan_job

  • スキャンジョブを開始します。device_id を省略すると、自動選択とデフォルトオプションが適用されます。
  • 入力（特に記載のない限り、すべて任意）：
    • device_id (string)
    • resolution_dpi (integer, 50–1200)
    • color_mode (Color | Gray | Lineart)：color_mode のデフォルトは Lineart（文書優先）です。 600dpi 以上では Color がデフォルトになります。高解像度の取り込みは通常、1ビットでは情報が失われる イラストや写真を対象とするためです。いずれのデフォルトも明示的に上書きするには、color_mode を指定してください。高解像度かどうかは 唯一の判断基準です。
    • source (Flatbed | ADF | ADF Duplex)
    • duplex (boolean)
    • page_size (Letter | A4 | Legal | Custom)
    • custom_size_mm { width, height }
    • doc_break_policy { type (page_count | none), page_count }：バッチを page_count ページ単位の文書に分割します
    • output_format (string、デフォルト tiff)
    • tmp_dir (string)
    • crop_carrier_sheets (boolean、デフォルト false)：キャリアシートの先端の帯を検出して、切り抜いたページの派生ファイルを書き出します。元のページは保持されます。

• get_job_status

  • ジョブの状態と生成物の数を確認します。
  • 入力：
    • job_id (string)

• cancel_job

  • ジョブのキャンセルを要求します。スキャンループ中のキャンセルはベストエフォートです。
  • 入力：
    • job_id (string)

• list_jobs

  • 受信トレイディレクトリにある最近のジョブを一覧表示します。
  • 入力（任意）：
    • limit (integer、最大 100)
    • state (running | completed | cancelled | error | unknown)

• get_manifest

  • ジョブの manifest.json を取得します。
  • 入力：
    • job_id (string)

• get_events

  • ジョブの events.jsonl ログを取得します。
  • 入力：
    • job_id (string)

入力形式は schemas/ の JSON Schema を参照してください。実行時の検証には zod (src/server/register.ts) を使用します。スキーマには仕様が記載され、テストではスキーマに対する適合性を検証します。

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

デフォルトでは、300dpi、適切なカラーモード、利用可能な場合は ADF／両面を選択します。スコアリングとフォールバックの詳細は、次のドキュメントを参照してください。

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

プロジェクト構成

• src/mcp.ts — MCP サーバーのエントリーポイントとツール登録
• src/services/* — ハードウェアインターフェースとジョブのオーケストレーション
• schemas/ — ツールの仕様を記述する JSON Schema（テストで使用）
• docs/ — アーキテクチャ、規約、詳細解説

開発

• npm run dev（stdio MCP サーバー）、npm run dev:http（HTTP トランスポート）
• make verify で lint、型チェック、テストを実行します
• 規約は docs/CONVENTIONS.md、アーキテクチャは docs/BLUEPRINT.md を参照してください

ロードマップ

アイデアと今後の改善項目は docs/ROADMAP.md に記載されています。