codesearch-mcp 0.0.17-alpha → 0.0.18-alpha

package/dist/src/setup.js

@@ -79,7 +79,7 @@ async function waitForDb(host, port, user, pass, db, maxWaitSec = 60, logger, st
     }
     const reason = 'PostgreSQL did not become ready in time.';
     console.error(`\n${reason}`);
-    logger?.error('waitForDb: timeout', { reason, steps });
+    logger?.error('waitForDb: timeout', { reason, steps: JSON.stringify(steps) });
     process.exit(1);
 }
 async function waitForOllama(host, maxWaitSec = 60, logger, steps) {
@@ -106,7 +106,7 @@ async function waitForOllama(host, maxWaitSec = 60, logger, steps) {
     }
     const reason = 'Ollama did not become ready in time.';
     console.error(`\n${reason}`);
-    logger?.error('waitForOllama: timeout', { reason, steps });
+    logger?.error('waitForOllama: timeout', { reason, steps: JSON.stringify(steps) });
     process.exit(1);
 }
 async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
@@ -120,7 +120,7 @@ async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`  Connection failed: ${msg}`);
-        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps });
+        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps: JSON.stringify(steps) });
         return false;
     }
 }
@@ -139,7 +139,7 @@ async function startDockerContainers(ollamaHost, dbPort, dbUser, dbPass, logger,
     if (upResult.status !== 0) {
         const reason = 'Failed to start Docker containers. Make sure Docker is running.';
         console.error(reason);
-        logger?.error('startDockerContainers: docker startup failed', { reason, steps });
+        logger?.error('startDockerContainers: docker startup failed', { reason, steps: JSON.stringify(steps) });
         process.exit(1);
     }
     await waitForDb('localhost', parseInt(dbPort), dbUser, dbPass, 'postgres', 60, logger, steps);
@@ -150,7 +150,7 @@ async function startDockerContainers(ollamaHost, dbPort, dbUser, dbPass, logger,
         const reason = 'Could not resolve ollama container ID from compose. Pull the model manually:';
         console.error(reason);
         console.error(`  docker exec <ollama-container> ollama pull ${constants_1.DEFAULT_EMBED_MODEL}`);
-        logger?.error('startDockerContainers: ollama container not found', { reason, steps });
+        logger?.error('startDockerContainers: ollama container not found', { reason, steps: JSON.stringify(steps) });
         process.exit(1);
     }
     console.log(`Pulling ${constants_1.DEFAULT_EMBED_MODEL} model (this may take a while)...`);
@@ -266,11 +266,11 @@ async function runSetup(logger) {
     }
     if (initError) {
         console.error(`Database schema init failed: ${initError.message}`);
-        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps });
+        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps: JSON.stringify(steps) });
         process.exit(1);
     }
     console.log('\nSetup complete!');
     console.log('\nNext steps:');
-    console.log(`  rag-index ${workspaceRoot}`);
+    console.log('  rag-index');
     console.log('  claude mcp add codesearch-mcp -s user -- rag-mcp');
 }

