DeckProbe MCP 服务器

让智能体无需打开 PDF、Office 或 iWork 文件，即可探知其中内容。

安装 · 工具 · 配置 · 安全 · 工作原理 · DeckProbe

一个 MCP 服务器，将 DeckProbe —— 文档领域的 ffprobe —— 以 四个类型化工具的形式暴露出来。查询页数、幻灯片数、元数据、加密和 宏信号、结构或完整性，即可获得有界、确定性的 JSON 结果，其中包含置信度、证据和实测 I/O 开销。

不渲染任何内容，不运行宏，不跟随任何外部引用，也不 打开任何网络连接。将其指向不受信任的文件是安全的。

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

安装

无需预先安装任何内容 —— npx 会同时获取服务器和引擎。

Claude Code

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

Claude Desktop、Cursor、VS Code、Zed 以及任何其他读取 mcpServers 的客户端

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

如需固定版本安装，请执行 npm install -g @deckflow/deckprobe-mcp，并使用 deckprobe-mcp 作为命令。

需要 Node.js 20 或更高版本。引擎二进制文件以按平台区分的 可选依赖形式提供，支持 macOS、Linux（glibc 和 musl）以及 Windows 的 x86-64 和 ARM64 架构；在其他任何平台上，服务器会回退到同一引擎的 WebAssembly 编译版本，因此只要 Node 可用，npx 就能在任何地方工作。

Related MCP server: document-parser

工具

此外还有一个资源 deckprobe://schema，携带随运行中的引擎一起打包的报告 JSON Schema。

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 接受短名称（slide_count）、规范名称 （powerpoint.slide_count）以及预设：

@summary 刻意省略了需要完整读取文件才能得到的统计信息。PDF 的 page_count 就是典型例子 —— 请显式请求它。

probe_batch

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

一个引擎进程处理整个批次。结果按输入顺序返回， 每个结果都带有自己的报告或自己的错误，因此一个坏文件永远不会破坏整个运行。 默认使用紧凑的 values 视图。仅支持字面路径 —— 请自行展开通配符。

list_formats 和 list_targets

list_targets 接受一个 format（pdf、docx、xlsx、pptx、doc、xls、 ppt、key、numbers、pages），并返回每个目标的别名、 描述、值类型、最低级别、开销类别和选择器成员资格。 传入 detail: "full" 可获取引擎的完整报告，包括每个目标的 JSON Schema 片段和展开的选择器列表。

两者都会在服务器进程的整个生命周期内缓存。

阅读报告

工具结果就是引擎自身的 schema-v2 信封，未做任何修改。在消费它之前， 有两件事值得了解：

• status: "partial" 不是失败。 它意味着至少有一个请求的 目标无法在请求的置信度下被解析。该目标会在 execution.unresolved_targets 中被点名，而所有其他结果仍然有效。

• confidence_score 是每个标签的固定常量（0.4、0.7、0.95、 1.0），不是校准后的概率。0.95 并不意味着该值在 95% 的情况下是正确的。

只有状态为 resolved 或 estimated 的结果才带有 value。unknown 很常见， 通常意味着文档根本没有记录该事实。

失败的调用会返回 isError，其中包含引擎的错误信封，外加一行 说明该如何处理。服务器在引擎运行之前自行引发的失败 —— 路径缺失、目录、 允许列表之外的路径、超出截止时间 —— 使用相同的信封形状，带有 MCP_ 前缀的代码和 origin: "mcp-server"。

配置

每个设置都是一个环境变量，在客户端的 MCP 配置中设置。 所有变量都是可选的。

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

安全

DeckProbe 专为不受信任的输入而构建：有界解析、无渲染器、无宏 解释器、无外部引用解析、无网络访问。此 服务器在此基础上增加了两项内容。

• 进程隔离和硬性截止时间。 每次探测都在自己独立的 短生命周期进程中运行，如果超过 DECKPROBE_MCP_TIMEOUT_MS 则被终止。

• 可选的读取允许列表。 DECKPROBE_MCP_ROOTS 固定了可访问的 目录树；路径在检查前会先解析符号链接，因此链接无法绕过它。 默认是不受限制的，与用户自己可以运行的 CLI 一致 —— 请在共享或自动化部署中设置它。

报告描述文档（元数据、计数、信号），而不是重现其 内容。请注意，报告值（如文档标题）仍然是攻击者控制的字符串： 服务器将它们作为 JSON 数据传递，绝不会将它们插入到指令中， 消费者应以同样的方式对待它们。

请按照 SECURITY.md 中的描述私下报告漏洞。

工作原理

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

服务器启动原生 DeckProbe CLI，而不是调用 WebAssembly 构建。CLI 只读取探测计划所需的字节范围，而 WebAssembly 路径会将整个文件保存在内存中，并且独立的操作系统进程既能 隔离不受信任的解析，也可以被直接终止。引擎按以下顺序选择：

1. DECKPROBE_MCP_BIN

2. 随此包的 @deckflow/deckprobe 依赖一起提供的二进制文件

3. PATH 上的 deckprobe

4. 随附的 WebAssembly 引擎

解析到的引擎会在启动时记录到 stderr。stdout 属于 MCP 传输层，不携带任何其他内容。

MCP 服务器还是智能体技能？

DeckProbe 还附带一个 Agent Skill， 用于教会具备 shell 能力的智能体直接使用 CLI。两者教授相同的 词汇表。当智能体拥有 shell 且你想要 CLI 的完整 功能面时，请使用该技能；当它没有 shell 时，或者当你希望在引擎运行之前 验证类型化参数时，请使用此服务器。

开发

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

欢迎贡献 —— 请参阅 CONTRIBUTING.md。设计 理由，包括被否决的备选方案，见 docs/rfc.md。

许可证

MIT。请参阅 LICENSE。