scan-mcp

Servidor MCP mínimo para captura de escáner (ADF/dúplex/tamaño de página), procesamiento por lotes y ensamblaje de varias páginas

GitHub
6
Prueba este MCPPatrocinado

Documentación

scan-mcp logo

scan-mcp

CI npm version node-current npm downloads

Servidor MCP mínimo para captura de escáner (ADF/dúplex/tamaño de página), procesamiento por lotes y ensamblado multipágina.

Características

  • Servidor MCP pequeño y tipado que expone herramientas para descubrimiento de dispositivos y trabajos de escaneo
  • Entradas validadas con JSON Schema y salidas tipadas y deterministas
  • Selección inteligente de dispositivo (prefiere ADF/dúplex, evita backends de cámara), valores predeterminados robustos
  • Transportes locales primero: stdio por defecto para mantener todo en el dispositivo, HTTP opcional para tus propios despliegues de red

Nota: Este paquete está dirigido a Node 22 y backends SANE de Linux (scanimage).

Inicio rápido (stdio local, predeterminado)

Añade una entrada de servidor a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "scan": {
      "command": "npx",
      "args": [
        "-y",
        "scan-mcp"
      ],
      "env": {
        "INBOX_DIR": "~/Documents/scanned_documents/inbox"
      }
    }
  }
}
  • Esta invocación se ejecuta sobre stdio para una configuración de una sola máquina y privacidad primero.
  • Llama a start_scan_job sin un device_id para seleccionar automáticamente un escáner y comenzar a escanear.
  • Los artefactos se escriben bajo INBOX_DIR por trabajo: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl. Cuando crop_carrier_sheets está configurado y se detecta una hoja portadora, también se escribe un derivado page_*.cropped.tiff por página afectada.

Transporte HTTP transmisible

¿Prefieres conectar el escáner a otra máquina de tu red? scan-mcp también admite el transporte HTTP transmisible:

scan-mcp --http
  • El puerto predeterminado es 3001; establece MCP_HTTP_PORT para anularlo (por ejemplo, MCP_HTTP_PORT=3333 scan-mcp --http).
  • Vincula todas las interfaces (::) por defecto; establece MCP_HTTP_HOST para restringir (por ejemplo, MCP_HTTP_HOST=127.0.0.1 cuando un proxy inverso está frente al servidor).
  • Las respuestas HTTP utilizan eventos enviados por el servidor (SSE) para la transmisión de salida de herramientas; clientes como Claude Desktop y Windsurf admiten este transporte.
  • Actualmente no hay autenticación; esto está destinado a redes LAN internas.

Instalación

  • Ejecuta con npx: npx scan-mcp (recomendado)
    • La CLI ejecuta una verificación previa rápida para Node 22+ y las herramientas de escáner/imagen requeridas, e imprime sugerencias de instalación si falta algo.
    • Consulta la configuración de servidor recomendada arriba
  • Usa npx scan-mcp --http para lanzar el transporte HTTP transmisible cuando se ejecuta en otra máquina.
  • Ayuda de la CLI: scan-mcp --help
  • Desde el código fuente (para desarrollo):
    • npm install
    • npm run build
  • Para la configuración de Cline y otra instalación agéntica automatizada, consulta llms-install.md

Requisitos del sistema

  • Linux con utilidades SANE: scanimage (y opcionalmente scanadf)
  • Herramientas TIFF: tiffcp (preferido) o ImageMagick convert

Variables de entorno

  • SCAN_MOCK (predeterminado: false): simula llamadas SANE y genera TIFF falsos para pruebas.
  • INBOX_DIR (predeterminado: scanned_documents/inbox): directorio base para ejecuciones de trabajos y artefactos.
  • SCANIMAGE_BIN / SCANADF_BIN (predeterminados: scanimage / scanadf): anula rutas de binarios.
  • TIFFCP_BIN / IM_CONVERT_BIN (predeterminados: tiffcp / convert): herramientas de ensamblado multipágina.
  • SCAN_EXCLUDE_BACKENDS (CSV): backends a excluir (por ejemplo, v4l).
  • SCAN_PREFER_BACKENDS (CSV): backends preferidos (por ejemplo, epjitsu,epson2).
  • PERSIST_LAST_USED_DEVICE (predeterminado: true): persiste y prefiere ligeramente el último dispositivo usado.
  • MCP_HTTP_PORT (predeterminado: 3001): puerto TCP para el transporte HTTP.

API

Herramientas

  • list_devices

    • Descubre escáneres conectados con detalles del backend.
    • Entradas: ninguna.

  • get_device_options

    • Obtén opciones SANE para un dispositivo específico.
    • Entradas:
      • device_id (cadena): Identificador del dispositivo objetivo.

  • start_scan_job

    • Inicia un trabajo de escaneo; omitir device_id activa la selección automática y las opciones predeterminadas.
    • Entradas (todas opcionales salvo que se indique):
      • device_id (cadena)
      • resolution_dpi (entero, 50–1200)
      • color_mode (Color | Gray | Lineart): color_mode predeterminado a Lineart (documento primero); a >= 600dpi predeterminado a Color, ya que la captura de alta resolución generalmente significa arte/fotos donde 1 bit destruye información. Pasa color_mode explícitamente para anular cualquiera de los predeterminados; alta resolución es la única señal utilizada.
      • 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 (cadena, predeterminado tiff)
      • tmp_dir (cadena)
      • crop_carrier_sheets (booleano, predeterminado false): detecta la banda del borde delantero de la hoja portadora y escribe derivados de página recortados; las páginas sin procesar se conservan

  • get_job_status

    • Inspecciona el estado del trabajo y los recuentos de artefactos.
    • Entradas:
      • job_id (cadena)

  • cancel_job

    • Solicita la cancelación del trabajo; mejor esfuerzo durante los bucles de escaneo.
    • Entradas:
      • job_id (cadena)

  • list_jobs

    • Lista trabajos recientes del directorio de entrada.
    • Entradas (opcionales):
      • limit (entero, máximo 100)
      • state (running | completed | cancelled | error | unknown)

  • get_manifest

    • Obtén el manifest.json de un trabajo.
    • Entradas:
      • job_id (cadena)

  • get_events

    • Recupera el registro events.jsonl de un trabajo.
    • Entradas:
      • job_id (cadena)

Consulta los JSON Schemas en schemas/ para las formas de entrada. Las pruebas verifican estos contratos.

Cómo funcionan la selección y los valores predeterminados

Los valores predeterminados apuntan a 300dpi, modo de color razonable y ADF/dúplex cuando esté disponible. Los detalles completos sobre puntuación y alternativas están en los documentos:

  • Selección y valores predeterminados: docs/SELECTION.md

Estructura del proyecto

  • src/mcp.ts — entrada del servidor MCP y registro de herramientas
  • src/services/* — interfaz de hardware y orquestación de trabajos
  • schemas/ — JSON Schemas utilizados para validación y pruebas
  • docs/ — arquitectura, convenciones y análisis profundos

Desarrollo

  • npm run dev (servidor MCP stdio), npm run dev:http (transporte HTTP)
  • make verify ejecuta lint, typecheck y pruebas
  • Convenciones: docs/CONVENTIONS.md y arquitectura en docs/BLUEPRINT.md

Hoja de ruta

Las ideas de seguimiento y mejoras futuras están documentadas en docs/ROADMAP.md.