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。