JinDaGe - scan-mcp MCP Details

article

README

🚀 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

环境变量

| 属性 | 详情 | |------|------| | 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）
  - 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。

scan-mcp