scan-mcp

Минимальный MCP-сервер для захвата со сканера (ADF/дуплекс/размер страницы), пакетной обработки и сборки многостраничных документов.

Возможности

• Небольшой типизированный MCP-сервер с инструментами для обнаружения устройств и заданий сканирования

• Входные данные, проверяемые по JSON Schema, с детерминированными типизированными выходными данными

• Умный выбор устройства (предпочитает ADF/дуплекс, избегает камерных бэкендов), надёжные значения по умолчанию

• Транспорты, ориентированные на локальную работу: stdio по умолчанию для полной автономности устройства, опциональный HTTP для собственных сетевых развёртываний

Примечание: этот пакет рассчитан на Node 22 и Linux-бэкенды SANE (scanimage).

Related MCP server: fsext-mcp-server-java

Быстрый старт (локальный 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).

• По умолчанию привязывается ко всем интерфейсам (::); задайте MCP_HTTP_HOST для ограничения (например, MCP_HTTP_HOST=127.0.0.1, когда перед сервером стоит обратный прокси).

• HTTP-ответы используют server-sent events (SSE) для потоковой передачи вывода инструментов; такие клиенты, как Claude Desktop и Windsurf, поддерживают этот транспорт.

• В настоящее время аутентификация отсутствует; это предназначено для внутренней LAN-сети.

Установка

• Запуск через npx: npx scan-mcp (рекомендуется)

  • CLI выполняет быструю предварительную проверку Node 22+ и необходимых инструментов сканера/изображений и выводит подсказки по установке, если чего-то не хватает.

  • См. рекомендуемую конфигурацию сервера выше.

• Используйте npx scan-mcp --http для запуска транспорта streamable HTTP при работе на другой машине.

• Справка CLI: scan-mcp --help

• Из исходников (для разработки):

  • npm install

  • npm run build

• Для настройки Cline и других автоматизированных агентных установок см. llms-install.md

Системные требования

• Linux с утилитами SANE: 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): TCP-порт для HTTP-транспорта.

API

Инструменты

• list_devices

  • Обнаружение подключённых сканеров с деталями бэкендов.

  • Входные данные: нет.

• get_device_options

  • Получение опций SANE для конкретного устройства.

  • Входные данные:

    • device_id (string): идентификатор целевого устройства.

• start_scan_job

  • Начало задания сканирования; пропуск device_id запускает автоматический выбор и опции по умолчанию.

  • Входные данные (все необязательны, если не указано иное):

    • device_id (string)

    • resolution_dpi (integer, 50–1200)

    • color_mode (Color | Gray | Lineart): color_mode по умолчанию — Lineart (в первую очередь для документов); при разрешении >= 600 dpi по умолчанию — Color, поскольку захват с высоким разрешением обычно означает изображения/фотографии, где 1-битный режим уничтожает информацию. Передайте color_mode явно, чтобы переопределить любой из значений по умолчанию; высокое разрешение — единственный используемый сигнал.

    • source (Flatbed | ADF | ADF Duplex)

    • duplex (boolean)

    • 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 (string, по умолчанию tiff)

    • tmp_dir (string)

    • crop_carrier_sheets (boolean, по умолчанию false): обнаруживать полосу передней кромки листа-носителя и записывать производные обрезанные страницы; исходные страницы сохраняются

• get_job_status

  • Проверка состояния задания и количества артефактов.

  • Входные данные:

    • job_id (string)

• cancel_job

  • Запрос отмены задания; выполняется по мере возможности во время циклов сканирования.

  • Входные данные:

    • job_id (string)

• list_jobs

  • Список недавних заданий из директории входящих.

  • Входные данные (необязательно):

    • limit (integer, максимум 100)

    • state (running | completed | cancelled | error | unknown)

• get_manifest

  • Получение manifest.json задания.

  • Входные данные:

    • job_id (string)

• get_events

  • Получение журнала events.jsonl задания.

  • Входные данные:

    • job_id (string)

См. JSON-схемы в schemas/ для описания форм входных данных. Тесты проверяют соответствие этим контрактам.

Как работают выбор и значения по умолчанию

Значения по умолчанию нацелены на 300 dpi, разумный цветовой режим и ADF/дуплекс при наличии. Полные подробности о подсчёте баллов и запасных вариантах — в документации:

• Выбор и значения по умолчанию: docs/SELECTION.md

Структура проекта

• src/mcp.ts — точка входа MCP-сервера и регистрация инструментов

• src/services/* — интерфейс оборудования и оркестрация заданий

• schemas/ — JSON-схемы, используемые для валидации и тестов

• docs/ — архитектура, соглашения и углублённые разборы

Разработка

• npm run dev (stdio MCP-сервер), npm run dev:http (HTTP-транспорт)

• make verify запускает lint, проверку типов и тесты

• Соглашения: docs/CONVENTIONS.md и архитектура в docs/BLUEPRINT.md

Дорожная карта

Отслеживание идей и будущих улучшений задокументировано в docs/ROADMAP.md.