scan-mcp

Servidor MCP mínimo para captura de scanner (ADF/duplex/tamanho de página), loteamento e montagem de múltiplas páginas

GitHub
6
Experimente este MCPPatrocinado

Documentação

scan-mcp logo

scan-mcp

CI npm version node-current npm downloads

Servidor MCP mínimo para captura de scanner (ADF/duplex/tamanho de página), processamento em lote e montagem de multipáginas.

Recursos

  • Servidor MCP pequeno e tipado, expondo ferramentas para descoberta de dispositivos e trabalhos de digitalização
  • Entradas validadas por JSON Schema com saídas determinísticas e tipadas
  • Seleção inteligente de dispositivo (prefere ADF/duplex, evita backends de câmera), padrões robustos
  • Transportes local-first: stdio por padrão para manter tudo no dispositivo, HTTP opcional para suas próprias implantações de rede

Nota: Este pacote tem como alvo Node 22 e backends SANE Linux (scanimage).

Início Rápido (stdio local, padrão)

Adicione uma entrada de servidor à configuração do seu cliente MCP:

{
  "mcpServers": {
    "scan": {
      "command": "npx",
      "args": [
        "-y",
        "scan-mcp"
      ],
      "env": {
        "INBOX_DIR": "~/Documents/scanned_documents/inbox"
      }
    }
  }
}
  • Esta invocação roda via stdio para uma configuração de máquina única, priorizando privacidade.
  • Chame start_scan_job sem um device_id para selecionar automaticamente um scanner e iniciar a digitalização.
  • Os artefatos são gravados em INBOX_DIR por trabalho: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl. Quando crop_carrier_sheets está definido e uma folha transportadora é detectada, um derivado page_*.cropped.tiff também é gravado por página afetada.

Transporte HTTP Streamable

Prefere conectar o scanner a outra máquina na sua rede? scan-mcp também suporta o transporte HTTP streamable:

scan-mcp --http
  • A porta padrão é 3001; defina MCP_HTTP_PORT para substituir (por exemplo, MCP_HTTP_PORT=3333 scan-mcp --http).
  • Vincula todas as interfaces (::) por padrão; defina MCP_HTTP_HOST para restringir (por exemplo, MCP_HTTP_HOST=127.0.0.1 quando um proxy reverso fica à frente do servidor).
  • As respostas HTTP usam server-sent events (SSE) para streaming da saída das ferramentas; clientes como Claude Desktop e Windsurf suportam este transporte.
  • Atualmente não há autenticação; isso é destinado a redes LAN internas

Instalação

  • Execute com npx: npx scan-mcp (recomendado)
    • A CLI executa uma verificação prévia rápida para Node 22+ e ferramentas de scanner/imagem necessárias, e imprime dicas de instalação se algo estiver faltando.
    • Veja a configuração de servidor recomendada acima
  • Use npx scan-mcp --http para iniciar o transporte HTTP streamable ao executar em outra máquina.
  • Ajuda da CLI: scan-mcp --help
  • A partir do código-fonte (para desenvolvimento):
    • npm install
    • npm run build
  • Para configuração do Cline e outras instalações agênticas automatizadas, veja llms-install.md

Requisitos do Sistema

  • Linux com utilitários SANE: scanimage (e opcionalmente scanadf)
  • Ferramentas TIFF: tiffcp (preferido) ou ImageMagick convert

Variáveis de Ambiente

  • SCAN_MOCK (padrão: false): simula chamadas SANE e gera TIFFs falsos para testes.
  • INBOX_DIR (padrão: scanned_documents/inbox): diretório base para execuções de trabalhos e artefatos.
  • SCANIMAGE_BIN / SCANADF_BIN (padrões: scanimage / scanadf): substitui caminhos de binários.
  • TIFFCP_BIN / IM_CONVERT_BIN (padrões: tiffcp / convert): ferramentas de montagem de multipáginas.
  • SCAN_EXCLUDE_BACKENDS (CSV): backends a excluir (por exemplo, v4l).
  • SCAN_PREFER_BACKENDS (CSV): backends preferidos (por exemplo, epjitsu,epson2).
  • PERSIST_LAST_USED_DEVICE (padrão: true): persiste e prefere levemente o último dispositivo usado.
  • MCP_HTTP_PORT (padrão: 3001): porta TCP para o transporte HTTP.

API

Ferramentas

  • list_devices

    • Descobre scanners conectados com detalhes do backend.
    • Entradas: nenhuma.

  • get_device_options

    • Obtém opções SANE para um dispositivo específico.
    • Entradas:
      • device_id (string): Identificador do dispositivo alvo.

  • start_scan_job

    • Inicia um trabalho de digitalização; omitir device_id aciona a seleção automática e opções padrão.
    • Entradas (todas opcionais, salvo indicação):
      • device_id (string)
      • resolution_dpi (inteiro, 50–1200)
      • color_mode (Color | Gray | Lineart): color_mode padrão é Lineart (documento primeiro); em >= 600dpi, o padrão é Color, já que captura em alta resolução geralmente significa arte/fotos onde 1-bit destrói informações. Passe color_mode explicitamente para substituir qualquer um dos padrões; alta resolução é o único sinal usado.
      • source (Flatbed | ADF | ADF Duplex)
      • duplex (booleano)
      • 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, padrão tiff)
      • tmp_dir (string)
      • crop_carrier_sheets (booleano, padrão false): detecta a banda da borda dianteira da folha transportadora e grava derivados de páginas recortadas; as páginas brutas são mantidas

  • get_job_status

    • Inspeciona o estado do trabalho e contagens de artefatos.
    • Entradas:
      • job_id (string)

  • cancel_job

    • Solicita cancelamento do trabalho; melhor esforço durante loops de digitalização.
    • Entradas:
      • job_id (string)

  • list_jobs

    • Lista trabalhos recentes do diretório de entrada.
    • Entradas (opcionais):
      • limit (inteiro, máx. 100)
      • state (running | completed | cancelled | error | unknown)

  • get_manifest

    • Busca o manifest.json de um trabalho.
    • Entradas:
      • job_id (string)

  • get_events

    • Recupera o log de events.jsonl de um trabalho.
    • Entradas:
      • job_id (string)

Veja os JSON Schemas em schemas/ para formatos de entrada. Testes verificam esses contratos.

Como Funcionam Seleção e Padrões

Os padrões visam 300dpi, modo de cor razoável e ADF/duplex quando disponível. Detalhes completos sobre pontuação e fallbacks estão na documentação:

  • Seleção e padrões: docs/SELECTION.md

Estrutura do Projeto

  • src/mcp.ts — entrada do servidor MCP e registro de ferramentas
  • src/services/* — interface de hardware e orquestração de trabalhos
  • schemas/ — JSON Schemas usados para validação e testes
  • docs/ — arquitetura, convenções e mergulhos profundos

Desenvolvimento

  • npm run dev (servidor MCP stdio), npm run dev:http (transporte HTTP)
  • make verify executa lint, typecheck e testes
  • Convenções: docs/CONVENTIONS.md e arquitetura em docs/BLUEPRINT.md

Roadmap

Ideias de rastreamento e melhorias futuras estão documentadas em docs/ROADMAP.md.