package/dist/src/tools/FindSymbolTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class FindSymbolTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/FindSymbolTool.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FindSymbolTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+const VALID_KINDS = ['function', 'class', 'type', 'interface', 'variable', 'method', 'all'];
+class FindSymbolTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'find_symbol',
+            description: 'Find TypeScript/JavaScript symbol definitions (functions, classes, types, interfaces, variables, methods) 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: VALID_KINDS, description: 'Symbol kind filter. Default: all.' },
+                },
+                required: ['name'],
+            },
+        };
+    }
+    async handle(args) {
+        const name = String(args.name ?? '');
+        const project = args.project ? String(args.project) : null;
+        const rawKind = args.kind;
+        const kind = VALID_KINDS.includes(rawKind) ? rawKind : 'all';
+        const { hits, truncated } = await this.searcher.findSymbol(name, project, kind);
+        if (hits.length === 0) {
+            return (0, format_helpers_1.textResponse)(`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 (0, format_helpers_1.textResponse)(lines.join('\n'));
+    }
+}
+exports.FindSymbolTool = FindSymbolTool;

package/dist/src/tools/GetCallersTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class GetCallersTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/GetCallersTool.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetCallersTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class GetCallersTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            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'],
+            },
+        };
+    }
+    async handle(args) {
+        const symbol = String(args.symbol ?? '');
+        const project = String(args.project ?? '');
+        const calleeFile = args.callee_file ? String(args.callee_file) : null;
+        const rows = await this.searcher.getCallers(symbol, project, calleeFile);
+        if (rows.length === 0) {
+            return (0, format_helpers_1.textResponse)(`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 (0, format_helpers_1.textResponse)(lines.join('\n'));
+    }
+}
+exports.GetCallersTool = GetCallersTool;

package/dist/src/tools/GetDependenciesTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class GetDependenciesTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/GetDependenciesTool.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetDependenciesTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class GetDependenciesTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'get_dependencies',
+            description: 'Show what files a given file imports (direct or transitive). Use to understand what a file depends on before modifying it. depType values: import | import-default | import-namespace | reexport | reexport-namespace.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'File path as returned by search_codebase' },
+                    project: { type: 'string', description: 'Project name (use list_projects to find it)' },
+                    symbol: { type: 'string', description: 'Filter to a specific imported symbol name (optional)' },
+                    transitive: { type: 'boolean', description: 'Include transitive (indirect) dependencies. Default: false.' },
+                },
+                required: ['file_path', 'project'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path);
+        const project = String(args.project);
+        const symbol = args.symbol ? String(args.symbol) : null;
+        const transitive = Boolean(args.transitive);
+        const rows = await this.searcher.getDependencies(filePath, project, symbol, transitive);
+        if (rows.length === 0) {
+            return (0, format_helpers_1.textResponse)(`No dependencies found for: ${filePath}`);
+        }
+        return (0, format_helpers_1.textResponse)((0, format_helpers_1.formatDependencies)(filePath, rows, transitive));
+    }
+}
+exports.GetDependenciesTool = GetDependenciesTool;

package/dist/src/tools/GetDependentsTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class GetDependentsTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/GetDependentsTool.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetDependentsTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+const format_helpers_2 = require("./format-helpers");
+class GetDependentsTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'get_dependents',
+            description: 'Show which files import a given file (reverse graph). Use before refactoring to find all callers and avoid breaking changes. depType values: import | import-default | import-namespace | reexport | reexport-namespace.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'File path as returned by search_codebase' },
+                    project: { type: 'string', description: 'Project name (use list_projects to find it)' },
+                    symbol: { type: 'string', description: 'Exported symbol name. Two behaviors: (1) if graph dependents exist, narrows them to imports of this symbol; (2) if the import graph returns zero results, triggers a whole-word text-search fallback (grep -F -w) across all .ts/.tsx/.js/.jsx files in the project to find runtime usages — DI containers, singletons, dynamic lookups, string references. Capped at 200 matches.' },
+                    transitive: { type: 'boolean', description: 'Include transitive (indirect) dependents. Default: false.' },
+                },
+                required: ['file_path', 'project'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path);
+        const project = String(args.project);
+        const symbol = args.symbol ? String(args.symbol) : null;
+        const transitive = Boolean(args.transitive);
+        const rows = await this.searcher.getDependents(filePath, project, symbol, transitive);
+        if (rows.length > 0) {
+            return (0, format_helpers_1.textResponse)((0, format_helpers_2.formatDependents)(filePath, rows, transitive));
+        }
+        const header = `**Dependents of** \`${filePath}\`\n\n**Direct:** No direct import dependents found.`;
+        if (!symbol) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\nTip: pass \`symbol\` to trigger a text-search fallback for runtime usages (e.g. via singleton or container).`);
+        }
+        const { matches, truncated } = await this.searcher.grepSymbol(symbol, project, filePath);
+        if (matches.length === 0) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\n**Fallback \`[text search]\` for \`${symbol}\`:** No results.`);
+        }
+        const grouped = new Map();
+        for (const m of matches) {
+            if (!grouped.has(m.filePath))
+                grouped.set(m.filePath, []);
+            grouped.get(m.filePath).push(m.line);
+        }
+        const fallbackLines = [`\n**Fallback \`[text search]\` for \`${symbol}\`:**${truncated ? ' *(truncated to 200 results)*' : ''}`];
+        for (const [fp, lines] of grouped) {
+            fallbackLines.push(`  ~ \`${fp}\`:${lines.join(', ')}`);
+        }
+        return (0, format_helpers_1.textResponse)(header + fallbackLines.join('\n'));
+    }
+}
+exports.GetDependentsTool = GetDependentsTool;

