@misterhuydo/cairn-mcp 1.6.21 → 1.7.0

package/README.md

@@ -44,7 +44,7 @@ No need to re-run `cairn install` — hooks and MCP config carry over between ve
 
 | Hook | Trigger | Effect |
 |---|---|---|
-| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline to save tokens |
+| `PreToolUse[Read]` | Every file read | Source files compressed ~68% before Claude sees them; large files show structural outline with **line numbers** to save tokens |
 | `PreToolUse[Edit]` | Every file edit | Blocks Edit if Claude only saw compressed content — requires a full re-read first |
 | `Stop` | End of every response | Session auto-saved to `.cairn/session.json` |
 | `UserPromptSubmit` | First message of a new session | Fresh project: Claude prompted to run `cairn_maintain`. Returning session: Claude prompted to run `cairn_resume` |
@@ -66,11 +66,11 @@ No manual steps. The index lives in `.cairn/index.db` inside your project — li
 
 | Tool | What it does |
 |---|---|
-| `cairn_maintain` | Full index of the current project |
+| `cairn_maintain` | Full index of the current project. Suggests adding `.cairn/` to `.gitignore` if not already present |
 | `cairn_resume` | Restore last session + re-index only changed files |
-| `cairn_search` | Find classes, functions, components by name or concept |
+| `cairn_search` | Find classes, functions, components by name or concept — results include file path and **line number** |
 | `cairn_describe` | Summarize what a folder or module does |
-| `cairn_outline` | Structural outline + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
+| `cairn_outline` | Structural outline with **line numbers** per symbol + heuristic issue detection. On large federated projects returns a per-service summary; use `repo` param to drill into one service |
 | `cairn_code_graph` | Dependency health — instability, cycles, load-bearing modules |
 | `cairn_security` | Scan for XSS, SQLi, hardcoded secrets, weak crypto, and more |
 | `cairn_todos` | Scan codebase for TODO/FIXME/HACK comments, add manual items, resolve and list them |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/cairn-mcp",
-  "version": "1.6.21",
+  "version": "1.7.0",
   "description": "MCP server that gives Claude Code persistent memory across sessions. Index your codebase once, search symbols, bundle source, scan for vulnerabilities, and checkpoint/resume work — across Java, TypeScript, Vue, Python, SQL and more.",
   "type": "module",
   "main": "index.js",

package/src/bundler/outliner.js

