@misterhuydo/cairn-mcp 1.0.0

package/src/indexer/buildParsers/npmParser.js

@@ -0,0 +1,17 @@
+export function parseNpm(filePath, content, repoName) {
+  const deps = [];
+
+  try {
+    const pkg = JSON.parse(content);
+    for (const [name, version] of Object.entries(pkg.dependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'dependencies', artifact: name, version, scope: 'runtime' });
+    for (const [name, version] of Object.entries(pkg.devDependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'devDependencies', artifact: name, version, scope: 'dev' });
+    for (const [name, version] of Object.entries(pkg.peerDependencies || {}))
+      deps.push({ manager: 'npm', group_id: 'peerDependencies', artifact: name, version, scope: 'peer' });
+  } catch {
+    // Malformed package.json — skip
+  }
+
+  return deps;
+}

package/src/indexer/fileWalker.js

@@ -0,0 +1,40 @@
+import fg from 'fast-glob';
+
+export const LANGUAGE_MAP = {
+  // JVM
+  '.java':       'java',
+  // JS/TS
+  '.ts':         'typescript',
+  '.tsx':        'typescript',
+  '.js':         'javascript',
+  '.jsx':        'javascript',
+  '.mjs':        'javascript',
+  // Vue
+  '.vue':        'vue',
+  // Python
+  '.py':         'python',
+  // Data / Config
+  '.sql':        'sql',
+  '.yml':        'config',
+  '.yaml':       'config',
+  '.properties': 'config',
+  '.env':        'config',
+  // Markup
+  '.xml':        'xml',
+  '.html':       'html',
+  '.md':         'markdown',
+};
+
+export const BUILD_FILES = ['pom.xml', 'package.json', 'build.gradle'];
+
+const IGNORE = [
+  '**/node_modules/**', '**/.git/**', '**/dist/**',
+  '**/build/**', '**/target/**', '**/.next/**',
+  '**/__pycache__/**', '**/*.min.js',
+];
+
+export async function walkRepo(repoRoot) {
+  const patterns = Object.keys(LANGUAGE_MAP).map(ext => `**/*${ext}`);
+  const files = await fg(patterns, { cwd: repoRoot, ignore: IGNORE, absolute: true });
+  return files;
+}

package/src/indexer/parserFactory.js

@@ -0,0 +1,35 @@
+import path from 'path';
+import { LANGUAGE_MAP } from './fileWalker.js';
+import { parseJava }     from './parsers/javaParser.js';
+import { parseTS }       from './parsers/tsParser.js';
+import { parseVue }      from './parsers/vueParser.js';
+import { parsePython }   from './parsers/pythonParser.js';
+import { parseSQL }      from './parsers/sqlParser.js';
+import { parseConfig }   from './parsers/configParser.js';
+import { parseXML }      from './parsers/xmlParser.js';
+import { parseMarkdown } from './parsers/markdownParser.js';
+
+const PARSERS = {
+  java:       parseJava,
+  typescript: parseTS,
+  javascript: parseTS,
+  vue:        parseVue,
+  python:     parsePython,
+  sql:        parseSQL,
+  config:     parseConfig,
+  xml:        parseXML,
+  html:       parseXML,
+  markdown:   parseMarkdown,
+};
+
+export function getParser(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const language = LANGUAGE_MAP[ext];
+  return { language, parser: PARSERS[language] || null };
+}
+
+export async function parseFile(filePath, content, repoName) {
+  const { language, parser } = getParser(filePath);
+  if (!parser) return null;
+  return parser(filePath, content, repoName, language);
+}

package/src/indexer/parsers/configParser.js

@@ -0,0 +1,17 @@
+export function parseConfig(filePath, content, repoName) {
+  const symbols = [];
+
+  for (const m of content.matchAll(/^([\w.-]+)\s*[:=]\s*(.+)/gm)) {
+    const key = m[1].trim();
+    if (key.startsWith('#')) continue;
+    symbols.push({
+      name: key,
+      fqn: `${filePath}::${key}`,
+      kind: 'config-key',
+      exported: false,
+      description: m[2].trim().substring(0, 80),
+    });
+  }
+
+  return { language: 'config', symbols, imports: [] };
+}

package/src/indexer/parsers/javaParser.js

