@deckflow/deckprobe-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tenly Wu and DeckProbe contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,244 @@
+<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).

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_CONCURRENCY = 4;
+export declare const DEFAULT_MAX_BATCH = 64;
+export interface Config {
+    /** Explicit engine binary, from `DECKPROBE_MCP_BIN`. */
+    readonly binOverride: string | undefined;
+    /** Allowed directory roots. Empty means unrestricted. */
+    readonly roots: readonly string[];
+    /** Hard per-call deadline on an engine process. */
+    readonly timeoutMs: number;
+    /** Maximum engine processes running at once, across every tool. */
+    readonly maxConcurrency: number;
+    /** Maximum paths accepted by one `probe_batch` call. */
+    readonly maxBatch: number;
+}
+/**
+ * Absolute, symlink-resolved form of a path. Roots and inputs are both put
+ * through this so an allow-list cannot be stepped around with a symlink, and
+ * so `/tmp` and `/private/tmp` compare equal on macOS.
+ *
+ * A path that does not exist yet cannot be resolved; the absolute form is
+ * returned instead and the caller's own existence check reports the problem.
+ */
+export declare function canonicalPath(path: string): string;
+/** True when `target` is inside `root`, by path segment rather than string prefix. */
+export declare function isInsideRoot(target: string, root: string): boolean;
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,MAAM,WAAW,MAAM;IACrB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAYD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAIlE;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAoBvE"}

package/dist/config.js

