scan-mcp

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

功能特性

• 小型、类型化的 MCP 服务器，提供设备发现和扫描任务工具

• 通过 JSON Schema 校验输入，输出确定且类型化

• 智能设备选择（优先 ADF/双面，避免相机后端），稳健的默认值

• 本地优先传输：默认使用 stdio 以保持全设备本地运行，可选 HTTP 用于自有网络部署

注意：本包面向 Node 22 和 Linux SANE 后端（scanimage）。

Related MCP server: MCPOSprint

快速开始（本地 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 派生文件。

流式 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 等客户端支持此传输方式。

• 目前没有身份验证；这仅适用于内部局域网使用。

安装

• 使用 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，因为高分辨率采集通常意味着艺术品/照片，而 1 位色深会丢失信息。可显式传入 color_mode 以覆盖任一默认值；高分辨率是唯一使用的信号。

    • 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。