@fino314-oss/contract-scanner-mcp 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# Contract Security Scanner — MCP Server
+
+Scan any Base L2 smart contract for security risks directly from your AI assistant.
+
+**3 tools exposed:**
+- `scan_contract` — Full security scan (source verification, risky selectors, age, activity)
+- `batch_scan` — Compare up to 5 contracts side by side
+- `interpret_risk` — Get an actionable recommendation (SAFE / CAUTION / HIGH_RISK / DO_NOT_USE)
+
+**Risk score: 0-100.** Analyzes: mint/blacklist/backdoor functions, proxy patterns, source verification, contract age, transaction activity.
+
+---
+
+## Installation
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "contract-scanner": {
+      "command": "node",
+      "args": ["/Users/sam/Desktop/samDev/p8/mcp/server.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools appear automatically.
+
+---
+
+### Cursor
+
+Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "contract-scanner": {
+      "command": "node",
+      "args": ["/Users/sam/Desktop/samDev/p8/mcp/server.js"]
+    }
+  }
+}
+```
+
+---
+
+### Cline (VS Code extension)
+
+1. Open Cline settings → MCP Servers → Add server
+2. Set type: `stdio`
+3. Command: `node /Users/sam/Desktop/samDev/p8/mcp/server.js`
+
+---
+
+### Any MCP client (generic)
+
+The server uses **stdio transport** — just pipe JSON-RPC messages:
+
+```bash
+node /Users/sam/Desktop/samDev/p8/mcp/server.js
+```
+
+---
+
+## Usage examples
+
+Once connected, just ask your AI assistant naturally:
+
+```
+"Scan this contract before I approve: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+
+"Compare the risk of these 3 Aave clones: 0x... 0x... 0x..."
+
+"Is this token safe to buy? 0x4ed4e862860bed51a9570b96d89af5e1b0efefed"
+```
+
+---
+
+## What gets analyzed
+
+| Check | Source |
+|-------|--------|
+| Source code verified? | BaseScan API |
+| Mint / burn functions | Bytecode selector scan |
+| Pause / freeze | Bytecode selector scan |
+| Blacklist / whitelist | Bytecode selector scan |
+| Backdoors (rescueTokens, withdrawAll) | Bytecode selector scan |
+| Upgradeable proxy | BaseScan + delegatecall detection |
+| Contract age | BaseScan transaction history |
+| Activity level | BaseScan recent txs |
+
+---
+
+## Risk scoring
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0-9 | SAFE | No red flags |
+| 10-29 | LOW | Minor concerns |
+| 30-49 | MEDIUM | Elevated risk — review before interacting |
+| 50-69 | HIGH | Significant risk — small amounts only |
+| 70+ | CRITICAL | Avoid — potential rug or backdoor |
+
+---
+
+## Technical notes
+
+- **Chain**: Base L2 only (`https://mainnet.base.org`)
+- **API**: BaseScan free tier (no key needed for basic checks; set `BASESCAN_API_KEY` env var for full source analysis)
+- **No wallet needed**: read-only RPC calls only
+- **Latency**: ~2-5s per contract (network dependent)
+
+---
+
+*Built on Base. Agent wallet: `0x804dd2cE4aA3296831c880139040e4326df13c6e`*

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@fino314-oss/contract-scanner-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.fino-oss/contract-scanner",
+  "description": "MCP server that scans Base L2 smart contracts for security risks. Detects mint/blacklist/backdoor/proxy patterns. Risk score 0-100.",
+  "type": "module",
+  "main": "server.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fino-oss/contract-scanner-mcp.git"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "inspect": "npx @modelcontextprotocol/inspector node server.js"
+  },
+  "keywords": ["mcp", "blockchain", "security", "base", "solidity", "smart-contracts", "defi"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ethers": "^6.0.0",
+    "zod": "^3.0.0"
+  }
+}

package/scanner.js

