codesearch-mcp 0.0.8-alpha → 0.0.9-alpha

package/dist/app.js

@@ -64,15 +64,14 @@ function printSummary(allStats) {
     console.log('TOTAL'.padEnd(cols.name), String(total.indexed).padStart(cols.num), String(total.skipped).padStart(cols.num), String(total.failed).padStart(cols.num), String(total.chunks).padStart(cols.num), String(total.elapsedSec.toFixed(1)).padStart(cols.num));
     // Reprint warnings at the end — progress bar activity scrolls per-project warnings out of
     // view, so we collect them on IndexStats and surface them here as an explicit section.
-    const projectsWithWarnings = allStats.filter(s => s.warnings.length > 0);
-    if (projectsWithWarnings.length > 0) {
-        console.log('\n=== Warnings ===');
-        for (const s of projectsWithWarnings) {
-            console.log(`\n${s.serviceName}:`);
-            for (const w of s.warnings)
-                console.log(`  ⚠ ${w}`);
-        }
-    }
+    // const projectsWithWarnings = allStats.filter(s => s.warnings.length > 0);
+    // if (projectsWithWarnings.length > 0) {
+    //   console.log('\n=== Warnings ===');
+    //   for (const s of projectsWithWarnings) {
+    //     console.log(`\n${s.serviceName}:`);
+    //     for (const w of s.warnings) console.log(`  ⚠ ${w}`);
+    //   }
+    // }
 }
 async function main() {
     const argv1 = path.basename(process.argv[1] ?? '');

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/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 };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.0.8-alpha",
+  "version": "0.0.9-alpha",
   "description": "Local semantic codebase search via MCP — indexes projects into pgvector, exposes search to Claude",
   "license": "MIT",
   "main": "dist/app.js",