codesearch-mcp 0.0.8-alpha → 0.0.10-alpha

package/dist/src/db/entities/code-symbol.entity.js

@@ -0,0 +1,59 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeSymbol = void 0;
+const typeorm_1 = require("typeorm");
+let CodeSymbol = class CodeSymbol {
+    id;
+    project;
+    filePath;
+    name;
+    kind;
+    signature;
+    line;
+    col;
+};
+exports.CodeSymbol = CodeSymbol;
+__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    __metadata("design:type", String)
+], CodeSymbol.prototype, "id", void 0);
+__decorate([
+    (0, typeorm_1.Column)(),
+    __metadata("design:type", String)
+], CodeSymbol.prototype, "project", void 0);
+__decorate([
+    (0, typeorm_1.Column)(),
+    __metadata("design:type", String)
+], CodeSymbol.prototype, "filePath", void 0);
+__decorate([
+    (0, typeorm_1.Column)(),
+    __metadata("design:type", String)
+], CodeSymbol.prototype, "name", void 0);
+__decorate([
+    (0, typeorm_1.Column)(),
+    __metadata("design:type", String)
+], CodeSymbol.prototype, "kind", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'text', nullable: true }),
+    __metadata("design:type", Object)
+], CodeSymbol.prototype, "signature", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    __metadata("design:type", Object)
+], CodeSymbol.prototype, "line", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    __metadata("design:type", Object)
+], CodeSymbol.prototype, "col", void 0);
+exports.CodeSymbol = CodeSymbol = __decorate([
+    (0, typeorm_1.Entity)()
+], CodeSymbol);

package/dist/src/db/index.d.ts

@@ -1,4 +1,3 @@
 export { CodeChunk } from './entities/code-chunk.entity';
 export { CodeDependency } from './entities/code-dependency.entity';
-export { db } from './data-source';
-export { initDb, initDbWithSchema } from './init';
+export { CodeSymbol } from './entities/code-symbol.entity';

package/dist/src/db/index.js

@@ -1,12 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initDbWithSchema = exports.initDb = exports.db = exports.CodeDependency = exports.CodeChunk = void 0;
+exports.CodeSymbol = exports.CodeDependency = exports.CodeChunk = void 0;
 var code_chunk_entity_1 = require("./entities/code-chunk.entity");
 Object.defineProperty(exports, "CodeChunk", { enumerable: true, get: function () { return code_chunk_entity_1.CodeChunk; } });
 var code_dependency_entity_1 = require("./entities/code-dependency.entity");
 Object.defineProperty(exports, "CodeDependency", { enumerable: true, get: function () { return code_dependency_entity_1.CodeDependency; } });
-var data_source_1 = require("./data-source");
-Object.defineProperty(exports, "db", { enumerable: true, get: function () { return data_source_1.db; } });
-var init_1 = require("./init");
-Object.defineProperty(exports, "initDb", { enumerable: true, get: function () { return init_1.initDb; } });
-Object.defineProperty(exports, "initDbWithSchema", { enumerable: true, get: function () { return init_1.initDbWithSchema; } });
+var code_symbol_entity_1 = require("./entities/code-symbol.entity");
+Object.defineProperty(exports, "CodeSymbol", { enumerable: true, get: function () { return code_symbol_entity_1.CodeSymbol; } });

package/dist/src/file-utils.d.ts

@@ -6,7 +6,8 @@ export interface ProjectMeta {
     notes: string | null;
     relations: Relations | null;
 }
-export declare function readRagMeta(projectDir: string): ProjectMeta | null;
+export type RagMetaResult = ProjectMeta | 'missing' | 'invalid';
+export declare function readRagMeta(projectDir: string): RagMetaResult;
 export declare const IGNORE_DIRS: Set<string>;
 export declare function loadIgnore(projectDir: string): ReturnType<typeof ignore>;
 export declare function collectFiles(dir: string, ig: ReturnType<typeof ignore>, rootDir: string): string[];

package/dist/src/file-utils.js

