deckprobe-mcp-server

<div align="center">

# 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)

</div>

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).