carto-md 2.0.6 → 2.0.8

package/src/mcp/server-v2.js

@@ -7,9 +7,26 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
 const { SQLiteStore } = require('../store/sqlite-store');
+const { normalizeFileArg } = require('../store/path-utils');
+const { syncFiles } = require('../store/sync-v2');
+const bitmapTools = require('../bitmap/tools');
+const { ensureBitmapFresh, invalidate: invalidateBitmap } = require('../bitmap/index');
+const { validateDiff, recordSideEffects } = require('./validate');
 
 const projectRoot = process.cwd();
 
+// Process-level safety nets. Without these, any error that
+// escapes the request handler (very rare, but possible from native bindings
+// or async stack frames) takes the whole MCP server down, and Claude Code /
+// Kiro surface `-32000 Failed to reconnect`. We log to stderr (which the
+// host logs but never terminates the JSON-RPC channel) and stay alive.
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[CARTO MCP] Uncaught exception: ${err && err.stack ? err.stack : err}\n`);
+});
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[CARTO MCP] Unhandled rejection: ${reason && reason.stack ? reason.stack : reason}\n`);
+});
+
 // Open SQLite directly — no re-indexing, instant startup
 let store = null;
 
@@ -17,19 +34,180 @@ function getStore() {
   if (store) return store;
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
   if (!fs.existsSync(dbPath)) return null;
-  store = new SQLiteStore(projectRoot);
-  store.open();
+  // Open BEFORE assigning to the module-scoped `store` so that if open()
+  // throws (corrupt DB, locked file, schema mismatch) we don't poison the
+  // cache with a broken instance — every subsequent call would otherwise
+  // return the broken object and never recover.
+  const s = new SQLiteStore(projectRoot);
+  s.open({ readonly: true }); // Defense in depth: MCP tools never write
+  store = s;
   return store;
 }
 
+/**
+ * getSidecar() — bitmap engine entry point.
+ *
+ * Lazily loads (or rebuilds) the in-memory bitmap sidecar for the
+ * bitmap-eligible MCP tools. Returns null on any failure so callers can
+ * fall back to the SQLite query path silently — bitmap is a *speedup*,
+ * never a behavior change. Stale-disk and corrupt-disk are handled
+ * inside `ensureBitmapFresh` (rebuilds from the SQLite source of truth).
+ *
+ * Failure modes that drop us back to SQLite:
+ *   - SQLite store unavailable (no `.carto/carto.db`).
+ *   - DB row read fails mid-build (race with a concurrent writer).
+ *   - Disk write to bitmap.bin fails (read-only FS, disk full) — the
+ *     in-memory sidecar is still returned, but if even build threw we
+ *     surface the error and use SQLite.
+ */
+function getSidecar() {
+  const s = getStore();
+  if (!s) return null;
+  const cartoDir = path.join(projectRoot, '.carto');
+  try {
+    return ensureBitmapFresh(cartoDir, s);
+  } catch (err) {
+    process.stderr.write(
+      `[CARTO MCP] bitmap load failed, falling back to SQLite: ` +
+      `${err && err.message ? err.message : err}\n`
+    );
+    return null;
+  }
+}
+
+/**
+ * lazyReparseFile(file) — MCP-side freshness check.
+ *
+ * Before answering a file-aware tool call, mtime+size check the requested
+ * file against the indexed row. If the file is stale (user edited it
+ * between the last `carto sync` and this MCP query — e.g. uncommitted
+ * work), re-parse it inline so the answer reflects current code.
+ *
+ * Three states:
+ *   - File missing on disk → leave the index alone. The user may have
+ *     deleted-and-recreated mid-session; we don't want to drop a row that
+ *     a sync would re-add seconds later.
+ *   - File present, in index, mtime+size match → fast path, no work.
+ *   - File present, stale or unknown → call syncFiles() with a transient
+ *     writable connection. syncFiles opens, writes, closes its own
+ *     connection so the cached read-only `store` keeps the readonly
+ *     guarantee that the MCP read path itself can never write.
+ *
+ * Best-effort: any failure (stat, parse, write contention) falls through
+ * to "answer with whatever the index has." Stale data beats a crash.
+ */
+function lazyReparseFile(file) {
+  if (!file || typeof file !== 'string') return;
+
+  const fullPath = path.resolve(projectRoot, file);
+  let stat;
+  try {
+    stat = fs.statSync(fullPath);
+  } catch {
+    return; // File doesn't exist on disk — leave index alone.
+  }
+
+  const s = getStore();
+  if (!s) return;
+
+  const existing = s.getFileByPath(file);
+  const mtime = Math.floor(stat.mtimeMs);
+  const size = stat.size;
+
+  // Fresh row → nothing to do.
+  if (existing && existing.mtime === mtime && existing.size === size) return;
+
+  // Stale or unknown — reparse just this file. syncFiles() opens its own
+  // writable connection and closes it, so the readonly `store` stays
+  // readonly. Costs ~5-50ms per stale file.
+  try {
+    syncFiles(projectRoot, [file]);
+  } catch (err) {
+    process.stderr.write(`[CARTO MCP] Lazy reparse failed for ${file}: ${err && err.message ? err.message : err}\n`);
+  }
+}
+
 function text(str) {
   return { content: [{ type: 'text', text: str }] };
 }
 
