avorelo 0.1.0

package/scripts/lib/mcp-least-privilege-policy.js

@@ -0,0 +1,303 @@
+"use strict";
+
+// ── MCP Least-Privilege Policy ────────────────────────────────────────────────
+//
+// Contract: avorelo.mcpLeastPrivilegePolicy.v1
+//
+// Builds least-privilege policy from risk report.
+// Preview only — does NOT modify any MCP config.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { REASON_CODES } = require("./mcp-tool-risk");
+
+const CONTRACT = "avorelo.mcpLeastPrivilegePolicy.v1";
+const SCHEMA_VERSION = 1;
+
+const POLICY_DIR_REL = ".claude/cco/orchestration/mcp-tool-governance";
+const POLICY_REL = `${POLICY_DIR_REL}/latest-policy.json`;
+const PREVIEW_REL = `${POLICY_DIR_REL}/latest-policy-preview.json`;
+
+// ── Policy decisions ──────────────────────────────────────────────────────────
+
+const DECISIONS = Object.freeze({
+  ALLOW: "allow",
+  WARN: "warn",
+  APPROVAL_REQUIRED: "approval_required",
+  BLOCK: "block",
+  NOT_ENOUGH_INFORMATION: "not_enough_information",
+});
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeWriteJson(filePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  } catch {
+    // non-fatal
+  }
+}
+
+// ── Policy decision logic ─────────────────────────────────────────────────────
+
+function decideMcpToolPolicy(toolRisk, context, options = {}) {
+  if (!toolRisk) {
+    return {
+      decision: DECISIONS.NOT_ENOUGH_INFORMATION,
+      reasonCodes: ["NO_TOOL_RISK_DATA"],
+      safeAlternative: "Run `avorelo mcp risk` to classify tools first.",
+      safeNextAction: "Run `avorelo mcp inventory` then `avorelo mcp risk`.",
+      taskStillExecutable: true,
+      approvalRequired: false,
+      redacted: true,
+    };
+  }
+
+  const codes = toolRisk.reasonCodes || [];
+  const riskLevel = toolRisk.riskLevel || "unknown";
+  let decision = DECISIONS.NOT_ENOUGH_INFORMATION;
+  let safeAlternative = null;
+  let safeNextAction = "Review tool risk before proceeding.";
+  let approvalRequired = false;
+  let taskStillExecutable = true;
+
+  // Critical: block suspicious metadata / tool poisoning signals
+  if (
+    codes.includes(REASON_CODES.SUSPICIOUS_TOOL_DESCRIPTION) ||
+    codes.includes(REASON_CODES.HIDDEN_UNICODE_OR_OBFUSCATION)
+  ) {
+    decision = DECISIONS.BLOCK;
+    safeAlternative = "Remove or replace the tool with a verified alternative.";
+    safeNextAction = "Quarantine this tool: do not use until metadata is reviewed and verified clean.";
+    taskStillExecutable = false;
+    approvalRequired = false;
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // Critical level: destructive/deploy/prod/shell → block or approval_required
+  if (
+    riskLevel === "critical" ||
+    codes.includes(REASON_CODES.DESTRUCTIVE_ACTION) ||
+    codes.includes(REASON_CODES.DEPLOY_OR_PROD_ACTION) ||
+    codes.includes(REASON_CODES.SHELL_COMMAND_CAPABILITY)
+  ) {
+    if (riskLevel === "critical") {
+      decision = DECISIONS.BLOCK;
+      taskStillExecutable = false;
+      safeAlternative = "Use a scoped read-only alternative if the task only needs inspection.";
+      safeNextAction = "This tool requires explicit operator approval before use. Escalate to a human reviewer.";
+    } else {
+      decision = DECISIONS.APPROVAL_REQUIRED;
+      approvalRequired = true;
+      taskStillExecutable = true;
+      safeAlternative = "Scope the tool to read-only or limit to the minimum required action.";
+      safeNextAction = "Get explicit approval before using this tool. Document the task scope.";
+    }
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // High level → approval_required by default
+  if (riskLevel === "high") {
+    decision = DECISIONS.APPROVAL_REQUIRED;
+    approvalRequired = true;
+    taskStillExecutable = true;
+    safeAlternative = "Prefer a scoped read-only tool if available.";
+    safeNextAction = "Approval required before using this tool. State the task scope and get sign-off.";
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // Unknown server → approval_required
+  if (codes.includes(REASON_CODES.UNKNOWN_SERVER) || codes.includes(REASON_CODES.UNTRUSTED_SOURCE)) {
+    decision = DECISIONS.APPROVAL_REQUIRED;
+    approvalRequired = true;
+    taskStillExecutable = true;
+    safeAlternative = "Register the server with a known owner before use.";
+    safeNextAction = "Identify and verify the server source before allowing. Add to approved server list.";
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // Medium level: approval_required for broad access, warn for scoped
+  if (riskLevel === "medium") {
+    if (
+      codes.includes(REASON_CODES.BROAD_FILESYSTEM_ACCESS) ||
+      codes.includes(REASON_CODES.AUTH_REQUIRED) ||
+      codes.includes(REASON_CODES.NETWORK_ACCESS)
+    ) {
+      decision = DECISIONS.APPROVAL_REQUIRED;
+      approvalRequired = true;
+      taskStillExecutable = true;
+      safeAlternative = "Scope to minimum required paths/endpoints.";
+      safeNextAction = "Confirm the tool is scoped to the task before proceeding.";
+    } else {
+      decision = DECISIONS.WARN;
+      safeNextAction = "Review tool access scope before use.";
+    }
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // Low / read-only → allow or warn
+  if (riskLevel === "low") {
+    if (codes.includes(REASON_CODES.LOW_RISK_READ_ONLY)) {
+      decision = DECISIONS.ALLOW;
+      safeNextAction = null;
+    } else {
+      decision = DECISIONS.WARN;
+      safeNextAction = "Verify read-only scope before use.";
+    }
+    return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+  }
+
+  // Fallback
+  decision = DECISIONS.NOT_ENOUGH_INFORMATION;
+  safeNextAction = "Run `avorelo mcp risk` to classify before proceeding.";
+  return { decision, reasonCodes: codes, safeAlternative, safeNextAction, taskStillExecutable, approvalRequired, redacted: true };
+}
+
+// ── Full policy build ─────────────────────────────────────────────────────────
+
+function buildMcpLeastPrivilegePolicy(cwd, riskReport, options = {}) {
+  if (!riskReport || riskReport.status === "pass" && riskReport.summary?.serverCount === 0) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "pass",
+      policyType: "least_privilege",
+      decisions: [],
+      summary: { allow: 0, warn: 0, approvalRequired: 0, blocked: 0, notEnoughInfo: 0 },
+      caveats: ["No MCP servers found — no policy decisions needed."],
+      previewOnly: true,
+      configNotModified: true,
+      redacted: true,
+    };
+  }
+
+  const decisions = [];
+  const context = options.context || {};
+
+  for (const toolRisk of riskReport.tools || []) {
+    const pd = decideMcpToolPolicy(toolRisk, context, options);
+    decisions.push({
+      toolId: toolRisk.toolId,
+      serverId: toolRisk.serverId,
+      name: toolRisk.name,
+      riskLevel: toolRisk.riskLevel,
+      ...pd,
+    });
+  }
+
+  const summary = {
+    allow: decisions.filter((d) => d.decision === DECISIONS.ALLOW).length,
+    warn: decisions.filter((d) => d.decision === DECISIONS.WARN).length,
+    approvalRequired: decisions.filter((d) => d.decision === DECISIONS.APPROVAL_REQUIRED).length,
+    blocked: decisions.filter((d) => d.decision === DECISIONS.BLOCK).length,
+    notEnoughInfo: decisions.filter((d) => d.decision === DECISIONS.NOT_ENOUGH_INFORMATION).length,
+  };
+
+  const overallStatus =
+    summary.blocked > 0 ? "blocked" :
+    summary.approvalRequired > 0 ? "needs_approval" :
+    summary.warn > 0 ? "warn" :
+    summary.notEnoughInfo > 0 ? "needs_review" : "pass";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status: overallStatus,
+    policyType: "least_privilege",
+    decisions,
+    summary,
+    caveats: riskReport.caveats || [],
+    previewOnly: true,
+    configNotModified: true,
+    redacted: true,
+  };
+}
+
+// ── Preview build ─────────────────────────────────────────────────────────────
+
+function buildMcpPolicyPreview(cwd, policy, options = {}) {
+  return {
+    contract: "avorelo.mcpPolicyPreview.v1",
+    schemaVersion: 1,
+    createdAt: nowIso(),
+    status: policy.status,
+    previewOnly: true,
+    configNotModified: true,
+    note: "This preview shows what policy WOULD be applied. No MCP config has been modified.",
+    summary: policy.summary,
+    topDecisions: (policy.decisions || [])
+      .filter((d) => ["block", "approval_required"].includes(d.decision))
+      .slice(0, 10)
+      .map((d) => ({
+        name: d.name,
+        riskLevel: d.riskLevel,
+        decision: d.decision,
+        safeNextAction: d.safeNextAction,
+        reasonCodes: (d.reasonCodes || []).slice(0, 4),
+      })),
+    caveats: policy.caveats || [],
+    redacted: true,
+  };
+}
+
+function writeMcpPolicy(cwd, policy) {
+  const absPath = path.join(cwd, POLICY_REL);
+  safeWriteJson(absPath, policy);
+  return POLICY_REL;
+}
+
+function writeMcpPolicyPreview(cwd, preview) {
+  const absPath = path.join(cwd, PREVIEW_REL);
+  safeWriteJson(absPath, preview);
+  return PREVIEW_REL;
+}
+
+function formatMcpPolicyText(policy, options = {}) {
+  const { debug } = options;
+  const s = policy.summary || {};
+  const lines = [
+    `MCP Least-Privilege Policy [${policy.status}]`,
+    `Allow: ${s.allow} · Warn: ${s.warn} · Approval: ${s.approvalRequired} · Blocked: ${s.blocked}`,
+    `Preview only — config not modified.`,
+  ];
+
+  if (debug && policy.decisions && policy.decisions.length > 0) {
+    for (const d of policy.decisions) {
+      lines.push(`  ${d.name || d.toolId} → ${d.decision} [${d.riskLevel}]`);
+      if (d.safeNextAction) lines.push(`    Next: ${d.safeNextAction}`);
+    }
+  } else if (s.blocked > 0 || s.approvalRequired > 0) {
+    const topIssues = (policy.decisions || [])
+      .filter((d) => ["block", "approval_required"].includes(d.decision))
+      .slice(0, 3);
+    for (const d of topIssues) {
+      lines.push(`  ${d.name || d.toolId} → ${d.decision}`);
+    }
+  }
+
+  lines.push(`Next: Run \`avorelo mcp doctor --json\` for full governance status.`);
+  return lines.join("\n");
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  POLICY_REL,
+  PREVIEW_REL,
+  DECISIONS,
+  buildMcpLeastPrivilegePolicy,
+  decideMcpToolPolicy,
+  buildMcpPolicyPreview,
+  writeMcpPolicy,
+  writeMcpPolicyPreview,
+  formatMcpPolicyText,
+};

package/scripts/lib/mcp-tool-inventory.js

@@ -0,0 +1,388 @@
+"use strict";
+
+// ── MCP Tool Inventory ────────────────────────────────────────────────────────
+//
+// Contract: avorelo.mcpToolInventory.v1
+//
+// Discovers MCP config files locally, parses them statically, and builds a
+// redacted inventory of servers and tool surfaces.
+//
+// SAFETY RULES (never violated):
+// - Does NOT execute MCP servers
+// - Does NOT call MCP tools
+// - Does NOT resolve remote URLs
+// - Does NOT read raw env values / secrets / auth headers
+// - Normalizes paths, handles invalid JSON gracefully (needs_review, not crash)
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const CONTRACT = "avorelo.mcpToolInventory.v1";
+const SCHEMA_VERSION = 1;
+
+const INVENTORY_DIR_REL = ".claude/cco/orchestration/mcp-tool-governance";
+const INVENTORY_REL = `${INVENTORY_DIR_REL}/latest-inventory.json`;
+
+// Known MCP config file locations (relative to cwd), in priority order
+const MCP_CONFIG_CANDIDATES = [
+  ".mcp.json",
+  "mcp.json",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".cursor/mcp.json",
+  ".vscode/mcp.json",
+  ".codex/mcp.json",
+  "AGENTS.md",   // reference-only: may mention MCP servers
+  "CLAUDE.md",   // reference-only
+];
+
+// Known MCP config formats we can parse structurally
+const SUPPORTED_FORMATS = new Set([
+  ".mcp.json",
+  "mcp.json",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".cursor/mcp.json",
+  ".vscode/mcp.json",
+  ".codex/mcp.json",
+]);
+
+// Patterns that look like secrets / env references (for redaction)
+const SECRET_REF_PATTERN = /\$\{?[A-Z_]{4,}\}?|sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|password|api[_-]?key|auth[_-]?token|bearer\s/i;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function safeWriteJson(filePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  } catch {
+    // non-fatal
+  }
+}
+
+function safeReadFile(absPath) {
+  try {
+    return fs.readFileSync(absPath, "utf8").replace(/^/, "");
+  } catch {
+    return null;
+  }
+}
+
+function safeParseJson(text) {
+  try {
+    return { ok: true, data: JSON.parse(text) };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function redactValue(value) {
+  if (typeof value !== "string") return "[non-string]";
+  if (SECRET_REF_PATTERN.test(value)) return "[redacted]";
+  // Redact long tokens / base64-like blobs
+  if (value.length > 80 && /^[A-Za-z0-9+/=_-]{40,}$/.test(value.trim())) return "[redacted-long-token]";
+  // Trim long values
+  if (value.length > 120) return value.slice(0, 60) + "…[truncated]";
+  return value;
+}
+
+function summarizeArgs(args) {
+  if (!Array.isArray(args) || args.length === 0) return "none";
+  return args.map((a) => {
+    if (typeof a === "string") return redactValue(a);
+    return "[non-string-arg]";
+  }).join(" ");
+}
+
+function summarizeEnv(envObj) {
+  if (!envObj || typeof envObj !== "object") return "none";
+  const keys = Object.keys(envObj);
+  if (keys.length === 0) return "none";
+  // Never log values — keys only, with count
+  return `${keys.length} env vars: ${keys.map((k) => `${k}=[redacted]`).join(", ")}`;
+}
+
+function classifyTransport(serverDef) {
+  if (!serverDef || typeof serverDef !== "object") return "unknown";
+  if (serverDef.transport === "stdio" || serverDef.command) return "stdio";
+  if (serverDef.transport === "http" || serverDef.url?.startsWith("http")) return "http";
+  if (serverDef.transport === "sse") return "sse";
+  return "unknown";
+}
+
+function makeSummaryRef(value, label) {
+  if (!value) return null;
+  const str = typeof value === "string" ? value : JSON.stringify(value);
+  return `[${label}: ${redactValue(str.length > 80 ? str.slice(0, 40) + "…" : str)}]`;
+}
+
+// ── Config discovery ──────────────────────────────────────────────────────────
+
+function discoverMcpConfigFiles(cwd, options = {}) {
+  const found = [];
+  const unsupported = [];
+  for (const rel of MCP_CONFIG_CANDIDATES) {
+    const absPath = path.join(cwd, rel);
+    try {
+      if (!fs.existsSync(absPath)) continue;
+    } catch {
+      continue;
+    }
+    const isSupported = SUPPORTED_FORMATS.has(rel);
+    const isMarkdown = rel.endsWith(".md");
+    if (isMarkdown) {
+      unsupported.push({ rel, reason: "markdown_reference_only" });
+      continue;
+    }
+    const stat = (() => { try { return fs.statSync(absPath); } catch { return null; } })();
+    if (!stat || !stat.isFile()) continue;
+    found.push({ rel, absPath, format: isSupported ? "json" : "unknown", supported: isSupported });
+  }
+  return { found, unsupported };
+}
+
+// ── Config parsing ────────────────────────────────────────────────────────────
+
+function parseMcpConfigFile(cwd, filePath, options = {}) {
+  const absPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+  const relPath = path.isAbsolute(filePath) ? path.relative(cwd, filePath) : filePath;
+  const raw = safeReadFile(absPath);
+  if (raw === null) {
+    return {
+      status: "not_found",
+      configRef: relPath,
+      servers: [],
+      caveats: [`Config file not found: ${relPath}`],
+      redacted: true,
+    };
+  }
+
+  const parsed = safeParseJson(raw);
+  if (!parsed.ok) {
+    return {
+      status: "invalid_json",
+      configRef: relPath,
+      servers: [],
+      caveats: [`Invalid JSON in ${relPath}: ${parsed.error}`],
+      redacted: true,
+    };
+  }
+
+  const data = parsed.data;
+  const servers = [];
+  const caveats = [];
+
+  // Extract MCP servers from known config shapes
+  // Shape 1: { mcpServers: { name: { command, args, env, ... } } }
+  // Shape 2: { servers: { name: { ... } } }
+  // Shape 3: { mcp: { servers: { ... } } }
+  const serverMap =
+    (data && data.mcpServers) ||
+    (data && data.servers) ||
+    (data && data.mcp && data.mcp.servers) ||
+    null;
+
+  if (!serverMap || typeof serverMap !== "object" || Array.isArray(serverMap)) {
+    caveats.push(`No mcpServers/servers block found in ${relPath}.`);
+    return { status: "no_servers", configRef: relPath, servers: [], caveats, redacted: true };
+  }
+
+  const names = Object.keys(serverMap);
+  for (const name of names) {
+    const def = serverMap[name];
+    if (!def || typeof def !== "object") {
+      caveats.push(`Server "${name}" has invalid definition (not an object).`);
+      continue;
+    }
+
+    const transport = classifyTransport(def);
+    const commandRef = def.command ? makeSummaryRef(def.command, "cmd") : null;
+    const argsSummary = summarizeArgs(def.args);
+    const envRefSummary = summarizeEnv(def.env);
+    const urlRef = def.url ? makeSummaryRef(def.url, "url") : null;
+
+    // Derive tools from schema (if present in config)
+    const rawTools = (def.tools && Array.isArray(def.tools)) ? def.tools : [];
+    const parsedTools = rawTools.map((t, i) => parseToolDef(t, name, i));
+
+    servers.push({
+      serverId: `server-${name}`,
+      name,
+      sourceConfigRef: relPath,
+      transport,
+      commandRef,
+      argsSummary,
+      envRefSummary,
+      urlRef,
+      trustedSource: "unknown",
+      owner: "unknown",
+      tools: parsedTools,
+      redacted: true,
+    });
+  }
+
+  return { status: "ok", configRef: relPath, servers, caveats, redacted: true };
+}
+
+function parseToolDef(toolDef, serverId, index) {
+  if (!toolDef || typeof toolDef !== "object") {
+    return {
+      toolId: `${serverId}-tool-${index}`,
+      serverId,
+      name: `unknown-tool-${index}`,
+      descriptionSummary: null,
+      schemaSummary: null,
+      declaredReadOnly: false,
+      declaredDestructive: false,
+      declaredNetwork: false,
+      declaredFilesystem: false,
+      declaredAuth: false,
+      metadataRiskSignals: ["MALFORMED_TOOL_DEF"],
+      redacted: true,
+    };
+  }
+
+  const name = toolDef.name || `tool-${index}`;
+  const desc = toolDef.description || toolDef.desc || "";
+  const schema = toolDef.inputSchema || toolDef.input_schema || toolDef.parameters || null;
+
+  const descSummary = desc.length > 0 ? (desc.length > 200 ? desc.slice(0, 100) + "…[truncated]" : desc) : null;
+  const schemaSummary = schema ? `properties:${Object.keys(schema.properties || {}).length}` : null;
+
+  return {
+    toolId: `${serverId}-${name}`,
+    serverId,
+    name,
+    descriptionSummary: descSummary,
+    schemaSummary,
+    declaredReadOnly: Boolean(toolDef.readOnly || toolDef.readonly),
+    declaredDestructive: Boolean(toolDef.destructive || toolDef.dangerous),
+    declaredNetwork: Boolean(toolDef.network || toolDef.http),
+    declaredFilesystem: Boolean(toolDef.filesystem || toolDef.files),
+    declaredAuth: Boolean(toolDef.auth || toolDef.authorization),
+    metadataRiskSignals: [],
+    redacted: true,
+  };
+}
+
+// ── Full inventory build ──────────────────────────────────────────────────────
+
+function buildMcpToolInventory(cwd, options = {}) {
+  const { found, unsupported } = discoverMcpConfigFiles(cwd, options);
+  const configFiles = [];
+  const allServers = [];
+  const allTools = [];
+  const caveats = [];
+
+  if (found.length === 0 && unsupported.length === 0) {
+    return {
+      contract: CONTRACT,
+      schemaVersion: SCHEMA_VERSION,
+      createdAt: nowIso(),
+      status: "none",
+      configFiles: [],
+      servers: [],
+      tools: [],
+      unsupportedConfigs: unsupported,
+      caveats: ["No MCP config files found. This is safe — no tool surfaces to govern."],
+      redacted: true,
+    };
+  }
+
+  for (const configFile of found) {
+    const parsed = parseMcpConfigFile(cwd, configFile.rel, options);
+    configFiles.push({ rel: configFile.rel, status: parsed.status });
+    caveats.push(...(parsed.caveats || []));
+
+    for (const server of parsed.servers) {
+      allServers.push(server);
+      for (const tool of server.tools || []) {
+        allTools.push(tool);
+      }
+    }
+  }
+
+  const hasInvalidJson = configFiles.some((f) => f.status === "invalid_json");
+  const hasNoServers = configFiles.every((f) => ["no_servers", "not_found"].includes(f.status));
+  const status = hasInvalidJson || unsupported.length > 0
+    ? "needs_review"
+    : hasNoServers && allServers.length === 0
+      ? "none"
+      : allServers.length > 0
+        ? "ready"
+        : "partial";
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    configFiles,
+    servers: allServers,
+    tools: allTools,
+    unsupportedConfigs: unsupported,
+    caveats: caveats.length > 0 ? caveats : [],
+    redacted: true,
+  };
+}
+
+function writeMcpToolInventory(cwd, inventory) {
+  const absPath = path.join(cwd, INVENTORY_REL);
+  safeWriteJson(absPath, inventory);
+  return INVENTORY_REL;
+}
+
+function buildMcpToolInventorySurface(cwd, options = {}) {
+  const inventory = buildMcpToolInventory(cwd, options);
+  writeMcpToolInventory(cwd, inventory);
+  return inventory;
+}
+
+function formatMcpToolInventoryText(inventory, options = {}) {
+  const { debug } = options;
+  const lines = [
+    `MCP Tool Inventory [${inventory.status}]`,
+    `Config files: ${inventory.configFiles.length} · Servers: ${inventory.servers.length} · Tools: ${inventory.tools.length}`,
+  ];
+
+  if (inventory.servers.length > 0) {
+    for (const s of inventory.servers) {
+      lines.push(`  Server: ${s.name} [${s.transport}] trust=${s.trustedSource}`);
+      if (debug && s.tools && s.tools.length > 0) {
+        for (const t of s.tools) {
+          lines.push(`    Tool: ${t.name}`);
+        }
+      }
+    }
+  }
+
+  if (inventory.unsupportedConfigs.length > 0) {
+    lines.push(`Unsupported configs: ${inventory.unsupportedConfigs.map((u) => u.rel).join(", ")}`);
+  }
+
+  if (inventory.caveats && inventory.caveats.length > 0 && debug) {
+    lines.push(`Caveats: ${inventory.caveats.join("; ")}`);
+  }
+
+  lines.push(`Next: Run \`avorelo mcp risk --json\` to classify tool risk.`);
+  return lines.join("\n");
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  INVENTORY_REL,
+  discoverMcpConfigFiles,
+  parseMcpConfigFile,
+  buildMcpToolInventory,
+  writeMcpToolInventory,
+  buildMcpToolInventorySurface,
+  formatMcpToolInventoryText,
+};