@@ -0,0 +1,31 @@
+export function parseJava(filePath, content, repoName) {
+  const pkg     = content.match(/^package\s+([\w.]+);/m)?.[1] || '';
+  const imports = [...content.matchAll(/^import\s+([\w.]+);/gm)].map(m => m[1]);
+
+  const classMatch = content.match(
+    /(?:public|protected)?\s+(?:abstract\s+)?(?:class|interface|enum|record)\s+(\w+)/
+  );
+  const name = classMatch?.[1] || '';
+  const kind = classMatch?.[0]?.match(/class|interface|enum|record/)?.[0] || 'class';
+  const fqn  = pkg ? `${pkg}.${name}` : name;
+
+  const methods = [...content.matchAll(
+    /(?:public|protected|private)[^{;]*\s+(\w+)\s*\([^)]*\)\s*(?:throws[^{]*)?\{/gm
+  )].map(m => m[1]);
+
+  const extendsMatch    = content.match(/extends\s+([\w.]+)/)?.[1];
+  const implementsMatch = content.match(/implements\s+([\w.,\s]+)/)?.[1]
+    ?.split(',').map(s => s.trim());
+
+  const javadoc = content.match(/\/\*\*([\s\S]*?)\*\//)?.[1]
+    ?.replace(/\s*\*\s?/g, ' ').trim();
+
+  return {
+    language: 'java',
+    symbols: [{ name, fqn, kind, exported: true, description: javadoc || '' }],
+    imports,
+    extends: extendsMatch ? [extendsMatch] : [],
+    implements: implementsMatch || [],
+    methods,
+  };
+}

package/src/indexer/parsers/markdownParser.js

@@ -0,0 +1,17 @@
+export function parseMarkdown(filePath, content, repoName) {
+  const symbols = [];
+
+  for (const m of content.matchAll(/^(#{1,3})\s+(.+)/gm)) {
+    const level = m[1].length;
+    const title = m[2].trim();
+    symbols.push({
+      name: title,
+      fqn: `${filePath}::${title.replace(/\s+/g, '-').toLowerCase()}`,
+      kind: level === 1 ? 'doc-title' : 'doc-section',
+      exported: true,
+      description: '',
+    });
+  }
+
+  return { language: 'markdown', symbols, imports: [] };
+}

package/src/indexer/parsers/pythonParser.js

@@ -0,0 +1,25 @@
+export function parsePython(filePath, content, repoName) {
+  const symbols = [];
+  const imports = [];
+
+  for (const m of content.matchAll(/^from\s+([\w.]+)\s+import\s+([\w,\s*]+)/gm))
+    imports.push(...m[2].split(',').map(s => s.trim()).filter(Boolean));
+  for (const m of content.matchAll(/^import\s+([\w.,\s]+)/gm))
+    imports.push(...m[1].split(',').map(s => s.trim()).filter(Boolean));
+
+  for (const m of content.matchAll(/^class\s+(\w+)(?:\(([^)]*)\))?:/gm)) {
+    const docstring = content.slice(m.index).match(/:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported: true, description: docstring || '' });
+  }
+
+  for (const m of content.matchAll(/^(?:async\s+)?def\s+(\w+)\s*\(/gm)) {
+    if (m[1].startsWith('_')) continue;
+    const docstring = content.slice(m.index).match(/\).*?:\s*\n\s+"""([\s\S]*?)"""/)?.[1]?.trim();
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: docstring || '' });
+  }
+
+  for (const m of content.matchAll(/^@([\w.]+)(?:\(([^)]*)\))?/gm))
+    symbols.push({ name: m[1], fqn: `${filePath}::@${m[1]}`, kind: 'decorator', exported: false, description: '' });
+
+  return { language: 'python', symbols, imports };
+}

package/src/indexer/parsers/sqlParser.js

