mcp-recon 0.2.2

package/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Euan McRosson
+
+   Full license text: https://www.apache.org/licenses/LICENSE-2.0.txt

package/README.md

@@ -0,0 +1,271 @@
+# mcp-recon
+
+[![CI](https://github.com/euanmcrosson-dotcom/mcp-recon/actions/workflows/ci.yml/badge.svg)](https://github.com/euanmcrosson-dotcom/mcp-recon/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-orange.svg)](docs/SPEC.md)
+[![Tests: 68 passing](https://img.shields.io/badge/tests-68_passing-success.svg)](#tests)
+[![Companion: capnagent](https://img.shields.io/badge/companion-capnagent-9cf.svg)](https://github.com/euanmcrosson-dotcom/capnagent)
+
+> **Reverse-engineer any MCP server's tool surface in 30 seconds.**
+> Connects to an MCP server (stdio or HTTP), enumerates its tools,
+> runs a schema-aware adversarial fuzzer, classifies the authority
+> each tool exposes against OWASP LLM Top 10 and MITRE ATLAS, and
+> emits a structured threat profile — JSON for machines, Markdown
+> for humans.
+
+The thesis: every team adopting MCP right now is asking *"what
+does this server actually do?"* and there's no tooling for it. The
+agentic ecosystem grew faster than its security tooling. mcp-recon
+is the recon side of that gap. [capnagent](https://github.com/euanmcrosson-dotcom/capnagent)
+is the defensive side: take a recon report, derive a tight
+capability caveat, deny everything outside it.
+
+> **Status:** v0.1.2 shipped 2026-04-30. Public dataset of every
+> stdio TypeScript MCP server in Anthropic's `@modelcontextprotocol/*`
+> namespace audited. See [`docs/WRITEUP.md`](docs/WRITEUP.md) for the
+> headline findings (DoS surface on `everything`,
+> missing-bounds finding on `filesystem` example wrapper, full
+> server-maturity ranking).
+
+## Contents
+
+- [At a glance](#at-a-glance)
+- [What you get](#what-you-get)
+- [Command cheatsheet](#command-cheatsheet)
+- [Sample output](#sample-output)
+- [Recon → capnagent in one pipe](#recon--capnagent-in-one-pipe)
+- [Why this exists](#why-this-exists)
+- [Installation](#installation)
+- [How it compares](#how-it-compares)
+- [What this is NOT](#what-this-is-not)
+- [Tests](#tests)
+- [Companion project — capnagent](#companion-project--capnagent)
+- [License](#license)
+
+## At a glance
+
+| Coverage | Surface | Performance |
+|---|---|---|
+| **4 / 4** Anthropic reference servers scanned | **5** commands · **4** schema-tagged artefacts | scan budget=200 in <60s on 14-tool server |
+| **37 tools classified** across the public dataset | enumerate · fuzz · classify · report · scan | deterministic (seeded PRNG, default `0xC0FFEE`) |
+| **1374 fuzz calls** across the dataset (1 confirmed DoS finding) | rules-based, not LLM-mediated | <256MB memory on 100-tool server |
+
+Maps tools to **OWASP LLM01 / LLM06 / LLM08** and **MITRE ATLAS** categories. Every output ships with a copy-pasteable [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) caveat per tool. Reproducibility contract in
+[capnagent's `docs/EVALUATION.md`](https://github.com/euanmcrosson-dotcom/capnagent/blob/master/docs/EVALUATION.md).
+
+## What you get
+
+Run `mcp-recon scan` against any MCP server (stdio or HTTP) and get a
+folder of evidence: a tool inventory, a fuzz transcript, a
+classification, and a Markdown threat profile that a security reviewer
+or developer-on-call can actually read. The JSON files are the
+machine-parseable evidence the writeup links to. Run against any of
+the 4 servers in the public dataset and your output matches
+`examples/public-servers/server-<name>/` byte-for-byte.
+
+## Command cheatsheet
+
+```bash
+mcp-recon enumerate <server-spec>                                # → inventory.json
+mcp-recon fuzz      <server-spec> [--budget=N] [--seed=N]        # → fuzz.json
+mcp-recon classify  <inventory.json> [--fuzz=<fuzz.json>]        # → classification.json
+mcp-recon report    <inventory.json> <classification.json> [--fuzz=<fuzz.json>]  # → report.md
+mcp-recon scan      <server-spec> --out=<dir> [--budget=N] [--seed=N]            # → 4 artefacts
+```
+
+Server-spec forms: `stdio:<command> [args...]` (spawn process, talk
+over stdio) or `http://host:port` (HTTP transport).
+
+## Sample output
+
+```bash
+$ mcp-recon scan "stdio:npx -y @modelcontextprotocol/server-filesystem /tmp" \
+    --out=./reports/filesystem --budget=200
+
+mcp-recon: 14 tools, 4 confused-deputy candidates
+mcp-recon: fuzz — ok=4 protocol_error=719 runtime_error=0
+mcp-recon: wrote 4 artefacts to ./reports/filesystem/
+
+$ ls ./reports/filesystem/
+inventory.json   fuzz.json   classification.json   report.md
+```
+
+A snippet from the resulting `classification.json` — every tool gets
+a class, an authority level, a confused-deputy verdict, and a
+copy-pasteable capnagent caveat:
+
+```json
+{
+  "tool": "edit_file",
+  "data_class": "filesystem",
+  "authority_level": "write",
+  "confused_deputy_candidate": true,
+  "confidence": 0.91,
+  "rationale": "name match \"\\b(write[_-]?file|edit[_-]?file|create[_-]?directory|move[_-]?file)\\b\" → filesystem/write (0.70); description match → filesystem/read (0.50); schema: arg \"path\" is path-shaped → filesystem (0.40); user-controllable string arg + non-read authority → confused-deputy candidate",
+  "recommended_caveat": "tool == \"edit_file\" AND caller == \"<your-caller-id>\" AND arg.path starts_with \"<your-sandbox-prefix>/\" AND now <= @<your-cap-expiry>  // WRITE filesystem"
+}
+```
+
+The full headline findings — including the `everything` server's DoS
+surface and the `filesystem` wrapper's missing-bounds — are in
+[`docs/WRITEUP.md`](docs/WRITEUP.md).
+
+## Recon → capnagent in one pipe
+
+```
+   ┌──────────────┐    inventory.json     ┌──────────────┐
+   │              │    fuzz.json          │              │
+   │  MCP server  │ ──▶  classification ──▶│  capnagent   │ ──▶ deny anything
+   │              │      .json            │   issuer     │     outside scope
+   │              │      report.md        │              │
+   └──────────────┘                       └──────────────┘
+        ▲                                       │
+        │                                       ▼
+        └────────── scoped caller ◀──────  signed capability
+```
+
+mcp-recon documents the tool surface; capnagent enforces the bound.
+Each project stands alone. Together they're a single security
+posture for any MCP-shaped agent. Run mcp-recon first, paste the
+suggested caveats into your capnagent issuer, ship.
+
+### From recon to a capnagent issuer in one pipe
+
+`classification.json` ships a copy-pasteable caveat per tool, but
+manual paste is its own foot-gun. The `caveats` command produces a
+machine-readable issuance plan ready to feed straight into a capnagent
+issuer:
+
+```bash
+$ mcp-recon caveats ./reports/filesystem/classification.json \
+    --caller=agent:planner \
+    --sandbox-prefix=/var/agent-sandbox/tenant-42 \
+    --expiry=2026-12-31T23:59:59Z \
+    > ./reports/filesystem/caveats.json
+
+mcp-recon: 14 plans (14 ready, 0 flagged) — schema=mcp-recon/v0.1/caveats
+```
+
+The output document (schema `mcp-recon/v0.1/caveats`) is one entry per
+tool, with `caveats: string[]` already split into individual capnagent
+DSL predicates and operator bindings substituted. Plans get flagged
+with a structured reason set (`classification_unknown`, `low_confidence`,
+`cdc_without_arg_constraint`, `unsubstituted_placeholder`) so the
+review surface is machine-checkable.
+
+Run with no bindings to get a "review pass" — every plan is flagged,
+but you can see exactly which placeholders need binding before
+committing values. Per-tool overrides (`per_tool_overrides` in the
+library API) let you tighten confused-deputy candidates the
+classifier didn't constrain.
+
+## Why this exists
+
+**For the developer adopting MCP.** Before you wire a third-party
+MCP server into your agent, run mcp-recon against it. You get an
+honest threat profile in 30 seconds — what does this thing
+*actually* let an agent do, and what's the smallest cap that
+preserves utility?
+
+**For the security team auditing an agent stack.** mcp-recon turns
+"we depend on N MCP servers" into "here's the consolidated tool
+surface, here's what each one is classified as, here's where the
+confused-deputy candidates are." A printable artifact you can
+review.
+
+**For the AI-security researcher.** mcp-recon's reports are the
+input to round-N writeups in the
+[capnagent purple-team corpus](https://github.com/euanmcrosson-dotcom/capnagent/tree/master/docs/purple-team).
+Recon → capability gap → attack PoC → fix → CLOSED.
+
+## Installation
+
+```bash
+# From source (the recommended path today; npm package is post-v0.2)
+git clone https://github.com/euanmcrosson-dotcom/mcp-recon
+cd mcp-recon
+npm install
+npm run -w @mcp-recon/cli build
+
+# Run the CLI directly via tsx (no build step needed for development)
+npx tsx packages/mcp-recon-cli/src/bin/recon.ts scan \
+  "stdio:npx -y @modelcontextprotocol/server-filesystem $HOME/sandbox" \
+  --out=./reports/filesystem --budget=200
+```
+
+> **Windows / Git Bash users:** prefix path-shaped flags with `MSYS_NO_PATHCONV=1` to prevent leading-slash path mangling. Example: `MSYS_NO_PATHCONV=1 mcp-recon caveats classification.json --sandbox-prefix=/var/sandbox --expiry=2026-12-31T23:59:59Z`
+
+## Documentation
+
+- [`docs/SPEC.md`](docs/SPEC.md) — v0.1 surface, server-spec syntax, output schemas
+- [`docs/METHODOLOGY.md`](docs/METHODOLOGY.md) — classifier rules, fuzz axes, signals, falsifiability
+- [`docs/WRITEUP.md`](docs/WRITEUP.md) — public-dataset findings + headline observations
+- [`schemas/`](schemas/) — formal JSON Schema files for the four wire formats
+- [`findings/`](findings/) — corpus of documented findings (F001–F006)
+- [`SECURITY.md`](SECURITY.md) — vulnerability reporting policy
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to add classifier rules, fuzz axes, dataset entries
+
+## How it compares
+
+|   | mcp-recon | [NVIDIA garak](https://github.com/NVIDIA/garak) | Burp / ZAP | manual review |
+|---|---|---|---|---|
+| **Scope** | MCP server tool surfaces | model-behavior testing | HTTP fuzzing | everything |
+| **Output** | structured JSON + Markdown | reports | proxy logs | human prose |
+| **Determinism** | yes (seeded PRNG) | partial | no | no |
+| **LLM in the loop** | no (rules-based) | yes | no | yes |
+| **OWASP LLM / MITRE ATLAS mapping** | yes (per-tool) | partial | no | author-dependent |
+| **Companion enforcement** | [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) | none | none | none |
+
+mcp-recon is **not** a replacement for any of those — it's the
+piece nobody else is building: a deterministic, schema-aware
+characterization of an MCP server's tool surface, in a format
+that wires straight into a capability-bounded enforcement layer.
+
+## What this is NOT
+
+- **Not a replacement for capnagent.** mcp-recon documents what's
+  there; capnagent enforces what's allowed. You want both.
+- **Not a vulnerability scanner for the model itself.** Use
+  [NVIDIA garak](https://github.com/NVIDIA/garak) for that. We
+  test the *tool surface*, not model behavior.
+- **Not an exploitation framework.** We send adversarial schemas
+  to characterize handling, not actual exploits.
+- **Not a proxy / MITM tool.** Out of scope. See
+  [`docs/SPEC.md`](docs/SPEC.md) §"What v0.1 does NOT do."
+
+## Tests
+
+The workspace has **68 unit + property-based tests** passing today
+(`npm test`), covering schema parsing, the seeded PRNG, fuzz
+generators along all six adversarial axes, the classification
+rules, the Markdown report renderer, and end-to-end `scan` flow.
+Two additional integration test files (`enumerate.integration.test.ts`,
+`fuzz.integration.test.ts`) exercise live transport against a
+locally-spawned MCP server when the dev environment provides one.
+
+```bash
+npm test           # all packages, vitest
+npm run typecheck  # tsc --noEmit, strict mode
+npm run lint       # biome check
+```
+
+## Companion project — capnagent
+
+mcp-recon is the offensive complement to
+[capnagent](https://github.com/euanmcrosson-dotcom/capnagent),
+which provides capability-bounded authorization for AI agent tool
+calls. Together they implement the standard
+*recon-then-bound* security workflow:
+
+```
+[ mcp-recon ]  →  threat profile  →  [ capnagent ]
+   "what is        "what should           "deny anything
+    here?"          we allow?"             outside that"
+```
+
+Each project stands alone. Together they're a single security
+posture for any MCP-shaped agent.
+
+## License
+
+[Apache-2.0](LICENSE).

package/dist/bin/recon.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * `mcp-recon` CLI entry point.
+ *
+ * v0.1 surface (see docs/SPEC.md §"What v0.1 does"):
+ *
+ *   mcp-recon enumerate <server-spec>      [implemented in scaffold]
+ *   mcp-recon fuzz <server-spec>           [stub — v0.1 week 2]
+ *   mcp-recon classify <inventory.json>    [stub — v0.1 week 3]
+ *   mcp-recon report <i.json> <f.json> <c.json>  [stub — v0.1 week 3]
+ *   mcp-recon scan <server-spec>           [stub — v0.1 week 4]
+ *
+ * Output is JSON to stdout for machine-parseable commands; logs to
+ * stderr so a piped invocation (`mcp-recon enumerate ... | jq ...`)
+ * works without contamination.
+ */
+export {};
+//# sourceMappingURL=recon.d.ts.map

package/dist/bin/recon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recon.d.ts","sourceRoot":"","sources":["../../src/bin/recon.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG"}

package/dist/bin/recon.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+/**
+ * `mcp-recon` CLI entry point.
+ *
+ * v0.1 surface (see docs/SPEC.md §"What v0.1 does"):
+ *
+ *   mcp-recon enumerate <server-spec>      [implemented in scaffold]
+ *   mcp-recon fuzz <server-spec>           [stub — v0.1 week 2]
+ *   mcp-recon classify <inventory.json>    [stub — v0.1 week 3]
+ *   mcp-recon report <i.json> <f.json> <c.json>  [stub — v0.1 week 3]
+ *   mcp-recon scan <server-spec>           [stub — v0.1 week 4]
+ *
+ * Output is JSON to stdout for machine-parseable commands; logs to
+ * stderr so a piped invocation (`mcp-recon enumerate ... | jq ...`)
+ * works without contamination.
+ */
+import * as fs from "node:fs";
+import { CAVEATS_SCHEMA, CLASSIFICATION_SCHEMA, classify, closeClient, enumerate, fuzz, openClient, parseServerSpec, planCaveats, renderCaveatsMarkdown, renderMarkdown, scan, } from "../index.js";
+function usage() {
+    process.stderr.write([
+        "mcp-recon — reverse-engineer MCP server tool surfaces",
+        "",
+        "Usage:",
+        "  mcp-recon enumerate <server-spec>",
+        "  mcp-recon fuzz <server-spec> [--budget=N] [--seed=N]",
+        "  mcp-recon classify <inventory.json> [--fuzz=<fuzz.json>]",
+        "  mcp-recon report <inventory.json> <classification.json> [--fuzz=<fuzz.json>]",
+        "  mcp-recon caveats <classification.json> [--caller=ID] [--sandbox-prefix=PATH] [--expiry=ISO] [--markdown]",
+        "  mcp-recon scan <server-spec> --out=<dir> [--budget=N] [--seed=N]",
+        "                                [--caller=ID] [--sandbox-prefix=PATH] [--expiry=ISO]",
+        "",
+        "Server-spec forms:",
+        "  stdio:<command> [args...]    — spawn process, talk over stdio",
+        "  http://host:port             — HTTP transport (v0.1 week 2)",
+        "",
+        "Examples:",
+        "  mcp-recon enumerate stdio:npx -y @modelcontextprotocol/server-filesystem /tmp",
+        "  mcp-recon fuzz stdio:npx -y @modelcontextprotocol/server-filesystem /tmp --budget=20",
+        "  mcp-recon classify inv.json --fuzz=fz.json > class.json",
+        "  mcp-recon report inv.json class.json --fuzz=fz.json > report.md",
+        "  mcp-recon caveats class.json --caller=agent:planner --sandbox-prefix=/srv/sb --expiry=2026-12-31T23:59:59Z > caveats.json",
+        "  mcp-recon caveats class.json --caller=agent:planner --sandbox-prefix=/srv/sb --expiry=2026-12-31T23:59:59Z --markdown > caveats.md",
+        "",
+    ].join("\n"));
+    process.exit(2);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (!cmd || cmd === "--help" || cmd === "-h") {
+        usage();
+    }
+    switch (cmd) {
+        case "enumerate":
+            return await runEnumerate(argv.slice(1));
+        case "fuzz":
+            return await runFuzz(argv.slice(1));
+        case "classify":
+            return runClassify(argv.slice(1));
+        case "report":
+            return runReport(argv.slice(1));
+        case "caveats":
+            return runCaveats(argv.slice(1));
+        case "scan":
+            return await runScan(argv.slice(1));
+        default:
+            process.stderr.write(`mcp-recon: unknown command '${cmd}'.\n`);
+            usage();
+    }
+}
+async function runEnumerate(args) {
+    const spec = args[0];
+    if (!spec) {
+        process.stderr.write("mcp-recon enumerate: missing <server-spec>\n");
+        return 2;
+    }
+    const parsed = parseServerSpec(spec);
+    process.stderr.write(`mcp-recon: connecting to ${spec}...\n`);
+    const client = await openClient(parsed);
+    try {
+        const inventory = await enumerate(client);
+        process.stderr.write(`mcp-recon: enumerated ${inventory.tools.length} tools from ${inventory.server.name ?? "unknown server"}\n`);
+        process.stdout.write(`${JSON.stringify(inventory, null, 2)}\n`);
+        return 0;
+    }
+    finally {
+        await closeClient(client);
+    }
+}
+async function runFuzz(args) {
+    // Pull --budget=N and --seed=N flags out; the first positional is the spec.
+    let budget;
+    let seed;
+    let spec;
+    for (const arg of args) {
+        if (arg.startsWith("--budget=")) {
+            const n = Number.parseInt(arg.slice("--budget=".length), 10);
+            if (Number.isNaN(n) || n <= 0) {
+                process.stderr.write(`mcp-recon fuzz: invalid --budget value\n`);
+                return 2;
+            }
+            budget = n;
+        }
+        else if (arg.startsWith("--seed=")) {
+            const n = Number.parseInt(arg.slice("--seed=".length), 10);
+            if (Number.isNaN(n)) {
+                process.stderr.write(`mcp-recon fuzz: invalid --seed value\n`);
+                return 2;
+            }
+            seed = n;
+        }
+        else if (!spec) {
+            spec = arg;
+        }
+        else {
+            process.stderr.write(`mcp-recon fuzz: unexpected argument ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!spec) {
+        process.stderr.write("mcp-recon fuzz: missing <server-spec>\n");
+        return 2;
+    }
+    const parsed = parseServerSpec(spec);
+    process.stderr.write(`mcp-recon: connecting to ${spec}...\n`);
+    const client = await openClient(parsed);
+    try {
+        const inventory = await enumerate(client);
+        process.stderr.write(`mcp-recon: fuzzing ${inventory.tools.length} tools (budget=${budget ?? 200}, seed=${seed ?? "default"})...\n`);
+        const opts = {};
+        if (budget !== undefined)
+            opts.budget = budget;
+        if (seed !== undefined)
+            opts.seed = seed;
+        const results = await fuzz(client, inventory, opts);
+        const totalCalls = results.calls.length;
+        const totalOk = results.summary.reduce((acc, s) => acc + s.ok, 0);
+        const totalProto = results.summary.reduce((acc, s) => acc + s.protocol_error, 0);
+        const totalRuntime = results.summary.reduce((acc, s) => acc + s.runtime_error, 0);
+        process.stderr.write(`mcp-recon: ${totalCalls} calls — ok=${totalOk} protocol_error=${totalProto} runtime_error=${totalRuntime}\n`);
+        process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
+        return 0;
+    }
+    finally {
+        await closeClient(client);
+    }
+}
+function runClassify(args) {
+    let inventoryPath;
+    let fuzzPath;
+    for (const arg of args) {
+        if (arg.startsWith("--fuzz=")) {
+            fuzzPath = arg.slice("--fuzz=".length);
+        }
+        else if (!inventoryPath) {
+            inventoryPath = arg;
+        }
+        else {
+            process.stderr.write(`mcp-recon classify: unexpected argument ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!inventoryPath) {
+        process.stderr.write("mcp-recon classify: missing <inventory.json>\n");
+        return 2;
+    }
+    const inventory = readJson(inventoryPath);
+    const fuzzData = fuzzPath ? readJson(fuzzPath) : undefined;
+    const result = classify(inventory, fuzzData);
+    process.stderr.write(`mcp-recon: classified ${result.classifications.length} tools (fuzz_informed=${result.fuzz_informed})\n`);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+}
+function runReport(args) {
+    let inventoryPath;
+    let classificationPath;
+    let fuzzPath;
+    for (const arg of args) {
+        if (arg.startsWith("--fuzz=")) {
+            fuzzPath = arg.slice("--fuzz=".length);
+        }
+        else if (!inventoryPath) {
+            inventoryPath = arg;
+        }
+        else if (!classificationPath) {
+            classificationPath = arg;
+        }
+        else {
+            process.stderr.write(`mcp-recon report: unexpected argument ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!inventoryPath || !classificationPath) {
+        process.stderr.write("mcp-recon report: missing arguments — needs <inventory.json> <classification.json>\n");
+        return 2;
+    }
+    const inventory = readJson(inventoryPath);
+    const classification = readJson(classificationPath);
+    if (classification.schema !== CLASSIFICATION_SCHEMA) {
+        process.stderr.write(`mcp-recon report: classification.json schema is "${classification.schema}", expected "${CLASSIFICATION_SCHEMA}"\n`);
+        return 64;
+    }
+    const fuzzData = fuzzPath ? readJson(fuzzPath) : undefined;
+    const md = renderMarkdown(fuzzData ? { inventory, classification, fuzz: fuzzData } : { inventory, classification });
+    process.stdout.write(md);
+    if (!md.endsWith("\n"))
+        process.stdout.write("\n");
+    return 0;
+}
+function readJson(filePath) {
+    const text = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(text);
+}
+function runCaveats(args) {
+    let classificationPath;
+    let markdown = false;
+    const bindings = {};
+    for (const arg of args) {
+        if (arg === "--markdown") {
+            markdown = true;
+        }
+        else if (arg.startsWith("--caller=")) {
+            bindings.caller = arg.slice("--caller=".length);
+        }
+        else if (arg.startsWith("--sandbox-prefix=")) {
+            bindings.sandbox_prefix = arg.slice("--sandbox-prefix=".length);
+        }
+        else if (arg.startsWith("--expiry=")) {
+            const expiry = arg.slice("--expiry=".length);
+            // Light validation: must parse as a date.
+            const parsed = new Date(expiry);
+            if (Number.isNaN(parsed.getTime())) {
+                process.stderr.write(`mcp-recon caveats: invalid --expiry value (must be ISO-8601)\n`);
+                return 2;
+            }
+            // Normalize to canonical ISO so downstream consumers see one shape.
+            bindings.expiry = parsed.toISOString();
+        }
+        else if (!classificationPath) {
+            classificationPath = arg;
+        }
+        else {
+            process.stderr.write(`mcp-recon caveats: unexpected argument ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!classificationPath) {
+        process.stderr.write("mcp-recon caveats: missing <classification.json>\n");
+        return 2;
+    }
+    const classification = readJson(classificationPath);
+    if (classification.schema !== CLASSIFICATION_SCHEMA) {
+        process.stderr.write(`mcp-recon caveats: classification.json schema is "${classification.schema}", expected "${CLASSIFICATION_SCHEMA}"\n`);
+        return 64;
+    }
+    const result = planCaveats(classification, bindings);
+    process.stderr.write(`mcp-recon: ${result.summary.total} plans (${result.summary.ready} ready, ${result.summary.flagged} flagged) — schema=${CAVEATS_SCHEMA}\n`);
+    if (markdown) {
+        const md = renderCaveatsMarkdown(result);
+        process.stdout.write(md);
+        if (!md.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    return 0;
+}
+async function runScan(args) {
+    let spec;
+    let outDir;
+    let budget;
+    let seed;
+    const bindings = {};
+    for (const arg of args) {
+        if (arg.startsWith("--out=")) {
+            outDir = arg.slice("--out=".length);
+        }
+        else if (arg.startsWith("--budget=")) {
+            const n = Number.parseInt(arg.slice("--budget=".length), 10);
+            if (Number.isNaN(n) || n <= 0) {
+                process.stderr.write("mcp-recon scan: invalid --budget value\n");
+                return 2;
+            }
+            budget = n;
+        }
+        else if (arg.startsWith("--seed=")) {
+            const n = Number.parseInt(arg.slice("--seed=".length), 10);
+            if (Number.isNaN(n)) {
+                process.stderr.write("mcp-recon scan: invalid --seed value\n");
+                return 2;
+            }
+            seed = n;
+        }
+        else if (arg.startsWith("--caller=")) {
+            bindings.caller = arg.slice("--caller=".length);
+        }
+        else if (arg.startsWith("--sandbox-prefix=")) {
+            bindings.sandbox_prefix = arg.slice("--sandbox-prefix=".length);
+        }
+        else if (arg.startsWith("--expiry=")) {
+            const expiry = arg.slice("--expiry=".length);
+            const parsed = new Date(expiry);
+            if (Number.isNaN(parsed.getTime())) {
+                process.stderr.write("mcp-recon scan: invalid --expiry value (must be ISO-8601)\n");
+                return 2;
+            }
+            bindings.expiry = parsed.toISOString();
+        }
+        else if (!spec) {
+            spec = arg;
+        }
+        else {
+            process.stderr.write(`mcp-recon scan: unexpected argument ${arg}\n`);
+            return 2;
+        }
+    }
+    if (!spec) {
+        process.stderr.write("mcp-recon scan: missing <server-spec>\n");
+        return 2;
+    }
+    if (!outDir) {
+        process.stderr.write("mcp-recon scan: --out=<dir> is required\n");
+        return 2;
+    }
+    const hasBindings = bindings.caller !== undefined ||
+        bindings.sandbox_prefix !== undefined ||
+        bindings.expiry !== undefined;
+    const parsed = parseServerSpec(spec);
+    process.stderr.write(`mcp-recon: connecting to ${spec}...\n`);
+    const client = await openClient(parsed);
+    try {
+        const opts = {
+            outDir,
+            ...(budget !== undefined ? { budget } : {}),
+            ...(seed !== undefined ? { seed } : {}),
+            ...(hasBindings ? { bindings } : {}),
+        };
+        process.stderr.write(`mcp-recon: running enumerate → fuzz → classify → report...\n`);
+        const result = await scan(client, opts);
+        const totalOk = result.fuzz.summary.reduce((acc, s) => acc + s.ok, 0);
+        const totalProto = result.fuzz.summary.reduce((acc, s) => acc + s.protocol_error, 0);
+        const totalRuntime = result.fuzz.summary.reduce((acc, s) => acc + s.runtime_error, 0);
+        const cdpCount = result.classification.classifications.filter((c) => c.confused_deputy_candidate).length;
+        process.stderr.write(`mcp-recon: ${result.inventory.tools.length} tools, ${cdpCount} confused-deputy candidates\n`);
+        process.stderr.write(`mcp-recon: fuzz — ok=${totalOk} protocol_error=${totalProto} runtime_error=${totalRuntime}\n`);
+        const artefactCount = result.caveats !== undefined ? 5 : 4;
+        process.stderr.write(`mcp-recon: wrote ${artefactCount} artefacts to ${outDir}/\n`);
+        return 0;
+    }
+    finally {
+        await closeClient(client);
+    }
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    process.stderr.write(`mcp-recon: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=recon.js.map