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）以及 x86-64 和 ARM64 架构的 Windows；其他环境中，服务会回退到编译为 WebAssembly 的同一引擎，因此凡是 Node 能运行的地方都能使用 npx。

工具

工具	用途
probe	获取一份文档的所有信息
probe_batch	在一次调用中盘点或分类处理多份文档
list_formats	查看支持哪些格式，以及支持范围
list_targets	查看某种格式提供的确切目标名称

此外还有一个资源 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）和预设：

预设	展开为
@header	仅容器身份信息——格式、大小、扩展名匹配情况、加密标记
@summary	身份信息、常见元数据和主要结构
@security	加密、宏、签名、外部引用、活动内容
@structure	格式自有的计数、名称和尺寸
@assets	图片、媒体、预览、字体、嵌入对象
@quality	完整性、修复、扩展名匹配、符合性
@format	当前级别下所有格式专属目标
@all	当前级别下所有可用内容

@summary 有意省略需要读取整个文件才能获取的统计信息。PDF 的 page_count 是其中的典型例子——请明确请求它。

probe_batch

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

整个批次由一个引擎进程处理。结果按输入顺序返回，每项都包含各自的报告或错误，因此单个文件出错不会影响整次运行。默认使用精简的 values 视图。仅接受字面路径——请自行展开 glob。

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_MCP_BIN	–	用于替代捆绑版本的引擎二进制文件
DECKPROBE_MCP_ROOTS	不限	允许访问的目录，分隔方式与 PATH 相同
DECKPROBE_MCP_TIMEOUT_MS	30000	引擎进程每次调用的硬性截止时间
DECKPROBE_MCP_MAX_CONCURRENCY	4	并发引擎进程数
DECKPROBE_MCP_MAX_BATCH	64	单次 probe_batch 调用接受的路径数

{
  "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 路径会将整个文件保存在内存中；此外，独立的 OS 进程既能隔离不可信内容的解析，也可以直接终止。引擎按以下顺序选择：

1. DECKPROBE_MCP_BIN
2. 随本软件包的 @deckflow/deckprobe 依赖一起提供的二进制文件
3. PATH 上的 deckprobe
4. 捆绑的 WebAssembly 引擎

启动时会将最终选用的引擎记录到 stderr。stdout 专供 MCP 传输使用，不会承载其他内容。

MCP 服务还是 Agent 技能？

DeckProbe 还提供了一个 Agent 技能，可指导能够使用 shell 的 Agent 直接使用 CLI。两者教授的词汇相同。当 Agent 能使用 shell，且你需要 CLI 的完整功能时，请使用该技能；如果 Agent 无法使用 shell，或者你希望在引擎运行前先验证类型化参数，请使用此服务。

开发

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

欢迎贡献，请参阅 CONTRIBUTING.md。设计依据（包括被否决的方案）见 docs/rfc.md。

许可证

MIT。请参阅 LICENSE。