@@ -0,0 +1,14 @@
+export function parseSQL(filePath, content, repoName) {
+  const symbols = [];
+
+  for (const m of content.matchAll(/CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"\w.]+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'table', exported: true, description: '' });
+
+  for (const m of content.matchAll(/CREATE\s+(?:OR\s+REPLACE\s+)?(?:PROCEDURE|FUNCTION)\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+
+  for (const m of content.matchAll(/CREATE\s+(?:OR\s+REPLACE\s+)?VIEW\s+(\w+)/gi))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'view', exported: true, description: '' });
+
+  return { language: 'sql', symbols, imports: [] };
+}

package/src/indexer/parsers/tsParser.js

@@ -0,0 +1,45 @@
+export function parseTS(filePath, content, repoName, language = 'typescript') {
+  const symbols = [];
+  const imports = [];
+
+  // Named imports: import { Foo, Bar } from './foo'
+  for (const m of content.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(...m[1].split(',').map(s => s.trim().split(' as ')[0]).filter(Boolean));
+
+  // Default imports: import Foo from './foo'
+  for (const m of content.matchAll(/import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g))
+    imports.push(m[1]);
+
+  // Classes
+  for (const m of content.matchAll(/(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/g)) {
+    const exported = m[0].startsWith('export');
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported, description: jsdoc });
+  }
+
+  // Interfaces & Types
+  for (const m of content.matchAll(/export\s+(?:interface|type)\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'interface', exported: true, description: '' });
+
+  // Exported named functions
+  for (const m of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g)) {
+    const jsdoc = extractJSDoc(content, m.index);
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: jsdoc });
+  }
+
+  // Exported arrow functions: export const foo = (...) =>
+  for (const m of content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '' });
+
+  // Enums
+  for (const m of content.matchAll(/export\s+(?:const\s+)?enum\s+(\w+)/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'enum', exported: true, description: '' });
+
+  return { language, symbols, imports };
+}
+
+function extractJSDoc(content, index) {
+  const before = content.substring(0, index);
+  const match  = before.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
+  return match ? match[1].replace(/\s*\*\s?/g, ' ').trim() : '';
+}

package/src/indexer/parsers/vueParser.js

