mcp-recon 0.2.2

package/dist/fuzz/schema.js

@@ -0,0 +1,84 @@
+/**
+ * JSON Schema walker — extracts what the fuzzer needs to know about a
+ * tool's argument shape.
+ *
+ * v0.1 supports JSON Schema Draft 7 (the dialect the official MCP
+ * filesystem server uses). We don't validate the schema — we extract
+ * structural facts: which keys exist, what types they declare, which
+ * are required, which look like paths or URLs.
+ *
+ * Heuristic shape-detection: arg names containing `path` are flagged
+ * path-shaped; arg names containing `url`, `origin`, `endpoint` are
+ * URL-shaped. The classifier (week 3) will refine these heuristics.
+ */
+/** Default seed for the deterministic fuzz PRNG (matches docs/SPEC.md). */
+export const DEFAULT_FUZZ_SEED = 0xc0_ffee;
+/** Default per-tool fuzz budget (matches docs/SPEC.md). */
+export const DEFAULT_FUZZ_BUDGET = 200;
+/** Walk one tool's `inputSchema`. Returns structural facts. */
+export function extractToolFacts(name, inputSchema) {
+    if (inputSchema === null || typeof inputSchema !== "object") {
+        return { name, args: [], isArgless: true };
+    }
+    const schema = inputSchema;
+    const properties = (schema["properties"] ?? {});
+    const requiredList = Array.isArray(schema["required"]) ? schema["required"] : [];
+    const requiredSet = new Set(requiredList);
+    const args = [];
+    for (const [argName, argSchema] of Object.entries(properties)) {
+        if (argSchema === null || typeof argSchema !== "object")
+            continue;
+        const a = argSchema;
+        const declaredType = pickType(a["type"]);
+        const enumRaw = a["enum"];
+        const enumValues = Array.isArray(enumRaw) ? enumRaw : undefined;
+        args.push({
+            path: [argName],
+            declaredType,
+            required: requiredSet.has(argName),
+            isPathShaped: looksPathy(argName),
+            isUrlShaped: looksUrly(argName),
+            isCommandShaped: looksCommandy(argName),
+            ...(enumValues ? { enumValues } : {}),
+        });
+    }
+    return { name, args, isArgless: args.length === 0 };
+}
+function pickType(declared) {
+    if (typeof declared === "string") {
+        if (declared === "string" ||
+            declared === "number" ||
+            declared === "integer" ||
+            declared === "boolean" ||
+            declared === "array" ||
+            declared === "object" ||
+            declared === "null") {
+            return declared;
+        }
+    }
+    if (Array.isArray(declared) && declared.length > 0) {
+        // Multi-type arg (`type: ["string", "null"]`) — pick the first non-null.
+        const first = declared.find((t) => t !== "null") ?? declared[0];
+        if (typeof first === "string")
+            return pickType(first);
+    }
+    return "unknown";
+}
+function looksPathy(argName) {
+    // Suppress when the arg name carries a non-path semantic that the
+    // path-name list (`source`, `target`, `destination`, ...) would otherwise
+    // false-positive on. Canonical case: `source_timezone` / `target_timezone`
+    // on `mcp-server-time` (F006). Add additional stop words here as new
+    // false-positive shapes surface.
+    if (/(^|_)(timezone|tz|zone|region|locale|currency|country|language)($|_|s$)/i.test(argName)) {
+        return false;
+    }
+    return /(^|_)(path|file|dir|directory|src|source|destination|dest|target)($|_|s$)/i.test(argName);
+}
+function looksUrly(argName) {
+    return /(^|_)(url|uri|origin|endpoint|host|hostname)($|_|s$)/i.test(argName);
+}
+function looksCommandy(argName) {
+    return /(^|_)(cmd|command|argv|exec|args)($|_|s$)/i.test(argName);
+}
+//# sourceMappingURL=schema.js.map

package/dist/fuzz/schema.js.map

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

