codesearch-mcp 0.0.16-alpha → 0.0.17-alpha.1

package/dist/src/services/IndexerService.js

@@ -69,7 +69,9 @@ class IndexerService {
         });
     }
     async backfillSymbols(signal) {
+        const t0 = Date.now();
         const rows = await this.db.query(`SELECT DISTINCT "serviceName", "filePath" FROM code_chunk ORDER BY "serviceName", "filePath"`);
+        this.logger.debug('IndexerService: backfillSymbols start', { total: rows.length });
         let processed = 0, skipped = 0, failed = 0;
         for (const { serviceName, filePath } of rows) {
             if (signal?.aborted)
@@ -103,6 +105,58 @@ class IndexerService {
                 process.stdout.isTTY ? process.stdout.write(msg + '\r') : console.log(msg);
             }
         }
+        this.logger.debug('IndexerService: backfillSymbols done', { total: rows.length, processed, skipped, failed, ms: Date.now() - t0 });
+        return { total: rows.length, processed, skipped, failed };
+    }
+    async backfillCalls(signal) {
+        const t0 = Date.now();
+        const rows = await this.db.query(`SELECT DISTINCT "serviceName", "filePath" FROM code_chunk ORDER BY "serviceName", "filePath"`);
+        this.logger.debug('IndexerService: backfillCalls start', { total: rows.length });
+        let processed = 0, skipped = 0, failed = 0;
+        for (const { serviceName, filePath } of rows) {
+            if (signal?.aborted)
+                break;
+            const absPath = path.join(this.config.workspaceRoot, filePath);
+            const projectRoot = path.join(this.config.workspaceRoot, serviceName);
+            if (!fs.existsSync(absPath)) {
+                skipped++;
+                continue;
+            }
+            try {
+                const { calls: rawCalls } = await this.ast.analyzeFile(absPath, serviceName, projectRoot);
+                const calls = rawCalls
+                    .filter(c => c.calleeFile.startsWith(this.config.workspaceRoot))
+                    .map(c => ({
+                    project: serviceName,
+                    fromFile: filePath,
+                    fromSymbol: c.fromSymbol,
+                    calleeName: c.calleeName,
+                    calleeFile: path.relative(this.config.workspaceRoot, c.calleeFile),
+                    calleeSymbol: c.calleeSymbol,
+                    line: c.line,
+                    col: c.col,
+                }));
+                await this.db.transaction(async (tx) => {
+                    await tx.delete(db_1.codeCall).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeCall.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeCall.fromFile, filePath)));
+                    if (calls.length > 0) {
+                        await tx.insert(db_1.codeCall).values(calls);
+                    }
+                });
+                processed++;
+            }
+            catch (err) {
+                const reason = err.message;
+                console.error(`  Failed: ${filePath} — ${reason}`);
+                this.logger.error('IndexerService: call backfill failed', { file: filePath, reason });
+                failed++;
+            }
+            const count = processed + failed;
+            if (count > 0 && count % 50 === 0) {
+                const msg = `  ${count}/${rows.length} files...`;
+                process.stdout.isTTY ? process.stdout.write(msg + '\r') : console.log(msg);
+            }
+        }
+        this.logger.debug('IndexerService: backfillCalls done', { total: rows.length, processed, skipped, failed, ms: Date.now() - t0 });
         return { total: rows.length, processed, skipped, failed };
     }
     discoverProjects(rootDir) {
@@ -125,10 +179,12 @@ class IndexerService {
     }
     async scanAndIndex(dir, serviceName, force = false, signal, preCollectedFiles) {
         const startTime = Date.now();
+        this.logger.debug('IndexerService: scanAndIndex start', { serviceName, dir, force });
         if (force) {
             await this.db.query(`UPDATE code_chunk SET "lastModified" = NULL, "contentHash" = NULL WHERE "serviceName" = $1`, [serviceName]);
         }
         const files = preCollectedFiles ?? (0, file_utils_1.collectFiles)(dir, (0, file_utils_1.loadIgnore)(dir), dir);
+        this.logger.debug('IndexerService: scanAndIndex files collected', { serviceName, count: files.length, force });
         const collectedRelPaths = new Set(files.map(f => path.relative(this.config.workspaceRoot, f)));
         const dbPaths = await this.db.query(`SELECT DISTINCT "filePath" FROM code_chunk WHERE "serviceName" = $1`, [serviceName]);
         for (const { filePath } of dbPaths) {
@@ -168,37 +224,46 @@ class IndexerService {
             console.log(`  ⚠ ${msg}`);
             warnings.push(msg);
         }
+        if (files.length > this.config.indexer.astBatchSize) {
+            console.log(`  ⚠ Large project (${files.length} files) — AST analysis uses batches of ${this.config.indexer.astBatchSize}; cross-batch dependency edges may be incomplete`);
+        }
         bar.start(files.length, 0, { serviceName, filename: '' });
         const stats = {
             serviceName, indexed: 0, skipped: 0, failed: 0, chunks: 0, elapsedSec: 0, warnings,
         };
         const mtimeRefreshBatch = [];
-        const analysisMap = await this.ast.analyzeProject(files, serviceName, dir);
-        for (const filePath of files) {
-            if (signal?.aborted) {
-                bar.stop();
-                console.log(`\n  Interrupted — ${serviceName}`);
-                stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
-                return stats;
-            }
-            bar.update({ filename: path.relative(dir, filePath) });
-            const mtimeMs = fs.statSync(filePath).mtimeMs;
-            const analysis = analysisMap.get(filePath);
-            if (analysis === undefined && /\.(ts|tsx|js|jsx)$/.test(filePath) && !/\.d\.ts$/.test(filePath)) {
-                this.logger.warn('IndexerService: no pre-computed analysis for TS file', { file: filePath });
-            }
-            const result = await this.ingestFile(filePath, serviceName, mtimeMs, dir, analysis);
-            if (result.pendingMtimeRefresh) {
-                mtimeRefreshBatch.push({ relFilePath: result.pendingMtimeRefresh, mtimeMs });
+        const isLargeProject = files.length > this.config.indexer.astBatchSize;
+        for (let batchStart = 0; batchStart < files.length; batchStart += this.config.indexer.astBatchSize) {
+            if (signal?.aborted)
+                break;
+            const batch = files.slice(batchStart, batchStart + this.config.indexer.astBatchSize);
+            const analysisMap = await this.ast.analyzeProject(batch, serviceName, dir, { skipDependencyResolution: isLargeProject });
+            for (const filePath of batch) {
+                if (signal?.aborted) {
+                    bar.stop();
+                    console.log(`\n  Interrupted — ${serviceName}`);
+                    stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
+                    return stats;
+                }
+                bar.update({ filename: path.relative(dir, filePath) });
+                const mtimeMs = fs.statSync(filePath).mtimeMs;
+                const analysis = analysisMap.get(filePath);
+                if (analysis === undefined && /\.(ts|tsx|js|jsx)$/.test(filePath) && !/\.d\.ts$/.test(filePath)) {
+                    this.logger.warn('IndexerService: no pre-computed analysis for TS file', { file: filePath });
+                }
+                const result = await this.ingestFile(filePath, serviceName, mtimeMs, dir, analysis, meta);
+                if (result.pendingMtimeRefresh) {
+                    mtimeRefreshBatch.push({ relFilePath: result.pendingMtimeRefresh, mtimeMs });
+                }
+                if (result.status === 'indexed')
+                    stats.indexed++;
+                else if (result.status === 'skipped')
+                    stats.skipped++;
+                else
+                    stats.failed++;
+                stats.chunks += result.chunks;
+                bar.increment();
             }
-            if (result.status === 'indexed')
-                stats.indexed++;
-            else if (result.status === 'skipped')
-                stats.skipped++;
-            else
-                stats.failed++;
-            stats.chunks += result.chunks;
-            bar.increment();
         }
         bar.stop();
         process.stdout.write('\x1B[J');
@@ -218,25 +283,63 @@ class IndexerService {
         }
         this.ast.clearCache(dir);
         stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
+        this.logger.debug('IndexerService: project indexed', {
+            project: serviceName,
+            indexed: stats.indexed,
+            skipped: stats.skipped,
+            failed: stats.failed,
+            chunks: stats.chunks,
+            elapsedSec: stats.elapsedSec,
+        });
         return stats;
     }
     getSplitter(filePath) {
         return SCHEMA_EXTENSIONS.test(filePath) ? this.schemaSplitter : this.jsSplitter;
     }
-    getEnrichedPrompt(chunk, analysis, serviceName, relPath) {
-        const { pageContent, metadata } = chunk;
-        const header = `Project: ${serviceName} | Path: ${relPath}`;
-        if (!analysis || analysis.symbols.length === 0) {
-            return `${header}\n${pageContent}`;
+    static inferRole(relPath) {
+        const p = relPath.toLowerCase();
+        if (p.includes('/services/') || p.endsWith('.service.ts'))
+            return 'Service';
+        if (p.includes('/controllers/') || p.endsWith('.controller.ts'))
+            return 'Controller';
+        if (p.includes('/entities/') || p.endsWith('.entity.ts'))
+            return 'Entity';
+        if (p.includes('/guards/') || p.endsWith('.guard.ts'))
+            return 'Guard';
+        if (p.includes('/commands/'))
+            return 'Command';
+        if (p.includes('/interfaces/'))
+            return 'Interface';
+        if (p.includes('/middleware/'))
+            return 'Middleware';
+        if (p.includes('/interceptors/'))
+            return 'Interceptor';
+        if (p.endsWith('.test.ts') || p.endsWith('.spec.ts') || p.includes('/tests/'))
+            return 'Test';
+        if (p.includes('/utils/') || p.includes('/helpers/') || p.endsWith('-utils.ts'))
+            return 'Utility';
+        return null;
+    }
+    getEnrichedPrompt(chunk, relPath, serviceName, _meta, edges, symbols) {
+        const chunkStart = (chunk.metadata?.loc?.lines?.from ?? 1);
+        const chunkEnd = (chunk.metadata?.loc?.lines?.to ?? chunkStart);
+        const lines = [];
+        lines.push(`Project: ${serviceName} | File: ${relPath}`);
+        const role = IndexerService.inferRole(relPath);
+        if (role)
+            lines.push(`Role: ${role}`);
+        const overlapping = symbols.filter(s => s.line != null &&
+            s.line <= chunkEnd &&
+            (s.endLine ?? s.line) >= chunkStart);
+        if (overlapping.length > 0) {
+            lines.push(`Symbols: ${overlapping.map(s => `${s.kind} ${s.name}`).join(', ')}`);
         }
-        const chunkStartLine = metadata?.loc?.lines?.from ?? 1;
-        const chunkEndLine = metadata?.loc?.lines?.to ?? chunkStartLine;
-        const relevantSymbols = analysis.symbols.filter(s => s.line != null && s.endLine != null && s.line <= chunkEndLine && s.endLine >= chunkStartLine);
-        if (relevantSymbols.length === 0) {
-            return `${header}\n${pageContent}`;
+        if (edges.length > 0) {
+            const depNames = [...new Set(edges.map(e => path.basename(e.toFile, path.extname(e.toFile)).split('.')[0]))];
+            lines.push(`Dependencies: ${depNames.join(', ')}`);
         }
-        const symbolsTag = `[Symbols: ${relevantSymbols.map(s => `${s.kind} ${s.name}`).join(', ')}]`;
-        return `${header}\n${symbolsTag}\n${pageContent}`;
+        lines.push(`Code: ${chunk.pageContent}`);
+        return lines.join('\n');
     }
     async embedText(prompt) {
         return this.embedder.embed(prompt);
@@ -244,7 +347,7 @@ class IndexerService {
     static hashContent(content) {
         return (0, crypto_1.createHash)('sha256').update(content).digest('hex');
     }
-    async ingestFile(filePath, serviceName, mtimeMs, projectRoot, analysis) {
+    async ingestFile(filePath, serviceName, mtimeMs, projectRoot, analysis, meta) {
         try {
             const relFilePath = path.relative(this.config.workspaceRoot, filePath);
             const [existing] = await this.db.orm
@@ -264,7 +367,7 @@ class IndexerService {
                 return { status: 'skipped', chunks: 0, pendingMtimeRefresh: relFilePath };
             }
             const tAst = Date.now();
-            const { edges: rawEdges, symbols: rawSymbols } = analysis ?? { edges: [], symbols: [] };
+            const { edges: rawEdges, symbols: rawSymbols, calls: rawCalls } = analysis ?? { edges: [], symbols: [], calls: [] };
             // astMs is near-zero — actual AST time is spent upfront in analyzeProject()
             // Normalize edges to workspace-relative paths
             const edges = rawEdges
@@ -274,6 +377,19 @@ class IndexerService {
                 fromFile: path.relative(this.config.workspaceRoot, e.fromFile),
                 toFile: path.relative(this.config.workspaceRoot, e.toFile),
             }));
+            // Normalize call edges to workspace-relative paths; keep only resolved internal calls
+            const calls = rawCalls
+                .filter(c => c.calleeFile.startsWith(this.config.workspaceRoot))
+                .map(c => ({
+                project: serviceName,
+                fromFile: relFilePath,
+                fromSymbol: c.fromSymbol,
+                calleeName: c.calleeName,
+                calleeFile: path.relative(this.config.workspaceRoot, c.calleeFile),
+                calleeSymbol: c.calleeSymbol,
+                line: c.line,
+                col: c.col,
+            }));
             // Normalize symbols: replace absolute filePath with workspace-relative, strip endLine (not stored)
             const symbols = [...new Map(rawSymbols.map(s => ({ ...s, filePath: relFilePath })).map(s => [`${s.name}:${s.kind}`, s])).values()].map(({ project, filePath: fp, name, kind, signature, line, col }) => ({ project, filePath: fp, name, kind, signature, line, col }));
             const astMs = Date.now() - tAst;
@@ -285,7 +401,7 @@ class IndexerService {
                 const batch = chunks.slice(i, i + this.config.indexer.batchSize);
                 const embedded = await Promise.all(batch.map(async (chunk) => {
                     const startLine = (chunk.metadata?.loc?.lines?.from ?? 1);
-                    const prompt = this.getEnrichedPrompt(chunk, analysis, serviceName, relPath);
+                    const prompt = this.getEnrichedPrompt(chunk, relPath, serviceName, meta ?? 'missing', edges, rawSymbols);
                     const embedding = await this.embedText(prompt);
                     return {
                         serviceName, filePath: relFilePath, startLine,
@@ -309,6 +425,10 @@ class IndexerService {
                 if (symbols.length > 0) {
                     await tx.insert(db_1.codeSymbol).values(symbols);
                 }
+                await tx.delete(db_1.codeCall).where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(db_1.codeCall.project, serviceName), (0, drizzle_orm_1.eq)(db_1.codeCall.fromFile, relFilePath)));
+                if (calls.length > 0) {
+                    await tx.insert(db_1.codeCall).values(calls);
+                }
             });
             const dbMs = Date.now() - t3;
             if (chunks.length > 0) {

package/dist/src/services/LoggerService.d.ts

@@ -4,7 +4,11 @@ export declare class LoggerService {
     private readonly logger;
     constructor(logger: pino.Logger);
     static silent(): LoggerService;
-    static fromEnv(name?: string): LoggerService;
+    static fromConfig(cfg: {
+        level: string;
+        dir?: string;
+    }, name?: string): LoggerService;
+    private static buildFromPath;
     debug(msg: string, data?: Record<string, unknown>): void;
     info(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;

package/dist/src/services/LoggerService.js

@@ -50,17 +50,20 @@ class LoggerService {
     static silent() {
         return new LoggerService((0, pino_1.default)({ level: 'silent' }));
     }
-    static fromEnv(name) {
-        const level = (process.env.LOG_LEVEL ?? 'error');
-        const logDirEnv = process.env.LOG_DIR;
-        const enabled = logDirEnv !== 'false' && logDirEnv !== '0';
+    static fromConfig(cfg, name) {
+        const level = cfg.level;
+        const dirVal = cfg.dir;
+        const enabled = dirVal !== 'false' && dirVal !== '0';
         let filePath = null;
         if (enabled) {
-            const logDir = logDirEnv || DEFAULT_LOG_DIR;
+            const logDir = dirVal || DEFAULT_LOG_DIR;
             filePath = name
                 ? path.join(logDir, name, `${name}.log`)
                 : path.join(logDir, 'rag.log');
         }
+        return LoggerService.buildFromPath(level, filePath);
+    }
+    static buildFromPath(level, filePath) {
         if (filePath)
             fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const transport = filePath

package/dist/src/services/McpServer.d.ts

@@ -7,6 +7,7 @@ export declare class McpServer {
     private logger;
     constructor(searcher: SearcherService, config: Config, logger?: LoggerService);
     start(startupError?: Error): Promise<void>;
+    private formatGraphContext;
     private formatChunk;
     private formatDependencies;
     private formatDependents;

package/dist/src/services/McpServer.js

@@ -59,6 +59,7 @@ Pick one workflow based on what you need:
 | Type | Signals | Workflow |
 |---|---|---|
 | **Lookup** | "where is X defined", "find Y" | find_symbol (if name known) → search_codebase (if not found) |
+| **Caller trace** | "who calls X", "find usages of Y", "what invokes Z" | find_symbol → get_callers |
 | **Conceptual** | "how does X work", "what is Y" | search_codebase → read_file_range |
 | **Flow audit** | "how does X connect to Y", "audit this flow", "trace the path" | search_codebase → **get_dependencies + get_dependents** → Grep |
 | **Impact** | "what would break if I change X", "what uses Z" | get_dependents → search_codebase for context |
@@ -73,6 +74,7 @@ Pick one workflow based on what you need:
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 - **find_symbol** — find where a symbol (function, class, type, interface, variable, method) is defined by exact name. Faster than semantic search when you know the name.
+- **get_callers** — find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called.
 - **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
 - **read_file** — read a complete file by **absolute path** with line numbers. Truncates at max_lines with a hint to continue.
 
@@ -83,8 +85,9 @@ Pick one workflow based on what you need:
 2. Use \`search_codebase\` to find relevant code by meaning. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
 3. If a result looks **truncated or incomplete**, call \`read_file_range\` with the returned \`file_path\` and \`start_line\`.
 4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`.
-5. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name.
-6. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
+5. To immediately see a file's imports and callers without extra tool calls, pass \`include_graph_context: true\` to \`search_codebase\`. Use this when doing a quick structural survey; switch to \`get_dependencies\`/\`get_dependents\` for full transitive graphs.
+6. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep (requires \`rag-index backfill --calls\` to have been run).
+7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
 
 ### Flow audit (mandatory steps — do not skip 3 and 4)
 1. Use \`list_projects\` to confirm project names.
@@ -131,6 +134,9 @@ class McpServer {
         this.logger = logger;
     }
     async start(startupError) {
+        if (startupError) {
+            this.logger.error('McpServer: startup failed, server will report error on every tool call', { reason: startupError.message });
+        }
         const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: buildInstructions(this.config.search.similarityThreshold) });
         server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             tools: [
@@ -144,6 +150,7 @@ class McpServer {
                             limit: { type: 'number', description: `Max results (default ${this.config.search.defaultLimit}, max ${this.config.search.maxLimit})` },
                             project: { type: 'string', description: 'Filter by project name (optional). Use list_projects to see available names.' },
                             include_neighbors: { type: 'boolean', description: 'Also include the chunk before and after each result from the same file (Small-to-Big retrieval). Useful when results look truncated.' },
+                            include_graph_context: { type: 'boolean', description: 'Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.' },
                             threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.config.search.similarityThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
                         },
                         required: ['query'],
@@ -208,6 +215,19 @@ class McpServer {
                         required: ['name'],
                     },
                 },
+                {
+                    name: 'get_callers',
+                    description: 'Find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called. Returns empty if rag-index backfill --calls has not been run.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            symbol: { type: 'string', description: 'Exact function or method name (case-sensitive)' },
+                            project: { type: 'string', description: 'Project name (from list_projects)' },
+                            callee_file: { type: 'string', description: 'Optional: filter by definition file path (as returned by find_symbol) to disambiguate overloaded names' },
+                        },
+                        required: ['symbol', 'project'],
+                    },
+                },
                 {
                     name: 'list_files',
                     description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
@@ -246,8 +266,10 @@ class McpServer {
                 };
             }
             try {
+                const t0 = Date.now();
                 if (req.params.name === 'list_projects') {
                     const rows = await this.searcher.listProjects();
+                    this.logger.debug('McpServer: list_projects', { count: rows.length, ms: Date.now() - t0 });
                     if (rows.length === 0) {
                         return { content: [{ type: 'text', text: 'No indexed projects found.' }] };
                     }
@@ -273,6 +295,7 @@ class McpServer {
                     const limit = Math.min(Math.max(1, Number(req.params.arguments?.limit) || this.config.search.defaultLimit), this.config.search.maxLimit);
                     const project = req.params.arguments?.project ? String(req.params.arguments.project) : null;
                     const includeNeighbors = Boolean(req.params.arguments?.include_neighbors);
+                    const includeGraphContext = Boolean(req.params.arguments?.include_graph_context);
                     const rawThreshold = req.params.arguments?.threshold;
                     const parsedThreshold = Number(rawThreshold);
                     const threshold = rawThreshold != null && !isNaN(parsedThreshold)
@@ -280,17 +303,30 @@ class McpServer {
                         : undefined;
                     const { query, translated } = await this.searcher.prepareQuery(raw);
                     const results = await this.searcher.searchChunks(query, limit, project, threshold);
+                    this.logger.debug('McpServer: search_codebase', {
+                        query: raw.slice(0, 120),
+                        project,
+                        threshold: threshold ?? this.config.search.similarityThreshold,
+                        limit,
+                        translated,
+                        count: results.length,
+                        ms: Date.now() - t0,
+                    });
                     if (results.length === 0) {
                         return { content: [{ type: 'text', text: 'No relevant results found.' }] };
                     }
                     const header = translated ? `> Query translated: "${raw}" → "${query}"\n\n` : '';
+                    let graphCtx = null;
+                    if (includeGraphContext) {
+                        graphCtx = await this.searcher.fetchGraphContext(results);
+                    }
                     if (includeNeighbors) {
                         const withNeighbors = await this.searcher.fetchNeighbors(results);
                         const blocks = withNeighbors.map(({ result, prevChunk, nextChunk }) => {
                             const parts = [];
                             if (prevChunk)
                                 parts.push(this.formatChunk(prevChunk, 'prev chunk'));
-                            parts.push(`${this.formatChunk(result)}\n**Relevance:** ${result.score}`);
+                            parts.push(`${this.formatChunk(result)}\n**Relevance:** ${result.score}${this.formatGraphContext(graphCtx?.get(result.filePath))}`);
                             if (nextChunk)
                                 parts.push(this.formatChunk(nextChunk, 'next chunk'));
                             return parts.join('\n\n');
@@ -298,7 +334,7 @@ class McpServer {
                         return { content: [{ type: 'text', text: header + blocks.join('\n\n---\n\n') }] };
                     }
                     const text = results
-                        .map(r => `${this.formatChunk(r)}\n**Relevance:** ${r.score}`)
+                        .map(r => `${this.formatChunk(r)}\n**Relevance:** ${r.score}${this.formatGraphContext(graphCtx?.get(r.filePath))}`)
                         .join('\n\n---\n\n');
                     return { content: [{ type: 'text', text: header + text }] };
                 }
@@ -307,6 +343,7 @@ class McpServer {
                     const startLine = Math.max(1, Number(req.params.arguments?.start_line) || 1);
                     const endLine = Number(req.params.arguments?.end_line) || startLine + 99;
                     const range = await this.searcher.readFileRange(filePath, startLine, endLine);
+                    this.logger.debug('McpServer: read_file_range', { file: filePath, startLine, endLine, ok: range.ok, ms: Date.now() - t0 });
                     if (!range.ok) {
                         const message = range.reason === 'invalid_path' ? `Invalid file path (outside workspace): ${filePath}` :
                             range.reason === 'not_indexed' ? `File is not indexed: ${filePath}. Run indexing first.` :
@@ -326,6 +363,7 @@ class McpServer {
                     const symbol = req.params.arguments?.symbol ? String(req.params.arguments.symbol) : null;
                     const transitive = Boolean(req.params.arguments?.transitive);
                     const rows = await this.searcher.getDependencies(filePath, project, symbol, transitive);
+                    this.logger.debug('McpServer: get_dependencies', { file: filePath, project, transitive, count: rows.length, ms: Date.now() - t0 });
                     if (rows.length === 0) {
                         return { content: [{ type: 'text', text: `No dependencies found for: ${filePath}` }] };
                     }
@@ -337,6 +375,7 @@ class McpServer {
                     const symbol = req.params.arguments?.symbol ? String(req.params.arguments.symbol) : null;
                     const transitive = Boolean(req.params.arguments?.transitive);
                     const rows = await this.searcher.getDependents(filePath, project, symbol, transitive);
+                    this.logger.debug('McpServer: get_dependents', { file: filePath, project, symbol, transitive, count: rows.length, ms: Date.now() - t0 });
                     if (rows.length > 0) {
                         return { content: [{ type: 'text', text: this.formatDependents(filePath, rows, transitive) }] };
                     }
@@ -367,6 +406,7 @@ class McpServer {
                     const validKinds = ['function', 'class', 'type', 'interface', 'variable', 'method', 'all'];
                     const kind = validKinds.includes(rawKind) ? rawKind : 'all';
                     const { hits, truncated } = await this.searcher.findSymbol(name, project, kind);
+                    this.logger.debug('McpServer: find_symbol', { name, kind, project, count: hits.length, ms: Date.now() - t0 });
                     if (hits.length === 0) {
                         return { content: [{ type: 'text', text: `No definitions found for symbol: ${name}` }] };
                     }
@@ -386,6 +426,7 @@ class McpServer {
                     const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
                     const pattern = req.params.arguments?.pattern ? String(req.params.arguments.pattern) : null;
                     const { tree, error } = this.searcher.listFiles(relPath, project, depth, pattern);
+                    this.logger.debug('McpServer: list_files', { path: relPath, project, depth, ms: Date.now() - t0 });
                     if (error) {
                         return { content: [{ type: 'text', text: `list_files error: ${error}` }] };
                     }
@@ -396,6 +437,7 @@ class McpServer {
                     const rawMax = Number(req.params.arguments?.max_lines);
                     const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
                     const result = await this.searcher.readFileAbsolute(filePath, maxLines);
+                    this.logger.debug('McpServer: read_file', { file: filePath, maxLines, ok: result.ok, ms: Date.now() - t0 });
                     if (!result.ok) {
                         const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
                             `File not found on disk: ${filePath}`;
@@ -408,6 +450,23 @@ class McpServer {
                     }
                     return { content: [{ type: 'text', text }] };
                 }
+                if (req.params.name === 'get_callers') {
+                    const symbol = String(req.params.arguments?.symbol ?? '');
+                    const project = String(req.params.arguments?.project ?? '');
+                    const calleeFile = req.params.arguments?.callee_file ? String(req.params.arguments.callee_file) : null;
+                    const rows = await this.searcher.getCallers(symbol, project, calleeFile);
+                    this.logger.debug('McpServer: get_callers', { symbol, project, count: rows.length, ms: Date.now() - t0 });
+                    if (rows.length === 0) {
+                        return { content: [{ type: 'text', text: `No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index backfill --calls\` if the call graph has not been populated yet.` }] };
+                    }
+                    const lines = [`**Call sites of \`${symbol}\`** (${rows.length} found)\n`];
+                    for (const r of rows) {
+                        const loc = r.line != null ? ` line ${r.line}` : '';
+                        const ctx = r.fromSymbol ? `, in \`${r.fromSymbol}\`` : '';
+                        lines.push(`  → \`${r.fromFile}\`${loc}${ctx}`);
+                    }
+                    return { content: [{ type: 'text', text: lines.join('\n') }] };
+                }
                 throw new Error(`Unknown tool: ${req.params.name}`);
             }
             catch (err) {
@@ -416,6 +475,15 @@ class McpServer {
             }
         });
         await server.connect(new stdio_js_1.StdioServerTransport());
+        this.logger.info('McpServer: started', { version: PKG_VERSION });
+    }
+    formatGraphContext(ctx) {
+        const parts = [];
+        if (ctx?.imports.length)
+            parts.push(`**Imports:** ${ctx.imports.join(' · ')}`);
+        if (ctx?.usedBy.length)
+            parts.push(`**Used by:** ${ctx.usedBy.join(' · ')}`);
+        return parts.length > 0 ? '\n' + parts.join('\n') : '';
     }
     formatChunk(r, label) {
         return `${label ? `*(${label})*\n` : ''}**File:** ${r.filePath}\n**Project:** ${r.serviceName}\n**Line:** ${r.startLine}\n\`\`\`\n${r.content}\n\`\`\``;

package/dist/src/services/OllamaEmbedder.d.ts

@@ -3,7 +3,9 @@ import type { IEmbedder } from '../interfaces/IEmbedder';
 export declare class OllamaEmbedder implements IEmbedder {
     private config;
     private client;
+    rerank?: (query: string, documents: string[], topN: number) => Promise<number[]>;
     constructor(config: Config);
     embed(text: string): Promise<number[]>;
     translate(text: string, model: string): Promise<string>;
+    private _rerank;
 }

package/dist/src/services/OllamaEmbedder.js

@@ -5,9 +5,18 @@ const ollama_1 = require("ollama");
 class OllamaEmbedder {
     config;
     client;
+    rerank;
     constructor(config) {
         this.config = config;
         this.client = new ollama_1.Ollama({ host: config.ollama.host });
+        if (config.search.rerankerEnabled) {
+            if (config.ollama.rerankerModel) {
+                this.rerank = this._rerank.bind(this);
+            }
+            else {
+                console.warn('[OllamaEmbedder] RERANKER_ENABLED=true but RERANKER_MODEL is not set — reranking disabled');
+            }
+        }
     }
     async embed(text) {
         const { embedding } = await this.client.embeddings({
@@ -23,5 +32,25 @@ class OllamaEmbedder {
         });
         return response.message.content.trim();
     }
+    async _rerank(query, documents, topN) {
+        const res = await fetch(this.config.ollama.rerankerUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(30_000),
+            body: JSON.stringify({
+                model: this.config.ollama.rerankerModel,
+                query,
+                documents,
+                top_n: topN,
+                truncate: true,
+            }),
+        });
+        if (!res.ok) {
+            const body = (await res.text().catch(() => res.statusText)).slice(0, 200);
+            throw new Error(`Ollama rerank failed: ${res.status} ${body}`);
+        }
+        const data = await res.json();
+        return data.results.map(r => r.index);
+    }
 }
 exports.OllamaEmbedder = OllamaEmbedder;

package/dist/src/services/SearcherService.d.ts

@@ -17,6 +17,10 @@ export interface NeighborResult {
     prevChunk: ChunkRow | null;
     nextChunk: ChunkRow | null;
 }
+export interface GraphContext {
+    imports: string[];
+    usedBy: string[];
+}
 export type FileRangeResult = {
     ok: true;
     filePath: string;
@@ -46,6 +50,13 @@ export interface GrepMatch {
     line: number;
 }
 export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'all';
+export interface CallerRow {
+    fromFile: string;
+    fromSymbol: string | null;
+    calleeName: string;
+    calleeFile: string;
+    line: number | null;
+}
 export interface SymbolHit {
     filePath: string;
     line: number;
@@ -66,8 +77,10 @@ export declare class SearcherService {
     listProjects(): Promise<ProjectRow[]>;
     searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
+    fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
     getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
     grepSymbol(symbol: string, project: string, excludeFile: string): {
         matches: GrepMatch[];
         truncated: boolean;