codesearch-mcp 0.2.1-alpha → 0.2.3-alpha

package/dist/src/symbol-rows.d.ts

@@ -1,12 +1,17 @@
 import type { SymbolEntry } from './interfaces/IAstParser';
-export type CodeSymbolRow = Pick<SymbolEntry, 'project' | 'filePath' | 'name' | 'kind' | 'signature' | 'line' | 'col' | 'container' | 'isStatic'>;
+export type CodeSymbolRow = Pick<SymbolEntry, 'project' | 'filePath' | 'name' | 'kind' | 'signature' | 'line' | 'col' | 'container' | 'isStatic' | 'target'>;
 /**
- * Combine top-level symbols and members into the rows written to `code_symbol`.
- * Overload signatures of one declaration — same `(container, name, kind,
- * isStatic)` — collapse to a single representative row: the one with a body
- * (the implementation) when present, otherwise the earliest by line (the first
- * signature in source order). Static and instance members sharing a name are
- * never collapsed into each other (`isStatic` is part of the group key). A
- * final dedup by `(container, name, kind, line)` matches the DB's unique index.
+ * Combine top-level symbols, members and GraphQL-named rows into the rows
+ * written to `code_symbol`. Overload signatures of one declaration — same
+ * `(container, name, kind, isStatic)` — collapse to a single representative
+ * row: the one with a body (the implementation) when present, otherwise the
+ * earliest by line (the first signature in source order). Static and instance
+ * members sharing a name are never collapsed into each other (`isStatic` is
+ * part of the group key). `graphqlNames` bypass this collapse — decorators
+ * cannot sit on overload signatures, so there is nothing to collapse, and the
+ * collapse's `(container, name, kind, isStatic)` key would wrongly merge two
+ * different methods exposing the same GraphQL name from two resolver classes
+ * (both with container `Query`). A final dedup by `(container, name, kind,
+ * line)` matches the DB's unique index.
  */
-export declare function buildSymbolRows(symbols: SymbolEntry[], members: SymbolEntry[]): CodeSymbolRow[];
+export declare function buildSymbolRows(symbols: SymbolEntry[], members: SymbolEntry[], graphqlNames?: SymbolEntry[]): CodeSymbolRow[];

package/dist/src/symbol-rows.js

@@ -2,15 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildSymbolRows = buildSymbolRows;
 /**
- * Combine top-level symbols and members into the rows written to `code_symbol`.
- * Overload signatures of one declaration — same `(container, name, kind,
- * isStatic)` — collapse to a single representative row: the one with a body
- * (the implementation) when present, otherwise the earliest by line (the first
- * signature in source order). Static and instance members sharing a name are
- * never collapsed into each other (`isStatic` is part of the group key). A
- * final dedup by `(container, name, kind, line)` matches the DB's unique index.
+ * Combine top-level symbols, members and GraphQL-named rows into the rows
+ * written to `code_symbol`. Overload signatures of one declaration — same
+ * `(container, name, kind, isStatic)` — collapse to a single representative
+ * row: the one with a body (the implementation) when present, otherwise the
+ * earliest by line (the first signature in source order). Static and instance
+ * members sharing a name are never collapsed into each other (`isStatic` is
+ * part of the group key). `graphqlNames` bypass this collapse — decorators
+ * cannot sit on overload signatures, so there is nothing to collapse, and the
+ * collapse's `(container, name, kind, isStatic)` key would wrongly merge two
+ * different methods exposing the same GraphQL name from two resolver classes
+ * (both with container `Query`). A final dedup by `(container, name, kind,
+ * line)` matches the DB's unique index.
  */
