scan-mcp

スキャナキャプチャ（ADF/両面/用紙サイズ）、バッチ処理、複数ページの結合のための最小限のMCPサーバーです。

特徴

• デバイス検出とスキャンジョブのためのツールを公開する、小規模で型付けされたMCPサーバー

• JSON Schemaで検証された入力と、決定的で型付けされた出力

• スマートなデバイス選択（ADF/両面を優先し、カメラバックエンドを回避）、堅牢なデフォルト設定

• ローカルファーストのトランスポート: デフォルトではstdioを使用してすべてをデバイス上に保持し、独自のネットワーク展開用にオプションのHTTPもサポート

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

Related MCP server: fsext-mcp-server-java

クイックスタート（ローカル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）。

• デフォルトではすべてのインターフェース（::）にバインドします。MCP_HTTP_HOSTを設定して制限します（例: リバースプロキシがサーバーの前にある場合はMCP_HTTP_HOST=127.0.0.1）。

• HTTPレスポンスは、ツール出力のストリーミングにサーバー送信イベント（SSE）を使用します。Claude DesktopやWindsurfなどのクライアントはこのトランスポートをサポートしています。

• 現在、認証はありません。これは社内LANネットワーク用に意図されています。

インストール

• 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（およびオプションでscanadf）

• TIFFツール: tiffcp（推奨）またはImageMagickのconvert

環境変数

• SCAN_MOCK（デフォルト: false）: テスト用にSANE呼び出しをモックし、偽のTIFFを生成します。

• INBOX_DIR（デフォルト: scanned_documents/inbox）: ジョブの実行と成果物のベースディレクトリ。

• SCANIMAGE_BIN / SCANADF_BIN（デフォルト: scanimage / scanadf）: バイナリパスを上書きします。

• TIFFCP_BIN / IM_CONVERT_BIN（デフォルト: tiffcp / convert）: 複数ページ結合ツール。

• SCAN_EXCLUDE_BACKENDS（CSV）: 除外するバックエンド（例: v4l）。

• SCAN_PREFER_BACKENDS（CSV）: 優先するバックエンド（例: epjitsu,epson2）。

• PERSIST_LAST_USED_DEVICE（デフォルト: true）: 最後に使用したデバイスを永続化し、軽く優先します。

• MCP_HTTP_PORT（デフォルト: 3001）: HTTPトランスポートのTCPポート。

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）: color_modeはデフォルトでLineart（ドキュメント優先）です。600dpi以上ではデフォルトでColorになります。高dpiキャプチャは通常、アートワークや写真を意味し、1ビットでは情報が破壊されるためです。どちらのデフォルトも上書きするにはcolor_modeを明示的に渡します。高dpiのみが使用されるシグナルです。

    • 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（文字列）

    • crop_carrier_sheets（ブール値、デフォルトfalse）: キャリアシートの先端バンドを検出し、切り抜いたページの派生ファイルを書き込みます。元のページは保持されます。

• 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 Schemaを参照してください。テストはこれらの契約に対して検証されます。

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

デフォルトは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に文書化されています。