DeckProbe MCP Server

Permite que un agente pregunte qué hay dentro de un archivo PDF, Office o iWork — sin abrirlo.

Instalación · Herramientas · Configuración · Seguridad · Cómo funciona · DeckProbe

Un servidor MCP que expone DeckProbe — ffprobe para documentos — como cuatro herramientas tipadas. Pide recuentos de páginas, recuentos de diapositivas, metadatos, señales de cifrado y macros, estructura o integridad, y recibe JSON acotado y determinista con confianza, evidencia y coste de E/S medido.

No se renderiza nada, no se ejecuta ninguna macro, no se sigue ninguna referencia externa y no se abre ninguna conexión de red. Es seguro apuntarlo a archivos no fiables.

// probe { "path": "deck.pptx", "targets": ["slide_count"], "view": "values" }
{
  "schema_version": 2,
  "status": "ok",
  "driver": { "id": "powerpoint", "profile": "pptx" },
  "values": { "powerpoint.slide_count": 31 },
  "view": "values"
}

Instalación

No hay nada que instalar de antemano — npx obtiene el servidor y el motor juntos.

Claude Code

claude mcp add deckprobe -- npx -y @deckflow/deckprobe-mcp

Claude Desktop, Cursor, VS Code, Zed y cualquier otra cosa que lea mcpServers

{
  "mcpServers": {
    "deckprobe": {
      "command": "npx",
      "args": ["-y", "@deckflow/deckprobe-mcp"]
    }
  }
}

Para una instalación con una versión fija, ejecuta npm install -g @deckflow/deckprobe-mcp y usa deckprobe-mcp como comando.

Requiere Node.js 20 o superior. El binario del motor se distribuye como dependencia opcional por plataforma para macOS, Linux (glibc y musl) y Windows en x86-64 y ARM64; en cualquier otro lugar el servidor recurre al mismo motor compilado a WebAssembly, por lo que npx funciona dondequiera que funcione Node.

Related MCP server: document-parser

Herramientas

También hay un recurso, deckprobe://schema, con el JSON Schema del informe que trae el motor en ejecución.

probe

{
  "path": "reports/q3.pptx",
  "targets": ["@summary", "@security"],  // presets, short names, or canonical names
  "level": "metadata",                   // header | metadata | deep
  "min_confidence": "high",              // low | medium | high | exact
  "target_confidence": { "slide_count": "exact" },
  "view": "report",                      // report | values
  "budget": { "max_physical_bytes": 8388608, "timeout_ms": 1000 }
}

targets acepta nombres cortos (slide_count), nombres canónicos (powerpoint.slide_count) y preajustes:

@summary omite deliberadamente las estadísticas que requieren una lectura completa del archivo. El page_count de un PDF es el caso notable — pídelo explícitamente.

probe_batch

{ "paths": ["a.pdf", "b.pptx", "c.xlsx"], "targets": ["@security"] }

Un solo proceso del motor gestiona todo el lote. Los resultados vuelven en el orden de entrada, cada uno con su propio informe o su propio error, de modo que un archivo malo nunca estropea la ejecución. Por defecto se usa la vista compacta values. Solo rutas literales — expande los globs tú mismo.

list_formats y list_targets

list_targets toma un format (pdf, docx, xlsx, pptx, doc, xls, ppt, key, numbers, pages) y devuelve los alias de cada objetivo, su descripción, tipo de valor, nivel mínimo, clase de coste y pertenencia a selectores. Pasa detail: "full" para obtener el informe completo del motor, incluidos los fragmentos JSON Schema por objetivo y las listas de selectores expandidas.

Ambos se almacenan en caché durante la vida del proceso del servidor.

Cómo leer un informe

El resultado de la herramienta es el sobre schema-v2 propio del motor, sin modificar. Hay dos cosas que conviene saber antes de consumirlo:

• status: "partial" no es un fallo. Significa que al menos un objetivo solicitado no pudo resolverse con el nivel de confianza solicitado. Se indica en execution.unresolved_targets, y todos los demás resultados siguen siendo válidos.