@@ -0,0 +1,59 @@
+import { realpathSync } from "node:fs";
+import { delimiter, isAbsolute, relative, resolve } from "node:path";
+import { ConfigError } from "./errors.js";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_CONCURRENCY = 4;
+export const DEFAULT_MAX_BATCH = 64;
+function readPositiveInt(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new ConfigError(`${name} must be a positive integer, got ${JSON.stringify(raw)}`);
+    }
+    return parsed;
+}
+/**
+ * Absolute, symlink-resolved form of a path. Roots and inputs are both put
+ * through this so an allow-list cannot be stepped around with a symlink, and
+ * so `/tmp` and `/private/tmp` compare equal on macOS.
+ *
+ * A path that does not exist yet cannot be resolved; the absolute form is
+ * returned instead and the caller's own existence check reports the problem.
+ */
+export function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** True when `target` is inside `root`, by path segment rather than string prefix. */
+export function isInsideRoot(target, root) {
+    if (target === root)
+        return true;
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+export function loadConfig(env = process.env) {
+    const rawRoots = env.DECKPROBE_MCP_ROOTS;
+    const roots = rawRoots === undefined || rawRoots.trim() === ""
+        ? []
+        : rawRoots
+            .split(delimiter)
+            .map((entry) => entry.trim())
+            .filter((entry) => entry !== "")
+            .map(canonicalPath);
+    const binOverride = env.DECKPROBE_MCP_BIN?.trim();
+    return {
+        binOverride: binOverride === "" ? undefined : binOverride,
+        roots,
+        timeoutMs: readPositiveInt(env, "DECKPROBE_MCP_TIMEOUT_MS", DEFAULT_TIMEOUT_MS),
+        maxConcurrency: readPositiveInt(env, "DECKPROBE_MCP_MAX_CONCURRENCY", DEFAULT_MAX_CONCURRENCY),
+        maxBatch: readPositiveInt(env, "DECKPROBE_MCP_MAX_BATCH", DEFAULT_MAX_BATCH),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AACzC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAepC,SAAS,eAAe,CAAC,GAAsB,EAAE,IAAY,EAAE,QAAgB;IAC7E,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,WAAW,CAAC,GAAG,IAAI,oCAAoC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,IAAY;IACvD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,CAAC;IACzC,MAAM,KAAK,GACT,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAC9C,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,QAAQ;aACL,KAAK,CAAC,SAAS,CAAC;aAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;aAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC;aAC/B,GAAG,CAAC,aAAa,CAAC,CAAC;IAE5B,MAAM,WAAW,GAAG,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAElD,OAAO;QACL,WAAW,EAAE,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;QACzD,KAAK;QACL,SAAS,EAAE,eAAe,CAAC,GAAG,EAAE,0BAA0B,EAAE,kBAAkB,CAAC;QAC/E,cAAc,EAAE,eAAe,CAAC,GAAG,EAAE,+BAA+B,EAAE,uBAAuB,CAAC;QAC9F,QAAQ,EAAE,eAAe,CAAC,GAAG,EAAE,yBAAyB,EAAE,iBAAiB,CAAC;KAC7E,CAAC;AACJ,CAAC"}

package/dist/engine/index.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from "../config.js";
+import type { Engine } from "./types.js";
+export type { Budget, Confidence, Engine, EngineOutcome, ProbeLevel, ProbeRequest, ProbeView, } from "./types.js";
+export { errorCodeOf, exitCodeOf, isRecord } from "./types.js";
+/**
+ * Picks the engine, in the order documented in the README:
+ * `DECKPROBE_MCP_BIN`, then the binary that came with the `@deckflow/deckprobe`
+ * dependency, then `deckprobe` on PATH, then the WebAssembly fallback.
+ */
+export declare function createEngine(config: Config): Promise<Engine>;
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,YAAY,EACV,MAAM,EACN,UAAU,EACV,MAAM,EACN,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAiB/D;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBlE"}

package/dist/engine/index.js

@@ -0,0 +1,60 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { ConfigError } from "../errors.js";
+import { NativeEngine } from "./native.js";
+import { WasmEngine } from "./wasm.js";
+export { errorCodeOf, exitCodeOf, isRecord } from "./types.js";
+const require = createRequire(import.meta.url);
+/**
+ * Picks the engine, in the order documented in the README:
+ * `DECKPROBE_MCP_BIN`, then the binary that came with the `@deckflow/deckprobe`
+ * dependency, then `deckprobe` on PATH, then the WebAssembly fallback.
+ */
+export async function createEngine(config) {
+    if (config.binOverride) {
+        if (!(await isRunnable(config.binOverride))) {
+            throw new ConfigError(`DECKPROBE_MCP_BIN=${config.binOverride} is not a runnable DeckProbe binary`);
+        }
+        return new NativeEngine(config.binOverride, config);
+    }
+    const packaged = await resolvePackagedBinary();
+    if (packaged)
+        return new NativeEngine(packaged, config);
+    if (await isRunnable("deckprobe"))
+        return new NativeEngine("deckprobe", config);
+    return new WasmEngine();
+}
+/**
+ * Resolves the per-platform optional dependency the same way the upstream npm
+ * launcher does, by reusing its own platform table — including the musl/glibc
+ * detection an independent copy of the table would get wrong.
+ */
+async function resolvePackagedBinary() {
+    try {
+        const packageRoot = dirname(require.resolve("@deckflow/deckprobe/package.json"));
+        const platformsUrl = pathToFileURL(join(packageRoot, "bin", "platforms.js"));
+        const platforms = (await import(platformsUrl.href));
+        const platform = platforms.currentPlatform();
+        if (!platform)
+            return undefined;
+        const dependencyRoot = dirname(require.resolve(`${platforms.packageName(platform)}/package.json`));
+        const binary = join(dependencyRoot, "bin", platforms.binaryName(platform));
+        return existsSync(binary) ? binary : undefined;
+    }
+    catch {
+        // No platform package for this OS/arch, an install that skipped optional
+        // dependencies, or an upstream layout change. Fall through to PATH.
+        return undefined;
+    }
+}
+function isRunnable(binary) {
+    return new Promise((settle) => {
+        const child = spawn(binary, ["--version"], { stdio: "ignore" });
+        child.on("error", () => settle(false));
+        child.on("close", (code) => settle(code === 0));
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"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"}

package/dist/engine/native.d.ts

@@ -0,0 +1,21 @@
+import type { Config } from "../config.js";
+import type { Engine, EngineOutcome, ProbeRequest } from "./types.js";
+/**
+ * Every option DeckProbe is given comes from here, in `--long=value` form so a
+ * target or format name can never be read as a flag. The document path is
+ * passed after `--` for the same reason.
+ */
+export declare function probeArgs(request: ProbeRequest): string[];
+export declare class NativeEngine implements Engine {
+    #private;
+    readonly kind: "native";
+    readonly description: string;
+    constructor(binary: string, config: Config);
+    version(): Promise<string>;
+    probe(path: string, request: ProbeRequest): Promise<EngineOutcome>;
+    probeBatch(paths: readonly string[], request: ProbeRequest): Promise<EngineOutcome[]>;
+    formats(): Promise<EngineOutcome>;
+    targets(format: string): Promise<EngineOutcome>;
+    schema(): Promise<EngineOutcome>;
+}
+//# sourceMappingURL=native.d.ts.map

package/dist/engine/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../../src/engine/native.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAuCtE;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,EAAE,CAsBzD;AAED,qBAAa,YAAa,YAAW,MAAM;;IACzC,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAMjB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAOpC,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IAK1B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAKlE,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAsBrF,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAIjC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI/C,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;CAoHvC"}

package/dist/engine/native.js

@@ -0,0 +1,193 @@
+import { spawn } from "node:child_process";
+import { ServerError } from "../errors.js";
+import { exitCodeOf } from "./types.js";
+/** Guards against an engine that never stops writing. Reports stay far below this. */
+const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+/** Grace period between the polite stop and the hard kill on a timeout. */
+const KILL_GRACE_MS = 2_000;
+class Semaphore {
+    #available;
+    #waiting = [];
+    constructor(permits) {
+        this.#available = permits;
+    }
+    async run(task) {
+        if (this.#available > 0) {
+            this.#available -= 1;
+        }
+        else {
+            await new Promise((release) => this.#waiting.push(release));
+        }
+        try {
+            return await task();
+        }
+        finally {
+            const next = this.#waiting.shift();
+            if (next)
+                next();
+            else
+                this.#available += 1;
+        }
+    }
+}
+/**
+ * Every option DeckProbe is given comes from here, in `--long=value` form so a
+ * target or format name can never be read as a flag. The document path is
+ * passed after `--` for the same reason.
+ */
+export function probeArgs(request) {
+    const args = [];
+    for (const target of request.targets ?? [])
+        args.push(`--targets=${target}`);
+    if (request.level)
+        args.push(`--probe-level=${request.level}`);
+    if (request.min_confidence)
+        args.push(`--minimum-confidence=${request.min_confidence}`);
+    for (const [target, confidence] of Object.entries(request.target_confidence ?? {})) {
+        args.push(`--target-confidence=${target}=${confidence}`);
+    }
+    if (request.view === "values")
+        args.push("--view=values");
+    const budget = request.budget;
+    if (budget?.max_physical_bytes !== undefined) {
+        args.push(`--probe-size=${budget.max_physical_bytes}`);
+    }
+    if (budget?.max_expanded_bytes !== undefined) {
+        args.push(`--max-expanded-bytes=${budget.max_expanded_bytes}`);
+    }
+    if (budget?.max_archive_entries !== undefined) {
+        args.push(`--max-archive-entries=${budget.max_archive_entries}`);
+    }
+    if (budget?.timeout_ms !== undefined)
+        args.push(`--timeout-ms=${budget.timeout_ms}`);
+    return args;
+}
+export class NativeEngine {
+    kind = "native";
+    description;
+    #binary;
+    #timeoutMs;
+    #semaphore;
+    constructor(binary, config) {
+        this.#binary = binary;
+        this.#timeoutMs = config.timeoutMs;
+        this.#semaphore = new Semaphore(config.maxConcurrency);
+        this.description = `native CLI at ${binary}`;
+    }
+    async version() {
+        const { stdout } = await this.#exec(["--version"]);
+        return stdout.trim();
+    }
+    async probe(path, request) {
+        const { code, stdout, stderr } = await this.#exec([...probeArgs(request), "--", path]);
+        return { exitCode: code, json: this.#parse(stdout, stderr, code) };
+    }
+    async probeBatch(paths, request) {
+        const records = paths.map((path) => JSON.stringify({ path })).join("\n");
+        const { stdout, stderr, code } = await this.#exec(["--jsonl", ...probeArgs(request)], `${records}\n`);
+        const lines = stdout.split("\n").filter((line) => line.trim() !== "");
+        if (lines.length !== paths.length) {
+            throw new ServerError("MCP_ENGINE_FAILURE", `expected ${paths.length} JSONL results, received ${lines.length}` +
+                `${stderr.trim() ? ` (stderr: ${truncate(stderr.trim(), 400)})` : ""}`);
+        }
+        return lines.map((line) => {
+            const json = this.#parse(line, stderr, code);
+            return { exitCode: exitCodeOf(json), json };
+        });
+    }
+    async formats() {
+        return this.#discovery(["formats"]);
+    }
+    async targets(format) {
+        return this.#discovery(["targets", "--format", format]);
+    }
+    async schema() {
+        return this.#discovery(["schema"]);
+    }
+    async #discovery(args) {
+        const { code, stdout, stderr } = await this.#exec(args);
+        return { exitCode: code, json: this.#parse(stdout, stderr, code) };
+    }
+    /**
+     * DeckProbe writes one JSON value to stdout for every outcome, success or
+     * failure, and never uses stderr for results. Anything else means the binary
+     * is not the one we think it is, so stderr is surfaced for diagnosis.
+     */
+    #parse(stdout, stderr, code) {
+        try {
+            return JSON.parse(stdout);
+        }
+        catch {
+            const detail = stderr.trim() || stdout.trim() || "(no output)";
+            throw new ServerError("MCP_ENGINE_FAILURE", `engine exited with status ${code} and did not write a JSON report: ${truncate(detail, 800)}`);
+        }
+    }
+    #exec(args, stdin) {
+        return this.#semaphore.run(() => new Promise((settle, fail) => {
+            const child = spawn(this.#binary, args, { stdio: ["pipe", "pipe", "pipe"] });
+            let stdout = "";
+            let stderr = "";
+            let overflowed = false;
+            let timedOut = false;
+            let hardKill;
+            const deadline = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                hardKill = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+            }, this.#timeoutMs);
+            const done = () => {
+                clearTimeout(deadline);
+                if (hardKill)
+                    clearTimeout(hardKill);
+            };
+            child.stdout.setEncoding("utf8");
+            child.stderr.setEncoding("utf8");
+            child.stdout.on("data", (chunk) => {
+                if (stdout.length + chunk.length > MAX_OUTPUT_BYTES) {
+                    overflowed = true;
+                    child.kill("SIGKILL");
+                    return;
+                }
+                stdout += chunk;
+            });
+            child.stderr.on("data", (chunk) => {
+                if (stderr.length < 64 * 1024)
+                    stderr += chunk;
+            });
+            child.on("error", (error) => {
+                done();
+                fail(new ServerError("MCP_ENGINE_FAILURE", `cannot run the DeckProbe engine at ${this.#binary}: ${error.message}`));
+            });
+            child.on("close", (code, signal) => {
+                done();
+                if (timedOut) {
+                    fail(new ServerError("MCP_TIMEOUT", `the probe exceeded the ${this.#timeoutMs} ms server deadline and was stopped`, "Raise DECKPROBE_MCP_TIMEOUT_MS, or lower the probe level or budget so the engine finishes sooner."));
+                    return;
+                }
+                if (overflowed) {
+                    fail(new ServerError("MCP_ENGINE_FAILURE", `the engine wrote more than ${MAX_OUTPUT_BYTES} bytes and was stopped`));
+                    return;
+                }
+                if (code === null) {
+                    fail(new ServerError("MCP_ENGINE_FAILURE", `the engine was killed by signal ${signal}`));
+                    return;
+                }
+                settle({ code, stdout, stderr });
+            });
+            if (stdin !== undefined) {
+                child.stdin.on("error", () => {
+                    // A record-level failure can close stdin before the last write
+                    // lands. The exit status and stdout still carry the outcome.
+                });
+                child.stdin.end(stdin);
+            }
+            else {
+                child.stdin.end();
+            }
+        }));
+    }
+}
+function truncate(text, limit) {
+    return text.length <= limit ? text : `${text.slice(0, limit)}…`;
+}
+//# sourceMappingURL=native.js.map