@@ -0,0 +1,25 @@
+import { parseTS } from './tsParser.js';
+
+export function parseVue(filePath, content, repoName) {
+  const componentName = filePath.split('/').pop().replace('.vue', '');
+
+  const scriptMatch = content.match(/<script(?:\s+setup)?(?:\s+lang=["']ts["'])?>([\s\S]*?)<\/script>/i);
+  const scriptContent = scriptMatch?.[1] || '';
+
+  const parsed = parseTS(filePath, scriptContent, repoName, 'vue');
+
+  const templateMatch = content.match(/<template>([\s\S]*?)<\/template>/i);
+  const childComponents = [...(templateMatch?.[1]?.matchAll(/<([A-Z][A-Za-z]+)/g) || [])]
+    .map(m => m[1]);
+
+  parsed.symbols.unshift({
+    name: componentName,
+    fqn: `${filePath}::${componentName}`,
+    kind: 'component',
+    exported: true,
+    description: `Vue component: ${componentName}`,
+  });
+
+  parsed.childComponents = [...new Set(childComponents)];
+  return parsed;
+}

package/src/indexer/parsers/xmlParser.js

@@ -0,0 +1,25 @@
+const HTML_TAGS = new Set([
+  'div','span','p','a','ul','ol','li','table','tr','td','th','thead','tbody',
+  'form','input','button','select','option','textarea','label','img','br','hr',
+  'h1','h2','h3','h4','h5','h6','head','body','html','script','style','link',
+  'meta','nav','header','footer','main','section','article','aside','figure',
+]);
+
+export function parseXML(filePath, content, repoName) {
+  const symbols = [];
+
+  // Spring bean IDs, component ids, any id="..." attribute
+  for (const m of content.matchAll(/\bid\s*=\s*["']([^"']+)["']/g))
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'bean', exported: true, description: '' });
+
+  // Non-standard (custom/component) tag names
+  const seen = new Set();
+  for (const m of content.matchAll(/<([a-z][a-z0-9-]*)(?:\s|\/?>)/gi)) {
+    const tag = m[1].toLowerCase();
+    if (HTML_TAGS.has(tag) || seen.has(tag)) continue;
+    seen.add(tag);
+    symbols.push({ name: tag, fqn: `${filePath}::${tag}`, kind: 'component', exported: true, description: '' });
+  }
+
+  return { language: 'xml', symbols, imports: [] };
+}

package/src/indexer/securityScanner.js

@@ -0,0 +1,103 @@
+export const VULN_PATTERNS = [
+  // ── Java ──────────────────────────────────────────────────────────────
+  { id: 'CWE-611', lang: ['java'],                          severity: 'HIGH',
+    name: 'XXE (XML External Entity)',
+    pattern: /builder\.parse\(/,
+    negPattern: /setFeature.*FEATURE_SECURE_PROCESSING/,
+    fix: 'Add dbf.setFeature(XMLConstants.FEATURE_SECURE_PROCESSING, true) before parse()' },
+
+  { id: 'CWE-89',  lang: ['java'],                          severity: 'HIGH',
+    name: 'SQL Injection',
+    pattern: /"SELECT|INSERT|UPDATE|DELETE.*"\s*\+/i,
+    fix: 'Use PreparedStatement with parameterized queries' },
+
+  { id: 'CWE-326', lang: ['java'],                          severity: 'HIGH',
+    name: 'Weak Cryptography',
+    pattern: /getInstance\("(MD5|SHA1|DES|RC4)"\)/,
+    fix: 'Use SHA-256 or AES-256' },
+
+  { id: 'CWE-502', lang: ['java'],                          severity: 'HIGH',
+    name: 'Unsafe Deserialization',
+    pattern: /new ObjectInputStream|\.readObject\(\)/,
+    fix: 'Validate input before deserialization; use safe deserialization libraries' },
+
+  { id: 'CWE-078', lang: ['java'],                          severity: 'HIGH',
+    name: 'Command Injection',
+    pattern: /Runtime\.getRuntime\(\)\.exec\(/,
+    fix: 'Use ProcessBuilder with argument list instead of string concatenation' },
+
+  // ── JavaScript / TypeScript / Vue ─────────────────────────────────────
+  { id: 'CWE-79',  lang: ['javascript', 'typescript', 'vue'], severity: 'HIGH',
+    name: 'XSS via innerHTML / dangerouslySetInnerHTML',
+    pattern: /\.innerHTML\s*=|dangerouslySetInnerHTML/,
+    fix: 'Use textContent or sanitize with DOMPurify' },
+
+  { id: 'CWE-89',  lang: ['javascript', 'typescript'],       severity: 'HIGH',
+    name: 'SQL Injection (JS)',
+    pattern: /`\s*(SELECT|INSERT|UPDATE|DELETE).*\$\{/i,
+    fix: 'Use parameterized queries or an ORM' },
+
+  { id: 'CWE-798', lang: ['javascript', 'typescript', 'vue'], severity: 'HIGH',
+    name: 'Hardcoded Secret',
+    pattern: /(api_key|apikey|secret|password|token)\s*[:=]\s*['"][^'"]{8,}['"]/i,
+    fix: 'Move secrets to environment variables or a secrets manager' },
+
+  { id: 'CWE-327', lang: ['javascript', 'typescript'],        severity: 'MEDIUM',
+    name: 'Weak Crypto (Node)',
+    pattern: /createHash\(['"]md5['"]\)|createHash\(['"]sha1['"]\)/,
+    fix: 'Use SHA-256 or stronger' },
+
+  { id: 'CWE-601', lang: ['javascript', 'typescript', 'vue'], severity: 'MEDIUM',
+    name: 'Open Redirect',
+    pattern: /res\.redirect\([^)]*req\.(query|params|body)/,
+    fix: 'Validate redirect URL against an allowlist' },
+
+  // ── Python ────────────────────────────────────────────────────────────
+  { id: 'CWE-089', lang: ['python'],                          severity: 'HIGH',
+    name: 'SQL Injection (Python)',
+    pattern: /execute\([f"'].*%(s|d)|execute\(.*format\(/,
+    fix: 'Use parameterized queries: cursor.execute(sql, params)' },
+
+  { id: 'CWE-078', lang: ['python'],                          severity: 'HIGH',
+    name: 'Command Injection (Python)',
+    pattern: /os\.system\(|subprocess\.call\(.*shell=True/,
+    fix: 'Use subprocess with a list of args and shell=False' },
+
+  { id: 'CWE-798', lang: ['python'],                          severity: 'HIGH',
+    name: 'Hardcoded Secret (Python)',
+    pattern: /(api_key|secret|password|token)\s*=\s*['"][^'"]{8,}['"]/i,
+    fix: 'Use environment variables or a secrets manager like Vault' },
+
+  // ── Universal (all languages) ─────────────────────────────────────────
+  { id: 'CWE-312', lang: null,                                severity: 'MEDIUM',
+    name: 'Cleartext Sensitive Data in Comments',
+    pattern: /\/\/.*?(password|secret|token)\s*[:=]\s*\S+/i,
+    fix: 'Remove sensitive data from comments' },
+];
+
+export function scanFile(filePath, content, language) {
+  const findings = [];
+  const lines = content.split('\n');
+
+  for (const rule of VULN_PATTERNS) {
+    if (rule.lang && !rule.lang.includes(language)) continue;
+
+    lines.forEach((line, i) => {
+      if (!rule.pattern.test(line)) return;
+      if (rule.negPattern) {
+        const ctx = lines.slice(Math.max(0, i - 5), i + 5).join('\n');
+        if (rule.negPattern.test(ctx)) return;
+      }
+      findings.push({
+        severity:     rule.severity,
+        cwe:          rule.id,
+        rule_name:    rule.name,
+        line:         i + 1,
+        code_snippet: line.trim().substring(0, 120),
+        description:  rule.fix,
+      });
+    });
+  }
+
+  return findings;
+}

package/src/tools/bundle.js

@@ -0,0 +1,30 @@
+import { writeBundle } from '../bundler/bundleWriter.js';
+
+export async function bundle(_db, args) {
+  const {
+    roots,
+    bundle_name      = 'default',
+    filter_paths     = null,
+    filter_language  = null,
+    no_comments      = true,
+    no_empty_lines   = true,
+    no_style         = false,
+    aggressive       = false,
+    only_changed     = false,
+    max_size_kb      = 800,
+  } = args;
+
+  const result = await writeBundle(roots, {
+    bundleName:   bundle_name,
+    noComments:   no_comments,
+    noEmptyLines: no_empty_lines,
+    noStyle:      no_style,
+    aggressive,
+    onlyChanged:  only_changed,
+    filterLang:   filter_language,
+    filterPaths:  filter_paths,
+    maxSizeKB:    max_size_kb,
+  });
+
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}

package/src/tools/codeGraph.js

@@ -0,0 +1,111 @@
+export function codeGraph(db, { module: modFilter, mode }) {
+  if (mode === 'health') {
+    const fileCount    = db.prepare('SELECT COUNT(*) as c FROM files').get()?.c || 0;
+    const symbolCount  = db.prepare('SELECT COUNT(*) as c FROM symbols').get()?.c || 0;
+    const depCount     = db.prepare('SELECT COUNT(*) as c FROM dependencies').get()?.c || 0;
+    const findingCount = db.prepare('SELECT COUNT(*) as c FROM security_findings').get()?.c || 0;
+    const byLang       = db.prepare('SELECT language, COUNT(*) as count FROM files GROUP BY language').all();
+    const lastIndexed  = db.prepare('SELECT MAX(last_indexed) as t FROM files').get()?.t;
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          files: fileCount, symbols: symbolCount,
+          dependencies: depCount, security_findings: findingCount,
+          by_language: byLang,
+          last_indexed: lastIndexed ? new Date(lastIndexed).toISOString() : null,
+        }, null, 2),
+      }],
+    };
+  }
+
+  if (mode === 'instability') {
+    const files = db.prepare('SELECT id, path, language FROM files').all();
+
+    // Group files by parent directory
+    const modules = {};
+    for (const f of files) {
+      const parts = f.path.replace(/\\/g, '/').split('/');
+      const moduleName = parts.slice(0, -1).join('/') || '/';
+      if (modFilter && !moduleName.includes(modFilter)) continue;
+      if (!modules[moduleName]) modules[moduleName] = { name: moduleName, language: f.language, fileIds: [] };
+      modules[moduleName].fileIds.push(f.id);
+    }
+
+    const results = [];
+    for (const [, mod] of Object.entries(modules)) {
+      if (mod.fileIds.length === 0) continue;
+      const ph = mod.fileIds.map(() => '?').join(',');
+
+      // Efferent (outgoing) deps
+      const ce = db.prepare(
+        `SELECT COUNT(DISTINCT to_fqn) as c FROM dependencies WHERE from_file_id IN (${ph})`
+      ).get(...mod.fileIds)?.c || 0;
+
+      // Afferent (incoming) deps
+      const fqns = db.prepare(
+        `SELECT fqn FROM symbols WHERE file_id IN (${ph})`
+      ).all(...mod.fileIds).map(s => s.fqn);
+
+      let ca = 0;
+      if (fqns.length > 0) {
+        const sph = fqns.map(() => '?').join(',');
+        ca = db.prepare(
+          `SELECT COUNT(DISTINCT from_file_id) as c FROM dependencies WHERE to_fqn IN (${sph})`
+        ).get(...fqns)?.c || 0;
+      }
+
+      const instability = (ca + ce) === 0 ? 0 : ce / (ca + ce);
+      const status = instability >= 0.8 ? 'safe_to_refactor'
+                   : instability >= 0.3 ? 'review_before_change'
+                   : 'load_bearing';
+      results.push({
+        name: mod.name,
+        language: mod.language,
+        instability: Math.round(instability * 100) / 100,
+        status,
+      });
+    }
+
+    results.sort((a, b) => b.instability - a.instability);
+
+    const godObjects = db.prepare(`
+      SELECT s.name || ' (' || COALESCE(s.language,'?') || ')' as label, COUNT(*) as dep_count
+      FROM dependencies d JOIN symbols s ON d.to_fqn = s.fqn
+      GROUP BY d.to_fqn ORDER BY dep_count DESC LIMIT 5
+    `).all().map(r => `${r.label} (${r.dep_count} deps)`);
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          modules: results.slice(0, 50),
+          god_objects: godObjects,
+          cycles_detected: [],
+        }, null, 2),
+      }],
+    };
+  }
+
+  if (mode === 'cycles') {
+    // Detect mutual imports between files
+    const cycles = db.prepare(`
+      SELECT DISTINCT f1.path as from_path, f2.path as to_path
+      FROM dependencies d1
+      JOIN symbols s1 ON d1.to_fqn = s1.fqn
+      JOIN files f1 ON d1.from_file_id = f1.id
+      JOIN files f2 ON s1.file_id = f2.id
+      JOIN dependencies d2 ON d2.from_file_id = f2.id
+      JOIN symbols s2 ON d2.to_fqn = s2.fqn
+      WHERE s2.file_id = d1.from_file_id
+      LIMIT 20
+    `).all();
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ cycles_detected: cycles }, null, 2) }],
+    };
+  }
+
+  return { content: [{ type: 'text', text: JSON.stringify({ error: `Unknown mode: ${mode}` }) }] };
+}

package/src/tools/describe.js

@@ -0,0 +1,51 @@
+export function describe(db, { path: dirPath }) {
+  const files = db.prepare('SELECT * FROM files WHERE path LIKE ?').all(`${dirPath}%`);
+
+  if (files.length === 0) {
+    return { content: [{ type: 'text', text: JSON.stringify({ path: dirPath, error: 'No files found' }) }] };
+  }
+
+  const fileIds = files.map(f => f.id);
+  const languages = [...new Set(files.map(f => f.language).filter(Boolean))];
+
+  const ph = fileIds.map(() => '?').join(',');
+
+  // Symbols grouped by kind
+  const symbols = db.prepare(`SELECT * FROM symbols WHERE file_id IN (${ph})`).all(...fileIds);
+  const grouped = {};
+  for (const sym of symbols) {
+    const key = sym.kind || 'other';
+    if (!grouped[key]) grouped[key] = [];
+    grouped[key].push(sym.name);
+  }
+
+  // Outgoing imports
+  const outgoing = db.prepare(
+    `SELECT DISTINCT to_fqn FROM dependencies WHERE from_file_id IN (${ph}) AND dep_type = 'imports'`
+  ).all(...fileIds).map(r => r.to_fqn);
+
+  // Incoming imports (what files import symbols defined in this path)
+  let incomingPaths = [];
+  if (symbols.length > 0) {
+    const fqns = symbols.map(s => s.fqn);
+    const sph  = fqns.map(() => '?').join(',');
+    incomingPaths = db.prepare(
+      `SELECT DISTINCT f.path FROM dependencies d JOIN files f ON d.from_file_id = f.id WHERE d.to_fqn IN (${sph})`
+    ).all(...fqns).map(r => r.path);
+  }
+
+  // External deps: outgoing references that don't match any known fqn
+  const allFqns = new Set(db.prepare('SELECT fqn FROM symbols').all().map(s => s.fqn));
+  const externalDeps = [...new Set(outgoing.filter(fqn => !allFqns.has(fqn)))].slice(0, 20);
+
+  const result = {
+    path: dirPath,
+    languages,
+    symbols: grouped,
+    imports_from:  outgoing.slice(0, 20),
+    imported_by:   incomingPaths.slice(0, 20),
+    external_deps: externalDeps,
+  };
+
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}