# DeckProbe MCP Server **Let an agent ask what's inside a PDF, Office, or iWork file — without opening it.** [![CI](https://github.com/deckflow/deckprobe-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/deckflow/deckprobe-mcp-server/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@deckflow/deckprobe-mcp.svg)](https://www.npmjs.com/package/@deckflow/deckprobe-mcp) [![License: MIT](https://img.shields.io/badge/license-MIT-2f80ed.svg)](LICENSE) [Install](#install) · [Tools](#tools) · [Configuration](#configuration) · [Security](#security) · [How it works](#how-it-works) · [DeckProbe](https://github.com/deckflow/deckprobe)
An [MCP](https://modelcontextprotocol.io) server that exposes [DeckProbe](https://github.com/deckflow/deckprobe) — `ffprobe` for documents — as four typed tools. Ask for page counts, slide counts, metadata, encryption and macro signals, structure, or integrity, and get back bounded, deterministic JSON with confidence, evidence, and measured I/O cost. Nothing is rendered, no macro runs, no external reference is followed, and no network connection is opened. It is safe to point at untrusted files. ```jsonc // 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" } ``` ## Install Nothing to install ahead of time — `npx` fetches the server and the engine together. **Claude Code** ```sh claude mcp add deckprobe -- npx -y @deckflow/deckprobe-mcp ``` **Claude Desktop, Cursor, VS Code, Zed, and anything else reading `mcpServers`** ```jsonc { "mcpServers": { "deckprobe": { "command": "npx", "args": ["-y", "@deckflow/deckprobe-mcp"] } } } ``` For a pinned install, `npm install -g @deckflow/deckprobe-mcp` and use `deckprobe-mcp` as the command. Requires Node.js 20 or newer. The engine binary arrives as a per-platform optional dependency for macOS, Linux (glibc and musl), and Windows on x86-64 and ARM64; anywhere else the server falls back to the same engine compiled to WebAssembly, so `npx` works wherever Node does. ## Tools | Tool | Use it for | | --- | --- | | `probe` | Everything about one document | | `probe_batch` | Inventory or triage many documents in one call | | `list_formats` | Which formats are supported, and where support stops | | `list_targets` | The exact target names a format offers | There is also one resource, `deckprobe://schema`, carrying the report JSON Schema bundled with the running engine. ### `probe` ```jsonc { "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` accepts short names (`slide_count`), canonical names (`powerpoint.slide_count`), and presets: | Preset | Expands to | | --- | --- | | `@header` | Container identity only — format, size, extension match, encryption flag | | `@summary` | Identity, common metadata, and primary structure | | `@security` | Encryption, macros, signatures, external references, active content | | `@structure` | Format-owned counts, names, and dimensions | | `@assets` | Images, media, previews, fonts, embedded objects | | `@quality` | Integrity, repair, extension match, conformance | | `@format` | Every format-specific target at the active level | | `@all` | Everything available at the active level | `@summary` deliberately omits statistics that need a full-file read. A PDF's `page_count` is the notable case — ask for it explicitly. ### `probe_batch` ```jsonc { "paths": ["a.pdf", "b.pptx", "c.xlsx"], "targets": ["@security"] } ``` One engine process handles the whole batch. Results come back in input order, each with its own report or its own error, so one bad file never spoils the run. Defaults to the compact `values` view. Literal paths only — expand globs yourself. ### `list_formats` and `list_targets` `list_targets` takes a `format` (`pdf`, `docx`, `xlsx`, `pptx`, `doc`, `xls`, `ppt`, `key`, `numbers`, `pages`) and returns each target's aliases, description, value type, minimum level, cost class, and selector membership. Pass `detail: "full"` for the engine's complete report, including per-target JSON Schema fragments and expanded selector lists. Both are cached for the lifetime of the server process. ## Reading a report The tool result is the engine's own schema-v2 envelope, unmodified. Two things are worth knowing before consuming it: - **`status: "partial"` is not a failure.** It means at least one requested target could not be resolved at the requested confidence. It is named in `execution.unresolved_targets`, and every other result still stands. - **`confidence_score` is a fixed constant per label** (`0.4`, `0.7`, `0.95`, `1.0`), not a calibrated probability. `0.95` does not mean the value is right 95% of the time. Only results with status `resolved` or `estimated` carry a `value`. `unknown` is common and usually means the document simply does not record that fact. A failing call returns `isError` with the engine's error envelope plus one line saying what to do about it. Failures the server itself raises before the engine runs — a missing path, a directory, a path outside the allow-list, an exceeded deadline — use the same envelope shape with an `MCP_`-prefixed code and `origin: "mcp-server"`. ## Configuration Every setting is an environment variable, set in your client's MCP config. All are optional. | Variable | Default | Meaning | | --- | --- | --- | | `DECKPROBE_MCP_BIN` | – | Engine binary to use instead of the bundled one | | `DECKPROBE_MCP_ROOTS` | unrestricted | Allowed directories, separated like `PATH` | | `DECKPROBE_MCP_TIMEOUT_MS` | `30000` | Hard per-call deadline on an engine process | | `DECKPROBE_MCP_MAX_CONCURRENCY` | `4` | Concurrent engine processes | | `DECKPROBE_MCP_MAX_BATCH` | `64` | Paths accepted by one `probe_batch` call | ```jsonc { "deckprobe": { "command": "npx", "args": ["-y", "@deckflow/deckprobe-mcp"], "env": { "DECKPROBE_MCP_ROOTS": "/Users/me/Documents:/Users/me/Downloads" } } } ``` ## Security DeckProbe is built for untrusted input: bounded parsing, no renderer, no macro interpreter, no external-reference resolution, and no network access. This server adds two things on top. - **Process isolation and a hard deadline.** Each probe runs in its own short-lived process, killed if it outruns `DECKPROBE_MCP_TIMEOUT_MS`. - **An optional read allow-list.** `DECKPROBE_MCP_ROOTS` pins the reachable tree; paths are symlink-resolved before the check, so a link cannot step around it. The default is unrestricted, matching the CLI the user could run themselves — set it for shared or automated deployments. Reports describe a document (metadata, counts, signals) rather than reproducing its contents. Note that report values such as a document title are still attacker-controlled strings: the server passes them through as JSON data and never interpolates them into instructions, and a consumer should treat them the same way. Report a vulnerability privately as described in [SECURITY.md](SECURITY.md). ## How it works ```text 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 ``` The server spawns the native DeckProbe CLI rather than calling the WebAssembly build. The CLI reads only the byte ranges a probe plan needs, where the WebAssembly path holds the whole file in memory, and a separate OS process both isolates untrusted parsing and can be killed outright. The engine is chosen in this order: 1. `DECKPROBE_MCP_BIN` 2. the binary that ships with this package's `@deckflow/deckprobe` dependency 3. `deckprobe` on `PATH` 4. the bundled WebAssembly engine The resolved engine is logged to stderr at startup. stdout belongs to the MCP transport and carries nothing else. ## MCP server or agent skill? DeckProbe also ships an [Agent Skill](https://github.com/deckflow/deckprobe#use-from-a-coding-agent) that teaches a shell-capable agent to use the CLI directly. Both teach the same vocabulary. Use the skill when the agent has a shell and you want the CLI's full surface; use this server when it does not, or when you want typed arguments validated before the engine ever runs. ## Development ```sh npm install npm test # typecheck, lint, build, and the full suite npm run test:watch ``` Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). The design rationale, including the alternatives that were rejected, is in [docs/rfc.md](docs/rfc.md). ## License MIT. See [LICENSE](LICENSE).