scan-mcp

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

Características

• Servidor MCP pequeño y tipado que expone herramientas para el descubrimiento de dispositivos y los trabajos de escaneo

• Entradas validadas con JSON Schema y salidas deterministas y tipadas

• Selección inteligente de dispositivo (prefiere ADF/dúplex, evita los backends de cámara), valores predeterminados robustos

• Transportes con prioridad local: stdio por defecto para mantenerlo todo en el dispositivo, HTTP opcional para tus propios despliegues de red

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

Related MCP server: fsext-mcp-server-java

Inicio rápido (stdio local, por defecto)

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 a través de stdio para una configuración de una sola máquina que prioriza la privacidad.

• Llama a start_scan_job sin device_id para seleccionar automáticamente un escáner y comenzar a escanear.

• Los artefactos se escriben en INBOX_DIR por trabajo: job-*/page_*.tiff, doc_*.tiff, manifest.json, events.jsonl. Cuando crop_carrier_sheets está activado y se detecta una hoja portadora, también se escribe un archivo derivado page_*.cropped.tiff para cada página afectada.

Transporte HTTP en streaming

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

scan-mcp --http

• El puerto por defecto es 3001; establece MCP_HTTP_PORT para sobrescribirlo (por ejemplo MCP_HTTP_PORT=3333 scan-mcp --http).

• Se vincula a todas las interfaces (::) por defecto; establece MCP_HTTP_HOST para restringirlo (por ejemplo MCP_HTTP_HOST=127.0.0.1 cuando un proxy inverso se sitúa delante del servidor).

• Las respuestas HTTP utilizan eventos enviados por el servidor (SSE) para transmitir la salida de las herramientas por streaming; clientes como Claude Desktop y Windsurf admiten este transporte.

• Actualmente no hay autenticación; está pensado para redes LAN internas.

Instalación

• Ejecútalo con npx: npx scan-mcp (recomendado)

  • La CLI realiza una comprobación previa rápida de Node 22+ y de las herramientas de escáner/imagen necesarias, e imprime sugerencias de instalación si falta algo.

  • Consulta la configuración de servidor recomendada más arriba

• Usa npx scan-mcp --http para lanzar el transporte HTTP en streaming cuando se ejecute 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 otras instalaciones de agentes automatizadas, consulta llms-install.md

Requisitos del sistema

• Linux con utilidades SANE: scanimage (y opcionalmente scanadf)

• Herramientas TIFF: tiffcp (preferido) o convert de ImageMagick

Variables de entorno

• SCAN_MOCK (por defecto: false): simula las llamadas SANE y genera TIFF simulados para las pruebas.

• INBOX_DIR (por defecto: scanned_documents/inbox): directorio base para las ejecuciones de trabajos y los artefactos.

• SCANIMAGE_BIN / SCANADF_BIN (por defecto: scanimage / scanadf): sobrescribe las rutas de los binarios.

• TIFFCP_BIN / IM_CONVERT_BIN (por defecto: tiffcp / convert): herramientas de ensamblado multipágina.

• SCAN_EXCLUDE_BACKENDS (CSV): backends a excluir (p. ej., v4l).

• SCAN_PREFER_BACKENDS (CSV): backends preferidos (p. ej., epjitsu,epson2).

• PERSIST_LAST_USED_DEVICE (por defecto: true): persiste y prefiere ligeramente el último dispositivo utilizado.

• MCP_HTTP_PORT (por defecto: 3001): puerto TCP para el transporte HTTP.

API

Herramientas

• list_devices

  • Descubre los escáneres conectados con detalles del backend.

  • Entradas: ninguna.

• get_device_options

  • Obtiene las opciones SANE de un dispositivo específico.

  • Entradas:

    • device_id (cadena): identificador del dispositivo de destino.

• 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 se establece en Lineart por defecto (prioridad a documentos); a partir de 600dpi se establece en Color, ya que la captura a alta resolución suele significar ilustraciones/fotos donde 1-bit destruye información. Pasa color_mode explícitamente para anular cualquiera de los dos valores predeterminados; la 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, por defecto tiff)

    • tmp_dir (cadena)

    • crop_carrier_sheets (booleano, por defecto false): detecta la banda del borde delantero de la hoja portadora y escribe archivos derivados de página recortados; las páginas originales 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; se intenta en la medida de lo posible durante los bucles de escaneo.

  • Entradas:

    • job_id (cadena)

• list_jobs

  • Enumera los trabajos recientes del directorio de entrada.

  • Entradas (opcionales):

    • limit (entero, máximo 100)

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

• get_manifest

  • Obtiene 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 conocer 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, un modo de color razonable y ADF/dúplex cuando esté disponible. Los detalles completos sobre la puntuación y los mecanismos de respaldo están en la documentación:

• 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 la validación y las pruebas

• docs/ — arquitectura, convenciones y análisis en profundidad

Desarrollo

• npm run dev (servidor MCP por 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 en seguimiento y las mejoras futuras están documentadas en docs/ROADMAP.md.