agentaudit 3.2.0 → 3.4.0

package/README.md

@@ -4,89 +4,144 @@
 
 **Security scanner for AI packages**
 
-Scan MCP servers, agent skills, and AI tools for vulnerabilities — from the terminal or via MCP.
+Scan MCP servers, agent skills, and AI tools for vulnerabilities.  
+MCP server for agents + standalone CLI for humans.
 
 [![npm](https://img.shields.io/npm/v/agentaudit?style=flat-square&color=00C853)](https://www.npmjs.com/package/agentaudit)
-[![Trust Registry](https://img.shields.io/badge/Registry-agentaudit.dev-00C853?style=flat-square)](https://agentaudit.dev)
+[![Registry](https://img.shields.io/badge/Registry-agentaudit.dev-00C853?style=flat-square)](https://agentaudit.dev)
 [![License](https://img.shields.io/badge/License-AGPL_3.0-F9A825?style=flat-square)](LICENSE)
 
 </div>
 
 ---
 
-## Quick Start
+## Getting Started
 
-```bash
-# Install globally
-npm install -g agentaudit
-
-# Setup (register + get API key — free, one-time)
-agentaudit setup
+There are two ways to use AgentAudit:
 
-# Scan a repo
-agentaudit scan https://github.com/owner/repo
+### Option A: MCP Server in your AI editor (recommended)
 
-# Scan multiple repos
-agentaudit scan repo1 repo2 repo3
+Add AgentAudit to Claude Desktop, Cursor, or Windsurf. **No API key needed** — your editor's agent runs audits using its own LLM.
 
-# Check if a package has been audited
-agentaudit check fastmcp
+```json
+{
+  "mcpServers": {
+    "agentaudit": {
+      "command": "npx",
+      "args": ["-y", "agentaudit"]
+    }
+  }
+}
 ```
 
-Or run without installing:
+Then just ask your agent: *"Check which MCP servers I have installed and audit any unaudited ones."*
+
+### Option B: CLI
 
 ```bash
-npx agentaudit scan https://github.com/owner/repo
+# Install
+npm install -g agentaudit    # or use npx agentaudit <command>
+
+# 1. Discover your MCP servers
+npx agentaudit discover
+
+# 2. Audit unaudited packages (needs an LLM API key)
+export ANTHROPIC_API_KEY=sk-ant-...    # or OPENAI_API_KEY=sk-...
+npx agentaudit audit https://github.com/owner/repo
+
+# 3. (Optional) Register to upload reports to the public registry
+npx agentaudit setup
 ```
 
-## What it does
+> **Note:** The `audit` command requires an LLM API key (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) to analyze code. The `discover`, `scan`, and `check` commands work without one. If you don't have an API key, use `--export` to generate a markdown file you can paste into any LLM, or use AgentAudit as an MCP server (Option A) where no extra key is needed.
+
+### Quick example
 
 ```
-◉  google-workspace-mcp  https://github.com/taylorwilsdon/google_workspace_mcp
-│  Python mcp-server  31 files scanned in 1.0s
-│
-├──  tool    drive_service                 ✔ ok
-├──  tool    docs_service                  ✔ ok
-├──  tool    start_google_auth             ✔ ok
-└──  tool    set_enabled_tools             ✔ ok
-│
-│  Findings (2)  static analysis — may include false positives
-├──  ● MEDIUM   Potential hardcoded secret
-│     .env.oauth21:9  SECRET="your-google-client-secret"
-└──  ● MEDIUM   Potential path traversal
-      auth/credential_store.py:123
-│
-└──  registry  LOW  Risk 10  https://agentaudit.dev/skills/google-workspace-mcp
+$ npx agentaudit discover
+
+  AgentAudit v3.3.0
+  Security scanner for AI packages
+
+•  Scanning Claude Desktop  ~/.claude/mcp.json    found 2 servers
+
+├──  fastmcp-demo       npm:fastmcp
+│    SAFE  Risk 0  ✔ official  https://agentaudit.dev/skills/fastmcp
+└──  my-tool            npm:some-mcp-tool
+     ⚠ not audited      Run: agentaudit audit https://github.com/user/some-mcp-tool
+
+  Summary  2 servers across 1 config
+
+  ✔  1 audited
+  ⚠  1 not audited
+
+  To audit unaudited servers:
+  agentaudit audit https://github.com/user/some-mcp-tool  (my-tool)
 ```
 
-**Detects:**
-- 🔴 Prompt injection & tool poisoning
-- 🔴 Shell command injection
-- 🔴 SQL injection
-- 🟡 Hardcoded secrets
-- 🟡 SSL/TLS verification disabled
-- 🟡 Path traversal
-- 🟡 Unsafe YAML/pickle deserialization
-- 🔵 Wildcard CORS
-- 🔵 Undisclosed telemetry
+---
 
-**Plus** registry lookup — shows if a package has already been officially audited on [agentaudit.dev](https://agentaudit.dev).
+## Commands
+
+| Command | What it does | Speed |
+|---------|-------------|-------|
+| `discover` | Find local MCP servers + check registry | ⚡ instant |
+| `check <name>` | Look up a package in the registry | ⚡ instant |
+| `scan <url>` | Quick static analysis (regex-based, local) | 🔵 ~2s |
+| `audit <url>` | **Deep LLM-powered security audit** | 🔴 ~30s |
+| `setup` | Register + configure API key | interactive |
+
+### `scan` vs `audit`
+
+| | `scan` | `audit` |
+|--|--------|---------|
+| **How** | Regex pattern matching | LLM 3-pass: UNDERSTAND → DETECT → CLASSIFY |
+| **Speed** | ~2 seconds | ~30 seconds |
+| **Depth** | Surface-level patterns | Semantic code understanding |
+| **Needs LLM API key** | No | Yes (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) |
+| **Uploads to registry** | No | Yes (with `agentaudit setup`) |
+
+### Examples
+
+```bash
+# Discover all MCP servers on your machine
+npx agentaudit discover
+
+# Quick static scan
+npx agentaudit scan https://github.com/owner/repo
+
+# Deep LLM-powered audit
+export ANTHROPIC_API_KEY=sk-ant-...
+npx agentaudit audit https://github.com/owner/repo
+
+# Export code + audit prompt for manual LLM review
+npx agentaudit audit https://github.com/owner/repo --export
+
+# Registry lookup
+npx agentaudit check fastmcp
+
+# Register for an API key (free)
+npx agentaudit setup
+```
 
 ---
 
 ## MCP Server
 
-Use AgentAudit as an MCP server in Claude Desktop, Cursor, Windsurf, or any MCP client. Your AI agent gets three tools:
+Add AgentAudit to your AI editor. Your agent gets 4 tools:
 
-| Tool | Description |
-|------|-------------|
-| `audit_package` | Clone a repo, return source code + audit prompt for deep LLM analysis |
-| `submit_report` | Upload completed audit report to [agentaudit.dev](https://agentaudit.dev) |
-| `check_package` | Look up a package in the registry |
+| MCP Tool | Description |
+|----------|-------------|
+| `discover_servers` | Find all locally installed MCP servers, check registry status |
+| `audit_package` | Clone a repo → return source code + audit prompt → you analyze → `submit_report` |
+| `submit_report` | Upload your audit report to [agentaudit.dev](https://agentaudit.dev) |
+| `check_package` | Quick registry lookup for a package |
 
-### Claude Desktop / Claude Code
+### Setup
 
-`~/.claude/mcp.json`:
+One-line config — works with `npx`, no manual clone needed:
+
+**Claude Desktop** (`~/.claude/mcp.json`):
 ```json
 {
   "mcpServers": {
@@ -98,9 +153,7 @@ Use AgentAudit as an MCP server in Claude Desktop, Cursor, Windsurf, or any MCP
 }
 ```
 
-### Cursor
-
-`.cursor/mcp.json`:
+**Cursor** (`.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
@@ -112,9 +165,7 @@ Use AgentAudit as an MCP server in Claude Desktop, Cursor, Windsurf, or any MCP
 }
 ```
 
-### Windsurf
-
-`~/.codeium/windsurf/mcp_config.json`:
+**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
 ```json
 {
   "mcpServers": {
@@ -126,100 +177,77 @@ Use AgentAudit as an MCP server in Claude Desktop, Cursor, Windsurf, or any MCP
 }
 ```
 
-> **That's it.** No manual clone, no path config. `npx` handles everything.
-
-### How the MCP audit works
+### How an audit works via MCP
 
 ```
-Agent calls audit_package("https://github.com/owner/repo")
-         ↓
-MCP Server clones repo, collects source files (max 300KB)
-         ↓
-Returns source code + 3-pass audit methodology
-         ↓
-Agent's LLM analyzes code (UNDERSTAND → DETECT → CLASSIFY)
-         ↓
-Agent calls submit_report(findings)
-         ↓
-Report published at agentaudit.dev/skills/{slug}
-```
-
----
-
-## Setup & Authentication
-
-```bash
-agentaudit setup
+You: "Audit the blender-mcp server"
+                ↓
+Agent calls discover_servers → finds blender-mcp
+                ↓
+Agent calls check_package("blender-mcp") → not in registry
+                ↓
+Agent calls audit_package("https://github.com/user/blender-mcp")
+                ↓
+MCP server clones repo, returns source code + audit methodology
+                ↓
+Agent's LLM analyzes code (3-pass: UNDERSTAND → DETECT → CLASSIFY)
+                ↓
+Agent calls submit_report(findings_json)
+                ↓
+Report published at agentaudit.dev/skills/blender-mcp
 ```
 
-Interactive wizard — choose:
-1. **Register new agent** (free) → API key created automatically
-2. **Enter existing API key** → if you already have one
+### Authentication
 
-Credentials are stored in `~/.config/agentaudit/credentials.json` (survives reinstalls).
+Run `npx agentaudit setup` once. Both CLI and MCP server find credentials automatically:
 
-The MCP server finds credentials automatically from:
 1. `AGENTAUDIT_API_KEY` environment variable
-2. `~/.config/agentaudit/credentials.json`
+2. `~/.config/agentaudit/credentials.json` (created by `setup`)
 
-**Scanning and checking work without a key.** Only submitting reports requires authentication.
+**`discover`, `scan`, and `check` work without a key.** Only `audit`/`submit_report` need one.
 
 ---
 
-## CLI Reference
+## What it detects
 
-```
-agentaudit discover                         Find local MCP servers + check registry
-agentaudit scan <url> [url...]              Quick static scan (regex, ~2s)
-agentaudit audit <url> [url...]             Deep LLM-powered audit (~30s)
-agentaudit check <name>                     Look up package in registry
-agentaudit setup                            Register + configure API key
-```
+### Static scan (`scan`)
 
-### `scan` vs `audit`
-
-| | `scan` | `audit` |
-|--|--------|---------|
-| **How** | Regex-based static analysis | LLM 3-pass analysis (UNDERSTAND → DETECT → CLASSIFY) |
-| **Speed** | ~2 seconds | ~30 seconds |
-| **Depth** | Pattern matching | Semantic code understanding |
-| **Needs API key** | No | Yes (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) |
-| **Upload to registry** | No | Yes (with `agentaudit setup`) |
-
-Use `scan` for quick checks, `audit` for thorough analysis.
-
-### Examples
-
-```bash
-# Discover all MCP servers on your machine
-agentaudit discover
+- 🔴 Prompt injection & tool poisoning
+- 🔴 Shell command injection
+- 🔴 SQL injection
+- 🔴 Unsafe deserialization (pickle, YAML)
+- 🟡 Hardcoded secrets
+- 🟡 SSL/TLS verification disabled
+- 🟡 Path traversal
+- 🔵 Wildcard CORS
+- 🔵 Undisclosed telemetry
 
-# Quick scan
-agentaudit scan https://github.com/jlowin/fastmcp
+### Deep audit (`audit` / MCP `audit_package`)
 
-# Deep audit (requires ANTHROPIC_API_KEY or OPENAI_API_KEY)
-agentaudit audit https://github.com/jlowin/fastmcp
+Everything above, plus:
 
-# Export audit for manual LLM review (no API key needed)
-agentaudit audit https://github.com/owner/repo --export
+- 🔴 Multi-file attack chains (credential harvest → exfiltration)
+- 🔴 Agent manipulation (impersonation, capability escalation, jailbreaks)
+- 🔴 MCP-specific: tool description injection, resource traversal, unpinned npx
+- 🟡 Persistence mechanisms (crontab, shell RC, git hooks, systemd)
+- 🟡 Obfuscation (base64 exec, zero-width chars, ANSI escapes)
+- 🟡 Context pollution & indirect prompt injection
 
-# Check registry
-agentaudit check mongodb-mcp-server
-```
+50+ detection patterns across 8 categories. [Full pattern list →](https://github.com/starbuck100/agentaudit-skill)
 
 ---
 
 ## Requirements
 
 - **Node.js 18+**
-- **Git** (for cloning repos during scan)
+- **Git** (for cloning repos)
 
 ---
 
 ## Related
 
-- [agentaudit.dev](https://agentaudit.dev) — Trust registry & audit reports
-- [agentaudit-skill](https://github.com/starbuck100/agentaudit-skill) — Full agent skill with gate scripts, detection patterns & peer review
+- **[agentaudit.dev](https://agentaudit.dev)** — Trust registry with 400+ audit reports
+- **[agentaudit-skill](https://github.com/starbuck100/agentaudit-skill)** — Full agent skill with gate scripts, detection patterns & peer review system
 
 ---
 

package/cli.mjs

@@ -157,17 +157,26 @@ async function setupCommand() {
 
   console.log();
   console.log(`  ${c.bold}Ready!${c.reset} You can now:`);
-  console.log(`  ${c.dim}•${c.reset} Scan packages:  ${c.cyan}agentaudit scan <repo-url>${c.reset}`);
-  console.log(`  ${c.dim}•${c.reset} Check registry:  ${c.cyan}agentaudit check <name>${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Discover servers: ${c.cyan}agentaudit discover${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Audit packages:   ${c.cyan}agentaudit audit <repo-url>${c.reset}  ${c.dim}(deep LLM analysis)${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Quick scan:        ${c.cyan}agentaudit scan <repo-url>${c.reset}  ${c.dim}(regex-based)${c.reset}`);
+  console.log(`  ${c.dim}•${c.reset} Check registry:    ${c.cyan}agentaudit check <name>${c.reset}`);
   console.log(`  ${c.dim}•${c.reset} Submit reports via MCP in Claude/Cursor/Windsurf`);
   console.log();
 }
 
 // ── Helpers ──────────────────────────────────────────────
 
+function getVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch { return '0.0.0'; }
+}
+
 function banner() {
   console.log();
-  console.log(`  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v1.0.0${c.reset}`);
+  console.log(`  ${c.bold}${c.cyan}AgentAudit${c.reset} ${c.dim}v${getVersion()}${c.reset}`);
   console.log(`  ${c.dim}Security scanner for AI packages${c.reset}`);
   console.log();
 }
@@ -705,6 +714,48 @@ function serverSlug(server) {
   return server.name.toLowerCase().replace(/[^a-z0-9-]/gi, '-');
 }
 
+async function resolveSourceUrl(server) {
+  // Already have it
+  if (server.sourceUrl) return server.sourceUrl;
+  
+  // Try npm registry
+  if (server.npmPackage) {
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(server.npmPackage)}`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        let repoUrl = data.repository?.url;
+        if (repoUrl) {
+          repoUrl = repoUrl.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^ssh:\/\/git@github\.com/, 'https://github.com');
+          if (repoUrl.startsWith('http')) return repoUrl;
+        }
+      }
+    } catch {}
+    // Fallback: npm page
+    return `https://www.npmjs.com/package/${server.npmPackage}`;
+  }
+  
+  // Try PyPI
+  if (server.pyPackage) {
+    try {
+      const res = await fetch(`https://pypi.org/pypi/${encodeURIComponent(server.pyPackage)}/json`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const urls = data.info?.project_urls || {};
+        const source = urls.Source || urls.Repository || urls.Homepage || urls['Source Code'] || data.info?.home_page;
+        if (source && source.startsWith('http')) return source;
+      }
+    } catch {}
+    return `https://pypi.org/project/${server.pyPackage}/`;
+  }
+  
+  return null;
+}
+
 async function discoverCommand() {
   console.log(`  ${c.bold}Discovering local MCP servers...${c.reset}`);
   console.log();
@@ -728,6 +779,7 @@ async function discoverCommand() {
   let checkedServers = 0;
   let auditedServers = 0;
   let unauditedServers = 0;
+  const unauditedWithUrls = [];
   
   for (const config of configs) {
     const servers = extractServersFromConfig(config.content);
@@ -779,11 +831,18 @@ async function discoverCommand() {
         console.log(`${pipe}  ${riskBadge(riskScore)} Risk ${riskScore}  ${hasOfficial ? `${c.green}✔ official${c.reset}  ` : ''}${c.dim}${REGISTRY_URL}/skills/${slug}${c.reset}`);
       } else {
         unauditedServers++;
+        // Resolve source URL
+        const resolvedUrl = await resolveSourceUrl(server);
         console.log(`${branch}  ${c.bold}${server.name}${c.reset}    ${sourceLabel}`);
-        console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Run: agentaudit audit <source-url>${c.reset}`);
+        if (resolvedUrl) {
+          console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Run: ${c.cyan}agentaudit audit ${resolvedUrl}${c.reset}`);
+          unauditedWithUrls.push({ name: server.name, sourceUrl: resolvedUrl });
+        } else {
+          console.log(`${pipe}  ${c.yellow}⚠ not audited${c.reset}  ${c.dim}Source URL unknown — check the package's GitHub/npm page${c.reset}`);
+        }
       }
       
-      if (server.sourceUrl) {
+      if (server.sourceUrl && !server.sourceUrl.includes('npmjs.com')) {
         console.log(`${pipe}  ${c.dim}source: ${server.sourceUrl}${c.reset}`);
       }
     }
@@ -800,8 +859,15 @@ async function discoverCommand() {
   console.log();
   
   if (unauditedServers > 0) {
-    console.log(`  ${c.dim}To audit unaudited servers, run:${c.reset}`);
-    console.log(`  ${c.cyan}agentaudit scan <github-url>${c.reset}`);
+    if (unauditedWithUrls.length > 0) {
+      console.log(`  ${c.dim}To audit unaudited servers:${c.reset}`);
+      for (const { name, sourceUrl } of unauditedWithUrls) {
+        console.log(`  ${c.cyan}agentaudit audit ${sourceUrl}${c.reset}  ${c.dim}(${name})${c.reset}`);
+      }
+    } else {
+      console.log(`  ${c.dim}To audit unaudited servers, run:${c.reset}`);
+      console.log(`  ${c.cyan}agentaudit audit <source-url>${c.reset}`);
+    }
     console.log();
   }
 }
@@ -857,15 +923,28 @@ async function auditRepo(url) {
   const openaiKey = process.env.OPENAI_API_KEY;
   
   if (!anthropicKey && !openaiKey) {
-    // No LLM API key — output the prepared audit for piping or MCP use
+    // No LLM API key — clear explanation
+    console.log();
+    console.log(`  ${c.yellow}No LLM API key found.${c.reset} The ${c.bold}audit${c.reset} command needs an LLM to analyze code.`);
+    console.log();
+    console.log(`  ${c.bold}Option 1: Set an API key${c.reset}`);
+    console.log(`  Supported keys: ${c.cyan}ANTHROPIC_API_KEY${c.reset} or ${c.cyan}OPENAI_API_KEY${c.reset}`);
+    console.log();
+    console.log(`  ${c.dim}# Linux / macOS:${c.reset}`);
+    console.log(`  ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
+    console.log(`  ${c.dim}export OPENAI_API_KEY=sk-...${c.reset}`);
+    console.log();
+    console.log(`  ${c.dim}# Windows (PowerShell):${c.reset}`);
+    console.log(`  ${c.dim}$env:ANTHROPIC_API_KEY = "sk-ant-..."${c.reset}`);
+    console.log(`  ${c.dim}$env:OPENAI_API_KEY = "sk-..."${c.reset}`);
     console.log();
-    console.log(`  ${c.yellow}No LLM API key found.${c.reset} To run the audit automatically, set one of:`);
-    console.log(`    ${c.dim}export ANTHROPIC_API_KEY=sk-ant-...${c.reset}`);
-    console.log(`    ${c.dim}export OPENAI_API_KEY=sk-...${c.reset}`);
+    console.log(`  ${c.bold}Option 2: Export for manual review${c.reset}`);
+    console.log(`  ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
+    console.log(`  ${c.dim}Creates a markdown file you can paste into any LLM (Claude, ChatGPT, etc.)${c.reset}`);
     console.log();
-    console.log(`  ${c.bold}Alternatives:${c.reset}`);
-    console.log(`    ${c.dim}1.${c.reset} Use the MCP server in Claude/Cursor — your agent runs the audit automatically`);
-    console.log(`    ${c.dim}2.${c.reset} Export for manual review: ${c.cyan}agentaudit audit ${url} --export${c.reset}`);
+    console.log(`  ${c.bold}Option 3: Use MCP in Claude/Cursor/Windsurf (no API key needed)${c.reset}`);
+    console.log(`  ${c.dim}Add AgentAudit as MCP server — your editor's agent runs the audit using its own LLM.${c.reset}`);
+    console.log(`  ${c.dim}Config: { "mcpServers": { "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } } }${c.reset}`);
     console.log();
     
     // Check if --export flag

package/index.mjs

@@ -2,25 +2,20 @@
 /**
  * AgentAudit MCP Server
  * 
- * Provides security audit capabilities via Model Context Protocol.
+ * Security audit capabilities via Model Context Protocol.
  * 
  * Tools:
- *   - audit_package: Clone a repo, read source files, return with audit prompt
- *   - submit_report: Upload a completed audit report to agentaudit.dev
- *   - check_package: Look up a package in the AgentAudit registry
+ *   - discover_servers  Find locally installed MCP servers + check registry status
+ *   - audit_package     Clone a repo, return source code + audit prompt for LLM analysis
+ *   - submit_report     Upload a completed audit report to agentaudit.dev
+ *   - check_package     Look up a package in the AgentAudit registry
  * 
  * Usage:
- *   node mcp-server/index.mjs
+ *   npx agentaudit                (starts MCP server via stdio)
+ *   node index.mjs                (same)
  * 
- * Configure in Claude/Cursor/etc:
- *   {
- *     "mcpServers": {
- *       "agentaudit": {
- *         "command": "node",
- *         "args": ["path/to/agentaudit/mcp-server/index.mjs"]
- *       }
- *     }
- *   }
+ * Configure in Claude/Cursor/Windsurf:
+ *   { "mcpServers": { "agentaudit": { "command": "npx", "args": ["-y", "agentaudit"] } } }
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -37,8 +32,8 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_DIR = path.resolve(__dirname);
 const REGISTRY_URL = 'https://agentaudit.dev';
-const MAX_FILE_SIZE = 50_000; // 50KB per file
-const MAX_TOTAL_SIZE = 300_000; // 300KB total code
+const MAX_FILE_SIZE = 50_000;
+const MAX_TOTAL_SIZE = 300_000;
 const SKIP_DIRS = new Set([
   'node_modules', '.git', '__pycache__', '.venv', 'venv', 'dist', 'build',
   '.next', '.nuxt', 'coverage', '.pytest_cache', '.mypy_cache', 'vendor',
@@ -61,7 +56,7 @@ const PRIORITY_FILES = [
   'Makefile', 'Dockerfile', 'docker-compose.yml',
 ];
 
-// ── Helpers ──────────────────────────────────────────────
+// ── Credentials ─────────────────────────────────────────
 
 function loadApiKey() {
   if (process.env.AGENTAUDIT_API_KEY) return process.env.AGENTAUDIT_API_KEY;
@@ -84,39 +79,32 @@ function loadApiKey() {
 
 function loadAuditPrompt() {
   const promptPath = path.join(SKILL_DIR, 'prompts', 'audit-prompt.md');
-  if (fs.existsSync(promptPath)) {
-    return fs.readFileSync(promptPath, 'utf8');
-  }
+  if (fs.existsSync(promptPath)) return fs.readFileSync(promptPath, 'utf8');
   return 'ERROR: audit-prompt.md not found at ' + promptPath;
 }
 
+// ── File Collection ─────────────────────────────────────
+
 function collectFiles(dir, basePath = '', collected = [], totalSize = { bytes: 0 }) {
   if (totalSize.bytes >= MAX_TOTAL_SIZE) return collected;
-  
   let entries;
   try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
   catch { return collected; }
-  
-  // Sort: priority files first
   entries.sort((a, b) => {
     const aP = PRIORITY_FILES.includes(a.name) ? 0 : 1;
     const bP = PRIORITY_FILES.includes(b.name) ? 0 : 1;
     return aP - bP || a.name.localeCompare(b.name);
   });
-  
   for (const entry of entries) {
     if (totalSize.bytes >= MAX_TOTAL_SIZE) break;
-    
     const relPath = basePath ? `${basePath}/${entry.name}` : entry.name;
     const fullPath = path.join(dir, entry.name);
-    
     if (entry.isDirectory()) {
       if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
       collectFiles(fullPath, relPath, collected, totalSize);
     } else {
       const ext = path.extname(entry.name).toLowerCase();
       if (SKIP_EXTENSIONS.has(ext)) continue;
-      
       try {
         const stat = fs.statSync(fullPath);
         if (stat.size > MAX_FILE_SIZE) {
@@ -124,24 +112,22 @@ function collectFiles(dir, basePath = '', collected = [], totalSize = { bytes: 0
           continue;
         }
         if (stat.size === 0) continue;
-        
         const content = fs.readFileSync(fullPath, 'utf8');
         totalSize.bytes += content.length;
         collected.push({ path: relPath, content });
-      } catch {
-        // Binary or unreadable — skip
-      }
+      } catch {}
     }
   }
   return collected;
 }
 
+// ── Repo Helpers ────────────────────────────────────────
+
 function cloneRepo(sourceUrl) {
   const tmpDir = fs.mkdtempSync('/tmp/agentaudit-');
   try {
     execSync(`git clone --depth 1 "${sourceUrl}" "${tmpDir}/repo" 2>/dev/null`, {
-      timeout: 30_000,
-      stdio: 'pipe',
+      timeout: 30_000, stdio: 'pipe',
     });
     return path.join(tmpDir, 'repo');
   } catch (err) {
@@ -150,30 +136,129 @@ function cloneRepo(sourceUrl) {
 }
 
 function cleanupRepo(repoPath) {
-  try {
-    execSync(`rm -rf "${path.dirname(repoPath)}"`, { stdio: 'pipe' });
-  } catch {}
+  try { execSync(`rm -rf "${path.dirname(repoPath)}"`, { stdio: 'pipe' }); } catch {}
 }
 
 function slugFromUrl(url) {
-  // https://github.com/owner/repo → owner-repo or just repo
   const match = url.match(/github\.com\/([^/]+)\/([^/.\s]+)/);
   if (match) return match[2].toLowerCase().replace(/[^a-z0-9-]/g, '-');
   return url.replace(/[^a-z0-9]/gi, '-').toLowerCase().slice(0, 60);
 }
 
+// ── Discover local MCP configs ──────────────────────────
+
+function discoverMcpServers() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const candidates = [
+    { platform: 'Claude Desktop', path: path.join(home, '.claude', 'mcp.json') },
+    { platform: 'Claude Desktop', path: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json') },
+    { platform: 'Claude Desktop', path: path.join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json') },
+    { platform: 'Claude Desktop', path: path.join(home, '.config', 'claude', 'claude_desktop_config.json') },
+    { platform: 'Cursor', path: path.join(home, '.cursor', 'mcp.json') },
+    { platform: 'Windsurf', path: path.join(home, '.codeium', 'windsurf', 'mcp_config.json') },
+    { platform: 'VS Code', path: path.join(home, '.vscode', 'mcp.json') },
+  ];
+
+  const results = [];
+
+  for (const c of candidates) {
+    if (!fs.existsSync(c.path)) {
+      results.push({ platform: c.platform, config_path: c.path, status: 'not found', servers: [] });
+      continue;
+    }
+    let content;
+    try { content = JSON.parse(fs.readFileSync(c.path, 'utf8')); }
+    catch { results.push({ platform: c.platform, config_path: c.path, status: 'parse error', servers: [] }); continue; }
+
+    const serverMap = content.mcpServers || content.servers || {};
+    const servers = [];
+    for (const [name, cfg] of Object.entries(serverMap)) {
+      const allArgs = [cfg.command, ...(cfg.args || [])].filter(Boolean).join(' ');
+      const npxMatch = allArgs.match(/npx\s+(?:-y\s+)?(@?[a-z0-9][\w./-]*)/i);
+      const pyMatch = allArgs.match(/(?:uvx|pip run|python -m)\s+(@?[a-z0-9][\w./-]*)/i);
+      servers.push({
+        name,
+        command: cfg.command || null,
+        args: cfg.args || [],
+        npm_package: npxMatch?.[1] || null,
+        pip_package: pyMatch?.[1] || null,
+      });
+    }
+    results.push({ platform: c.platform, config_path: c.path, status: 'found', server_count: servers.length, servers });
+  }
+
+  return results;
+}
+
+async function resolveSourceUrl(server) {
+  if (server.npm_package) {
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(server.npm_package)}`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        let repoUrl = data.repository?.url;
+        if (repoUrl) {
+          repoUrl = repoUrl.replace(/^git\+/, '').replace(/\.git$/, '').replace(/^ssh:\/\/git@github\.com/, 'https://github.com');
+          if (repoUrl.startsWith('http')) return repoUrl;
+        }
+      }
+    } catch {}
+    return `https://www.npmjs.com/package/${server.npm_package}`;
+  }
+  if (server.pip_package) {
+    try {
+      const res = await fetch(`https://pypi.org/pypi/${encodeURIComponent(server.pip_package)}/json`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      if (res.ok) {
+        const data = await res.json();
+        const urls = data.info?.project_urls || {};
+        const source = urls.Source || urls.Repository || urls.Homepage || urls['Source Code'] || data.info?.home_page;
+        if (source && source.startsWith('http')) return source;
+      }
+    } catch {}
+    return `https://pypi.org/project/${server.pip_package}/`;
+  }
+  return null;
+}
+
+async function checkRegistry(slug) {
+  try {
+    const res = await fetch(`${REGISTRY_URL}/api/skills/${encodeURIComponent(slug)}`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.ok) return await res.json();
+  } catch {}
+  return null;
+}
+
 // ── MCP Server ───────────────────────────────────────────
 
 const server = new Server(
-  { name: 'agentaudit', version: '1.0.0' },
+  { name: 'agentaudit', version: '3.2.0' },
   { capabilities: { tools: {} } }
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    {
+      name: 'discover_servers',
+      description: 'Find all locally installed MCP servers by scanning config files (Claude Desktop, Cursor, Windsurf, VS Code). Returns the list of configured servers with their names, commands, and package sources. Use this to see what MCP servers are installed, then check each against the registry with check_package, or audit them with audit_package.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          check_registry: {
+            type: 'boolean',
+            description: 'If true, also check each discovered server against the AgentAudit registry (default: true)',
+          },
+        },
+      },
+    },
     {
       name: 'audit_package',
-      description: 'Clone a repository and prepare it for security audit. Returns the source code and audit instructions. You (the agent) then analyze the code following the audit prompt and call submit_report with the results.',
+      description: 'Deep security audit: clone a repository and prepare it for LLM-powered analysis. Returns the source code and a 3-pass audit methodology (UNDERSTAND → DETECT → CLASSIFY). You (the agent) then analyze the code following the instructions and call submit_report with your findings. This is a DEEP audit — use check_package first for a quick registry lookup.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -187,13 +272,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'submit_report',
-      description: 'Submit a completed security audit report to the AgentAudit registry (agentaudit.dev). Call this after you have analyzed the code from audit_package.',
+      description: 'Submit a completed security audit report to the AgentAudit registry (agentaudit.dev). Call this after you have analyzed the code from audit_package. The report becomes publicly available and helps other agents make install decisions.',
       inputSchema: {
         type: 'object',
         properties: {
           report: {
             type: 'object',
-            description: 'The audit report JSON object. Must include: skill_slug, source_url, risk_score (0-100), result (safe|caution|unsafe), findings (array), findings_count, max_severity.',
+            description: 'The audit report JSON object. Required fields: skill_slug, source_url, risk_score (0-100), result (safe|caution|unsafe), findings (array), findings_count, max_severity, package_type.',
           },
         },
         required: ['report'],
@@ -201,7 +286,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'check_package',
-      description: 'Look up a package in the AgentAudit security registry. Returns the latest audit results if available.',
+      description: 'Quick registry lookup: check if a package has already been audited on agentaudit.dev. Returns the latest audit results (risk score, findings, official status) if available. Use this before audit_package to avoid duplicate work.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -218,39 +303,106 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  
+
   switch (name) {
+
+    // ── discover_servers ──────────────────────────────────
+    case 'discover_servers': {
+      const doRegistryCheck = args.check_registry !== false;
+      const configs = discoverMcpServers();
+      const foundConfigs = configs.filter(c => c.status === 'found');
+      const allServers = foundConfigs.flatMap(c => c.servers.map(s => ({ ...s, platform: c.platform })));
+
+      let text = `# Discovered MCP Servers\n\n`;
+      text += `Scanned ${configs.length} config locations. Found ${foundConfigs.length} config(s) with ${allServers.length} server(s).\n\n`;
+
+      for (const config of configs) {
+        if (config.status === 'not found') continue;
+        text += `## ${config.platform}\n`;
+        text += `Config: \`${config.config_path}\`\n\n`;
+
+        if (config.servers.length === 0) {
+          text += `No servers configured.\n\n`;
+          continue;
+        }
+
+        for (const srv of config.servers) {
+          const slug = srv.npm_package?.replace(/^@/, '').replace(/\//g, '-')
+            || srv.pip_package?.replace(/[^a-z0-9-]/gi, '-')
+            || srv.name.toLowerCase().replace(/[^a-z0-9-]/gi, '-');
+
+          text += `### ${srv.name}\n`;
+          text += `- Command: \`${[srv.command, ...srv.args].join(' ')}\`\n`;
+          if (srv.npm_package) text += `- npm: ${srv.npm_package}\n`;
+          if (srv.pip_package) text += `- pip: ${srv.pip_package}\n`;
+
+          if (doRegistryCheck) {
+            const regData = await checkRegistry(slug);
+            if (regData) {
+              const risk = regData.risk_score ?? regData.latest_risk_score ?? 0;
+              const official = regData.has_official_audit ? ' (official)' : '';
+              text += `- **Registry: ✅ Audited** — Risk ${risk}/100${official}\n`;
+              text += `- Report: ${REGISTRY_URL}/skills/${slug}\n`;
+            } else {
+              const sourceUrl = await resolveSourceUrl(srv);
+              text += `- **Registry: ⚠️ Not audited** — no audit report found\n`;
+              if (sourceUrl) {
+                text += `- Source: ${sourceUrl}\n`;
+                text += `- To audit: call \`audit_package\` with source_url \`${sourceUrl}\`\n`;
+              } else {
+                text += `- Source URL unknown — check the package's GitHub/npm page\n`;
+                text += `- To audit: find the source URL, then call \`audit_package\`\n`;
+              }
+            }
+          }
+          text += `\n`;
+        }
+      }
+
+      if (allServers.length === 0) {
+        text += `No MCP servers found. Config locations searched:\n`;
+        text += `- Claude Desktop: ~/.claude/mcp.json\n`;
+        text += `- Cursor: ~/.cursor/mcp.json\n`;
+        text += `- Windsurf: ~/.codeium/windsurf/mcp_config.json\n`;
+        text += `- VS Code: ~/.vscode/mcp.json\n`;
+      }
+
+      return { content: [{ type: 'text', text }] };
+    }
+
+    // ── audit_package ─────────────────────────────────────
     case 'audit_package': {
       const { source_url } = args;
       if (!source_url || !source_url.startsWith('http')) {
         return { content: [{ type: 'text', text: 'Error: source_url must be a valid HTTP(S) URL' }] };
       }
-      
+
       let repoPath;
       try {
         repoPath = cloneRepo(source_url);
         const files = collectFiles(repoPath);
         const slug = slugFromUrl(source_url);
         const auditPrompt = loadAuditPrompt();
-        
-        // Build the response
+
         let codeBlock = '';
         for (const file of files) {
           codeBlock += `\n### FILE: ${file.path}\n\`\`\`\n${file.content}\n\`\`\`\n`;
         }
-        
+
         const response = [
-          `# Security Audit Request`,
+          `# Security Audit: ${slug}`,
           ``,
-          `**Package:** ${slug}`,
           `**Source:** ${source_url}`,
           `**Files collected:** ${files.length}`,
           ``,
-          `## Instructions`,
+          `## Your Task`,
           ``,
-          `Analyze the source code below following the audit methodology. After your analysis, call the \`submit_report\` tool with your findings as a JSON object.`,
+          `1. Analyze the source code below using the 3-pass audit methodology`,
+          `2. Call \`submit_report\` with your findings as JSON`,
           ``,
-          `The report JSON must include:`,
+          `## Report Format`,
+          ``,
+          `Your report JSON must include:`,
           '```json',
           `{`,
           `  "skill_slug": "${slug}",`,
@@ -285,7 +437,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           ``,
           codeBlock,
         ].join('\n');
-        
+
         return { content: [{ type: 'text', text: response }] };
       } catch (err) {
         return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
@@ -293,27 +445,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (repoPath) cleanupRepo(repoPath);
       }
     }
-    
+
+    // ── submit_report ─────────────────────────────────────
     case 'submit_report': {
       const { report } = args;
       if (!report || typeof report !== 'object') {
         return { content: [{ type: 'text', text: 'Error: report must be a JSON object' }] };
       }
-      
+
       const apiKey = loadApiKey();
       if (!apiKey) {
-        return { content: [{ type: 'text', text: 'Error: No API key configured. Set AGENTAUDIT_API_KEY or register first.' }] };
+        return { content: [{ type: 'text', text: 'Error: No API key configured. Run `npx agentaudit setup` or set AGENTAUDIT_API_KEY.' }] };
       }
-      
-      // Validate required fields
+
       const required = ['skill_slug', 'source_url', 'risk_score', 'result'];
       for (const field of required) {
         if (report[field] == null) {
           return { content: [{ type: 'text', text: `Error: Missing required field "${field}" in report` }] };
         }
       }
-      
-      // Auto-fix findings
+
       if (!Array.isArray(report.findings)) report.findings = [];
       report.findings_count = report.findings.length;
       if (!report.max_severity) {
@@ -324,7 +475,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           return fi < mi ? f.severity : max;
         }, 'none');
       }
-      
+
       try {
         const res = await fetch(`${REGISTRY_URL}/api/reports`, {
           method: 'POST',
@@ -335,13 +486,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           body: JSON.stringify(report),
           signal: AbortSignal.timeout(60_000),
         });
-        
+
         const body = await res.text();
         let data;
         try { data = JSON.parse(body); } catch { data = { raw: body }; }
-        
+
         if (res.ok) {
-          return { content: [{ type: 'text', text: `Report submitted successfully!\nReport ID: ${data.report_id || 'unknown'}\nURL: ${REGISTRY_URL}/skills/${report.skill_slug}\n\n${JSON.stringify(data, null, 2)}` }] };
+          return { content: [{ type: 'text', text: `✅ Report submitted!\n\nReport ID: ${data.report_id || 'unknown'}\nURL: ${REGISTRY_URL}/skills/${report.skill_slug}\nRisk: ${report.risk_score}/100 (${report.result})\nFindings: ${report.findings_count}` }] };
         } else {
           return { content: [{ type: 'text', text: `Upload failed (HTTP ${res.status}): ${JSON.stringify(data, null, 2)}` }] };
         }
@@ -349,31 +500,42 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return { content: [{ type: 'text', text: `Upload error: ${err.message}` }] };
       }
     }
-    
+
+    // ── check_package ─────────────────────────────────────
     case 'check_package': {
       const { package_name } = args;
       if (!package_name) {
         return { content: [{ type: 'text', text: 'Error: package_name is required' }] };
       }
-      
+
       try {
         const res = await fetch(`${REGISTRY_URL}/api/skills/${encodeURIComponent(package_name)}`, {
           signal: AbortSignal.timeout(10_000),
         });
-        
+
         if (res.status === 404) {
-          return { content: [{ type: 'text', text: `Package "${package_name}" not found in registry. It may not have been audited yet. Use audit_package to audit it.` }] };
+          return { content: [{ type: 'text', text: `Package "${package_name}" not found in registry.\n\nIt hasn't been audited yet. To audit it:\n1. Find the source URL (GitHub repo)\n2. Call audit_package with the URL\n3. Analyze the code\n4. Call submit_report with your findings` }] };
         }
-        
+
         const data = await res.json();
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        const risk = data.risk_score ?? data.latest_risk_score ?? 'unknown';
+        const official = data.has_official_audit ? '✅ Officially audited' : 'Community audit';
+
+        let summary = `# ${package_name}\n\n`;
+        summary += `**Risk Score:** ${risk}/100\n`;
+        summary += `**Status:** ${official}\n`;
+        if (data.source_url) summary += `**Source:** ${data.source_url}\n`;
+        summary += `**Registry:** ${REGISTRY_URL}/skills/${package_name}\n\n`;
+        summary += `## Full Data\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\``;
+
+        return { content: [{ type: 'text', text: summary }] };
       } catch (err) {
         return { content: [{ type: 'text', text: `Registry lookup failed: ${err.message}` }] };
       }
     }
-    
+
     default:
-      return { content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+      return { content: [{ type: 'text', text: `Unknown tool: ${name}. Available: discover_servers, audit_package, submit_report, check_package` }] };
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentaudit",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Security scanner for AI packages — MCP server + CLI",
   "type": "module",
   "bin": {