• confidence_score es una constante fija por etiqueta (0.4, 0.7, 0.95, 1.0), no una probabilidad calibrada. 0.95 no significa que el valor sea correcto el 95 % de las veces.

Solo los resultados con estado resolved o estimated llevan un value. unknown es común y normalmente significa que el documento simplemente no registra ese dato.

Una llamada fallida devuelve isError con el sobre de error del motor más una línea que indica qué hacer al respecto. Los fallos que el propio servidor genera antes de que el motor se ejecute — una ruta inexistente, un directorio, una ruta fuera de la lista de permitidos, un plazo superado — usan la misma forma de sobre con un código prefijado con MCP_ y origin: "mcp-server".

Configuración

Todos los ajustes son variables de entorno que se definen en la configuración MCP de tu cliente. Todos son opcionales.

{
  "deckprobe": {
    "command": "npx",
    "args": ["-y", "@deckflow/deckprobe-mcp"],
    "env": { "DECKPROBE_MCP_ROOTS": "/Users/me/Documents:/Users/me/Downloads" }
  }
}

Seguridad

DeckProbe está diseñado para entradas no fiables: análisis acotado, sin renderizador, sin intérprete de macros, sin resolución de referencias externas y sin acceso a la red. Este servidor añade dos cosas más.

• Aislamiento de procesos y un plazo máximo. Cada análisis se ejecuta en su propio proceso de vida corta, que se termina si supera DECKPROBE_MCP_TIMEOUT_MS.

• Una lista de permitidos de lectura opcional. DECKPROBE_MCP_ROOTS fija el árbol accesible; las rutas se resuelven a través de enlaces simbólicos antes de la comprobación, de modo que un enlace no pueda saltársela. El valor predeterminado es sin restricciones, igual que la CLI que el usuario podría ejecutar por sí mismo — configúrala para despliegues compartidos o automatizados.

Los informes describen un documento (metadatos, recuentos, señales) en lugar de reproducir su contenido. Ten en cuenta que los valores del informe, como el título de un documento, siguen siendo cadenas controladas por el atacante: el servidor las pasa como datos JSON y nunca las interpola en instrucciones, y un consumidor debe tratarlas de la misma manera.

Notifica una vulnerabilidad de forma privada como se describe en SECURITY.md.

Cómo funciona

MCP client
    │  JSON-RPC over stdio
    ▼
deckprobe-mcp ── validates arguments, resolves the path, maps the result
    │  argv + stdout (one process per probe, or one --jsonl process per batch)
    ▼
DeckProbe engine ── plans the cheapest paths that answer the request

El servidor lanza la CLI nativa de DeckProbe en lugar de usar la compilación WebAssembly. La CLI solo lee los rangos de bytes que necesita un plan de análisis, mientras que la vía WebAssembly mantiene el archivo completo en memoria; además, un proceso separado del sistema operativo aísla el análisis de datos no fiables y puede terminarse por completo. El motor se elige en este orden:

1. DECKPROBE_MCP_BIN

2. el binario que se incluye con la dependencia @deckflow/deckprobe de este paquete

3. deckprobe en PATH

4. el motor WebAssembly incluido

El motor resuelto se registra en stderr al arrancar. stdout pertenece al transporte MCP y no lleva nada más.

¿Servidor MCP o habilidad de agente?

DeckProbe también incluye una Agent Skill que enseña a un agente capaz de usar un shell a utilizar la CLI directamente. Ambos enseñan el mismo vocabulario. Usa la habilidad cuando el agente tenga un shell y quieras la superficie completa de la CLI; usa este servidor cuando no lo tenga, o cuando quieras que los argumentos tipados se validen antes de que el motor llegue a ejecutarse.

Desarrollo

npm install
npm test          # typecheck, lint, build, and the full suite
npm run test:watch

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md. La justificación del diseño, incluidas las alternativas que se rechazaron, se encuentra en docs/rfc.md.

Licencia

MIT. Consulta LICENSE.