-function buildSymbolRows(symbols, members) {
+function buildSymbolRows(symbols, members, graphqlNames = []) {
     const groups = new Map();
     for (const entry of [...symbols, ...members]) {
         const key = JSON.stringify([entry.container, entry.name, entry.kind, entry.isStatic]);
@@ -30,9 +35,10 @@ function buildSymbolRows(symbols, members) {
         collapsed.push(implementation ?? group.reduce((a, b) => ((a.line ?? 0) <= (b.line ?? 0) ? a : b)));
     }
     const dedup = new Map();
-    for (const entry of collapsed) {
+    for (const entry of [...collapsed, ...graphqlNames]) {
         const key = JSON.stringify([entry.container, entry.name, entry.kind, entry.line]);
-        dedup.set(key, entry);
+        if (!dedup.has(key))
+            dedup.set(key, entry);
     }
-    return [...dedup.values()].map(({ project, filePath, name, kind, signature, line, col, container, isStatic }) => ({ project, filePath, name, kind, signature, line, col, container, isStatic }));
+    return [...dedup.values()].map(({ project, filePath, name, kind, signature, line, col, container, isStatic, target }) => ({ project, filePath, name, kind, signature, line, col, container, isStatic, target: target ?? null }));
 }

package/dist/src/tools/FindSymbolTool.js

@@ -5,8 +5,14 @@ const format_helpers_1 = require("./format-helpers");
 const VALID_KINDS = [
     'function', 'class', 'type', 'interface', 'variable',
     'method', 'get_accessor', 'set_accessor', 'constructor', 'function_property', 'method_signature',
+    'graphql_query', 'graphql_mutation', 'graphql_subscription', 'graphql_field', 'graphql_type',
     'all',
 ];
+const GRAPHQL_KINDS = new Set([
+    'graphql_query', 'graphql_mutation', 'graphql_subscription', 'graphql_field', 'graphql_type',
+]);
+const GRAPHQL_STALE_INDEX_HINT = 'Files indexed before GraphQL indexing was added have no GraphQL rows until `rag-index --reindex` — ' +
+    'this miss does not prove the name is absent.';
 class FindSymbolTool {
     searcher;
     constructor(searcher) {
@@ -20,7 +26,10 @@ class FindSymbolTool {
                 'properties), interface and type-literal method signatures, and namespace-level declarations. Accepts a bare name ' +
                 '(any container), a qualified name (`Class.method`, `NS.Class.method`), a quoted name for string-literal members ' +
                 "(`Router.'kebab-name'`), or a computed name (`Stack.[Symbol.iterator]`). Use when you know the symbol name and " +
-                'want its definition location fast.',
+                'want its definition location fast. Also finds a NestJS GraphQL operation (`@Query`/`@Mutation`/`@Subscription`), ' +
+                'resolve field (`@ResolveField`) or type (`@ObjectType`/`@InputType`/`@InterfaceType`) by its GraphQL name — the ' +
+                'name the schema exposes, which may differ from the TypeScript declaration name. Pass the matching `graphql_*` ' +
+                'kind when the name comes from a schema, a GraphQL document or a frontend.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -45,21 +54,21 @@ class FindSymbolTool {
             return (0, format_helpers_1.errorResponse)(err.message);
         }
         const { hits, truncated, grepFailed } = parsed;
-        const notice = await this.searcher.outdatedNotice(project);
         const lines = [];
-        if (notice)
-            lines.push(notice + '\n');
         if (hits.length === 0) {
             const suffix = grepFailed ? ' (grep fallback failed — see log)' : '';
             lines.push(`No definitions found for symbol: ${name}${suffix}`);
+            if (GRAPHQL_KINDS.has(kind))
+                lines.push(GRAPHQL_STALE_INDEX_HINT);
             return (0, format_helpers_1.textResponse)(lines.join('\n'));
         }
         if (truncated)
             lines.push(`*(truncated to ${hits.length} results)*\n`);
         for (const h of hits) {
             const staticTag = h.isStatic ? ' static' : '';
+            const targetTag = h.target ? ` → \`${h.target}\`` : '';
             const grepTag = h.source === 'grep' ? ' (grep — not in index; may be stale or imprecise)' : '';
-            lines.push(`**${h.kind}** \`${h.qualified}\`${staticTag} \`${h.filePath}\` line ${h.line}, col ${h.column}${grepTag}`);
+            lines.push(`**${h.kind}** \`${h.qualified}\`${staticTag}${targetTag} \`${h.filePath}\` line ${h.line}, col ${h.column}${grepTag}`);
             lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
         }
         return (0, format_helpers_1.textResponse)(lines.join('\n'));

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

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

package/dist/src/tools/GetCallersTool.js

@@ -4,8 +4,10 @@ exports.GetCallersTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class GetCallersTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     definition() {
         return {
@@ -20,7 +22,7 @@ class GetCallersTool {
                 properties: {
                     symbol: { type: 'string', description: 'Bare or qualified (Class.method) function/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' },
+                    callee_file: { type: 'string', description: `Optional: only calls to the definition in this file, to disambiguate overloaded names. ${(0, format_helpers_1.pathArgDescription)()}` },
                 },
                 required: ['symbol', 'project'],
             },
@@ -29,7 +31,18 @@ class GetCallersTool {
     async handle(args) {
         const symbol = String(args.symbol ?? '');
         const project = String(args.project ?? '');
-        const calleeFile = args.callee_file ? String(args.callee_file) : null;
+        const rawCallee = args.callee_file;
+        let calleeFile = null;
+        if (rawCallee != null && rawCallee !== '') {
+            const input = String(rawCallee);
+            const resolved = await this.searcher.resolveToolPath(input);
+            if (!resolved.ok)
+                return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_callers', 'callee_file', input, input, resolved);
+            const failure = await this.searcher.checkGraphPath(resolved.relPath);
+            if (failure)
+                return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_callers', 'callee_file', input, resolved.relPath, failure);
+            calleeFile = resolved.relPath;
+        }
         let rows;
         try {
             rows = await this.searcher.getCallers(symbol, project, calleeFile);
@@ -37,10 +50,7 @@ class GetCallersTool {
         catch (err) {
             return (0, format_helpers_1.errorResponse)(err.message);
         }
-        const notice = await this.searcher.outdatedNotice(project);
         const lines = [];
-        if (notice)
-            lines.push(notice + '\n');
         if (rows.length === 0) {
             lines.push(`No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index --reindex\` if the call graph has not been populated yet.`);
             return (0, format_helpers_1.textResponse)(lines.join('\n'));

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

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

package/dist/src/tools/GetDependenciesTool.js

@@ -4,32 +4,39 @@ exports.GetDependenciesTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class GetDependenciesTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     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.',
+            description: 'Show what files a given file imports (direct or transitive), in any project. Use to understand what a file depends on before modifying it. depType values: import | import-default | import-namespace | import-side-effect | 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)' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
                     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'],
+                required: ['file_path'],
             },
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path);
-        const project = String(args.project);
+        const input = args.file_path == null ? '' : String(args.file_path);
         const symbol = args.symbol ? String(args.symbol) : null;
         const transitive = Boolean(args.transitive);
-        const rows = await this.searcher.getDependencies(filePath, project, symbol, transitive);
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependencies', 'file_path', input, input, resolved);
+        const filePath = resolved.relPath;
+        const rows = await this.searcher.getDependencies(filePath, symbol, transitive);
         if (rows.length === 0) {
+            const failure = await this.searcher.checkGraphPath(filePath);
+            if (failure)
+                return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependencies', 'file_path', input, filePath, failure);
             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));

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

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

package/dist/src/tools/GetDependentsTool.js

@@ -2,52 +2,67 @@
 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) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     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.',
+            description: 'Show which files import a given file (reverse graph), in any project. Use before refactoring to find all callers and avoid breaking changes. depType values: import | import-default | import-namespace | import-side-effect | 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.' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
+                    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 of the project owning the file 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'],
+                required: ['file_path'],
             },
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path);
-        const project = String(args.project);
+        const input = args.file_path == null ? '' : String(args.file_path);
         const symbol = args.symbol ? String(args.symbol) : null;
         const transitive = Boolean(args.transitive);
-        const rows = await this.searcher.getDependents(filePath, project, symbol, transitive);
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependents', 'file_path', input, input, resolved);
+        const filePath = resolved.relPath;
+        const rows = await this.searcher.getDependents(filePath, symbol, transitive);
         if (rows.length > 0) {
-            return (0, format_helpers_1.textResponse)((0, format_helpers_2.formatDependents)(filePath, rows, transitive));
+            return (0, format_helpers_1.textResponse)((0, format_helpers_1.formatDependents)(filePath, rows, transitive));
         }
+        const failure = await this.searcher.checkGraphPath(filePath);
+        if (failure)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependents', 'file_path', input, filePath, failure);
         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 rootDir = this.searcher.fallbackRoot(filePath);
+        if (rootDir === null)
+            return (0, format_helpers_1.textResponse)(header);
+        const fallbackHeader = `**Fallback \`[text search]\` for \`${symbol}\`:**`;
+        const grep = await this.searcher.grepSymbol(symbol, rootDir, filePath);
+        if (!grep.ok) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\n${fallbackHeader} failed`);
+        }
+        if (grep.matches.length === 0) {
+            return (0, format_helpers_1.textResponse)(`${header}\n\n${fallbackHeader} No results.`);
         }
         const grouped = new Map();
-        for (const m of matches) {
+        for (const m of grep.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)*' : ''}`];
+        const notes = (grep.truncated ? ' *(truncated to 200 results)*' : '') +
+            (grep.partial ? ' *(partial — some files could not be searched)*' : '');
+        const fallbackLines = [`\n${fallbackHeader}${notes}`];
         for (const [fp, lines] of grouped) {
             fallbackLines.push(`  ~ \`${fp}\`:${lines.join(', ')}`);
         }

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

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

package/dist/src/tools/ListFilesTool.js

@@ -4,36 +4,38 @@ exports.ListFilesTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ListFilesTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     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.',
+            description: 'List files and directories under a workspace directory as an indented tree. Use to understand project structure before reading files; list_projects prints each project\'s directory.',
             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)' },
+                    path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)('directory') },
                     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'],
+                required: ['path'],
             },
         };
     }
     async handle(args) {
-        const relPath = String(args.path ?? '.');
-        const project = String(args.project ?? '');
+        const input = args.path == null ? '' : String(args.path);
         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\`\`\``);