package/dist/src/tools/ListFilesTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class ListFilesTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/ListFilesTool.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListFilesTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ListFilesTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            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'],
+            },
+        };
+    }
+    async handle(args) {
+        const relPath = String(args.path ?? '.');
+        const project = String(args.project ?? '');
+        const rawDepth = Number(args.depth);
+        const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
+        const pattern = args.pattern ? String(args.pattern) : null;
+        const { tree, error } = this.searcher.listFiles(relPath, project, depth, pattern);
+        if (error) {
+            return (0, format_helpers_1.textResponse)(`list_files error: ${error}`);
+        }
+        return (0, format_helpers_1.textResponse)(`**${project}/${relPath}**\n\`\`\`\n${tree}\n\`\`\``);
+    }
+}
+exports.ListFilesTool = ListFilesTool;

package/dist/src/tools/ListProjectsTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class ListProjectsTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(_args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/ListProjectsTool.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListProjectsTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ListProjectsTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'list_projects',
+            description: 'List all indexed projects with their chunk counts and metadata (description, stack, notes, relations from .ragmeta.json).',
+            inputSchema: { type: 'object', properties: {} },
+        };
+    }
+    async handle(_args) {
+        const rows = await this.searcher.listProjects();
+        if (rows.length === 0) {
+            return (0, format_helpers_1.textResponse)('No indexed projects found.');
+        }
+        return (0, format_helpers_1.textResponse)(rows.map(r => {
+            const lines = [`${r.serviceName}: ${r.chunks} chunks`];
+            if (r.packageName)
+                lines.push(`  package: ${r.packageName}`);
+            if (r.type)
+                lines.push(`  type: ${r.type}`);
+            if (r.description)
+                lines.push(`  description: ${r.description}`);
+            if (r.stack)
+                lines.push(`  stack: ${r.stack}`);
+            if (r.notes)
+                lines.push(`  notes: ${r.notes}`);
+            if (r.relations) {
+                for (const [key, val] of Object.entries(r.relations)) {
+                    const list = Array.isArray(val) ? val.join(', ') : val;
+                    lines.push(`  ${key}: ${list}`);
+                }
+            }
+            return lines.join('\n');
+        }).join('\n\n'));
+    }
+}
+exports.ListProjectsTool = ListProjectsTool;

