Scan MCP

🚀 scan-mcp

scan-mcp 是一個輕量級的 MCP 服務器，用於掃描儀捕獲（ADF/雙面/頁面尺寸）、批量處理和多頁組裝。它提供了設備發現和掃描作業的工具，具有小體積、類型化的特點，輸入經過 JSON Schema 驗證，輸出具有確定性和類型化。

🚀 快速開始

本地標準輸入輸出（默認）

在你的 MCP 客戶端配置中添加服務器條目：

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

• 此調用通過標準輸入輸出運行，適用於注重隱私的單機設置。
• 調用 start_scan_job 時不指定 device_id，即可自動選擇掃描儀並開始掃描。
• 每個作業的工件將寫入 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 等客戶端支持此傳輸方式。
• 目前沒有身份驗證；此功能適用於內部局域網。

✨ 主要特性

• 小型、類型化的 MCP 服務器，提供設備發現和掃描作業工具。
• 輸入經過 JSON Schema 驗證，輸出具有確定性和類型化。
• 智能設備選擇（優先選擇 ADF/雙面，避免使用相機後端），具有強大的默認設置。
• 本地優先傳輸：默認使用標準輸入輸出，將所有操作保留在設備上，可選 HTTP 用於自己的網絡部署。

📦 安裝指南

• 使用 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

環境變量

📚 詳細文檔

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 Schemas。測試會根據這些契約進行斷言。

選擇和默認設置的工作原理

默認設置目標為 300dpi、合理的顏色模式，並在可用時使用 ADF/雙面。評分和回退的詳細信息請參閱文檔：

• 選擇和默認設置：docs/SELECTION.md

項目佈局

• src/mcp.ts — MCP 服務器入口和工具註冊
• src/services/* — 硬件接口和作業編排
• schemas/ — 用於驗證和測試的 JSON Schemas
• docs/ — 架構、約定和深入探討

開發

• npm run dev（標準輸入輸出 MCP 服務器），npm run dev:http（HTTP 傳輸）
• make verify 運行 lint、類型檢查和測試
• 約定：docs/CONVENTIONS.md 和架構在 docs/BLUEPRINT.md

路線圖

跟蹤想法和未來改進的文檔位於 docs/ROADMAP.md。