@@ -0,0 +1,447 @@
+/**
+ * scanner.js — Contract Security Scanner
+ *
+ * Analyzes an EVM contract address and returns a risk score + findings.
+ * Uses: Base RPC (free) + Etherscan API (free tier, 100k/day)
+ *
+ * Usage:
+ *   node research/scanner.js <contractAddress>
+ *   node research/scanner.js 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+ */
+
+import { ethers } from 'ethers';
+import { createHash } from 'crypto';
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const BASE_RPC         = 'https://mainnet.base.org';
+const ETHERSCAN_BASE   = 'https://api.etherscan.io/v2/api'; // V2 endpoint (chain-agnostic)
+const ETHERSCAN_CHAIN  = '8453'; // Base L2 chain ID
+const ETHERSCAN_KEY    = process.env.BASESCAN_API_KEY || 'YourApiKeyToken';
+
+const provider = new ethers.JsonRpcProvider(BASE_RPC);
+
+// ─── Known Risk Patterns in Bytecode ─────────────────────────────────────────
+
+// Solidity function selectors for risky functions
+const RISKY_SELECTORS = {
+  // Ownership / control
+  'f2fde38b': { name: 'transferOwnership(address)',  severity: 'info',   label: 'transferOwnership' },
+  '715018a6': { name: 'renounceOwnership()',         severity: 'good',   label: 'renounceOwnership' },
+  'e30c3978': { name: 'pendingOwner()',              severity: 'info',   label: 'pendingOwner' },
+
+  // Minting / supply control
+  '40c10f19': { name: 'mint(address,uint256)',       severity: 'high',   label: 'mint' },
+  'a0712d68': { name: 'mint(uint256)',               severity: 'high',   label: 'mint' },
+  '1249c58b': { name: 'mint()',                      severity: 'high',   label: 'mint' },
+  '4e6ec247': { name: 'mintTokens(address,uint256)', severity: 'high',   label: 'mint' },
+
+  // Pause / freeze
+  '8456cb59': { name: 'pause()',                     severity: 'medium', label: 'pause' },
+  '3f4ba83a': { name: 'unpause()',                   severity: 'medium', label: 'unpause' },
+  'bedb86fb': { name: 'pause(bool)',                 severity: 'medium', label: 'pause' },
+
+  // Blacklist / whitelist
+  'f9f92be4': { name: 'blacklist(address)',           severity: 'high',   label: 'blacklist' },
+  '1a895266': { name: 'blacklist(address,bool)',      severity: 'high',   label: 'blacklist' },
+  '42966c68': { name: 'burn(uint256)',                severity: 'info',   label: 'burn' },
+  '79cc6790': { name: 'burnFrom(address,uint256)',    severity: 'info',   label: 'burnFrom' },
+
+  // Fee manipulation
+  '518ab2a8': { name: 'setFee(uint256)',              severity: 'medium', label: 'setFee' },
+  '3d3e3c6f': { name: 'setTaxFee(uint256)',           severity: 'medium', label: 'setTaxFee' },
+
+  // Hidden backdoors (common in rugs)
+  'e0f7392b': { name: 'rescueTokens()',              severity: 'critical', label: 'rescueTokens' },
+  'f1b9e7d8': { name: 'withdrawAll()',               severity: 'critical', label: 'withdrawAll' },
+};
+
+// ERC20 standard selectors (good signs)
+const ERC20_SELECTORS = ['18160ddd', 'dd62ed3e', '095ea7b3', '23b872dd', 'a9059cbb', '70a08231'];
+
+// Proxy patterns (bytecode starts with these)
+const PROXY_PATTERNS = [
+  { prefix: '3d602d', label: 'EIP-1167 Minimal Proxy (Clone)' },
+  { prefix: '6080604052', label: 'Standard Contract (not a proxy)' }, // not a proxy
+  { prefix: '363d3d373d3d3d363d73', label: 'EIP-1167 Minimal Proxy' },
+];
+
+// ─── Etherscan API helpers ────────────────────────────────────────────────────
+
+async function fetchEtherscan(params) {
+  const url = new URL(ETHERSCAN_BASE);
+  url.searchParams.set('chainid', ETHERSCAN_CHAIN);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  url.searchParams.set('apikey', ETHERSCAN_KEY);
+
+  try {
+    const res = await fetch(url.toString());
+    const data = await res.json();
+    if (data.status === '1') return data.result;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function getContractSource(address) {
+  return fetchEtherscan({
+    module: 'contract',
+    action: 'getsourcecode',
+    address,
+  });
+}
+
+async function getContractABI(address) {
+  return fetchEtherscan({
+    module: 'contract',
+    action: 'getabi',
+    address,
+  });
+}
+
+async function getTxCount(address) {
+  const result = await fetchEtherscan({
+    module: 'account',
+    action: 'txlist',
+    address,
+    startblock: 0,
+    endblock: 99999999,
+    page: 1,
+    offset: 10,
+    sort: 'desc',
+  });
+  return result ? result.length : 0;
+}
+
+// ─── Analysis functions ───────────────────────────────────────────────────────
+
+function analyzeSelectors(bytecode) {
+  const found = [];
+  const hex = bytecode.toLowerCase().slice(2); // remove 0x
+
+  for (const [selector, info] of Object.entries(RISKY_SELECTORS)) {
+    if (hex.includes(selector)) {
+      found.push({ selector, ...info });
+    }
+  }
+
+  // Check ERC20 compliance
+  const erc20Count = ERC20_SELECTORS.filter(s => hex.includes(s)).length;
+  const isERC20 = erc20Count >= 4;
+
+  return { found, isERC20, erc20Count };
+}
+
+function detectProxy(bytecode) {
+  const hex = bytecode.toLowerCase();
+  for (const p of PROXY_PATTERNS) {
+    if (hex.includes(p.prefix) && p.label !== 'Standard Contract (not a proxy)') {
+      return { isProxy: true, type: p.label };
+    }
+  }
+  // Check for delegatecall pattern (0xf4 opcode = delegatecall)
+  // In hex: f4 appears frequently in non-proxy contracts too, look for pattern
+  const hasDelegatecall = hex.includes('5af4');
+  return { isProxy: hasDelegatecall, type: hasDelegatecall ? 'Potential Proxy (delegatecall found)' : 'Not a proxy' };
+}
+
+function computeRiskScore(findings) {
+  let score = 0;
+  const weights = { critical: 30, high: 20, medium: 10, info: 3, good: -10 };
+
+  for (const f of findings) {
+    score += (weights[f.severity] || 0);
+  }
+
+  return Math.max(0, Math.min(100, score));
+}
+
+// ─── Main scanner ─────────────────────────────────────────────────────────────
+
+export async function scanContract(address) {
+  const findings = [];
+  const meta = {};
+
+  console.log(`\n🔍 Scanning ${address} on Base...`);
+
+  // 1. Basic on-chain info
+  const [code, txCount] = await Promise.all([
+    provider.getCode(address),
+    provider.getTransactionCount(address),
+  ]);
+
+  if (code === '0x') {
+    return {
+      error: 'Not a contract',
+      address,
+      riskScore: 0,
+      findings: [],
+      summary: 'NOT_A_CONTRACT',
+    };
+  }
+
+  meta.bytecodeSize = (code.length - 2) / 2; // bytes
+  meta.deployerTxCount = txCount;
+
+  console.log(`  Bytecode: ${meta.bytecodeSize} bytes`);
+
+  // 2. Source code verification
+  const sourceInfo = await getContractSource(address);
+  if (sourceInfo && sourceInfo[0]) {
+    const s = sourceInfo[0];
+    meta.contractName  = s.ContractName || 'Unknown';
+    meta.compiler      = s.CompilerVersion || '?';
+    meta.sourceVerified = s.SourceCode && s.SourceCode.length > 0;
+    meta.isProxy       = s.Proxy === '1';
+    meta.implementation = s.Implementation || null;
+
+    console.log(`  Name: ${meta.contractName}`);
+    console.log(`  Verified: ${meta.sourceVerified}`);
+
+    if (!meta.sourceVerified) {
+      findings.push({
+        severity: 'high',
+        label: 'unverified_source',
+        name: 'Source code not verified',
+        detail: 'Cannot inspect source code — high risk of hidden backdoors',
+      });
+    } else {
+      findings.push({
+        severity: 'good',
+        label: 'verified_source',
+        name: 'Source code verified',
+        detail: `Contract: ${meta.contractName}`,
+      });
+    }
+
+    if (meta.isProxy) {
+      findings.push({
+        severity: 'medium',
+        label: 'upgradeable_proxy',
+        name: 'Upgradeable proxy',
+        detail: `Implementation: ${meta.implementation || 'unknown'} — owner can upgrade the logic`,
+      });
+    }
+  } else {
+    meta.sourceVerified = false;
+    findings.push({
+      severity: 'high',
+      label: 'unverified_source',
+      name: 'Source code not verified',
+      detail: 'BaseScan has no source code for this contract',
+    });
+  }
+
+  // 3. Bytecode selector analysis
+  const { found: selectorFindings, isERC20 } = analyzeSelectors(code);
+  meta.isERC20 = isERC20;
+
+  if (isERC20) {
+    findings.push({
+      severity: 'good',
+      label: 'erc20_compliant',
+      name: 'ERC20 compliant',
+      detail: 'Standard transfer/approve/allowance functions detected',
+    });
+  }
+
+  for (const sf of selectorFindings) {
+    findings.push({
+      severity: sf.severity,
+      label: sf.label,
+      name: sf.name,
+      detail: `Selector 0x${sf.selector} found in bytecode`,
+    });
+  }
+
+  // 4. Proxy bytecode detection
+  const proxyInfo = detectProxy(code);
+  if (proxyInfo.isProxy && !meta.isProxy) {
+    findings.push({
+      severity: 'medium',
+      label: 'proxy_pattern',
+      name: 'Proxy pattern detected in bytecode',
+      detail: proxyInfo.type,
+    });
+  }
+
+  // 5. Age check
+  try {
+    const txs = await fetchEtherscan({
+      module: 'account',
+      action: 'txlist',
+      address,
+      startblock: 0,
+      endblock: 99999999,
+      page: 1,
+      offset: 1,
+      sort: 'asc',
+    });
+    if (txs && txs[0]) {
+      const deployTs = parseInt(txs[0].timeStamp);
+      const agedays = (Date.now() / 1000 - deployTs) / 86400;
+      meta.agedays = Math.round(agedays);
+      meta.deployer = txs[0].from;
+
+      if (agedays < 7) {
+        findings.push({
+          severity: 'high',
+          label: 'new_contract',
+          name: 'Contract deployed < 7 days ago',
+          detail: `Deployed ${meta.agedays} days ago by ${meta.deployer}`,
+        });
+      } else if (agedays < 30) {
+        findings.push({
+          severity: 'medium',
+          label: 'recent_contract',
+          name: 'Contract deployed < 30 days ago',
+          detail: `Deployed ${meta.agedays} days ago`,
+        });
+      } else {
+        findings.push({
+          severity: 'good',
+          label: 'established_contract',
+          name: `Contract established (${meta.agedays} days old)`,
+          detail: `Deployed ${meta.agedays} days ago`,
+        });
+      }
+    }
+  } catch { /* skip age check */ }
+
+  // 6. Transaction volume (activity check)
+  try {
+    const recentTxs = await fetchEtherscan({
+      module: 'account',
+      action: 'txlist',
+      address,
+      startblock: 0,
+      endblock: 99999999,
+      page: 1,
+      offset: 100,
+      sort: 'desc',
+    });
+    meta.recentTxCount = recentTxs ? recentTxs.length : 0;
+
+    if (meta.recentTxCount === 0) {
+      findings.push({
+        severity: 'medium',
+        label: 'no_activity',
+        name: 'No recent transactions',
+        detail: 'Contract has no transaction history — low usage or brand new',
+      });
+    } else if (meta.recentTxCount >= 10) {
+      findings.push({
+        severity: 'good',
+        label: 'active_contract',
+        name: `Active contract (${meta.recentTxCount}+ recent txs)`,
+        detail: 'Contract shows regular usage',
+      });
+    }
+  } catch { /* skip */ }
+
+  // ─── Compute risk score ────────────────────────────────────────────────────
+
+  const riskScore = computeRiskScore(findings);
+  const riskLabel = riskScore >= 70 ? 'CRITICAL' :
+                    riskScore >= 50 ? 'HIGH' :
+                    riskScore >= 30 ? 'MEDIUM' :
+                    riskScore >= 10 ? 'LOW' : 'SAFE';
+
+  // ─── Build result ─────────────────────────────────────────────────────────
+
+  const criticalFindings = findings.filter(f => f.severity === 'critical');
+  const highFindings     = findings.filter(f => f.severity === 'high');
+  const mediumFindings   = findings.filter(f => f.severity === 'medium');
+  const goodFindings     = findings.filter(f => f.severity === 'good');
+
+  const summaryParts = [
+    `RISK:${riskScore}/${riskLabel}`,
+    criticalFindings.length > 0 ? `critical:${criticalFindings.map(f => f.label).join(',')}` : null,
+    highFindings.length > 0     ? `high:${highFindings.map(f => f.label).join(',')}` : null,
+    mediumFindings.length > 0   ? `medium:${mediumFindings.map(f => f.label).join(',')}` : null,
+    `age:${meta.agedays ?? '?'}d`,
+    meta.sourceVerified ? 'verified:YES' : 'verified:NO',
+  ].filter(Boolean).join(' | ');
+
+  const result = {
+    address,
+    timestamp: new Date().toISOString(),
+    riskScore,
+    riskLabel,
+    meta,
+    findings,
+    summary: summaryParts.slice(0, 500), // max 500 chars for on-chain
+    criticalCount:  criticalFindings.length,
+    highCount:      highFindings.length,
+    mediumCount:    mediumFindings.length,
+    goodCount:      goodFindings.length,
+  };
+
+  // Compute result hash (keccak256 of full JSON)
+  const resultJson = JSON.stringify(result);
+  result.resultHash = '0x' + createHash('sha256').update(resultJson).digest('hex');
+  // Note: using sha256 here, contract uses bytes32 — compatible
+
+  return result;
+}
+
+// ─── Print helper ──────────────────────────────────────────────────────────────
+
+function printResult(result) {
+  if (result.error) {
+    console.log(`\n❌ Error: ${result.error}`);
+    return;
+  }
+
+  const emoji = result.riskScore >= 70 ? '🔴' :
+                result.riskScore >= 50 ? '🟠' :
+                result.riskScore >= 30 ? '🟡' :
+                result.riskScore >= 10 ? '🟢' : '✅';
+
+  console.log(`\n${'═'.repeat(60)}`);
+  console.log(`${emoji}  RISK SCORE: ${result.riskScore}/100 — ${result.riskLabel}`);
+  console.log(`${'═'.repeat(60)}`);
+  console.log(`Contract  : ${result.address}`);
+  console.log(`Name      : ${result.meta.contractName || '?'}`);
+  console.log(`Age       : ${result.meta.agedays ?? '?'} days`);
+  console.log(`Verified  : ${result.meta.sourceVerified ? '✅ Yes' : '❌ No'}`);
+  console.log(`Bytecode  : ${result.meta.bytecodeSize} bytes`);
+  console.log(`Txs (recent): ${result.meta.recentTxCount ?? '?'}`);
+  console.log(`\nFindings:`);
+
+  const severityOrder = ['critical', 'high', 'medium', 'info', 'good'];
+  const sorted = [...result.findings].sort((a, b) =>
+    severityOrder.indexOf(a.severity) - severityOrder.indexOf(b.severity)
+  );
+
+  for (const f of sorted) {
+    const icon = { critical: '🔴', high: '🟠', medium: '🟡', info: 'ℹ️ ', good: '✅' }[f.severity] || '·';
+    console.log(`  ${icon}  [${f.severity.toUpperCase().padEnd(8)}] ${f.name}`);
+    if (f.detail) console.log(`          ${f.detail}`);
+  }
+
+  console.log(`\nSummary (on-chain):`);
+  console.log(`  ${result.summary}`);
+  console.log(`\nResult hash: ${result.resultHash}`);
+  console.log(`${'═'.repeat(60)}\n`);
+}
+
+// ─── CLI entry point ──────────────────────────────────────────────────────────
+
+if (process.argv[1]?.endsWith('scanner.js')) {
+  const address = process.argv[2];
+  if (!address) {
+    console.error('Usage: node research/scanner.js <contractAddress>');
+    process.exit(1);
+  }
+
+  scanContract(address)
+    .then(result => {
+      printResult(result);
+    })
+    .catch(err => {
+      console.error('Scan failed:', err.message);
+      process.exit(1);
+    });
+}

package/server.js

@@ -0,0 +1,270 @@
+/**
+ * MCP Server — Contract Security Scanner
+ *
+ * Exposes the p8 contract scanner as an MCP tool.
+ * Compatible with: Claude Desktop, Cursor, Cline, any MCP client.
+ *
+ * Usage (stdio):
+ *   node /path/to/p8/mcp/server.js
+ *
+ * Tools exposed:
+ *   scan_contract(address)     — Full security scan of a Base contract
+ *   scan_contract_quick(address) — Bytecode-only scan (no Etherscan API needed)
+ */
+
+import { McpServer }    from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z }            from 'zod';
+import { scanContract } from './scanner.js';
+
+// ─── Server ───────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'contract-scanner',
+  version: '1.0.0',
+});
+
+// ─── Tool: scan_contract ──────────────────────────────────────────────────────
+
+server.tool(
+  'scan_contract',
+  `Scans an EVM smart contract on Base L2 for security risks.
+
+Analyzes:
+- Source code verification status
+- Risky function selectors (mint, blacklist, pause, backdoors, etc.)
+- Proxy / upgradeability patterns
+- Contract age (new contracts = higher risk)
+- Transaction activity
+
+Returns a risk score (0-100) and categorized findings (critical/high/medium/good).
+
+Use this before:
+- Interacting with an unknown contract
+- Approving a token spend
+- Investing in a DeFi protocol
+- Auditing a smart contract`,
+  {
+    address: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{40}$/, 'Must be a valid EVM address (0x + 40 hex chars)')
+      .describe('Contract address on Base L2 to scan'),
+    include_raw: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe('Include raw findings array in response (default: false)'),
+  },
+  async ({ address, include_raw }) => {
+    try {
+      const result = await scanContract(address);
+
+      if (result.error) {
+        return {
+          content: [{
+            type: 'text',
+            text: `❌ **Scan failed**: ${result.error}\n\nAddress \`${address}\` is not a deployed contract on Base.`,
+          }],
+          isError: true,
+        };
+      }
+
+      // Risk emoji
+      const emoji = result.riskScore >= 70 ? '🔴' :
+                    result.riskScore >= 50 ? '🟠' :
+                    result.riskScore >= 30 ? '🟡' :
+                    result.riskScore >= 10 ? '🟢' : '✅';
+
+      // Build markdown response
+      const lines = [
+        `## ${emoji} Risk Score: ${result.riskScore}/100 — ${result.riskLabel}`,
+        ``,
+        `**Contract**: \`${result.address}\``,
+        `**Name**: ${result.meta.contractName || 'Unknown'}`,
+        `**Age**: ${result.meta.agedays ?? '?'} days`,
+        `**Source verified**: ${result.meta.sourceVerified ? '✅ Yes' : '❌ No'}`,
+        `**Bytecode**: ${result.meta.bytecodeSize} bytes`,
+        `**Recent txs**: ${result.meta.recentTxCount ?? '?'}`,
+        ``,
+      ];
+
+      // Group findings by severity
+      const bySeverity = { critical: [], high: [], medium: [], info: [], good: [] };
+      for (const f of result.findings) {
+        (bySeverity[f.severity] || bySeverity.info).push(f);
+      }
+
+      const icons = { critical: '🔴', high: '🟠', medium: '🟡', info: 'ℹ️', good: '✅' };
+
+      for (const [sev, items] of Object.entries(bySeverity)) {
+        if (items.length === 0) continue;
+        lines.push(`### ${icons[sev]} ${sev.toUpperCase()} (${items.length})`);
+        for (const f of items) {
+          lines.push(`- **${f.name}**${f.detail ? `: ${f.detail}` : ''}`);
+        }
+        lines.push('');
+      }
+
+      // Summary
+      lines.push(`---`);
+      lines.push(`**On-chain summary**: \`${result.summary}\``);
+      lines.push(`**Result hash**: \`${result.resultHash}\``);
+      lines.push(`**Scanned at**: ${result.timestamp}`);
+
+      const text = lines.join('\n');
+
+      const content = [{ type: 'text', text }];
+
+      if (include_raw) {
+        content.push({
+          type: 'text',
+          text: `\n\n<details>\n<summary>Raw JSON</summary>\n\n\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\`\n</details>`,
+        });
+      }
+
+      return { content };
+
+    } catch (err) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ **Scanner error**: ${err.message}\n\nPlease check the address and try again.`,
+        }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ─── Tool: batch_scan ────────────────────────────────────────────────────────
+
+server.tool(
+  'batch_scan',
+  `Scans multiple contracts at once and returns a risk comparison table.
+  
+Useful for:
+- Comparing multiple DeFi protocols before choosing one
+- Auditing all contracts in a project
+- Quick portfolio risk assessment
+
+Scans up to 5 contracts in parallel.`,
+  {
+    addresses: z
+      .array(z.string().regex(/^0x[0-9a-fA-F]{40}$/))
+      .min(2)
+      .max(5)
+      .describe('List of 2-5 contract addresses on Base L2'),
+  },
+  async ({ addresses }) => {
+    try {
+      // Scan all in parallel
+      const results = await Promise.allSettled(
+        addresses.map(addr => scanContract(addr))
+      );
+
+      const lines = [
+        `## 📊 Batch Scan — ${addresses.length} contracts`,
+        ``,
+        `| Contract | Name | Risk | Score | Verified | Age |`,
+        `|----------|------|------|-------|----------|-----|`,
+      ];
+
+      for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        if (r.status === 'rejected' || r.value?.error) {
+          lines.push(`| \`${addresses[i].slice(0, 10)}...\` | ERROR | ❓ | N/A | N/A | N/A |`);
+          continue;
+        }
+        const v = r.value;
+        const emoji = v.riskScore >= 70 ? '🔴' :
+                      v.riskScore >= 50 ? '🟠' :
+                      v.riskScore >= 30 ? '🟡' :
+                      v.riskScore >= 10 ? '🟢' : '✅';
+
+        lines.push(
+          `| \`${v.address.slice(0, 10)}...\` | ${v.meta.contractName || '?'} | ${emoji} ${v.riskLabel} | ${v.riskScore}/100 | ${v.meta.sourceVerified ? '✅' : '❌'} | ${v.meta.agedays ?? '?'}d |`
+        );
+      }
+
+      lines.push('');
+      lines.push(`_Scanned at ${new Date().toISOString()}_`);
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `❌ Batch scan error: ${err.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// ─── Tool: interpret_risk ────────────────────────────────────────────────────
+
+server.tool(
+  'interpret_risk',
+  `Given a risk score and findings from a scan, provides an actionable recommendation.
+
+Returns: SAFE_TO_USE / PROCEED_WITH_CAUTION / HIGH_RISK / DO_NOT_USE`,
+  {
+    risk_score: z.number().min(0).max(100).describe('Risk score from scan_contract'),
+    risk_label: z.enum(['SAFE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL']).describe('Risk label from scan_contract'),
+    has_unverified_source: z.boolean().describe('Whether source code is unverified'),
+    has_backdoor: z.boolean().optional().default(false).describe('Whether rescueTokens/withdrawAll detected'),
+    context: z.enum(['token', 'defi', 'nft', 'unknown']).optional().default('unknown').describe('Type of contract being evaluated'),
+  },
+  async ({ risk_score, risk_label, has_unverified_source, has_backdoor, context }) => {
+    let verdict = '';
+    let explanation = '';
+    let actions = [];
+
+    if (has_backdoor) {
+      verdict = '🔴 DO_NOT_USE';
+      explanation = 'Backdoor functions detected (rescueTokens/withdrawAll). This contract can drain funds.';
+      actions = ['Do not approve any token spend', 'Do not deposit funds', 'Warn your community'];
+    } else if (risk_score >= 70 || (has_unverified_source && risk_score >= 40)) {
+      verdict = '🟠 HIGH_RISK';
+      explanation = `Score ${risk_score}/100 indicates significant risk. ${has_unverified_source ? 'Unverified source makes it impossible to audit fully.' : ''}`;
+      actions = ['Only interact with small amounts to test', 'Check if audited by a firm', 'Look for team doxxing'];
+    } else if (risk_score >= 30) {
+      verdict = '🟡 PROCEED_WITH_CAUTION';
+      explanation = `Score ${risk_score}/100. Some elevated-risk patterns found but no critical issues.`;
+      actions = [
+        'Check if mint/pause are behind a timelock',
+        context === 'defi' ? 'Verify TVL history before depositing' : null,
+        'Read the contract documentation',
+      ].filter(Boolean);
+    } else {
+      verdict = '✅ SAFE_TO_USE';
+      explanation = `Score ${risk_score}/100. No critical issues detected. Standard risk for a ${context} contract.`;
+      actions = ['Standard due diligence still recommended', 'Monitor for contract upgrades if proxy'];
+    }
+
+    const text = [
+      `## ${verdict}`,
+      ``,
+      explanation,
+      ``,
+      `**Recommended actions:**`,
+      ...actions.map(a => `- ${a}`),
+    ].join('\n');
+
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // MCP servers communicate via stdio — no console.log here
+}
+
+main().catch(err => {
+  process.stderr.write(`MCP server error: ${err.message}\n`);
+  process.exit(1);
+});