package/dist/src/tools/ReadFileRangeTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class ReadFileRangeTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/ReadFileRangeTool.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileRangeTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ReadFileRangeTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'read_file_range',
+            description: 'Read a specific line range from an indexed source file. Use this when a search result looks incomplete — read the surrounding lines to get full context.',
+            inputSchema: {
+                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). 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'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path);
+        const startLine = Math.max(1, Number(args.start_line) || 1);
+        const endLine = Number(args.end_line) || startLine + 99;
+        const range = await this.searcher.readFileRange(filePath, startLine, endLine);
+        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.` :
+                    `File was deleted from disk after indexing: ${filePath}. Re-run indexing to update.`;
+            return (0, format_helpers_1.textResponse)(message);
+        }
+        const numbered = range.lines.map((line, i) => `${startLine + i}: ${line}`).join('\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 (0, format_helpers_1.textResponse)(text);
+    }
+}
+exports.ReadFileRangeTool = ReadFileRangeTool;

package/dist/src/tools/ReadFileTool.d.ts

@@ -0,0 +1,8 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+export declare class ReadFileTool implements IMcpToolHandler {
+    private searcher;
+    constructor(searcher: ISearcher);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/ReadFileTool.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ReadFileTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'read_file',
+            description: 'Read a file by absolute path. 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. Note: search_codebase returns relative paths — construct the absolute path from your workspace root.' },
+                    max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
+                },
+                required: ['file_path'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path ?? '');
+        const rawMax = Number(args.max_lines);
+        const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
+        const result = await this.searcher.readFileAbsolute(filePath, maxLines);
+        if (!result.ok) {
+            const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
+                `File not found on disk: ${filePath}`;
+            return (0, format_helpers_1.textResponse)(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 (0, format_helpers_1.textResponse)(text);
+    }
+}
+exports.ReadFileTool = ReadFileTool;

package/dist/src/tools/SearchCodebaseTool.d.ts

@@ -0,0 +1,13 @@
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISearcher } from '../interfaces/ISearcher';
+import type { ILogger } from '../interfaces/ILogger';
+export declare class SearchCodebaseTool implements IMcpToolHandler {
+    private searcher;
+    private defaultLimit;
+    private maxLimit;
+    private defaultThreshold;
+    private logger;
+    constructor(searcher: ISearcher, defaultLimit: number, maxLimit: number, defaultThreshold: number, logger: ILogger);
+    definition(): ToolDefinition;
+    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+}

package/dist/src/tools/SearchCodebaseTool.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchCodebaseTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class SearchCodebaseTool {
+    searcher;
+    defaultLimit;
+    maxLimit;
+    defaultThreshold;
+    logger;
+    constructor(searcher, defaultLimit, maxLimit, defaultThreshold, logger) {
+        this.searcher = searcher;
+        this.defaultLimit = defaultLimit;
+        this.maxLimit = maxLimit;
+        this.defaultThreshold = defaultThreshold;
+        this.logger = logger;
+    }
+    definition() {
+        return {
+            name: 'search_codebase',
+            description: 'Search local project codebase by semantic similarity',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string' },
+                    limit: { type: 'number', description: `Max results (default ${this.defaultLimit}, max ${this.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.defaultThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
+                },
+                required: ['query'],
+            },
+        };
+    }
+    async handle(args) {
+        const t0 = Date.now();
+        const raw = String(args.query);
+        const limit = Math.min(Math.max(1, Number(args.limit) || this.defaultLimit), this.maxLimit);
+        const project = args.project ? String(args.project) : null;
+        const includeNeighbors = Boolean(args.include_neighbors);
+        const includeGraphContext = Boolean(args.include_graph_context);
+        const rawThreshold = args.threshold;
+        const parsedThreshold = Number(rawThreshold);
+        const threshold = rawThreshold != null && !isNaN(parsedThreshold)
+            ? Math.min(1, Math.max(0, parsedThreshold))
+            : undefined;
+        const { query, translated } = await this.searcher.prepareQuery(raw);
+        const results = await this.searcher.searchChunks(query, limit, project, threshold);
+        this.logger.debug('SearchCodebaseTool: handle', {
+            query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
+            limit, translated, count: results.length, ms: Date.now() - t0,
+        });
+        if (results.length === 0) {
+            return (0, format_helpers_1.textResponse)('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((0, format_helpers_1.formatChunk)(prevChunk, 'prev chunk'));
+                parts.push(`${(0, format_helpers_1.formatChunk)(result)}\n**Relevance:** ${result.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(result.filePath))}`);
+                if (nextChunk)
+                    parts.push((0, format_helpers_1.formatChunk)(nextChunk, 'next chunk'));
+                return parts.join('\n\n');
+            });
+            return (0, format_helpers_1.textResponse)(header + blocks.join('\n\n---\n\n'));
+        }
+        const text = results
+            .map(r => `${(0, format_helpers_1.formatChunk)(r)}\n**Relevance:** ${r.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(r.filePath))}`)
+            .join('\n\n---\n\n');
+        return (0, format_helpers_1.textResponse)(header + text);
+    }
+}
+exports.SearchCodebaseTool = SearchCodebaseTool;

package/dist/src/tools/format-helpers.d.ts

@@ -0,0 +1,8 @@
+import type { ChunkRow, DependencyRow, GraphContext } from '../services/SearcherService';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+export declare function textResponse(text: string): ToolResponse;
+export declare function errorResponse(text: string): ToolResponse;
+export declare function formatChunk(r: ChunkRow, label?: string): string;
+export declare function formatGraphContext(ctx: GraphContext | undefined): string;
+export declare function formatDependencies(filePath: string, rows: DependencyRow[], transitive: boolean): string;
+export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean): string;