scan-mcp

scan-mcp

用于扫描仪采集（ADF/双面/页面尺寸）、批处理和多页组装的精简 MCP 服务。

功能

• 小巧、类型安全的 MCP 服务，提供用于发现设备和创建扫描任务的工具
• 使用 zod 验证输入；schemas/ 中的 JSON Schema 描述了接口契约，并通过契约测试验证
• 智能选择设备（优先使用 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 运行，适用于注重隐私的单机设置。
• 调用 start_scan_job，无需指定 device_id，即可自动选择扫描仪并开始扫描。
• 每个任务的文件都会写入 INBOX_DIR：job-*/page_*.tiff、doc_*.tiff、manifest.json、events.jsonl。设置 crop_carrier_sheets 后，如果检测到载纸页，还会为每个受影响的页面写入一个 page_*.cropped.tiff 衍生文件。

Streamable HTTP 传输

想要将扫描仪连接到网络中的另一台机器？scan-mcp 也支持 Streamable 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=:: 开放到所有接口，或指定一个局域网地址）；服务没有身份验证，因此仅应在可信网络中这样做。
• HTTP 响应使用服务器发送事件（SSE）流式传输工具输出；Claude Desktop 和 Windsurf 等客户端支持 此传输方式。
• 目前没有身份验证；仅在可信的内部网络中扩大绑定地址范围。

安装

• 使用 npx 运行：npx scan-mcp（推荐）
  • CLI 会快速预检 Node 22+ 和所需的扫描仪/图像工具；若有缺失，会显示安装提示。
  • 请参阅上方推荐的服务配置
• 在另一台机器上运行时，使用 npx scan-mcp --http 启动 Streamable HTTP 传输。
• CLI 帮助：scan-mcp --help
• 从源代码安装（用于开发）：
  • npm install
  • npm run build
• Cline 配置及其他自动化 Agent 安装方式，请参阅 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（字符串）：目标设备标识符。

• start_scan_job

  • 开始扫描任务；省略 device_id 时会自动选择设备并使用默认选项。
  • 输入（除非另有注明，均为可选）：
    • device_id（字符串）
    • resolution_dpi（整数，50–1200）
    • color_mode（Color | Gray | Lineart）：color_mode 默认为 Lineart（优先适用于文档）； 分辨率达到或超过 600dpi 时默认为 Color，因为高分辨率采集通常用于艺术作品或照片，而 1 位色深会丢失信息。传入 color_mode 可覆盖任一默认值；高分辨率是唯一采用的信号。
    • source（Flatbed | ADF | ADF Duplex）
    • duplex（布尔值）
    • page_size（Letter | A4 | Legal | Custom）
    • custom_size_mm { width, height }
    • doc_break_policy { type（page_count | none），page_count }：将批次拆分为每份 page_count 页的文档
    • 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 Schemas。运行时验证使用 zod（src/server/register.ts）；Schemas 用于说明契约，测试会根据它们进行断言。

选择与默认值的工作方式

默认值旨在采用 300dpi、合理的色彩模式，并在可用时使用 ADF/双面扫描。有关评分和回退机制的完整详情，请参阅文档：

• 选择与默认值：docs/SELECTION.md

项目布局

• src/mcp.ts — MCP 服务入口和工具注册
• src/services/* — 硬件接口和任务编排
• schemas/ — 说明工具契约的 JSON Schemas（供测试使用）
• docs/ — 架构、约定和深入说明

开发

• npm run dev（stdio MCP 服务），npm run dev:http（HTTP 传输）
• make verify 运行 lint、类型检查和测试
• 约定：docs/CONVENTIONS.md；架构见 docs/BLUEPRINT.md

路线图

想法和未来改进记录在 docs/ROADMAP.md 中。