@@ -43,12 +43,10 @@ exports.collectFiles = collectFiles;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const ignore_1 = __importDefault(require("ignore"));
-// Returns null if file is missing or contains invalid JSON.
-// Returns ProjectMeta (fields may be null) if file exists and parses correctly.
 function readRagMeta(projectDir) {
     const metaPath = path.join(projectDir, '.ragmeta.json');
     if (!fs.existsSync(metaPath))
-        return null;
+        return 'missing';
     try {
         const raw = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
         return {
@@ -59,7 +57,7 @@ function readRagMeta(projectDir) {
         };
     }
     catch {
-        return null;
+        return 'invalid';
     }
 }
 exports.IGNORE_DIRS = new Set([
@@ -79,7 +77,14 @@ function loadIgnore(projectDir) {
 }
 function collectFiles(dir, ig, rootDir) {
     const result = [];
-    for (const file of fs.readdirSync(dir)) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return result;
+    }
+    for (const file of entries) {
         const fullPath = path.join(dir, file);
         const relPath = path.relative(rootDir, fullPath);
         if (ig.ignores(relPath))

package/dist/src/graph.js

@@ -243,10 +243,11 @@ function buildHtml(nodes, edges) {
 }
 // Single entry point — reads meta once, prints console summary and writes HTML
 function generateProjectGraph(projects, workspacePath) {
-    const nodes = projects.map(p => ({
-        name: p.name,
-        ...((0, file_utils_1.readRagMeta)(p.path) ?? { description: null, stack: null, notes: null, relations: null }),
-    }));
+    const EMPTY = { description: null, stack: null, notes: null, relations: null };
+    const nodes = projects.map(p => {
+        const meta = (0, file_utils_1.readRagMeta)(p.path);
+        return { name: p.name, ...(typeof meta === 'object' ? meta : EMPTY) };
+    });
     const edges = buildEdges(nodes);
     printConsole(nodes, edges, workspacePath);
     const htmlPath = path.join(workspacePath, 'project-graph.html');

package/dist/src/help.js

@@ -19,7 +19,7 @@ function printHelp(command) {
             console.log('  -h, --help        Show this help message');
             console.log('');
             console.log('Subcommands:');
-            console.log('  backfill          Populate dependency graph for already-indexed files');
+            console.log('  backfill          Populate symbol index (code_symbol) for already-indexed files');
             break;
         case 'rag-mcp':
         case 'mcp':

package/dist/src/indexer.js

@@ -236,6 +236,7 @@ async function scanAndIndex(dir, serviceName, force = false, signal, preCollecte
         bar.increment();
     }
     bar.stop();
+    process.stdout.write('\x1B[J'); // erase any blank lines cli-progress left below the bar
     stats.elapsedSec = Math.round((Date.now() - startTime) / 100) / 10;
     return stats;
 }

package/dist/src/interfaces/IAstParser.d.ts

@@ -0,0 +1,24 @@
+export interface DepEdge {
+    project: string;
+    fromFile: string;
+    fromSymbol: string | null;
+    toFile: string;
+    toSymbol: string | null;
+    depType: string;
+}
+export interface SymbolEntry {
+    project: string;
+    filePath: string;
+    name: string;
+    kind: 'function' | 'class' | 'interface' | 'type' | 'variable';
+    signature: string | null;
+    line: number | null;
+    col: number | null;
+}
+export interface FileAnalysis {
+    edges: DepEdge[];
+    symbols: SymbolEntry[];
+}
+export interface IAstParser {
+    analyzeFile(filePath: string, serviceName: string, projectRoot?: string): Promise<FileAnalysis>;
+}

package/dist/src/interfaces/IAstParser.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interfaces/IEmbedder.d.ts

@@ -0,0 +1,4 @@
+export interface IEmbedder {
+    embed(text: string): Promise<number[]>;
+    translate?(text: string, model: string): Promise<string>;
+}

package/dist/src/interfaces/IEmbedder.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/interrupt.d.ts

@@ -1,3 +1 @@
-export declare const signal: AbortSignal;
-export declare function setupInterrupt(): void;
-export declare function teardownInterrupt(): void;
+export declare function setupInterrupt(controller: AbortController): () => void;

package/dist/src/interrupt.js

@@ -1,27 +1,25 @@
 "use strict";
-// Graceful interruption signal for long-running CLI operations.
-// Listens for ESC or Ctrl+C on stdin and aborts the shared controller.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.signal = void 0;
 exports.setupInterrupt = setupInterrupt;
-exports.teardownInterrupt = teardownInterrupt;
-const controller = new AbortController();
-exports.signal = controller.signal;
-function setupInterrupt() {
+// Graceful interruption for long-running CLI operations.
+// Caller creates the AbortController; this function wires stdin and returns a cleanup function.
+function setupInterrupt(controller) {
     if (!process.stdin.isTTY)
-        return;
+        return () => { };
     process.stdin.setRawMode(true);
     process.stdin.resume();
     process.stdin.setEncoding('utf8');
-    process.stdin.on('data', (key) => {
+    const handler = (key) => {
         if (key === '\x1b' || key === '\x03')
             controller.abort();
-    });
+    };
+    process.stdin.on('data', handler);
     console.log('Press ESC or Ctrl+C to interrupt.\n');
-}
-function teardownInterrupt() {
-    if (!process.stdin.isTTY)
-        return;
-    process.stdin.setRawMode(false);
-    process.stdin.pause();
+    return () => {
+        process.stdin.off('data', handler);
+        if (process.stdin.isTTY) {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+        }
+    };
 }

package/dist/src/mcp.js

@@ -64,8 +64,11 @@ You have access to a local semantic code search server. Use these tools to navig
 
 1. Use \`list_projects\` to discover available projects before filtering by \`project\`.
 2. Use \`search_codebase\` to find relevant code by meaning.
-3. If a result looks **truncated or incomplete** (e.g. you see only the middle of a function), call \`read_file_range\` with the returned \`file_path\` and lines around \`startLine\` to get the full picture.
+3. If a result looks **truncated or incomplete** (e.g. you see only the middle of a function), call \`read_file_range\` with the returned \`file_path\` and \`start_line\` set to the **Line** number shown in the result. Example: if the result shows **Line:** 150, pass \`start_line: 150\`.
 4. For exploratory searches where you expect results to span chunk boundaries, pass \`include_neighbors: true\` to automatically include the chunk before and after each match.
+5. Use \`find_symbol\` when you know the exact name of a function or class and want its definition location immediately — faster than semantic search.
+6. Use \`list_files\` to explore project structure (src/, components/, etc.) before diving into files.
+7. Use \`read_file\` to read a complete file when you have its absolute path from \`search_codebase\` results.
 
 ## When to use read_file_range vs include_neighbors
 
@@ -84,6 +87,9 @@ Lower score = better match (cosine distance). Results above the configured thres
 
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use when you need 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 and avoid breaking changes.
+- **find_symbol** — find where a symbol (function, class, type, interface, variable) is defined by exact name. Faster than semantic search when you know the name.
+- **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.
 
 Both tools require \`file_path\` (as returned by \`search_codebase\`) and \`project\` (from \`list_projects\`). Pass \`transitive: true\` for the full dependency chain.
 `.trim();
@@ -153,8 +159,8 @@ async function startMCP() {
                     type: 'object',
                     properties: {
                         file_path: { type: 'string', description: 'File path as returned by search_codebase' },
-                        start_line: { type: 'number', description: 'First line to read (1-based, inclusive). Default: 1' },
-                        end_line: { type: 'number', description: 'Last line to read (1-based, inclusive). Default: start_line + 99' },
+                        start_line: { type: 'number', description: 'First line to read (1-based). Use the **Line** number from search_codebase results. Default: 1.' },
+                        end_line: { type: 'number', description: 'Last line to read (1-based, inclusive). Default: start_line + 99.' },
                     },
                     required: ['file_path'],
                 },
@@ -187,6 +193,45 @@ async function startMCP() {
                     required: ['file_path', 'project'],
                 },
             },
+            {
+                name: 'find_symbol',
+                description: 'Find TypeScript/JavaScript symbol definitions (functions, classes, types, interfaces, variables) by exact name. Use when you know the symbol name and want its definition location fast.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string', description: 'Exact symbol name (case-sensitive, whole-word match)' },
+                        project: { type: 'string', description: 'Limit search to this project (optional). Use list_projects to find names.' },
+                        kind: { type: 'string', enum: ['function', 'class', 'type', 'interface', 'variable', 'all'], description: 'Symbol kind filter. Default: all.' },
+                    },
+                    required: ['name'],
+                },
+            },
+            {
+                name: 'list_files',
+                description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'Directory path relative to the project root (e.g. "src/components" or "." for root)' },
+                        project: { type: 'string', description: 'Project name (from list_projects)' },
+                        depth: { type: 'number', description: 'Tree depth: 1 = immediate children only, up to 5. Default: 2.' },
+                        pattern: { type: 'string', description: 'Optional filename filter (substring or extension like ".ts"). Only matching files are shown.' },
+                    },
+                    required: ['path', 'project'],
+                },
+            },
+            {
+                name: 'read_file',
+                description: 'Read a file from the workspace by absolute path (as returned by search_codebase). Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        file_path: { type: 'string', description: 'Absolute path to the file (as returned in filePath by search_codebase)' },
+                        max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
+                    },
+                    required: ['file_path'],
+                },
+            },
         ],
     }));
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
@@ -254,12 +299,11 @@ async function startMCP() {
                     return { content: [{ type: 'text', text: message }] };
                 }
                 const numbered = range.lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
