deckprobe

DeckProbe（ドキュメント向けの ffprobe）を4つの型付きツールとして提供するMCP サーバーです。ページ数、スライド数、メタデータ、暗号化やマクロの兆候、構造、整合性を問い合わせると、信頼度、根拠、計測済みのI/Oコストを含む、サイズ制限付きの決定的なJSONが返されます。

レンダリングは行われず、マクロも実行されず、外部参照も追跡されず、ネットワーク接続も開かれません。信頼できないファイルを指定しても安全です。

// 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以降が必要です。エンジンのバイナリは、x86-64およびARM64のmacOS、Linux（glibcおよびmusl）、Windows向けに、プラットフォームごとのオプション依存関係として提供されます。それ以外の環境では、サーバーはWebAssemblyにコンパイルされた同じエンジンにフォールバックするため、Node.jsが動作する環境であれば npx を利用できます。

ツール

ツール	用途
probe	1つのドキュメントに関するすべての情報を取得します
probe_batch	1回の呼び出しで複数のドキュメントを一覧化またはトリアージします
list_formats	対応形式と、その対応範囲を確認します
list_targets	形式で指定できるターゲット名を正確に確認します

さらに、実行中のエンジンにバンドルされているレポートJSON Schemaを含むリソース deckprobe://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"] }

1つのエンジンプロセスでバッチ全体を処理します。結果は入力順に返され、それぞれに個別のレポートまたはエラーが含まれるため、1つのファイルに問題があっても処理全体には影響しません。デフォルトではコンパクトな values ビューを返します。リテラルパスのみ対応しています。グロブはご自身で展開してください。

list_formats と list_targets

list_targets では format（pdf、docx、xlsx、pptx、doc、xls、ppt、key、numbers、pages）を指定します。各ターゲットのエイリアス、説明、値の型、最小レベル、コスト分類、セレクターへの所属が返されます。detail: "full" を渡すと、ターゲットごとのJSON Schema断片や展開済みのセレクター一覧を含む、エンジンの完全なレポートが返されます。

どちらもサーバープロセスの実行中はキャッシュされます。

レポートを読む

ツールの結果は、エンジン独自の schema-v2 エンベロープそのもので、変更は加えられていません。利用する前に知っておくべき点が2つあります。

• status: "partial" は失敗ではありません。 要求されたターゲットのうち、少なくとも1つを指定された信頼度で解決できなかったことを意味します。そのターゲットは execution.unresolved_targets に記載され、ほかの結果はすべて有効です。
• confidence_score はラベルごとに固定された定数（0.4、0.7、0.95、1.0）であり、校正済みの確率ではありません。0.95 は、その値が95%の確率で正しいという意味ではありません。

resolved または estimated のステータスを持つ結果にのみ value が含まれます。unknown はよくある値で、通常はその事実が文書に記録されていないことを意味します。

呼び出しが失敗すると、エンジンのエンベロープに加えて、対処方法を説明する1行を含む isError が返されます。エンジンの実行前にサーバー自体が発生させる失敗（パスが存在しない、ディレクトリである、許可リスト外のパスである、期限超過など）には、MCP_ が先頭に付いたコードと origin: "mcp-server" を含む同じ形式のエンベロープが使われます。

設定

すべての設定は環境変数で、クライアントの MCP 設定に指定します。いずれも省略可能です。

変数	デフォルト	意味
DECKPROBE_MCP_BIN	–	同梱版の代わりに使用するエンジンのバイナリ
DECKPROBE_MCP_ROOTS	unrestricted	PATH と同じ形式で区切って指定する、許可されたディレクトリ
DECKPROBE_MCP_TIMEOUT_MS	30000	エンジンプロセスごとの厳格な実行期限
DECKPROBE_MCP_MAX_CONCURRENCY	4	同時に実行できるエンジンプロセス数
DECKPROBE_MCP_MAX_BATCH	64	1回の probe_batch 呼び出しで受け付けるパス数

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

セキュリティ

DeckProbe は、信頼できない入力を扱うように設計されています。解析に上限を設け、レンダラーやマクロインタープリター、外部参照の解決機能を持たず、ネットワークにもアクセスしません。このサーバーは、これに加えて2つの機能を備えています。

• プロセスの分離と厳格な実行期限。 各プローブは短時間だけ実行される独自のプロセスで動作し、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

サーバーは WebAssembly ビルドを呼び出すのではなく、ネイティブの DeckProbe CLI を起動します。CLI はプローブ計画に必要なバイト範囲だけを読み取りますが、WebAssembly の場合はファイル全体をメモリに保持します。また、独立した OS プロセスにすることで、信頼できない入力の解析を分離し、プロセスを即座に終了させることもできます。エンジンは次の順に選択されます。

1. DECKPROBE_MCP_BIN
2. このパッケージの @deckflow/deckprobe 依存関係に同梱されたバイナリ
3. PATH 上の deckprobe
4. 同梱の WebAssembly エンジン

解決されたエンジンは、起動時に stderr へ記録されます。stdout は MCP トランスポート用であり、それ以外の内容は出力されません。

MCP サーバーとエージェントスキルのどちらを使うべきですか？

DeckProbe には、シェルを使用できるエージェントが CLI を直接使えるようにする エージェントスキル も含まれています。どちらも同じ用語を教えます。エージェントがシェルを利用でき、CLI の機能をすべて使いたい場合はスキルを使用してください。シェルを利用できない場合や、エンジンを実行する前に型付き引数を検証したい場合は、このサーバーを使用してください。

開発

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

貢献を歓迎します。CONTRIBUTING.md をご覧ください。却下された代替案を含む設計上の根拠は、docs/rfc.md に記載されています。

ライセンス

MIT。LICENSE をご覧ください。