@@ -24,8 +24,8 @@ function outlineCStyle(content, { annotations = false } = {}) {
   const out = [];
   let depth = 0;
 
-  for (const raw of lines) {
-    const line = raw.trim();
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
     if (!line) continue;
 
     const { opens, closes } = countBraces(line);
@@ -33,11 +33,11 @@ function outlineCStyle(content, { annotations = false } = {}) {
 
     if (depth === 0) {
       const sig = topLevelSig(line);
-      if (sig !== null) out.push(sig);
+      if (sig !== null) out.push(`${i + 1}: ${sig}`);
       else if (line === '}') out.push('}'); // close class/block
     } else if (depth === 1) {
       const sig = memberSig(line, annotations);
-      if (sig !== null) out.push(INDENT + sig);
+      if (sig !== null) out.push(`${INDENT}${i + 1}: ${sig}`);
     }
     // depth > 1: skip (inside method bodies)
 
@@ -138,14 +138,16 @@ function countBraces(line) {
 
 function outlinePython(content) {
   const out = [];
-  for (const line of content.split('\n')) {
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
     if (!line.trim()) continue;
     const trimmed = line.trimStart();
     if (trimmed.startsWith('import ') || trimmed.startsWith('from ')) {
       out.push(line);
     } else if (trimmed.startsWith('class ') || trimmed.startsWith('def ') ||
                trimmed.startsWith('async def ')) {
-      out.push(line.replace(/:(\s*)$/, ':'));  // keep signature, no body
+      out.push(`${i + 1}: ${line.trim().replace(/:(\s*)$/, ':')}`);
     }
   }
   return out.join('\n');
@@ -175,10 +177,11 @@ function outlineVue(content) {
 
 function outlineSQL(content) {
   const out = [];
-  for (const line of content.split('\n')) {
-    const t = line.trim();
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
     if (/^(CREATE|ALTER|DROP|INSERT|UPDATE|DELETE|SELECT|WITH|GRANT|REVOKE|BEGIN|COMMIT)\b/i.test(t)) {
-      out.push(t.slice(0, 120) + (t.length > 120 ? '...' : ''));
+      out.push(`${i + 1}: ${t.slice(0, 120)}${t.length > 120 ? '...' : ''}`);
     }
   }
   return out.join('\n');

package/src/graph/db.js

@@ -21,7 +21,8 @@ const SCHEMA = `
     kind        TEXT,
     language    TEXT,
     exported    INTEGER DEFAULT 0,
-    description TEXT
+    description TEXT,
+    line        INTEGER
   );
 
   CREATE TABLE IF NOT EXISTS dependencies (
@@ -147,7 +148,7 @@ function tableSelect(schema, table, offset) {
     case 'files':
       return `SELECT id+${offset} AS id, repo, path, language, file_type, last_indexed FROM ${q}.files`;
     case 'symbols':
-      return `SELECT id+${offset} AS id, file_id+${offset} AS file_id, fqn, name, kind, language, exported, description FROM ${q}.symbols`;
+      return `SELECT id+${offset} AS id, file_id+${offset} AS file_id, fqn, name, kind, language, exported, description, line FROM ${q}.symbols`;
     case 'dependencies':
       return `SELECT from_file_id+${offset} AS from_file_id, to_fqn, dep_type FROM ${q}.dependencies`;
     case 'build_deps':
@@ -187,6 +188,8 @@ export function openDB() {
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA synchronous = NORMAL');
   db.exec(SCHEMA);
+  // Migration: add line column to existing DBs that predate v1.7.0
+  try { db.exec('ALTER TABLE main.symbols ADD COLUMN line INTEGER'); } catch {}
   mountParentSubIndexes(db);
   refreshFederatedViews(db);
   return db;

package/src/graph/nodes.js

@@ -14,16 +14,16 @@ export function upsertFile(db, { repo, path, language, file_type }) {
   return result.lastInsertRowid;
 }
 
-export function upsertSymbol(db, { file_id, fqn, name, kind, language, exported, description }) {
+export function upsertSymbol(db, { file_id, fqn, name, kind, language, exported, description, line }) {
   const existing = db.prepare('SELECT id FROM main.symbols WHERE fqn = ?').get(fqn);
   if (existing) {
     db.prepare(
-      'UPDATE main.symbols SET file_id=?, name=?, kind=?, language=?, exported=?, description=? WHERE id=?'
-    ).run(file_id, name, kind, language, exported ? 1 : 0, description || '', existing.id);
+      'UPDATE main.symbols SET file_id=?, name=?, kind=?, language=?, exported=?, description=?, line=? WHERE id=?'
+    ).run(file_id, name, kind, language, exported ? 1 : 0, description || '', line ?? null, existing.id);
   } else {
     db.prepare(
-      'INSERT INTO main.symbols (file_id, fqn, name, kind, language, exported, description) VALUES (?, ?, ?, ?, ?, ?, ?)'
-    ).run(file_id, fqn, name, kind, language, exported ? 1 : 0, description || '');
+      'INSERT INTO main.symbols (file_id, fqn, name, kind, language, exported, description, line) VALUES (?, ?, ?, ?, ?, ?, ?, ?)'
+    ).run(file_id, fqn, name, kind, language, exported ? 1 : 0, description || '', line ?? null);
   }
 }
 

package/src/indexer/parsers/javaParser.js

@@ -1,17 +1,21 @@
+function lineOf(content, index) {
+  return content.substring(0, index).split('\n').length;
+}
+
 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 classRe = /(?:public|protected)?\s+(?:abstract\s+)?(?:class|interface|enum|record)\s+(\w+)/;
+  const classMatch = classRe.exec(content);
   const name = classMatch?.[1] || '';
   const kind = classMatch?.[0]?.match(/class|interface|enum|record/)?.[0] || 'class';
   const fqn  = pkg ? `${pkg}.${name}` : name;
+  const classLine = classMatch ? lineOf(content, classMatch.index) : null;
 
-  const methodNames = [...content.matchAll(
+  const methodMatches = [...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]
@@ -21,12 +25,12 @@ export function parseJava(filePath, content, repoName) {
     ?.replace(/\s*\*\s?/g, ' ').trim();
 
   const methodSymbols = fqn
-    ? methodNames.map(m => ({ name: m, fqn: `${fqn}.${m}`, kind: 'method', exported: false, description: '' }))
+    ? methodMatches.map(m => ({ name: m[1], fqn: `${fqn}.${m[1]}`, kind: 'method', exported: false, description: '', line: lineOf(content, m.index) }))
     : [];
 
   return {
     language: 'java',
-    symbols: [{ name, fqn, kind, exported: true, description: javadoc || '' }, ...methodSymbols],
+    symbols: [{ name, fqn, kind, exported: true, description: javadoc || '', line: classLine }, ...methodSymbols],
     imports,
     extends: extendsMatch ? [extendsMatch] : [],
     implements: implementsMatch || [],

package/src/indexer/parsers/pythonParser.js

@@ -1,3 +1,7 @@
+function lineOf(content, index) {
+  return content.substring(0, index).split('\n').length;
+}
+
 export function parsePython(filePath, content, repoName) {
   const symbols = [];
   const imports = [];
@@ -9,17 +13,17 @@ export function parsePython(filePath, content, repoName) {
 
   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 || '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported: true, description: docstring || '', line: lineOf(content, m.index) });
   }
 
   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 || '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: docstring || '', line: lineOf(content, m.index) });
   }
 
   for (const m of content.matchAll(/^@([\w.]+)(?:\(([^)]*)\))?/gm))
-    symbols.push({ name: m[1], fqn: `${filePath}::@${m[1]}`, kind: 'decorator', exported: false, description: '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::@${m[1]}`, kind: 'decorator', exported: false, description: '', line: lineOf(content, m.index) });
 
   return { language: 'python', symbols, imports };
 }

package/src/indexer/parsers/tsParser.js

@@ -1,3 +1,7 @@
+function lineOf(content, index) {
+  return content.substring(0, index).split('\n').length;
+}
+
 export function parseTS(filePath, content, repoName, language = 'typescript') {
   const symbols = [];
   const imports = [];
@@ -14,26 +18,26 @@ export function parseTS(filePath, content, repoName, language = 'typescript') {
   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 });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'class', exported, description: jsdoc, line: lineOf(content, m.index) });
   }
 
   // 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: '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'interface', exported: true, description: '', line: lineOf(content, m.index) });
 
   // 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 });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: jsdoc, line: lineOf(content, m.index) });
   }
 
   // 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: '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'function', exported: true, description: '', line: lineOf(content, m.index) });
 
   // 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: '' });