-                return {
-                    content: [{
-                            type: 'text',
-                            text: `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``,
-                        }],
-                };
+                let text = `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+                if (range.hasMore) {
+                    text += `\n\n[file has more lines — call read_file_range again with start_line: ${range.endLine + 1}]`;
+                }
+                return { content: [{ type: 'text', text }] };
             }
             if (req.params.name === 'get_dependencies') {
                 const filePath = String(req.params.arguments?.file_path);
@@ -301,6 +345,54 @@ async function startMCP() {
                 }
                 return { content: [{ type: 'text', text: header + fallbackLines.join('\n') }] };
             }
+            if (req.params.name === 'find_symbol') {
+                const name = String(req.params.arguments?.name ?? '');
+                const project = req.params.arguments?.project ? String(req.params.arguments.project) : null;
+                const rawKind = req.params.arguments?.kind;
+                const validKinds = ['function', 'class', 'type', 'interface', 'variable', 'all'];
+                const kind = validKinds.includes(rawKind) ? rawKind : 'all';
+                const { hits, truncated } = (0, searcher_1.findSymbol)(name, project, kind);
+                if (hits.length === 0) {
+                    return { content: [{ type: 'text', text: `No definitions found for symbol: ${name}` }] };
+                }
+                const lines = [];
+                if (truncated)
+                    lines.push(`*(truncated to ${hits.length} results)*\n`);
+                for (const h of hits) {
+                    lines.push(`**${h.kind}** \`${h.filePath}\` line ${h.line}, col ${h.column}`);
+                    lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            if (req.params.name === 'list_files') {
+                const relPath = String(req.params.arguments?.path ?? '.');
+                const project = String(req.params.arguments?.project ?? '');
+                const rawDepth = Number(req.params.arguments?.depth);
+                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 } = (0, searcher_1.listFiles)(relPath, project, depth, pattern);
+                if (error) {
+                    return { content: [{ type: 'text', text: `list_files error: ${error}` }] };
+                }
+                return { content: [{ type: 'text', text: `**${project}/${relPath}**\n\`\`\`\n${tree}\n\`\`\`` }] };
+            }
+            if (req.params.name === 'read_file') {
+                const filePath = String(req.params.arguments?.file_path ?? '');
+                const rawMax = Number(req.params.arguments?.max_lines);
+                const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
+                const result = await (0, searcher_1.readFileAbsolute)(filePath, maxLines);
+                if (!result.ok) {
+                    const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
+                        `File not found on disk: ${filePath}`;
+                    return { content: [{ type: 'text', text: message }] };
+                }
+                const numbered = result.lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
+                let text = `**File:** ${result.filePath}\n**Lines:** 1–${result.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+                if (result.hasMore) {
+                    text += `\n\n[truncated: file has more lines — use read_file_range with file_path: "${result.filePath}", start_line: ${result.endLine + 1} to continue]`;
+                }
+                return { content: [{ type: 'text', text }] };
+            }
             throw new Error(`Unknown tool: ${req.params.name}`);
         }
         catch (err) {

package/dist/src/searcher.d.ts

@@ -19,6 +19,7 @@ export type FileRangeResult = {
     startLine: number;
     endLine: number;
     lines: string[];
+    hasMore: boolean;
 } | {
     ok: false;
     reason: 'not_indexed' | 'not_on_disk' | 'invalid_path';
@@ -53,4 +54,21 @@ export declare function grepSymbol(symbol: string, project: string, excludeFile:
     matches: GrepMatch[];
     truncated: boolean;
 };
+export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'all';
+export interface SymbolHit {
+    filePath: string;
+    line: number;
+    column: number;
+    kind: Exclude<SymbolKind, 'all'>;
+    signature: string;
+}
+export declare function findSymbol(name: string, project: string | null, kind: SymbolKind): {
+    hits: SymbolHit[];
+    truncated: boolean;
+};
+export declare function listFiles(relativePath: string, project: string, depth: number, pattern: string | null): {
+    tree: string;
+    error?: string;
+};
+export declare function readFileAbsolute(absPath: string, maxLines: number): Promise<FileRangeResult>;
 export declare function readFileRange(filePath: string, startLine: number, endLine: number): Promise<FileRangeResult>;

package/dist/src/searcher.js

@@ -40,6 +40,9 @@ exports.fetchNeighbors = fetchNeighbors;
 exports.getDependencies = getDependencies;
 exports.getDependents = getDependents;
 exports.grepSymbol = grepSymbol;
+exports.findSymbol = findSymbol;
+exports.listFiles = listFiles;
+exports.readFileAbsolute = readFileAbsolute;
 exports.readFileRange = readFileRange;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -240,6 +243,171 @@ function grepSymbol(symbol, project, excludeFile) {
     });
     return { matches: all.slice(0, GREP_MAX_RESULTS), truncated: all.length > GREP_MAX_RESULTS };
 }
+const FIND_SYMBOL_LIMIT = 50;
+const FIND_SYMBOL_RAW_LIMIT = FIND_SYMBOL_LIMIT * 10;
+function buildFindSymbolPattern(name, kind) {
+    const patterns = {
+        function: `(export[[:space:]]+)?(async[[:space:]]+)?function[[:space:]]+${name}[[:space:](<]`,
+        class: `(export[[:space:]]+)?(abstract[[:space:]]+)?class[[:space:]]+${name}[[:space:]{<]`,
+        type: `(export[[:space:]]+)?type[[:space:]]+${name}[[:space:]=<]`,
+        interface: `(export[[:space:]]+)?interface[[:space:]]+${name}[[:space:]{<]`,
+        variable: `(export[[:space:]]+)?(const|let|var)[[:space:]]+${name}[[:space:]=:]`,
+    };
+    if (kind === 'all')
+        return Object.values(patterns).join('|');
+    return patterns[kind];
+}
+function inferKind(line, name) {
+    const before = line.slice(0, line.indexOf(name));
+    if (/\bfunction\s+$/.test(before))
+        return 'function';
+    if (/\bclass\s+$/.test(before))
+        return 'class';
+    if (/\binterface\s+$/.test(before))
+        return 'interface';
+    if (/\btype\s+$/.test(before))
+        return 'type';
+    return 'variable';
+}
+function findSymbol(name, project, kind) {
+    if (!/^[\w$]+$/.test(name))
+        throw new Error('Invalid symbol name');
+    const searchDir = project
+        ? path.join(config_1.config.workspaceRoot, project)
+        : config_1.config.workspaceRoot;
+    const pattern = buildFindSymbolPattern(name, kind);
+    const result = (0, child_process_1.spawnSync)('grep', [
+        '-rn', '-E',
+        '-m', String(FIND_SYMBOL_RAW_LIMIT),
+        '--include=*.ts', '--include=*.tsx', '--include=*.js', '--include=*.jsx',
+        ...GREP_EXCLUDE_DIRS,
+        pattern,
+        searchDir,
+    ], { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    if (result.error) {
+        console.error(`[findSymbol] grep failed: ${result.error.message}`);
+        return { hits: [], truncated: false };
+    }
+    if (!result.stdout)
+        return { hits: [], truncated: false };
+    const hits = [];
+    for (const raw of result.stdout.split('\n')) {
+        if (hits.length >= FIND_SYMBOL_LIMIT)
+            break;
+        // grep -n format: "/abs/path/file.ts:42:   export function Foo(...)"
+        // File paths can contain colons on some systems, so split carefully:
+        // find first colon after a path separator, use lastIndexOf on the line number part
+        const m = raw.match(/^(.+?):(\d+):(.*)$/);
+        if (!m)
+            continue;
+        const [, absFile, lineNumStr, matchedLine] = m;
+        const lineNum = parseInt(lineNumStr, 10);
+        if (isNaN(lineNum))
+            continue;
+        const col = matchedLine.indexOf(name);
+        if (col === -1)
+            continue;
+        hits.push({
+            filePath: path.relative(config_1.config.workspaceRoot, absFile),
+            line: lineNum,
+            column: col + 1,
+            kind: inferKind(matchedLine, name),
+            signature: matchedLine.trim(),
+        });
+    }
+    return { hits, truncated: hits.length >= FIND_SYMBOL_LIMIT };
+}
+// ── list_files ────────────────────────────────────────────────────────────────
+function walkDir(absDir, currentDepth, maxDepth, pattern, lines) {
+    let entries;
+    try {
+        entries = fs.readdirSync(absDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => {
+        const ad = a.isDirectory() ? 0 : 1;
+        const bd = b.isDirectory() ? 0 : 1;
+        if (ad !== bd)
+            return ad - bd;
+        return a.name.localeCompare(b.name);
+    });
+    for (const entry of entries) {
+        if (file_utils_1.IGNORE_DIRS.has(entry.name))
+            continue;
+        const indent = '  '.repeat(currentDepth);
+        if (entry.isDirectory()) {
+            lines.push(`${indent}${entry.name}/`);
+            if (currentDepth < maxDepth) {
+                walkDir(path.join(absDir, entry.name), currentDepth + 1, maxDepth, pattern, lines);
+            }
+        }
+        else {
+            if (pattern && !entry.name.includes(pattern))
+                continue;
+            lines.push(`${indent}${entry.name}`);
+        }
+    }
+}
+function listFiles(relativePath, project, depth, pattern) {
+    const projectRoot = path.join(config_1.config.workspaceRoot, project);
+    const resolvedTarget = path.resolve(projectRoot, relativePath);
+    const resolvedProject = path.resolve(projectRoot);
+    if (resolvedTarget !== resolvedProject && !resolvedTarget.startsWith(resolvedProject + path.sep)) {
+        return { tree: '', error: 'Path escapes project root' };
+    }
+    if (!fs.existsSync(resolvedTarget)) {
+        return { tree: '', error: `Path not found: ${relativePath}` };
+    }
+    if (!fs.statSync(resolvedTarget).isDirectory()) {
+        return { tree: '', error: `Not a directory: ${relativePath}` };
+    }
+    const clampedDepth = Math.min(5, Math.max(1, depth));
+    const lines = [];
+    walkDir(resolvedTarget, 0, clampedDepth - 1, pattern, lines);
+    if (lines.length === 0) {
+        return { tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
+    }
+    return { tree: lines.join('\n') };
+}
+// ── readFileAbsolute ──────────────────────────────────────────────────────────
+// Variant of readFileRange that accepts an absolute path and skips the DB index check.
+// Used by the read_file MCP tool, which receives absolute paths from search_codebase.
+async function readFileAbsolute(absPath, maxLines) {
+    const resolvedRoot = path.resolve(config_1.config.workspaceRoot);
+    const resolved = path.resolve(absPath);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+        return { ok: false, reason: 'invalid_path' };
+    }
+    if (!fs.existsSync(resolved))
+        return { ok: false, reason: 'not_on_disk' };
+    const lines = [];
+    const stream = fs.createReadStream(resolved, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    let lineNo = 0;
+    let hasMore = false;
+    try {
+        for await (const line of rl) {
+            lineNo++;
+            if (lineNo <= maxLines)
+                lines.push(line);
+            if (lineNo >= maxLines) {
+                hasMore = true;
+                rl.close();
+                stream.destroy();
+                break;
+            }
+        }
+    }
+    catch (err) {
+        rl.close();
+        stream.destroy();
+        throw err;
+    }
+    const relPath = path.relative(resolvedRoot, resolved);
+    return { ok: true, filePath: relPath, startLine: 1, endLine: lineNo, lines, hasMore };
+}
 // Read a line range from a file that is present in the index
 async function readFileRange(filePath, startLine, endLine) {
     // Defensive: reject paths that escape the workspace root (e.g. "../../etc/passwd")
@@ -260,17 +428,19 @@ async function readFileRange(filePath, startLine, endLine) {
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
     let lineNo = 0;
     let lastRead = 0;
+    let hasMore = false;
     for await (const line of rl) {
         lineNo++;
         lastRead = lineNo;
         if (lineNo >= startLine && lineNo <= endLine)
             lines.push(line);
         if (lineNo >= endLine) {
+            hasMore = true;
             rl.close();
             stream.destroy();
             break;
         }
     }
     // If we broke out early, lastRead is endLine. If file was shorter, lastRead is file length.
-    return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines };
+    return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
 }