package/dist/fuzz/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Wire-format types for the v0.1 fuzz document. Mirrors the Rust core's
+ * `mcp_recon_core::fuzzer` types so the two stay in lock-step.
+ *
+ * Schema tag: `mcp-recon/v0.1/fuzz`. Downstream consumers (classifier,
+ * reporter, capnagent's caveat-suggestion bridge) parse based on this
+ * string.
+ */
+/** Schema-version tag for fuzz documents. */
+export declare const FUZZ_SCHEMA: "mcp-recon/v0.1/fuzz";
+/** Six categorical axes (per docs/SPEC.md §"Fuzzing strategy"). */
+export type FuzzAxis = "boundary_values" | "type_confusion" | "encoding_tricks" | "path_traversal" | "url_hostility" | "schema_violation";
+/** What the underlying tool / transport did with the fuzz input. */
+export type FuzzOutcome = {
+    kind: "ok";
+    snippet: string;
+} | {
+    kind: "protocol_error";
+    message: string;
+} | {
+    kind: "runtime_error";
+    message: string;
+};
+/** One recorded fuzz interaction. */
+export interface FuzzCall {
+    tool: string;
+    axis: FuzzAxis;
+    rationale: string;
+    arguments: Record<string, unknown>;
+    outcome: FuzzOutcome;
+}
+/** Per-tool count summary. */
+export interface FuzzToolSummary {
+    tool: string;
+    total: number;
+    ok: number;
+    protocol_error: number;
+    runtime_error: number;
+}
+/** Top-level fuzz document. */
+export interface FuzzResults {
+    schema: typeof FUZZ_SCHEMA;
+    scanned_at: string;
+    server: {
+        name?: string;
+        version?: string;
+    };
+    seed: number;
+    budget: number;
+    summary: FuzzToolSummary[];
+    calls: FuzzCall[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/fuzz/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/fuzz/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6CAA6C;AAC7C,eAAO,MAAM,WAAW,EAAG,qBAA8B,CAAC;AAE1D,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,CAAC;AAEvB,oEAAoE;AACpE,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,WAAW,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB"}

package/dist/fuzz/types.js

@@ -0,0 +1,11 @@
+/**
+ * Wire-format types for the v0.1 fuzz document. Mirrors the Rust core's
+ * `mcp_recon_core::fuzzer` types so the two stay in lock-step.
+ *
+ * Schema tag: `mcp-recon/v0.1/fuzz`. Downstream consumers (classifier,
+ * reporter, capnagent's caveat-suggestion bridge) parse based on this
+ * string.
+ */
+/** Schema-version tag for fuzz documents. */
+export const FUZZ_SCHEMA = "mcp-recon/v0.1/fuzz";
+//# sourceMappingURL=types.js.map

package/dist/fuzz/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/fuzz/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,WAAW,GAAG,qBAA8B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@mcp-recon/cli` — public library surface.
+ *
+ * The CLI binary in `bin/recon.ts` is the daily-driver. This module
+ * re-exports the same primitives so other tools can compose them
+ * without spawning the CLI as a subprocess.
+ *
+ * v0.1 surface (per docs/SPEC.md):
+ *
+ *   - parseServerSpec(spec)           — string → ServerSpec
+ *   - openClient(spec)                — ServerSpec → connected SDK Client
+ *   - enumerate(client)               → ToolInventory (one tool inventory document)
+ *   - fuzz(client, inventory)         → FuzzResults (one fuzz document)
+ *
+ * v0.1 weeks 3+ will add `classify`, `report`, `scan` exports here.
+ */
+export { type ServerSpec, parseServerSpec, openClient, closeClient, } from "./transport.js";
+export { type ToolInventory, type EnumeratedTool, type EnumerateOptions, enumerate, INVENTORY_SCHEMA, DEFAULT_ENUMERATE_TIMEOUT_MS, DEFAULT_MAX_DESCRIPTION_CHARS, TRUNCATION_MARKER, } from "./enumerate.js";
+export { type FuzzAxis, type FuzzCall, type FuzzOutcome, type FuzzResults, type FuzzToolSummary, type FuzzOptions, fuzz, FUZZ_SCHEMA, } from "./fuzz/index.js";
+export { type AuthorityLevel, type Classification, type ClassificationResults, type DataClass, classify, noisyOr, synthesizeCaveat, CLASSIFICATION_SCHEMA, } from "./classify/index.js";
+export { type RenderInput, renderMarkdown, } from "./report/index.js";
+export { type CaveatBindings, type CaveatPlan, type CaveatsResults, type FlagReason, planCaveats, CAVEATS_SCHEMA, } from "./caveats/index.js";
+export { renderCaveatsMarkdown } from "./caveats/render.js";
+export { type ScanResult, type ScanOptions, scan, } from "./scan/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,eAAe,EACf,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,SAAS,EACT,gBAAgB,EAChB,4BAA4B,EAC5B,6BAA6B,EAC7B,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,IAAI,EACJ,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,KAAK,WAAW,EAChB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EACL,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,IAAI,GACL,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@mcp-recon/cli` — public library surface.
+ *
+ * The CLI binary in `bin/recon.ts` is the daily-driver. This module
+ * re-exports the same primitives so other tools can compose them
+ * without spawning the CLI as a subprocess.
+ *
+ * v0.1 surface (per docs/SPEC.md):
+ *
+ *   - parseServerSpec(spec)           — string → ServerSpec
+ *   - openClient(spec)                — ServerSpec → connected SDK Client
+ *   - enumerate(client)               → ToolInventory (one tool inventory document)
+ *   - fuzz(client, inventory)         → FuzzResults (one fuzz document)
+ *
+ * v0.1 weeks 3+ will add `classify`, `report`, `scan` exports here.
+ */
+export { parseServerSpec, openClient, closeClient, } from "./transport.js";
+export { enumerate, INVENTORY_SCHEMA, DEFAULT_ENUMERATE_TIMEOUT_MS, DEFAULT_MAX_DESCRIPTION_CHARS, TRUNCATION_MARKER, } from "./enumerate.js";
+export { fuzz, FUZZ_SCHEMA, } from "./fuzz/index.js";
+export { classify, noisyOr, synthesizeCaveat, CLASSIFICATION_SCHEMA, } from "./classify/index.js";
+export { renderMarkdown, } from "./report/index.js";
+export { planCaveats, CAVEATS_SCHEMA, } from "./caveats/index.js";
+export { renderCaveatsMarkdown } from "./caveats/render.js";
+export { scan, } from "./scan/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,eAAe,EACf,UAAU,EACV,WAAW,GACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAIL,SAAS,EACT,gBAAgB,EAChB,4BAA4B,EAC5B,6BAA6B,EAC7B,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAOL,IAAI,EACJ,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAKL,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAEL,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAKL,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAGL,IAAI,GACL,MAAM,iBAAiB,CAAC"}

package/dist/report/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Markdown reporter — render an inventory + classification (+ optional
+ * fuzz) into a single Markdown threat profile a security reviewer
+ * actually reads.
+ *
+ * The output structure:
+ *
+ *   1. Heading + generated-at + server identity
+ *   2. Summary stats (counts, distributions, headline finding)
+ *   3. Per-tool sections, ordered by authority (privileged →
+ *      destructive → write → read), with the recommended caveat in
+ *      a copy-pasteable code block
+ *   4. Footer linking back to capnagent / mcp-recon docs
+ */
+import type { ToolInventory } from "../enumerate.js";
+import type { FuzzResults } from "../fuzz/types.js";
+import type { ClassificationResults } from "../classify/types.js";
+export interface RenderInput {
+    inventory: ToolInventory;
+    classification: ClassificationResults;
+    fuzz?: FuzzResults;
+}
+/** Render a Markdown threat profile. Pure function — no I/O. */
+export declare function renderMarkdown(input: RenderInput): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/report/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAGV,qBAAqB,EAEtB,MAAM,sBAAsB,CAAC;AAS9B,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,aAAa,CAAC;IACzB,cAAc,EAAE,qBAAqB,CAAC;IACtC,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA6EzD"}

package/dist/report/index.js

@@ -0,0 +1,133 @@
+/**
+ * Markdown reporter — render an inventory + classification (+ optional
+ * fuzz) into a single Markdown threat profile a security reviewer
+ * actually reads.
+ *
+ * The output structure:
+ *
+ *   1. Heading + generated-at + server identity
+ *   2. Summary stats (counts, distributions, headline finding)
+ *   3. Per-tool sections, ordered by authority (privileged →
+ *      destructive → write → read), with the recommended caveat in
+ *      a copy-pasteable code block
+ *   4. Footer linking back to capnagent / mcp-recon docs
+ */
+const AUTHORITY_ORDER = {
+    privileged: 0,
+    destructive: 1,
+    write: 2,
+    read: 3,
+};
+/** Render a Markdown threat profile. Pure function — no I/O. */
+export function renderMarkdown(input) {
+    const { inventory, classification, fuzz } = input;
+    const out = [];
+    const serverLabel = `${inventory.server.name ?? "(unnamed server)"} v${inventory.server.version ?? "?"}`;
+    out.push(`# Threat profile: ${serverLabel}`);
+    out.push("");
+    out.push(`> Generated by [mcp-recon](https://github.com/euanmcrosson-dotcom/mcp-recon) at ${classification.scanned_at}.`);
+    out.push("> Companion to [capnagent](https://github.com/euanmcrosson-dotcom/capnagent) — every recommended caveat below is a copy-pasteable capnagent predicate.");
+    out.push("");
+    // ─── Summary ─────────────────────────────────────────────────
+    out.push("## Summary");
+    out.push("");
+    const byClass = countBy(classification.classifications, (c) => c.data_class);
+    const byAuthority = countBy(classification.classifications, (c) => c.authority_level);
+    const cdpCount = classification.classifications.filter((c) => c.confused_deputy_candidate).length;
+    const total = classification.classifications.length;
+    out.push(`- **Tools:** ${total}`);
+    out.push(`- **Data-class distribution:** ${formatDistribution(byClass)}`);
+    out.push(`- **Authority-level distribution:** ${formatDistribution(byAuthority)}`);
+    out.push(`- **Confused-deputy candidates:** ${cdpCount} / ${total}${cdpCount === 0 ? " ✅" : ""}`);
+    if (fuzz) {
+        const fOk = fuzz.summary.reduce((acc, s) => acc + s.ok, 0);
+        const fProto = fuzz.summary.reduce((acc, s) => acc + s.protocol_error, 0);
+        const fRuntime = fuzz.summary.reduce((acc, s) => acc + s.runtime_error, 0);
+        const fTotal = fOk + fProto + fRuntime;
+        out.push(`- **Fuzz:** ${fTotal} calls — ok=${fOk}, protocol_error=${fProto}, runtime_error=${fRuntime}${fRuntime > 0 ? "  ⚠️ at least one input escaped protocol-error handling" : ""}`);
+    }
+    out.push("");
+    // ─── Per-tool sections ───────────────────────────────────────
+    out.push("## Tools");
+    out.push("");
+    const fuzzByTool = new Map();
+    if (fuzz) {
+        for (const s of fuzz.summary) {
+            fuzzByTool.set(s.tool, toolFuzzSummary(s));
+        }
+    }
+    // Sort by authority (privileged first), then by data-class, then by name.
+    const sortedClassifications = [...classification.classifications].sort((a, b) => {
+        const ord = AUTHORITY_ORDER[a.authority_level] - AUTHORITY_ORDER[b.authority_level];
+        if (ord !== 0)
+            return ord;
+        if (a.data_class !== b.data_class)
+            return a.data_class.localeCompare(b.data_class);
+        return a.tool.localeCompare(b.tool);
+    });
+    for (const c of sortedClassifications) {
+        const tool = inventory.tools.find((t) => t.name === c.tool);
+        out.push(...renderTool(c, tool?.description ?? "", fuzzByTool.get(c.tool)));
+        out.push("");
+    }
+    // ─── Footer ──────────────────────────────────────────────────
+    out.push("---");
+    out.push("");
+    out.push("## How to read this report");
+    out.push("");
+    out.push("Every classification has a `confidence` score (noisy-OR over fired rules — see [docs/METHODOLOGY.md](https://github.com/euanmcrosson-dotcom/mcp-recon/blob/master/docs/METHODOLOGY.md)) and a free-form `rationale` listing every rule that fired. If you disagree with a classification:");
+    out.push("");
+    out.push("1. Read the `rationale` — which rules fired, and which you'd reweight.");
+    out.push("2. Edit `crates/mcp-recon-core/src/rules/v0_1.rs` (rule weights) or `packages/mcp-recon-cli/src/classify/rules.ts` (TS mirror) and re-run.");
+    out.push("3. Open an issue with your reasoning so future runs benefit.");
+    out.push("");
+    out.push("**Recommended caveats are starting points, not finish lines.** Tighten the placeholders to match your deployment, and consider attaching additional caveats (caller binding, time-of-day windows, rate limits enforced upstream).");
+    out.push("");
+    return out.join("\n");
+}
+function renderTool(c, description, fuzzStats) {
+    const out = [];
+    const cdp = c.confused_deputy_candidate ? " ⚠️ confused-deputy candidate" : "";
+    out.push(`### ${c.tool}`);
+    out.push("");
+    out.push(`**Class:** \`${c.data_class}\` · **Authority:** \`${c.authority_level}\`${cdp} · **Confidence:** ${(c.confidence * 100).toFixed(1)}%`);
+    if (description) {
+        const trimmed = description.length > 320 ? `${description.slice(0, 320)}…` : description;
+        out.push("");
+        out.push(`**Description:** ${trimmed.replace(/\s+/g, " ")}`);
+    }
+    out.push("");
+    out.push(`**Rationale:** ${c.rationale}`);
+    if (fuzzStats) {
+        out.push("");
+        out.push(`**Fuzz:** ${fuzzStats.total} calls — ok=${fuzzStats.ok}, protocol_error=${fuzzStats.protocol_error}, runtime_error=${fuzzStats.runtime_error}${fuzzStats.runtime_error > 0 ? "  ⚠️" : ""}`);
+    }
+    out.push("");
+    out.push(`**Recommended capnagent caveat:**`);
+    out.push("");
+    out.push("```");
+    out.push(c.recommended_caveat);
+    out.push("```");
+    return out;
+}
+function countBy(items, key) {
+    const out = {};
+    for (const item of items) {
+        const k = key(item);
+        out[k] = (out[k] ?? 0) + 1;
+    }
+    return out;
+}
+function formatDistribution(d) {
+    const entries = Object.entries(d).sort((a, b) => b[1] - a[1]);
+    return entries.map(([k, v]) => `${k} (${v})`).join(", ") || "(none)";
+}
+function toolFuzzSummary(s) {
+    return {
+        total: s.total,
+        ok: s.ok,
+        protocol_error: s.protocol_error,
+        runtime_error: s.runtime_error,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/report/index.js.map

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

package/dist/scan/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `scan` — one-shot orchestrator: enumerate → fuzz → classify → report.
+ *
+ * The daily-driver command. Composes the four primitives defined in
+ * `enumerate.ts`, `fuzz/index.ts`, `classify/index.ts`, `report/index.ts`
+ * and writes all four artefacts to a single output directory.
+ *
+ * When operator bindings are supplied (caller / sandbox-prefix / expiry /
+ * per-tool overrides), `scan` also emits a 5th artefact, `caveats.json`,
+ * by running the classification through the caveats planner. This closes
+ * the bridge to capnagent in a single command. Without bindings, `scan`
+ * keeps its original 4-artefact behaviour intact.
+ *
+ * Returns the bag of intermediate values so a caller (CLI or library)
+ * can post-process beyond the on-disk artefacts.
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { CaveatBindings, CaveatsResults } from "../caveats/types.js";
+import type { ClassificationResults } from "../classify/types.js";
+import type { ToolInventory } from "../enumerate.js";
+import { type FuzzOptions } from "../fuzz/index.js";
+import type { FuzzResults } from "../fuzz/types.js";
+export interface ScanResult {
+    inventory: ToolInventory;
+    fuzz: FuzzResults;
+    classification: ClassificationResults;
+    reportMarkdown: string;
+    /** Present when bindings triggered caveats emission. */
+    caveats?: CaveatsResults;
+}
+export interface ScanOptions extends FuzzOptions {
+    /** If set, write the artefacts to this directory. */
+    outDir?: string;
+    /**
+     * If set AND has at least one of caller / sandbox_prefix / expiry /
+     * per_tool_overrides populated, scan additionally produces a caveats
+     * document (and writes `caveats.json` when `outDir` is set). Empty
+     * objects, or objects with only undefined values, do not trigger
+     * caveats emission.
+     */
+    bindings?: CaveatBindings;
+}
+/**
+ * Run the full pipeline. Caller owns the client (open + close).
+ *
+ * Side effects (only when `outDir` is provided):
+ *   - mkdir -p outDir
+ *   - write inventory.json / fuzz.json / classification.json / report.md
+ *   - write caveats.json IFF bindings provided with at least one field set
+ */
+export declare function scan(client: Client, options?: ScanOptions): Promise<ScanResult>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scan/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGxE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,cAAc,EAAE,qBAAqB,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAmBD;;;;;;;GAOG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAmCzF"}

package/dist/scan/index.js

@@ -0,0 +1,81 @@
+/**
+ * `scan` — one-shot orchestrator: enumerate → fuzz → classify → report.
+ *
+ * The daily-driver command. Composes the four primitives defined in
+ * `enumerate.ts`, `fuzz/index.ts`, `classify/index.ts`, `report/index.ts`
+ * and writes all four artefacts to a single output directory.
+ *
+ * When operator bindings are supplied (caller / sandbox-prefix / expiry /
+ * per-tool overrides), `scan` also emits a 5th artefact, `caveats.json`,
+ * by running the classification through the caveats planner. This closes
+ * the bridge to capnagent in a single command. Without bindings, `scan`
+ * keeps its original 4-artefact behaviour intact.
+ *
+ * Returns the bag of intermediate values so a caller (CLI or library)
+ * can post-process beyond the on-disk artefacts.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { planCaveats } from "../caveats/index.js";
+import { classify } from "../classify/index.js";
+import { enumerate } from "../enumerate.js";
+import { fuzz } from "../fuzz/index.js";
+import { renderMarkdown } from "../report/index.js";
+/**
+ * Returns true if the bindings object has at least one populated field
+ * relevant to caveats emission. We treat empty strings as "set" so the
+ * operator's intent is honoured (the bridge handles substitution
+ * downstream and will flag empty values via `unsubstituted_placeholder`
+ * if appropriate).
+ */
+function hasAnyBinding(bindings) {
+    if (bindings.caller !== undefined)
+        return true;
+    if (bindings.sandbox_prefix !== undefined)
+        return true;
+    if (bindings.expiry !== undefined)
+        return true;
+    if (bindings.per_tool_overrides !== undefined) {
+        if (Object.keys(bindings.per_tool_overrides).length > 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Run the full pipeline. Caller owns the client (open + close).
+ *
+ * Side effects (only when `outDir` is provided):
+ *   - mkdir -p outDir
+ *   - write inventory.json / fuzz.json / classification.json / report.md
+ *   - write caveats.json IFF bindings provided with at least one field set
+ */
+export async function scan(client, options = {}) {
+    const { outDir, bindings, ...fuzzOptions } = options;
+    const inventory = await enumerate(client);
+    const fuzzResults = await fuzz(client, inventory, fuzzOptions);
+    const classification = classify(inventory, fuzzResults);
+    const reportMarkdown = renderMarkdown({
+        inventory,
+        classification,
+        fuzz: fuzzResults,
+    });
+    const caveats = bindings !== undefined && hasAnyBinding(bindings)
+        ? planCaveats(classification, bindings)
+        : undefined;
+    if (outDir !== undefined) {
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, "inventory.json"), `${JSON.stringify(inventory, null, 2)}\n`);
+        fs.writeFileSync(path.join(outDir, "fuzz.json"), `${JSON.stringify(fuzzResults, null, 2)}\n`);
+        fs.writeFileSync(path.join(outDir, "classification.json"), `${JSON.stringify(classification, null, 2)}\n`);
+        const md = reportMarkdown.endsWith("\n") ? reportMarkdown : `${reportMarkdown}\n`;
+        fs.writeFileSync(path.join(outDir, "report.md"), md);
+        if (caveats !== undefined) {
+            fs.writeFileSync(path.join(outDir, "caveats.json"), `${JSON.stringify(caveats, null, 2)}\n`);
+        }
+    }
+    const result = { inventory, fuzz: fuzzResults, classification, reportMarkdown };
+    if (caveats !== undefined)
+        result.caveats = caveats;
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/scan/index.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Server-spec parsing + transport construction.
+ *
+ * Per docs/SPEC.md, v0.1 supports three forms:
+ *
+ *   stdio:<command> [args...]      — spawn process; stdio transport
+ *   stdio:./path/to/binary --arg   — relative path also accepted
+ *   http://localhost:3000          — HTTP transport
+ *
+ * The HTTP transport stub is here for v0.1; the implementation
+ * lands in week 2 once we have a real HTTP-transport MCP server to
+ * test against. For week 1 the focus is stdio + the official
+ * @modelcontextprotocol/server-filesystem.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+/** A parsed server-spec — the union of supported transport variants. */
+export type ServerSpec = {
+    kind: "stdio";
+    command: string;
+    args: string[];
+} | {
+    kind: "http";
+    url: string;
+};
+/**
+ * Parse a server-spec string into structured form.
+ *
+ * Throws if the spec doesn't match a supported shape — we fail loud
+ * here rather than silently degrading to a default, because a
+ * mistyped spec produces a confusing connect-failure later.
+ */
+export declare function parseServerSpec(spec: string): ServerSpec;
+/**
+ * Open a connected MCP `Client` for the given spec.
+ *
+ * Caller owns shutdown — pass the result to `closeClient` when
+ * finished. We do not auto-close on process exit because some
+ * commands (`scan`) hold the client across multiple steps.
+ */
+export declare function openClient(spec: ServerSpec): Promise<Client>;
+/** Close a client opened by `openClient`. Safe to call multiple times. */
+export declare function closeClient(client: Client): Promise<void>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAwBxD;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBlE;AAED,0EAA0E;AAC1E,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D"}