+        const resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'list_files', 'path', input, input, resolved, 'directory');
+        const result = await this.searcher.listFiles(resolved.relPath, depth, pattern);
+        if (!result.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'list_files', 'path', input, resolved.relPath, result, 'directory');
+        return (0, format_helpers_1.textResponse)(`**Directory:** ${resolved.relPath}\n\`\`\`\n${result.tree}\n\`\`\``);
     }
 }
 exports.ListFilesTool = ListFilesTool;

package/dist/src/tools/ListProjectsTool.js

@@ -10,7 +10,7 @@ class ListProjectsTool {
     definition() {
         return {
             name: 'list_projects',
-            description: 'List all indexed projects with their chunk counts and metadata (description, stack, notes, relations from .ragmeta.json).',
+            description: 'List all indexed projects with their chunk counts, workspace-relative directory (`path:`) and metadata (description, stack, notes, relations from .ragmeta.json).',
             inputSchema: { type: 'object', properties: {} },
         };
     }
@@ -21,6 +21,10 @@ class ListProjectsTool {
         }
         return (0, format_helpers_1.textResponse)(rows.map(r => {
             const lines = [`${r.serviceName}: ${r.chunks} chunks`];
+            if (r.relPath) {
+                const state = !r.rootError ? '' : r.rootError === 'ENOENT' ? ' (not on disk)' : ` (${r.rootError})`;
+                lines.push(`  path: ${r.relPath}${state}`);
+            }
             if (r.packageName)
                 lines.push(`  package: ${r.packageName}`);
             if (r.type)

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

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

package/dist/src/tools/ReadFileRangeTool.js

@@ -4,17 +4,19 @@ exports.ReadFileRangeTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ReadFileRangeTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     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.',
+            description: 'Read a specific line range from a file under the workspace, indexed or not. 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' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
                     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.' },
                 },
@@ -23,16 +25,15 @@ class ReadFileRangeTool {
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path);
+        const input = args.file_path == null ? '' : 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 resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file_range', 'file_path', input, input, resolved);
+        const range = await this.searcher.readFileRange(resolved.relPath, startLine, endLine);
+        if (!range.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file_range', 'file_path', input, resolved.relPath, range);
         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) {

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

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

package/dist/src/tools/ReadFileTool.js

@@ -4,17 +4,19 @@ exports.ReadFileTool = void 0;
 const format_helpers_1 = require("./format-helpers");
 class ReadFileTool {
     searcher;
-    constructor(searcher) {
+    logger;
+    constructor(searcher, logger) {
         this.searcher = searcher;
+        this.logger = logger;
     }
     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.',
+            description: 'Read a complete file under the workspace, indexed or not. 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.' },
+                    file_path: { type: 'string', description: (0, format_helpers_1.pathArgDescription)() },
                     max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
                 },
                 required: ['file_path'],
@@ -22,15 +24,15 @@ class ReadFileTool {
         };
     }
     async handle(args) {
-        const filePath = String(args.file_path ?? '');
+        const input = args.file_path == null ? '' : 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 resolved = await this.searcher.resolveToolPath(input);
+        if (!resolved.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file', 'file_path', input, input, resolved);
+        const result = await this.searcher.readFile(resolved.relPath, maxLines);
+        if (!result.ok)
+            return (0, format_helpers_1.pathErrorResponse)(this.logger, 'read_file', 'file_path', input, resolved.relPath, result);
         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) {

package/dist/src/tools/SearchCodebaseTool.js

@@ -28,6 +28,7 @@ class SearchCodebaseTool {
                     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.` },
+                    rerank: { type: 'boolean', description: 'Override whether this call reranks, regardless of config. false skips reranking (use for "what does X do" / "where is X" lookups described without an exact name — reranking measurably hurts these; if you know the exact symbol name, use find_symbol instead). true forces reranking on if a reranker is configured (no-op otherwise). Omit to use config.reranker.enabled (good default for conceptual/architectural queries).' },
                 },
                 required: ['query'],
             },
@@ -45,8 +46,9 @@ class SearchCodebaseTool {
         const threshold = rawThreshold != null && !isNaN(parsedThreshold)
             ? Math.min(1, Math.max(0, parsedThreshold))
             : undefined;
+        const rerank = typeof args.rerank === 'boolean' ? args.rerank : undefined;
         const { query, translated } = await this.searcher.prepareQuery(raw);
-        const results = await this.searcher.searchChunks(query, limit, project, threshold);
+        const results = await this.searcher.searchChunks(query, limit, project, threshold, rerank);
         this.logger.debug('SearchCodebaseTool: handle', {
             query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
             limit, translated, count: results.length, ms: Date.now() - t0,

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

@@ -1,8 +1,23 @@
-import type { ChunkRow, DependencyRow, GraphContext } from '../services/SearcherService';
+import type { ChunkRow, DependencyRow, GraphContext, FileRangeResult, PathFailure, PathRefusal } from '../services/SearcherService';
 import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ILogger } from '../interfaces/ILogger';
 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;
+export type PathKind = 'file' | 'directory';
+export declare const PATH_EXAMPLE: Record<PathKind, string>;
+/** Description of a path argument; `kind` names what the path points at. */
+export declare function pathArgDescription(kind?: PathKind): string;
+export type PathError = PathRefusal | PathFailure | Extract<FileRangeResult, {
+    reason: 'past_end' | 'bad_range';
+}>;
+/**
+ * Text of a path error. `input` is the raw argument (echoed by refusals);
+ * `relPath` its canonical form, printed by every other message.
+ */
+export declare function pathErrorText(argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): string;
+/** Error response for a path error, logged at `warn` — a caller or index-freshness problem, not a server fault. */
+export declare function pathErrorResponse(logger: ILogger, tool: string, argName: string, input: string, relPath: string, err: PathError, kind?: PathKind): ToolResponse;