@authora/agent-audit 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,11 +1,101 @@
 #!/usr/bin/env node
 import { scanDirectory } from "./scanner.js";
 import { formatReport } from "./reporter.js";
+import { scanMcpServer } from "./mcp-scanner.js";
+import { formatMcpReport } from "./mcp-reporter.js";
 const args = process.argv.slice(2);
-const targetDir = args[0] ?? ".";
 const jsonOutput = args.includes("--json");
 const badgeOutput = args.includes("--badge");
-async function main() {
+function getFlag(flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+// -- MCP subcommand -----------------------------------------------------------
+async function mcpMain() {
+    const positionals = args.filter((a) => !a.startsWith("--") && a !== "mcp");
+    // Also grab positional after a --flag value
+    let url = positionals[0];
+    if (!url || args.includes("--help")) {
+        console.log(`
+  \x1b[1m@authora/agent-audit mcp\x1b[0m -- MCP Server Security Scanner
+
+  \x1b[1mUsage:\x1b[0m
+    npx @authora/agent-audit mcp <url> [options]
+
+  \x1b[1mOptions:\x1b[0m
+    --api-key <key>      API key (sent as api-key header)
+    --bearer <token>     Bearer token (sent as Authorization header)
+    --json               Output JSON for CI pipelines
+    --fail-below <grade> Exit 1 if grade is below threshold (A+, A, B+, B, C, D)
+    --help               Show this help
+
+  \x1b[1mExamples:\x1b[0m
+    npx @authora/agent-audit mcp https://mcp.authora.dev --api-key authora_live_xxx
+    npx @authora/agent-audit mcp https://my-server.com --bearer sk-xxx --json
+    npx @authora/agent-audit mcp https://my-server.com --fail-below B
+
+  \x1b[90mBy Authora -- https://authora.dev\x1b[0m
+`);
+        process.exit(0);
+    }
+    if (!url.startsWith("http"))
+        url = `https://${url}`;
+    const headers = {};
+    const apiKey = getFlag("--api-key");
+    const bearer = getFlag("--bearer");
+    const authenticated = !!(apiKey || bearer);
+    if (apiKey)
+        headers["api-key"] = apiKey;
+    if (bearer)
+        headers["Authorization"] = `Bearer ${bearer}`;
+    if (!jsonOutput) {
+        process.stdout.write(`  \x1b[90mScanning ${url} ...\x1b[0m`);
+    }
+    const result = await scanMcpServer(url, headers, authenticated);
+    if (jsonOutput) {
+        process.stdout.write("\r" + " ".repeat(60) + "\r");
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        process.stdout.write("\r" + " ".repeat(60) + "\r");
+        console.log(formatMcpReport(result));
+    }
+    // CI gate
+    const failBelow = getFlag("--fail-below");
+    if (failBelow) {
+        const threshold = failBelow.toUpperCase();
+        const order = ["F", "D", "C", "B", "B+", "A", "A+"];
+        const resultIdx = order.indexOf(result.letter);
+        const thresholdIdx = order.indexOf(threshold);
+        if (resultIdx >= 0 && thresholdIdx >= 0 && resultIdx < thresholdIdx) {
+            if (!jsonOutput) {
+                console.log(`  \x1b[31m\x1b[1mFAILED:\x1b[0m Grade ${result.letter} is below threshold ${threshold}`);
+                console.log();
+            }
+            process.exit(1);
+        }
+    }
+}
+// -- Local scan (original) ----------------------------------------------------
+async function localMain() {
+    const targetDir = args.filter((a) => !a.startsWith("--"))[0] ?? ".";
+    if (args.includes("--help")) {
+        console.log(`
+  \x1b[1m@authora/agent-audit\x1b[0m -- Agent Security Scanner
+
+  \x1b[1mUsage:\x1b[0m
+    npx @authora/agent-audit [directory]     Scan local codebase
+    npx @authora/agent-audit mcp <url>       Scan remote MCP server
+
+  \x1b[1mOptions:\x1b[0m
+    --json     Output JSON
+    --badge    Show README badge
+    --help     Show this help
+
+  \x1b[90mBy Authora -- https://authora.dev\x1b[0m
+`);
+        process.exit(0);
+    }
     if (!jsonOutput) {
         console.log("");
         console.log("  \x1b[1m\x1b[36mAgent Security Audit\x1b[0m");
@@ -31,6 +121,15 @@ async function main() {
     }
     process.exit(findings.score >= 6 ? 0 : 1);
 }
+// -- Router -------------------------------------------------------------------
+async function main() {
+    if (args[0] === "mcp") {
+        await mcpMain();
+    }
+    else {
+        await localMain();
+    }
+}
 main().catch((err) => {
     console.error("  \x1b[31mError:\x1b[0m", err.message);
     process.exit(2);

package/dist/mcp-reporter.d.ts

@@ -0,0 +1,2 @@
+import type { McpAuditResult } from "./mcp-scanner.js";
+export declare function formatMcpReport(result: McpAuditResult): string;

package/dist/mcp-reporter.js

@@ -0,0 +1,59 @@
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[90m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+};
+const gradeColors = {
+    "A+": c.green, A: c.green,
+    "B+": c.green, B: c.green,
+    C: c.yellow,
+    D: c.red,
+    F: c.red,
+};
+export function formatMcpReport(result) {
+    const gc = gradeColors[result.letter] ?? c.reset;
+    const lines = [];
+    lines.push("");
+    lines.push(`  ${c.bold}MCP Security Audit${c.reset}  ${c.dim}via ${result.method}${c.reset}`);
+    lines.push(`  ${c.dim}${"─".repeat(50)}${c.reset}`);
+    lines.push("");
+    lines.push(`  ${gc}${c.bold}  ${result.letter}  ${c.reset}  ${c.dim}Grade${c.reset}  ${c.bold}${result.score}${c.reset}${c.dim}/100${c.reset}  ${result.authenticated ? `${c.green}AUTH${c.reset}` : `${c.red}NO AUTH${c.reset}`}`);
+    lines.push("");
+    lines.push(`  ${c.bold}${result.total}${c.reset} tools  ${c.green}${result.safe}${c.reset} safe  ${c.yellow}${result.review}${c.reset} review  ${c.red}${result.dangerous}${c.reset} dangerous`);
+    lines.push("");
+    // Dangerous tools
+    const dangerTools = result.tools.filter((t) => t.level === "danger");
+    if (dangerTools.length > 0) {
+        lines.push(`  ${c.red}${c.bold}Dangerous tools:${c.reset}`);
+        for (const t of dangerTools) {
+            lines.push(`  ${c.red}*${c.reset} ${c.bold}${t.name}${c.reset}${t.description ? c.dim + " -- " + t.description.slice(0, 60) + c.reset : ""}`);
+        }
+        lines.push("");
+    }
+    // Review tools (collapsed)
+    const reviewTools = result.tools.filter((t) => t.level === "warn");
+    if (reviewTools.length > 0) {
+        const show = reviewTools.slice(0, 5);
+        const remaining = reviewTools.length - show.length;
+        lines.push(`  ${c.yellow}${c.bold}Needs review:${c.reset}`);
+        for (const t of show) {
+            lines.push(`  ${c.yellow}*${c.reset} ${t.name}${t.description ? c.dim + " -- " + t.description.slice(0, 60) + c.reset : ""}`);
+        }
+        if (remaining > 0) {
+            lines.push(`  ${c.dim}  ... and ${remaining} more${c.reset}`);
+        }
+        lines.push("");
+    }
+    // Badge
+    const badgeColor = result.score >= 70 ? "brightgreen" : result.score >= 50 ? "yellow" : "red";
+    lines.push(`  ${c.dim}README badge:${c.reset}`);
+    lines.push(`  ${c.dim}![MCP Security: ${result.letter}](https://img.shields.io/badge/MCP_Security-${encodeURIComponent(result.letter)}-${badgeColor})${c.reset}`);
+    lines.push("");
+    lines.push(`  ${c.dim}Web inspector: https://mcp.authora.dev/inspect${c.reset}`);
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/mcp-scanner.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP Server Security Scanner
+ *
+ * Connects to a remote MCP server, discovers tools,
+ * classifies them by risk level, and produces a security grade.
+ */
+export interface McpTool {
+    name: string;
+    description: string;
+    level: "safe" | "warn" | "danger";
+}
+export interface McpAuditResult {
+    tools: McpTool[];
+    total: number;
+    safe: number;
+    review: number;
+    dangerous: number;
+    score: number;
+    letter: string;
+    method: string;
+    authenticated: boolean;
+}
+export declare function scanMcpServer(url: string, headers: Record<string, string>, authenticated: boolean): Promise<McpAuditResult>;

package/dist/mcp-scanner.js

@@ -0,0 +1,165 @@
+/**
+ * MCP Server Security Scanner
+ *
+ * Connects to a remote MCP server, discovers tools,
+ * classifies them by risk level, and produces a security grade.
+ */
+// Dangerous: destructive or privilege-escalating operations
+const DANGEROUS = [
+    "delete", "remove", "drop", "exec", "execute", "shell", "command",
+    "run_command", "kill", "terminate", "destroy", "purge", "wipe", "force",
+    "override", "revoke", "suspend", "deactivate", "disable", "deny", "reject",
+    "reset", "unregister", "detach", "disconnect",
+];
+// Safe: read-only, observability, and query operations
+const SAFE = [
+    "read", "get", "list", "search", "query", "fetch", "check", "verify",
+    "status", "health", "describe", "count", "view", "show", "inspect", "find",
+    "lookup", "validate", "export", "audit", "log", "monitor", "history",
+    "report", "resolve", "whoami", "me", "info", "version", "ping", "echo",
+    "help", "capabilities", "schema", "metadata", "stats", "summary",
+    "discover", "enumerate", "batch_get", "batch_list",
+];
+// Review: mutations that change state but are not destructive
+const REVIEW = [
+    "create", "write", "modify", "send", "deploy", "publish", "update",
+    "assign", "grant", "approve", "set", "add", "configure", "delegate",
+    "escalate", "notify", "alert", "rotate", "renew", "generate", "import",
+    "register", "trigger", "enable", "activate", "reactivate", "connect",
+    "attach", "invite", "enroll", "submit", "request", "initiate", "provision",
+    "emit", "push", "post", "put", "patch", "insert", "upsert", "merge",
+    "sync", "transfer", "move", "copy", "clone", "fork", "sign", "issue",
+    "mint", "encode", "encrypt", "authorize", "consent", "accept",
+    "acknowledge", "confirm", "start", "stop", "pause", "resume", "schedule",
+    "cancel", "retry", "replay", "release", "promote", "demote", "tag",
+    "label", "annotate", "comment", "flag", "pin", "bookmark", "subscribe",
+    "unsubscribe", "follow", "unfollow", "mute", "unmute", "archive", "restore",
+];
+function wordBoundaryMatch(text, word) {
+    return new RegExp(`(^|[_\\-\\s.])${word}([_\\-\\s.]|$)`).test(text);
+}
+function classifyTool(name, description) {
+    const text = `${name} ${description ?? ""}`.toLowerCase();
+    for (const kw of DANGEROUS) {
+        if (wordBoundaryMatch(text, kw))
+            return "danger";
+    }
+    for (const kw of SAFE) {
+        if (wordBoundaryMatch(text, kw))
+            return "safe";
+    }
+    for (const kw of REVIEW) {
+        if (wordBoundaryMatch(text, kw))
+            return "warn";
+    }
+    return "warn";
+}
+function gradeLetter(score) {
+    if (score >= 90)
+        return "A+";
+    if (score >= 80)
+        return "A";
+    if (score >= 70)
+        return "B+";
+    if (score >= 60)
+        return "B";
+    if (score >= 50)
+        return "C";
+    if (score >= 30)
+        return "D";
+    return "F";
+}
+export async function scanMcpServer(url, headers, authenticated) {
+    const base = url.replace(/\/sse\/?$/, "").replace(/\/$/, "");
+    let rawTools = [];
+    let method = "";
+    // Try REST /tools
+    try {
+        const res = await fetch(`${base}/tools`, {
+            headers,
+            signal: AbortSignal.timeout(15000),
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            rawTools = data.tools ?? [];
+            method = "REST /tools";
+        }
+        else if (res.status === 401) {
+            throw new Error("Server returned 401 Unauthorized. Provide --api-key or --bearer.");
+        }
+    }
+    catch (e) {
+        if (e.message.includes("401"))
+            throw e;
+    }
+    // Fallback: JSON-RPC tools/list
+    if (rawTools.length === 0) {
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: { ...headers, "Content-Type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 1 }),
+                signal: AbortSignal.timeout(15000),
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                rawTools = data.result?.tools ?? data.tools ?? [];
+                method = "JSON-RPC";
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (rawTools.length === 0) {
+        throw new Error("Could not retrieve tools. Check the URL and authentication.");
+    }
+    // Deduplicate by name
+    const seen = new Set();
+    const tools = [];
+    let safe = 0, review = 0, dangerous = 0;
+    for (const t of rawTools) {
+        if (seen.has(t.name))
+            continue;
+        seen.add(t.name);
+        const level = classifyTool(t.name, t.description);
+        if (level === "safe")
+            safe++;
+        else if (level === "warn")
+            review++;
+        else
+            dangerous++;
+        tools.push({ name: t.name, description: t.description ?? "", level });
+    }
+    // Sort: dangerous first, then review, then safe
+    tools.sort((a, b) => {
+        const order = { danger: 0, warn: 1, safe: 2 };
+        return order[a.level] - order[b.level];
+    });
+    // Score: ratio-based
+    const total = tools.length;
+    const safeRatio = safe / total;
+    const dangerRatio = dangerous / total;
+    let score = Math.round(safeRatio * 60 + (1 - dangerRatio) * 30);
+    if (authenticated)
+        score += 10;
+    if (dangerRatio > 0.3)
+        score -= 15;
+    else if (dangerRatio > 0.2)
+        score -= 5;
+    const undocDanger = tools.filter((t) => t.level === "danger" && !t.description).length;
+    if (dangerous > 0 && undocDanger / dangerous > 0.5)
+        score -= 10;
+    score = Math.max(0, Math.min(100, score));
+    return {
+        tools,
+        total,
+        safe,
+        review,
+        dangerous,
+        score,
+        letter: gradeLetter(score),
+        method,
+        authenticated,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@authora/agent-audit",
-  "version": "0.1.0",
-  "description": "Security scanner for AI agents. Find vulnerabilities in your agent setup in 30 seconds.",
+  "version": "0.2.0",
+  "description": "Security scanner for AI agents and MCP servers. Scan local codebases or remote MCP servers in seconds.",
   "bin": {
     "agent-audit": "./dist/cli.js"
   },
@@ -15,9 +15,11 @@
     "security",
     "audit",
     "mcp",
+    "model-context-protocol",
     "agent-identity",
     "llm-security",
-    "ai-security"
+    "ai-security",
+    "mcp-security"
   ],
   "author": "Authora <admin@authora.dev> (https://authora.dev)",
   "license": "MIT",

package/src/cli.ts

@@ -2,13 +2,114 @@
 
 import { scanDirectory } from "./scanner.js";
 import { formatReport } from "./reporter.js";
+import { scanMcpServer } from "./mcp-scanner.js";
+import { formatMcpReport } from "./mcp-reporter.js";
 
 const args = process.argv.slice(2);
-const targetDir = args[0] ?? ".";
 const jsonOutput = args.includes("--json");
 const badgeOutput = args.includes("--badge");
 
-async function main() {
+function getFlag(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx >= 0 && idx + 1 < args.length ? args[idx + 1] : undefined;
+}
+
+// -- MCP subcommand -----------------------------------------------------------
+
+async function mcpMain() {
+  const positionals = args.filter((a) => !a.startsWith("--") && a !== "mcp");
+  // Also grab positional after a --flag value
+  let url = positionals[0];
+
+  if (!url || args.includes("--help")) {
+    console.log(`
+  \x1b[1m@authora/agent-audit mcp\x1b[0m -- MCP Server Security Scanner
+
+  \x1b[1mUsage:\x1b[0m
+    npx @authora/agent-audit mcp <url> [options]
+
+  \x1b[1mOptions:\x1b[0m
+    --api-key <key>      API key (sent as api-key header)
+    --bearer <token>     Bearer token (sent as Authorization header)
+    --json               Output JSON for CI pipelines
+    --fail-below <grade> Exit 1 if grade is below threshold (A+, A, B+, B, C, D)
+    --help               Show this help
+
+  \x1b[1mExamples:\x1b[0m
+    npx @authora/agent-audit mcp https://mcp.authora.dev --api-key authora_live_xxx
+    npx @authora/agent-audit mcp https://my-server.com --bearer sk-xxx --json
+    npx @authora/agent-audit mcp https://my-server.com --fail-below B
+
+  \x1b[90mBy Authora -- https://authora.dev\x1b[0m
+`);
+    process.exit(0);
+  }
+
+  if (!url.startsWith("http")) url = `https://${url}`;
+
+  const headers: Record<string, string> = {};
+  const apiKey = getFlag("--api-key");
+  const bearer = getFlag("--bearer");
+  const authenticated = !!(apiKey || bearer);
+  if (apiKey) headers["api-key"] = apiKey;
+  if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
+
+  if (!jsonOutput) {
+    process.stdout.write(`  \x1b[90mScanning ${url} ...\x1b[0m`);
+  }
+
+  const result = await scanMcpServer(url, headers, authenticated);
+
+  if (jsonOutput) {
+    process.stdout.write("\r" + " ".repeat(60) + "\r");
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    process.stdout.write("\r" + " ".repeat(60) + "\r");
+    console.log(formatMcpReport(result));
+  }
+
+  // CI gate
+  const failBelow = getFlag("--fail-below");
+  if (failBelow) {
+    const threshold = failBelow.toUpperCase();
+    const order = ["F", "D", "C", "B", "B+", "A", "A+"];
+    const resultIdx = order.indexOf(result.letter);
+    const thresholdIdx = order.indexOf(threshold);
+    if (resultIdx >= 0 && thresholdIdx >= 0 && resultIdx < thresholdIdx) {
+      if (!jsonOutput) {
+        console.log(
+          `  \x1b[31m\x1b[1mFAILED:\x1b[0m Grade ${result.letter} is below threshold ${threshold}`,
+        );
+        console.log();
+      }
+      process.exit(1);
+    }
+  }
+}
+
+// -- Local scan (original) ----------------------------------------------------
+
+async function localMain() {
+  const targetDir = args.filter((a) => !a.startsWith("--"))[0] ?? ".";
+
+  if (args.includes("--help")) {
+    console.log(`
+  \x1b[1m@authora/agent-audit\x1b[0m -- Agent Security Scanner
+
+  \x1b[1mUsage:\x1b[0m
+    npx @authora/agent-audit [directory]     Scan local codebase
+    npx @authora/agent-audit mcp <url>       Scan remote MCP server
+
+  \x1b[1mOptions:\x1b[0m
+    --json     Output JSON
+    --badge    Show README badge
+    --help     Show this help
+
+  \x1b[90mBy Authora -- https://authora.dev\x1b[0m
+`);
+    process.exit(0);
+  }
+
   if (!jsonOutput) {
     console.log("");
     console.log("  \x1b[1m\x1b[36mAgent Security Audit\x1b[0m");
@@ -40,6 +141,16 @@ async function main() {
   process.exit(findings.score >= 6 ? 0 : 1);
 }
 
+// -- Router -------------------------------------------------------------------
+
+async function main() {
+  if (args[0] === "mcp") {
+    await mcpMain();
+  } else {
+    await localMain();
+  }
+}
+
 main().catch((err) => {
   console.error("  \x1b[31mError:\x1b[0m", (err as Error).message);
   process.exit(2);

package/src/mcp-reporter.ts

@@ -0,0 +1,78 @@
+import type { McpAuditResult } from "./mcp-scanner.js";
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[90m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+};
+
+const gradeColors: Record<string, string> = {
+  "A+": c.green, A: c.green,
+  "B+": c.green, B: c.green,
+  C: c.yellow,
+  D: c.red,
+  F: c.red,
+};
+
+export function formatMcpReport(result: McpAuditResult): string {
+  const gc = gradeColors[result.letter] ?? c.reset;
+  const lines: string[] = [];
+
+  lines.push("");
+  lines.push(`  ${c.bold}MCP Security Audit${c.reset}  ${c.dim}via ${result.method}${c.reset}`);
+  lines.push(`  ${c.dim}${"─".repeat(50)}${c.reset}`);
+  lines.push("");
+  lines.push(
+    `  ${gc}${c.bold}  ${result.letter}  ${c.reset}  ${c.dim}Grade${c.reset}  ${c.bold}${result.score}${c.reset}${c.dim}/100${c.reset}  ${result.authenticated ? `${c.green}AUTH${c.reset}` : `${c.red}NO AUTH${c.reset}`}`,
+  );
+  lines.push("");
+  lines.push(
+    `  ${c.bold}${result.total}${c.reset} tools  ${c.green}${result.safe}${c.reset} safe  ${c.yellow}${result.review}${c.reset} review  ${c.red}${result.dangerous}${c.reset} dangerous`,
+  );
+  lines.push("");
+
+  // Dangerous tools
+  const dangerTools = result.tools.filter((t) => t.level === "danger");
+  if (dangerTools.length > 0) {
+    lines.push(`  ${c.red}${c.bold}Dangerous tools:${c.reset}`);
+    for (const t of dangerTools) {
+      lines.push(
+        `  ${c.red}*${c.reset} ${c.bold}${t.name}${c.reset}${t.description ? c.dim + " -- " + t.description.slice(0, 60) + c.reset : ""}`,
+      );
+    }
+    lines.push("");
+  }
+
+  // Review tools (collapsed)
+  const reviewTools = result.tools.filter((t) => t.level === "warn");
+  if (reviewTools.length > 0) {
+    const show = reviewTools.slice(0, 5);
+    const remaining = reviewTools.length - show.length;
+    lines.push(`  ${c.yellow}${c.bold}Needs review:${c.reset}`);
+    for (const t of show) {
+      lines.push(
+        `  ${c.yellow}*${c.reset} ${t.name}${t.description ? c.dim + " -- " + t.description.slice(0, 60) + c.reset : ""}`,
+      );
+    }
+    if (remaining > 0) {
+      lines.push(`  ${c.dim}  ... and ${remaining} more${c.reset}`);
+    }
+    lines.push("");
+  }
+
+  // Badge
+  const badgeColor = result.score >= 70 ? "brightgreen" : result.score >= 50 ? "yellow" : "red";
+  lines.push(`  ${c.dim}README badge:${c.reset}`);
+  lines.push(
+    `  ${c.dim}![MCP Security: ${result.letter}](https://img.shields.io/badge/MCP_Security-${encodeURIComponent(result.letter)}-${badgeColor})${c.reset}`,
+  );
+  lines.push("");
+  lines.push(`  ${c.dim}Web inspector: https://mcp.authora.dev/inspect${c.reset}`);
+  lines.push("");
+
+  return lines.join("\n");
+}

package/src/mcp-scanner.ts

@@ -0,0 +1,186 @@
+/**
+ * MCP Server Security Scanner
+ *
+ * Connects to a remote MCP server, discovers tools,
+ * classifies them by risk level, and produces a security grade.
+ */
+
+export interface McpTool {
+  name: string;
+  description: string;
+  level: "safe" | "warn" | "danger";
+}
+
+export interface McpAuditResult {
+  tools: McpTool[];
+  total: number;
+  safe: number;
+  review: number;
+  dangerous: number;
+  score: number;
+  letter: string;
+  method: string;
+  authenticated: boolean;
+}
+
+// Dangerous: destructive or privilege-escalating operations
+const DANGEROUS = [
+  "delete", "remove", "drop", "exec", "execute", "shell", "command",
+  "run_command", "kill", "terminate", "destroy", "purge", "wipe", "force",
+  "override", "revoke", "suspend", "deactivate", "disable", "deny", "reject",
+  "reset", "unregister", "detach", "disconnect",
+];
+
+// Safe: read-only, observability, and query operations
+const SAFE = [
+  "read", "get", "list", "search", "query", "fetch", "check", "verify",
+  "status", "health", "describe", "count", "view", "show", "inspect", "find",
+  "lookup", "validate", "export", "audit", "log", "monitor", "history",
+  "report", "resolve", "whoami", "me", "info", "version", "ping", "echo",
+  "help", "capabilities", "schema", "metadata", "stats", "summary",
+  "discover", "enumerate", "batch_get", "batch_list",
+];
+
+// Review: mutations that change state but are not destructive
+const REVIEW = [
+  "create", "write", "modify", "send", "deploy", "publish", "update",
+  "assign", "grant", "approve", "set", "add", "configure", "delegate",
+  "escalate", "notify", "alert", "rotate", "renew", "generate", "import",
+  "register", "trigger", "enable", "activate", "reactivate", "connect",
+  "attach", "invite", "enroll", "submit", "request", "initiate", "provision",
+  "emit", "push", "post", "put", "patch", "insert", "upsert", "merge",
+  "sync", "transfer", "move", "copy", "clone", "fork", "sign", "issue",
+  "mint", "encode", "encrypt", "authorize", "consent", "accept",
+  "acknowledge", "confirm", "start", "stop", "pause", "resume", "schedule",
+  "cancel", "retry", "replay", "release", "promote", "demote", "tag",
+  "label", "annotate", "comment", "flag", "pin", "bookmark", "subscribe",
+  "unsubscribe", "follow", "unfollow", "mute", "unmute", "archive", "restore",
+];
+
+function wordBoundaryMatch(text: string, word: string): boolean {
+  return new RegExp(`(^|[_\\-\\s.])${word}([_\\-\\s.]|$)`).test(text);
+}
+
+function classifyTool(name: string, description?: string): "safe" | "warn" | "danger" {
+  const text = `${name} ${description ?? ""}`.toLowerCase();
+
+  for (const kw of DANGEROUS) {
+    if (wordBoundaryMatch(text, kw)) return "danger";
+  }
+  for (const kw of SAFE) {
+    if (wordBoundaryMatch(text, kw)) return "safe";
+  }
+  for (const kw of REVIEW) {
+    if (wordBoundaryMatch(text, kw)) return "warn";
+  }
+  return "warn";
+}
+
+function gradeLetter(score: number): string {
+  if (score >= 90) return "A+";
+  if (score >= 80) return "A";
+  if (score >= 70) return "B+";
+  if (score >= 60) return "B";
+  if (score >= 50) return "C";
+  if (score >= 30) return "D";
+  return "F";
+}
+
+export async function scanMcpServer(
+  url: string,
+  headers: Record<string, string>,
+  authenticated: boolean,
+): Promise<McpAuditResult> {
+  const base = url.replace(/\/sse\/?$/, "").replace(/\/$/, "");
+  let rawTools: Array<{ name: string; description?: string }> = [];
+  let method = "";
+
+  // Try REST /tools
+  try {
+    const res = await fetch(`${base}/tools`, {
+      headers,
+      signal: AbortSignal.timeout(15000),
+    });
+    if (res.ok) {
+      const data = (await res.json()) as any;
+      rawTools = data.tools ?? [];
+      method = "REST /tools";
+    } else if (res.status === 401) {
+      throw new Error(
+        "Server returned 401 Unauthorized. Provide --api-key or --bearer.",
+      );
+    }
+  } catch (e: any) {
+    if (e.message.includes("401")) throw e;
+  }
+
+  // Fallback: JSON-RPC tools/list
+  if (rawTools.length === 0) {
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 1 }),
+        signal: AbortSignal.timeout(15000),
+      });
+      if (res.ok) {
+        const data = (await res.json()) as any;
+        rawTools = data.result?.tools ?? data.tools ?? [];
+        method = "JSON-RPC";
+      }
+    } catch {
+      // fall through
+    }
+  }
+
+  if (rawTools.length === 0) {
+    throw new Error(
+      "Could not retrieve tools. Check the URL and authentication.",
+    );
+  }
+
+  // Deduplicate by name
+  const seen = new Set<string>();
+  const tools: McpTool[] = [];
+  let safe = 0, review = 0, dangerous = 0;
+
+  for (const t of rawTools) {
+    if (seen.has(t.name)) continue;
+    seen.add(t.name);
+    const level = classifyTool(t.name, t.description);
+    if (level === "safe") safe++;
+    else if (level === "warn") review++;
+    else dangerous++;
+    tools.push({ name: t.name, description: t.description ?? "", level });
+  }
+
+  // Sort: dangerous first, then review, then safe
+  tools.sort((a, b) => {
+    const order = { danger: 0, warn: 1, safe: 2 };
+    return order[a.level] - order[b.level];
+  });
+
+  // Score: ratio-based
+  const total = tools.length;
+  const safeRatio = safe / total;
+  const dangerRatio = dangerous / total;
+  let score = Math.round(safeRatio * 60 + (1 - dangerRatio) * 30);
+  if (authenticated) score += 10;
+  if (dangerRatio > 0.3) score -= 15;
+  else if (dangerRatio > 0.2) score -= 5;
+  const undocDanger = tools.filter((t) => t.level === "danger" && !t.description).length;
+  if (dangerous > 0 && undocDanger / dangerous > 0.5) score -= 10;
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    tools,
+    total,
+    safe,
+    review,
+    dangerous,
+    score,
+    letter: gradeLetter(score),
+    method,
+    authenticated,
+  };
+}