DeckProbe MCP Server

Lassen Sie einen Agenten fragen, was in einer PDF-, Office- oder iWork-Datei steckt — ohne sie zu öffnen.

Installation · Tools · Konfiguration · Sicherheit · So funktioniert's · DeckProbe

Ein MCP-Server, der DeckProbe — ffprobe für Dokumente — als vier typisierte Tools bereitstellt. Fragen Sie nach Seitenzahlen, Folienzahlen, Metadaten, Verschlüsselungs- und Makrosignalen, Struktur oder Integrität, und Sie erhalten begrenztes, deterministisches JSON mit Konfidenz, Belegen und gemessenen I/O-Kosten zurück.

Es wird nichts gerendert, kein Makro ausgeführt, kein externer Verweis verfolgt und keine Netzwerkverbindung geöffnet. Es ist sicher, ihn auf nicht vertrauenswürdige Dateien zu richten.

// 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"
}

Installation

Vorab ist nichts zu installieren — npx lädt Server und Engine gemeinsam herunter.

Claude Code

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

Claude Desktop, Cursor, VS Code, Zed und alles andere, das mcpServers liest

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

Für eine Installation mit fester Version: npm install -g @deckflow/deckprobe-mcp ausführen und deckprobe-mcp als Befehl verwenden.

Erfordert Node.js 20 oder neuer. Die Engine-Binärdatei wird als optionale Abhängigkeit pro Plattform für macOS, Linux (glibc und musl) und Windows auf x86-64 und ARM64 mitgeliefert; überall sonst fällt der Server auf dieselbe als WebAssembly kompilierte Engine zurück, sodass npx überall dort funktioniert, wo Node läuft.

Related MCP server: document-parser

Tools

Es gibt außerdem eine Ressource, deckprobe://schema, die das mit der laufenden Engine gebündelte JSON-Schema des Berichts trägt.

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 akzeptiert Kurznamen (slide_count), kanonische Namen (powerpoint.slide_count) und Presets:

@summary lässt bewusst Statistiken aus, die ein vollständiges Lesen der Datei erfordern. Der page_count einer PDF ist der markante Fall — fragen Sie explizit danach.

probe_batch

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

Ein einziger Engine-Prozess übernimmt den gesamten Stapel. Ergebnisse kommen in Eingabereihenfolge zurück, jeweils mit eigenem Bericht oder eigenem Fehler, sodass eine fehlerhafte Datei den Lauf nie verdirbt. Standardmäßig wird die kompakte values-Ansicht verwendet. Nur literale Pfade — expandieren Sie Globs selbst.

list_formats und list_targets

list_targets nimmt ein format entgegen (pdf, docx, xlsx, pptx, doc, xls, ppt, key, numbers, pages) und liefert für jedes Ziel dessen Aliase, Beschreibung, Werttyp, Mindestebene, Kostenklasse und Selektorzugehörigkeit. Übergeben Sie detail: "full", um den vollständigen Bericht der Engine zu erhalten, einschließlich JSON-Schema-Fragmenten pro Ziel und erweiterten Selektorlisten.

Beide werden für die Lebensdauer des Serverprozesses zwischengespeichert.

Einen Bericht lesen

Das Tool-Ergebnis ist das eigene Schema-v2-Envelope der Engine, unverändert. Zwei Dinge sollten Sie wissen, bevor Sie es verarbeiten:

• status: "partial" ist kein Fehler. Es bedeutet, dass mindestens ein angefordertes Ziel nicht mit der angeforderten Konfidenz aufgelöst werden konnte. Es wird in execution.unresolved_targets benannt, und alle anderen Ergebnisse behalten ihre Gültigkeit.

• confidence_score ist eine feste Konstante pro Label (0.4, 0.7, 0.95, 1.0), keine kalibrierte Wahrscheinlichkeit. 0.95 bedeutet nicht, dass der Wert in 95 % der Fälle richtig ist.