+    symbols.push({ name: m[1], fqn: `${filePath}::${m[1]}`, kind: 'enum', exported: true, description: '', line: lineOf(content, m.index) });
 
   return { language, symbols, imports };
 }

package/src/tools/maintain.js

@@ -132,8 +132,22 @@ export async function maintain(db, { languages } = {}) {
     refreshFederatedViews(db);
   }
 
+  // Check if .cairn is gitignored; suggest adding it if not
+  let gitignoreHint = null;
+  try {
+    const gitignorePath = path.join(root, '.gitignore');
+    const gitignoreContent = await fs.readFile(gitignorePath, 'utf-8').catch(() => '');
+    const lines = gitignoreContent.split('\n').map(l => l.trim());
+    const covered = lines.some(l => l === '.cairn' || l === '.cairn/' || l === '/.cairn' || l === '/.cairn/');
+    if (!covered) {
+      gitignoreHint = 'Add .cairn/ to your .gitignore to avoid committing the index and session cache.';
+    }
+  } catch {}
+
   stats.duration_ms = Date.now() - startTime;
-  return { content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }] };
+  const result = { ...stats };
+  if (gitignoreHint) result.gitignore_hint = gitignoreHint;
+  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
 }
 
 // Incremental re-index: only process a specific list of changed file paths

package/src/tools/outline.js

@@ -105,7 +105,7 @@ export function outlineProject(db, { paths: scopePaths, repo, checks } = {}) {
   }
 
   const allSymbols = db.prepare(
-    `SELECT file_id, fqn, name, kind, exported FROM symbols ORDER BY file_id, kind, name`
+    `SELECT file_id, fqn, name, kind, exported, line FROM symbols ORDER BY file_id, kind, name`
   ).all();
 
   for (const sym of allSymbols) {
@@ -141,16 +141,19 @@ export function outlineProject(db, { paths: scopePaths, repo, checks } = {}) {
 
     for (const [className, { meta, members }] of classes) {
       const exported = meta.exported ? '+' : '-';
-      outlineLines.push(`  ${exported} ${meta.kind} ${className}`);
+      const lineTag = meta.line ? `:${meta.line}` : '';
+      outlineLines.push(`  ${exported} ${meta.kind} ${className}${lineTag}`);
       for (const m of members) {
         const vis = m.exported ? '+' : '-';
-        outlineLines.push(`      ${vis} ${m.name}  (${m.kind})`);
+        const mLineTag = m.line ? `:${m.line}` : '';
+        outlineLines.push(`      ${vis} ${m.name}${mLineTag}  (${m.kind})`);
       }
     }
     for (const sym of topLevel) {
       if (sym.kind === 'class') continue; // already handled above
       const vis = sym.exported ? '+' : '-';
-      outlineLines.push(`  ${vis} ${sym.name}  (${sym.kind})`);
+      const lineTag = sym.line ? `:${sym.line}` : '';
+      outlineLines.push(`  ${vis} ${sym.name}${lineTag}  (${sym.kind})`);
     }
   }
 

package/src/tools/search.js

@@ -44,5 +44,20 @@ export function search(db, { query, limit = 10, language, kind }) {
     return true;
   });
 
-  return { content: [{ type: 'text', text: JSON.stringify(deduped.slice(0, limit), null, 2) }] };
+  const top = deduped.slice(0, limit);
+
+  // Look up line numbers from symbols table (not stored in FTS index)
+  const fqnToLine = new Map();
+  for (const schema of schemas) {
+    const missing = top.filter(r => !fqnToLine.has(r.fqn)).map(r => r.fqn);
+    if (missing.length === 0) break;
+    try {
+      const phs = missing.map(() => '?').join(',');
+      const rows = db.prepare(`SELECT fqn, line FROM ${schema}.symbols WHERE fqn IN (${phs})`).all(...missing);
+      for (const r of rows) if (r.line != null) fqnToLine.set(r.fqn, r.line);
+    } catch {}
+  }
+
+  const results = top.map(r => ({ ...r, line: fqnToLine.get(r.fqn) ?? null }));
+  return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
 }