+/**
+ * withWriter(fn) — run `fn(writer)` against a brief writable connection
+ * scoped to a single MCP call. The cached MCP `store` is opened readonly
+ * (so a buggy tool path can never write through SQLite); episodic-memory
+ * tools that need to record decisions/interventions go through this
+ * helper instead. The writer opens, writes, closes within this function
+ * — the readonly `store` is untouched. Failures are swallowed (returned
+ * as null) because validation should always degrade gracefully — the
+ * read result matters more than the audit log row.
+ */
+function withWriter(fn) {
+  let writer = null;
+  try {
+    writer = new SQLiteStore(projectRoot);
+    writer.open();
+    return fn(writer);
+  } catch (err) {
+    process.stderr.write(
+      `[CARTO MCP] writer connection failed: ${err && err.message ? err.message : err}\n`
+    );
+    return null;
+  } finally {
+    if (writer) {
+      try { writer.close(); } catch {}
+    }
+  }
+}
+
 function notIndexed() {
   return text('No .carto/carto.db found. Run `carto sync` first.');
 }
 
+/**
+ * parseTimeRange("7d" | "24h" | "1h" | "30m" | "60s") → ms | null
+ *
+ * Small parser for the `get_recent_decisions` time_range arg.
+ * Returns null on malformed input so the caller can surface a clear
+ * error message instead of silently treating "auth" as 0ms.
+ */
+function parseTimeRange(s) {
+  if (typeof s !== 'string' || s.length === 0) return null;
+  const m = s.trim().match(/^(\d+)\s*([smhdw])?$/i);
+  if (!m) return null;
+  const n = parseInt(m[1], 10);
+  if (!Number.isFinite(n) || n < 0) return null;
+  const unit = (m[2] || 'd').toLowerCase();
+  const mult = unit === 's' ? 1000 :
+               unit === 'm' ? 60_000 :
+               unit === 'h' ? 3_600_000 :
+               unit === 'd' ? 86_400_000 :
+               unit === 'w' ? 604_800_000 : null;
+  if (mult === null) return null;
+  return n * mult;
+}
+
+/**
+ * summarizeDecisionPayload(json) → short string
+ *
+ * Renders a one-line summary of a `decisions.payload_json` row for the
+ * Markdown tables. Defensive against missing/malformed JSON — never
+ * throws, never echoes raw payload bytes.
+ */
+function summarizeDecisionPayload(json) {
+  if (!json) return '—';
+  let obj;
+  try { obj = JSON.parse(json); } catch { return '_(unparseable payload)_'; }
+  if (!obj || typeof obj !== 'object') return '—';
+  const parts = [];
+  if (obj.risk) parts.push(`risk=${obj.risk}`);
+  if (typeof obj.violationCount === 'number') parts.push(`violations=${obj.violationCount}`);
+  if (typeof obj.blastUnion === 'number') parts.push(`blast=${obj.blastUnion}`);
+  if (Array.isArray(obj.files) && obj.files.length > 0) {
+    parts.push(`files=${obj.files.length === 1 ? obj.files[0] : `${obj.files.length}`}`);
+  }
+  return parts.length === 0 ? '—' : parts.join(', ');
+}
+
 // ─── Tool definitions (same as V1) ──────────────────────────────────────────
 
 const TOOLS = [
@@ -49,6 +227,13 @@ const TOOLS = [
   { name: 'get_file_summary', description: 'Get a 3-sentence description of what a file does, its role in the project, and its key dependencies and dependents.', inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path from project root' } }, required: ['file'] } },
   { name: 'get_change_plan', description: 'Given a natural-language intent (e.g. "add rate limiting to /api/users"), returns: files to touch, domains affected, blast radius, and similar patterns in the codebase.', inputSchema: { type: 'object', properties: { intent: { type: 'string', description: 'Natural language description of the change you want to make' } }, required: ['intent'] } },
   { name: 'get_similar_patterns', description: 'Given a file, find structurally similar files — same import pattern, same route shape, or same domain. Use to find conventions to follow before writing new code.', inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Relative file path from project root' }, limit: { type: 'number', description: 'Max results to return (default 5)' } }, required: ['file'] } },
+  { name: 'simulate_change_impact', description: 'Given a list of files, returns all files transitively affected by changing them simultaneously, with hop distance. Powered by the bitmap engine — only feasible at this speed (sub-millisecond) with bitmap OR-aggregation. Use when planning a refactor that touches multiple files.', inputSchema: { type: 'object', properties: { files: { type: 'array', items: { type: 'string' }, description: 'Array of relative file paths from project root' } }, required: ['files'] } },
+  // ─── Validation API + Episodic Memory ─────────────────────────────
+  { name: 'validate_diff', description: 'Given a unified diff, returns: violations (cross-domain imports, high-blast files), blast radius per file, risk level (SAFE/LOW/MEDIUM/HIGH), and suggestions. Sub-15ms p99 on a 7K-file repo. Each call is recorded in the episodic memory log so other tools can ask "did we discuss this?".', inputSchema: { type: 'object', properties: { diff: { type: 'string', description: 'Unified diff text (output of `git diff` / GitHub PR patch).' }, session_id: { type: 'number', description: 'Optional session id. Defaults to the most recent active session, or a fresh one.' } }, required: ['diff'] } },
+  { name: 'get_recent_decisions', description: 'List recent validation decisions and architectural choices the AI has made in this project. Returns time-descending rows.', inputSchema: { type: 'object', properties: { time_range: { type: 'string', description: 'Time window like "7d", "24h", "1h" (default "7d").' }, kind: { type: 'string', description: 'Optional filter — e.g. "validation".' } }, required: [] } },
+  { name: 'get_session_context', description: 'Full context for an AI session: every decision and every intervention, ordered chronologically. Use to recap what happened in a long-running session.', inputSchema: { type: 'object', properties: { session_id: { type: 'number', description: 'Session id. Defaults to the most recent active session.' } }, required: [] } },
+  { name: 'did_we_discuss_this', description: 'Substring search over the episodic memory log (decisions + interventions) for prior discussions of a topic. Use to avoid re-deciding settled questions.', inputSchema: { type: 'object', properties: { topic: { type: 'string', description: 'Topic to search for, e.g. "auth", "snake_case", "blast radius".' } }, required: ['topic'] } },
+  { name: 'get_intervention_history', description: 'List interventions (Carto-issued violations and suggestions) optionally filtered by file. Use to see prior warnings on a file before editing it.', inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Optional file filter (relative path from project root).' } }, required: [] } },
 ];
 
 // ─── Server setup ─────────────────────────────────────────────────────────────
@@ -62,8 +247,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  const s = getStore();
-  if (!s) return notIndexed();
+  // Normalize file-arg tools to the canonical SQLite-stored form so
+  // `./lib/x.js`, absolute paths, and Windows separators all resolve.
+  // Tools that don't take a `file` arg are unaffected.
+  if (args && typeof args.file === 'string') {
+    args.file = normalizeFileArg(projectRoot, args.file);
+    // Lazy mtime+size check. Re-parse the requested file inline
+    // if it's stale on disk (user edited but didn't commit). Best-effort:
+    // failures here never block the answer.
+    lazyReparseFile(args.file);
+  }
+  // Wrap entire handler body so any tool error (SQLite, null deref, bad
+  // input) returns a structured error response instead of crashing the
+  // MCP transport. An unhandled throw here would kill the stdio
+  // connection and Claude Code/Kiro would surface
+  // `-32000 Failed to reconnect`.
+  try {
+    const s = getStore();
+    if (!s) return notIndexed();
 
   if (name === 'get_routes') {
     const routes = s.getRoutes();
@@ -74,7 +275,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_blast_radius') {
-    const deps = s.getBlastRadius(args.file);
+    // Bitmap path with SQLite fallback. Output shape and
+    // formatting are identical between the two paths.
+    const sidecar = getSidecar();
+    const deps = sidecar
+      ? bitmapTools.blastRadius(sidecar, args.file)
+      : s.getBlastRadius(args.file);
     if (!deps) return text(`File not found in index: ${args.file}`);
     if (deps.length === 0) return text(`No dependents found for: ${args.file}`);
     const lines = [`# Blast Radius: ${args.file}\n`, `**Affected files:** ${deps.length}\n`];
@@ -105,6 +311,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_domain') {
+    // Guard: AI clients sometimes call this with no/empty `domain` arg.
+    // Without the guard we'd call args.domain.toUpperCase() on undefined and crash.
+    if (!args.domain || typeof args.domain !== 'string') {
+      return text('Missing required argument: domain. Use get_domains_list to see available domains.');
+    }
     const domain = s.getDomain(args.domain);
     if (!domain) return text(`Domain not found: ${args.domain}. Use get_domains_list to see available domains.`);
 
@@ -133,7 +344,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       models: domain.models.map(m => ({
         ...m,
         className: m.name,
-        fields: m.fields_json ? JSON.parse(m.fields_json) : []
+        // Wrap parse so one corrupt row doesn't take down the whole tool call.
+        fields: (() => {
+          if (!m.fields_json) return [];
+          try { return JSON.parse(m.fields_json); } catch { return []; }
+        })()
       })),
       functions: {},
       envVars: [],
@@ -167,7 +382,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_cross_domain') {
-    const xd = s.getCrossDomainDeps();
+    // Bitmap path with SQLite fallback.
+    const sidecar = getSidecar();
+    const xd = sidecar ? bitmapTools.crossDomain(sidecar) : s.getCrossDomainDeps();
     if (xd.length === 0) return text('No cross-domain dependencies found.');
     const lines = [`# Cross-Domain Dependencies (${xd.length})\n`];
     lines.push('| From | From Domain | To | To Domain |');
@@ -219,7 +436,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_high_impact_files') {
-    const files = s.getHighImpactFiles(args.limit || 10);
+    // Bitmap path with SQLite fallback. The bitmap layer
+    // pre-builds `popcountIndex` (sorted DESC by direct-dependent count)
+    // at sidecar-build time so this becomes an O(1) array slice — much
+    // faster than walking the reverse bitmaps + popcount per file at
+    // query time.
+    const sidecar = getSidecar();
+    const limit = args.limit || 10;
+    const files = sidecar
+      ? bitmapTools.highImpactFiles(sidecar, limit)
+      : s.getHighImpactFiles(limit);
     if (files.length === 0) return text('No high impact files found.');
     const lines = [`# High Impact Files\n`];
     lines.push('| File | Dependents |');
@@ -257,6 +483,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (st.stack.length > 0) lines.push(`**Stack:** ${st.stack.join(', ')}\n`);
     lines.push(`**Size:** ${st.meta.totalFiles} files · ${st.meta.totalRoutes} routes · ${st.meta.totalImportEdges} import edges\n`);
 
+    // Surface extractor failures so the agent knows the index
+    // is partial (and which routes/models may be missing).
+    const errCountRaw = s.getMeta('extraction_error_count');
+    const errCount = errCountRaw ? parseInt(errCountRaw, 10) : 0;
+    if (errCount > 0) {
+      lines.push(`> ⚠️  **${errCount} extraction error${errCount === 1 ? '' : 's'}** — some files failed to parse and their routes/models are missing. Run \`carto check\` for details.\n`);
+    }
+
+    // Surface unavailable grammars so the agent knows which
+    // languages have reduced extraction accuracy.
+    const unavailRaw = s.getMeta('unavailable_languages_json');
+    const unavailLangs = unavailRaw ? (() => { try { return JSON.parse(unavailRaw); } catch { return []; } })() : [];
+    if (unavailLangs.length > 0) {
+      lines.push(`> ⚠️  **${unavailLangs.length} language grammar${unavailLangs.length === 1 ? '' : 's'} unavailable** (${unavailLangs.join(', ')}) — these languages use regex-only extraction with reduced accuracy.\n`);
+    }
+
     // Domains
     if (domains.length > 0) {
       lines.push('## Domains\n');
@@ -345,6 +587,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_similar_patterns') {
+    // Bitmap path: Jaccard similarity over forward-import sets.
+    // Different semantics from the legacy 3-strategy SQL (same domain /
+    // same routes / shared imports) but the standard graph similarity
+    // metric and ~100× faster on large repos. Falls back to SQLite when
+    // bitmap is unavailable.
+    const sidecar = getSidecar();
+    if (sidecar) {
+      const limit = Math.min(args.limit || 5, 20);
+      const results = bitmapTools.similarPatterns(sidecar, args.file, limit);
+      if (results === null) return text(`File not found in index: ${args.file}`);
+      const lines = [`# Similar Patterns to: ${args.file}\n`];
+      if (results.length === 0) {
+        lines.push('_No similar files found — this file has no resolved imports to compare against._');
+        return text(lines.join('\n'));
+      }
+      lines.push('Files ranked by Jaccard similarity over their import sets:\n');
+      lines.push('| File | Score | Shared Imports |');
+      lines.push('|------|-------|----------------|');
+      for (const r of results) {
+        lines.push(`| \`${r.file}\` | ${r.score.toFixed(2)} | ${r.shared} |`);
+      }
+      return text(lines.join('\n'));
+    }
+
+    // SQLite fallback path — kept for the (rare) case bitmap load fails.
     const file = s.getFileByPath(args.file);
     if (!file) return text(`File not found in index: ${args.file}`);
 
@@ -445,7 +712,267 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return text(lines.join('\n'));
   }
 
+  if (name === 'simulate_change_impact') {
+    // Returns the union of every transitively
+    // affected file when a *set* of files changes simultaneously. Only
+    // feasible with bitmaps: an N×SQL `getBlastRadius` approach takes
+    // hundreds of milliseconds on large repos; bitmap OR-aggregate runs
+    // in microseconds. If the bitmap engine is unavailable for any
+    // reason, surface a clear "unsupported" error rather than an
+    // O(N×F×E) SQL fallback that would block the agent.
+    if (!Array.isArray(args.files) || args.files.length === 0) {
+      return text('Missing or empty argument: files (array of relative paths from project root).');
+    }
+
+    // Normalize each input path the same way the single-file tools do,
+    // and run lazy mtime check so any locally-edited input file is
+    // re-parsed before we read the index. The lazy reparse will
+    // invalidate the bitmap singleton if it triggers — getSidecar()
+    // below picks that up.
+    const normalizedFiles = [];
+    for (const f of args.files) {
+      if (typeof f !== 'string' || f.length === 0) continue;
+      const norm = normalizeFileArg(projectRoot, f);
+      normalizedFiles.push(norm);
+      lazyReparseFile(norm);
+    }
+    if (normalizedFiles.length === 0) {
+      return text('No valid file paths in `files` argument.');
+    }
+
+    const sidecar = getSidecar();
+    if (!sidecar) {
+      return text(
+        '`simulate_change_impact` requires the bitmap engine, which failed to load. ' +
+        'Run `carto sync` to rebuild `.carto/bitmap.bin`.'
+      );
+    }
+
+    const result = bitmapTools.simulateChangeImpact(sidecar, normalizedFiles);
+    const lines = [
+      `# Simulate Change Impact\n`,
+      `Changing **${normalizedFiles.length}** file${normalizedFiles.length === 1 ? '' : 's'} ` +
+      `simultaneously affects **${result.count}** transitive dependent` +
+      `${result.count === 1 ? '' : 's'}.\n`,
+    ];
+    lines.push('## Input files\n');
+    for (const f of normalizedFiles) lines.push(`- \`${f}\``);
+    lines.push('');
+    if (result.count === 0) {
+      lines.push('_No additional files would be affected. None of the input files have dependents in the index._');
+    } else {
+      lines.push('## Affected files\n');
+      lines.push('| File | Min Hop |');
+      lines.push('|------|---------|');
+      for (const r of result.files.slice(0, 200)) {
+        lines.push(`| \`${r.file}\` | ${r.hop_distance} |`);
+      }
+      if (result.count > 200) lines.push(`\n_...and ${result.count - 200} more._`);
+    }
+    return text(lines.join('\n'));
+  }
+
+  // ─── Validation API + Episodic Memory ─────────────────────────────
+
+  if (name === 'validate_diff') {
+    if (!args || typeof args.diff !== 'string' || args.diff.length === 0) {
+      return text('Missing required argument: diff (unified diff text).');
+    }
+    const sidecar = getSidecar();
+    const result = validateDiff(s, sidecar, args.diff);
+
+    // Persist via brief writer connection. Don't fail the
+    // user-facing response if the audit log write fails (read-only FS,
+    // disk full, schema migration in flight). Per-call `session_id`
+    // override falls through to "create a session if none exists".
+    withWriter((writer) => {
+      let sessionId = args.session_id;
+      if (typeof sessionId !== 'number' || sessionId <= 0) {
+        const session = writer.getOrCreateActiveSession('mcp');
+        sessionId = session.id;
+      }
+      recordSideEffects(writer, sessionId, args.diff, result);
+    });
+
+    // Render a markdown response. The shape is the visible artifact —
+    // every AI tool the user runs will see this output.
+    const lines = ['# Diff Validation\n'];
+    const riskBadge = {
+      SAFE: '🟢 SAFE',
+      LOW: '🟡 LOW',
+      MEDIUM: '🟠 MEDIUM',
+      HIGH: '🔴 HIGH',
+    }[result.risk] || result.risk;
+    lines.push(`**Risk:** ${riskBadge}`);
+    lines.push(`**Files changed:** ${result.diff.length}`);
+    lines.push(`**Union blast radius:** ${result.blast_radius.union} transitive dependents\n`);
+
+    if (result.diff.length > 0) {
+      lines.push('## Files\n');
+      lines.push('| File | Kind | +Lines | -Lines | Blast |');
+      lines.push('|------|------|-------:|-------:|------:|');
+      for (const d of result.diff) {
+        const blast = result.blast_radius.perFile[d.path] || 0;
+        lines.push(`| \`${d.path}\` | ${d.kind} | ${d.addedCount} | ${d.removedCount} | ${blast} |`);
+      }
+      lines.push('');
+    }
+
+    if (result.violations.length > 0) {
+      lines.push(`## Violations (${result.violations.length})\n`);
+      lines.push('| Severity | Kind | File | Detail |');
+      lines.push('|----------|------|------|--------|');
+      for (const v of result.violations) {
+        lines.push(`| ${v.severity} | ${v.kind} | \`${v.file}\` | ${v.message} |`);
+      }
+      lines.push('');
+    } else {
+      lines.push('_No violations detected._\n');
+    }
+
+    if (result.suggestions.length > 0) {
+      lines.push(`## Suggestions (${result.suggestions.length})\n`);
+      for (const sug of result.suggestions) {
+        lines.push(`- **${sug.kind}** on \`${sug.file}\`: ${sug.message}`);
+      }
+      lines.push('');
+    }
+
+    return text(lines.join('\n'));
+  }
+
+  if (name === 'get_recent_decisions') {
+    const range = (args && args.time_range) || '7d';
+    const ms = parseTimeRange(range);
+    if (ms === null) {
+      return text(`Invalid time_range: "${range}". Use formats like "7d", "24h", "1h".`);
+    }
+    const kind = args && args.kind ? String(args.kind) : null;
+    const rows = s.getRecentDecisions(ms, kind);
+    if (rows.length === 0) {
+      return text(`No decisions in the last ${range}${kind ? ` (kind=${kind})` : ''}.`);
+    }
+    const lines = [`# Recent Decisions (last ${range}${kind ? `, kind=${kind}` : ''})\n`];
+    lines.push(`**${rows.length}** decision${rows.length === 1 ? '' : 's'} found.\n`);
+    lines.push('| When | Kind | File | Summary |');
+    lines.push('|------|------|------|---------|');
+    for (const r of rows.slice(0, 50)) {
+      const when = new Date(r.ts).toISOString();
+      const summary = summarizeDecisionPayload(r.payload_json);
+      lines.push(`| ${when} | ${r.kind} | ${r.file ? `\`${r.file}\`` : '—'} | ${summary} |`);
+    }
+    if (rows.length > 50) lines.push(`\n_...and ${rows.length - 50} more._`);
+    return text(lines.join('\n'));
+  }
+
+  if (name === 'get_session_context') {
+    let sessionId = args && args.session_id;
+    if (typeof sessionId !== 'number' || sessionId <= 0) {
+      const cur = s.getCurrentSession();
+      if (!cur) return text('No active session found. Run a tool that creates one (e.g. `validate_diff`) first.');
+      sessionId = cur.id;
+    }
+    const ctx = s.getSessionContext(sessionId);
+    if (!ctx) return text(`Session not found: ${sessionId}`);
+    const lines = [`# Session ${ctx.session.id}\n`];
+    lines.push(`**Started:** ${new Date(ctx.session.started_at).toISOString()}`);
+    if (ctx.session.ended_at) {
+      lines.push(`**Ended:** ${new Date(ctx.session.ended_at).toISOString()}`);
+    } else {
+      lines.push('**Ended:** _(active)_');
+    }
+    if (ctx.session.client_name) lines.push(`**Client:** ${ctx.session.client_name}`);
+    lines.push('');
+    lines.push(`## Decisions (${ctx.decisions.length})\n`);
+    if (ctx.decisions.length === 0) {
+      lines.push('_None._\n');
+    } else {
+      lines.push('| When | Kind | File | Summary |');
+      lines.push('|------|------|------|---------|');
+      for (const d of ctx.decisions.slice(0, 50)) {
+        const when = new Date(d.ts).toISOString();
+        const summary = summarizeDecisionPayload(d.payload_json);
+        lines.push(`| ${when} | ${d.kind} | ${d.file ? `\`${d.file}\`` : '—'} | ${summary} |`);
+      }
+      if (ctx.decisions.length > 50) lines.push(`\n_...and ${ctx.decisions.length - 50} more._`);
+      lines.push('');
+    }
+    lines.push(`## Interventions (${ctx.interventions.length})\n`);
+    if (ctx.interventions.length === 0) {
+      lines.push('_None._');
+    } else {
+      lines.push('| When | Severity | Kind | File | Message |');
+      lines.push('|------|----------|------|------|---------|');
+      for (const iv of ctx.interventions.slice(0, 50)) {
+        const when = new Date(iv.ts).toISOString();
+        lines.push(`| ${when} | ${iv.severity || '—'} | ${iv.kind} | ${iv.file ? `\`${iv.file}\`` : '—'} | ${iv.message || ''} |`);
+      }
+      if (ctx.interventions.length > 50) lines.push(`\n_...and ${ctx.interventions.length - 50} more._`);
+    }
+    return text(lines.join('\n'));
+  }
+
+  if (name === 'did_we_discuss_this') {
+    if (!args || typeof args.topic !== 'string' || args.topic.length === 0) {
+      return text('Missing required argument: topic (string).');
+    }
+    const decisions = s.searchDecisions(args.topic);
+    const interventions = s.searchInterventions(args.topic);
+    if (decisions.length === 0 && interventions.length === 0) {
+      return text(`No prior discussion of "${args.topic}" found in the episodic memory log.`);
+    }
+    const lines = [`# Prior discussions of "${args.topic}"\n`];
+    if (decisions.length > 0) {
+      lines.push(`## Decisions (${decisions.length})\n`);
+      lines.push('| When | Session | Kind | File | Summary |');
+      lines.push('|------|---------|------|------|---------|');
+      for (const d of decisions.slice(0, 25)) {
+        const when = new Date(d.ts).toISOString();
+        const summary = summarizeDecisionPayload(d.payload_json);
+        lines.push(`| ${when} | ${d.session_id || '—'} | ${d.kind} | ${d.file ? `\`${d.file}\`` : '—'} | ${summary} |`);
+      }
+      if (decisions.length > 25) lines.push(`\n_...and ${decisions.length - 25} more._`);
+      lines.push('');
+    }
+    if (interventions.length > 0) {
+      lines.push(`## Interventions (${interventions.length})\n`);
+      lines.push('| When | Session | Severity | Kind | File | Message |');
+      lines.push('|------|---------|----------|------|------|---------|');
+      for (const iv of interventions.slice(0, 25)) {
+        const when = new Date(iv.ts).toISOString();
+        lines.push(`| ${when} | ${iv.session_id || '—'} | ${iv.severity || '—'} | ${iv.kind} | ${iv.file ? `\`${iv.file}\`` : '—'} | ${iv.message || ''} |`);
+      }
+      if (interventions.length > 25) lines.push(`\n_...and ${interventions.length - 25} more._`);
+    }
+    return text(lines.join('\n'));
+  }
+
+  if (name === 'get_intervention_history') {
+    const file = args && args.file ? args.file : null;
+    const rows = s.getInterventionsForFile(file);
+    if (rows.length === 0) {
+      return text(file ? `No interventions for \`${file}\`.` : 'No interventions in the log.');
+    }
+    const lines = [`# Intervention History${file ? `: \`${file}\`` : ''}\n`];
+    lines.push(`**${rows.length}** intervention${rows.length === 1 ? '' : 's'} found.\n`);
+    lines.push('| When | Severity | Kind | File | Message |');
+    lines.push('|------|----------|------|------|---------|');
+    for (const iv of rows.slice(0, 100)) {
+      const when = new Date(iv.ts).toISOString();
+      lines.push(`| ${when} | ${iv.severity || '—'} | ${iv.kind} | ${iv.file ? `\`${iv.file}\`` : '—'} | ${iv.message || ''} |`);
+    }
+    if (rows.length > 100) lines.push(`\n_...and ${rows.length - 100} more._`);
+    return text(lines.join('\n'));
+  }
+
   return text(`Unknown tool: ${name}`);
+  } catch (err) {
+    process.stderr.write(`[CARTO MCP] Tool "${name}" error: ${err.stack || err.message || err}\n`);
+    return {
+      content: [{ type: 'text', text: `Error in ${name}: ${err.message || String(err)}` }],
+      isError: true,
+    };
+  }
 });
 
 async function main() {