Nur Ergebnisse mit dem Status resolved oder estimated tragen einen value. unknown ist häufig und bedeutet meist, dass das Dokument diese Tatsache schlicht nicht festhält.

Ein fehlgeschlagener Aufruf liefert isError mit dem Fehler-Envelope der Engine plus einer Zeile, die sagt, was zu tun ist. Fehler, die der Server selbst auslöst, bevor die Engine läuft — ein fehlender Pfad, ein Verzeichnis, ein Pfad außerhalb der Zulassungsliste, ein überschrittenes Zeitlimit — verwenden dieselbe Envelope-Form mit einem Code mit MCP_-Präfix und origin: "mcp-server".

Konfiguration

Jede Einstellung ist eine Umgebungsvariable, die in der MCP-Konfiguration Ihres Clients gesetzt wird. Alle sind optional.

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

Sicherheit

DeckProbe ist für nicht vertrauenswürdige Eingaben gebaut: begrenztes Parsing, kein Renderer, kein Makro-Interpreter, keine Auflösung externer Verweise und kein Netzwerkzugriff. Dieser Server fügt obendrein zwei Dinge hinzu.

• Prozessisolation und ein hartes Zeitlimit. Jeder Probevorgang läuft in einem eigenen kurzlebigen Prozess, der abgebrochen wird, wenn er DECKPROBE_MCP_TIMEOUT_MS überschreitet.

• Eine optionale Lese-Zulassungsliste. DECKPROBE_MCP_ROOTS begrenzt den erreichbaren Verzeichnisbaum; Pfade werden vor der Prüfung symlink-aufgelöst, sodass ein Link die Liste nicht umgehen kann. Der Standard ist uneingeschränkt und entspricht dem CLI, das der Benutzer selbst ausführen könnte — setzen Sie sie für gemeinsame oder automatisierte Bereitstellungen.

Berichte beschreiben ein Dokument (Metadaten, Zählwerte, Signale), statt dessen Inhalte zu reproduzieren. Beachten Sie, dass Berichtswerte wie ein Dokumenttitel dennoch vom Angreifer kontrollierte Zeichenketten sind: Der Server gibt sie als JSON-Daten unverändert weiter und interpoliert sie nie in Anweisungen; ein Konsument sollte sie genauso behandeln.

Melden Sie eine Schwachstelle vertraulich, wie in SECURITY.md beschrieben.

So funktioniert's

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

Der Server startet das native DeckProbe-CLI, anstatt die WebAssembly-Version aufzurufen. Das CLI liest nur die Bytebereiche, die ein Probe-Plan benötigt, während der WebAssembly-Pfad die gesamte Datei im Speicher hält; ein separater Betriebssystemprozess isoliert zum einen das Parsen nicht vertrauenswürdiger Daten und kann zum anderen jederzeit beendet werden. Die Engine wird in dieser Reihenfolge ausgewählt:

1. DECKPROBE_MCP_BIN

2. die Binärdatei, die mit der @deckflow/deckprobe-Abhängigkeit dieses Pakets geliefert wird

3. deckprobe im PATH

4. die gebündelte WebAssembly-Engine

Die aufgelöste Engine wird beim Start auf stderr protokolliert. stdout gehört zum MCP-Transport und enthält nichts anderes.

MCP-Server oder Agent Skill?

DeckProbe wird außerdem mit einer Agent Skill ausgeliefert, die einem shell-fähigen Agenten beibringt, das CLI direkt zu verwenden. Beide vermitteln denselben Wortschatz. Nutzen Sie die Skill, wenn der Agent eine Shell hat und Sie den vollständigen Funktionsumfang des CLI möchten; nutzen Sie diesen Server, wenn das nicht der Fall ist oder wenn Sie möchten, dass typisierte Argumente validiert werden, bevor die Engine überhaupt läuft.

Entwicklung

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

Beiträge sind willkommen — siehe CONTRIBUTING.md. Die Design-Begründung, einschließlich der verworfenen Alternativen, findet sich in docs/rfc.md.

Lizenz

MIT. Siehe LICENSE.