codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

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

@@ -1,8 +1,18 @@
-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>;
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ISymbolLookup } from '../interfaces/ISymbolLookup';
+import type { SymbolKind } from '../interfaces/ISymbolLookup';
+import type { ILogger } from '../interfaces/ILogger';
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{
+    name: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    kind: z.ZodType<SymbolKind, unknown, z.core.$ZodTypeInternals<SymbolKind, unknown>>;
+}, z.core.$strip>;
+export declare class FindSymbolTool extends McpTool<typeof ARGS> {
+    private symbols;
+    constructor(symbols: ISymbolLookup, logger?: ILogger);
+    protected run({ name, project, kind }: z.output<typeof ARGS>): Promise<ToolResponse>;
+    private emptyText;
 }
+export {};

package/dist/src/tools/FindSymbolTool.js

@@ -1,7 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FindSymbolTool = void 0;
+const zod_1 = require("zod");
+const LoggerService_1 = require("../services/LoggerService");
 const format_helpers_1 = require("./format-helpers");
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
 const VALID_KINDS = [
     'function', 'class', 'type', 'interface', 'variable',
     'method', 'get_accessor', 'set_accessor', 'constructor', 'function_property', 'method_signature',
@@ -13,13 +17,17 @@ const GRAPHQL_KINDS = new Set([
 ]);
 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) {
-        this.searcher = searcher;
-    }
-    definition() {
-        return {
+const GREP_ADVICE = 'The index may be behind the source, so check with Grep before concluding the symbol does not exist.';
+const PARTIAL_NOTE = '*(partial — some files could not be searched)*';
+const ARGS = zod_1.z.object({
+    name: (0, tool_args_1.requiredText)('Bare, qualified (Class.method), quoted, or computed symbol name (case-sensitive)'),
+    project: (0, tool_args_1.optionalText)('Limit search to this project (optional). Use list_projects to find names.'),
+    kind: (0, tool_args_1.oneOf)('Symbol kind filter. Default: all.', VALID_KINDS, 'all'),
+});
+class FindSymbolTool extends McpTool_1.McpTool {
+    symbols;
+    constructor(symbols, logger = LoggerService_1.LoggerService.silent()) {
+        super({
             name: 'find_symbol',
             description: 'Find TypeScript/JavaScript symbol definitions by exact name: top-level declarations (functions, classes, types, ' +
                 'interfaces, variables), class/object-literal members (methods, get/set accessors, constructors, function ' +
@@ -30,48 +38,59 @@ class FindSymbolTool {
                 '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: {
-                    name: { type: 'string', description: 'Bare, qualified (Class.method), quoted, or computed symbol name (case-sensitive)' },
-                    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'],
-            },
-        };
+            args: ARGS,
+        }, logger);
+        this.symbols = symbols;
     }
-    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';
+    async run({ name, project, kind }) {
         let parsed;
         try {
-            parsed = await this.searcher.findSymbol(name, project, kind);
+            parsed = await this.symbols.findSymbol(name, project ?? null, kind);
         }
         catch (err) {
             return (0, format_helpers_1.errorResponse)(err.message);
         }
-        const { hits, truncated, grepFailed } = parsed;
+        const { hits, truncated, grep } = parsed;
+        if (hits.length === 0)
+            return (0, format_helpers_1.textResponse)(this.emptyText(name, project ?? null, kind, parsed).join('\n'));
         const lines = [];
-        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`);
+        const notes = [
+            ...(truncated ? [`*(truncated to ${hits.length} results)*`] : []),
+            ...(grep.outcome === 'partial' ? [PARTIAL_NOTE] : []),
+        ];
+        if (notes.length > 0)
+            lines.push(`${notes.join(' ')}\n`);
+        const grepTag = name.includes('.')
+            ? ' (grep — not in index; container not checked; may be stale or imprecise)'
+            : ' (grep — not in index; may be stale or imprecise)';
         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}${targetTag} \`${h.filePath}\` line ${h.line}, col ${h.column}${grepTag}`);
+            const sourceTag = h.source === 'grep' ? grepTag : '';
+            lines.push(`**${h.kind}** \`${h.qualified}\`${staticTag}${targetTag} \`${h.filePath}\` line ${h.line}, col ${h.column}${sourceTag}`);
             lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
         }
         return (0, format_helpers_1.textResponse)(lines.join('\n'));
     }
+    emptyText(name, project, kind, { grep, similar }) {
+        const suffix = grep.outcome === 'failed' ? ` (grep fallback failed: ${grep.cause})` : '';
+        const lines = [`No definitions found for symbol: ${name}${suffix}`];
+        if (GRAPHQL_KINDS.has(kind))
+            return [...lines, GRAPHQL_STALE_INDEX_HINT];
+        if (grep.outcome === 'no-project-directory') {
+            lines.push(`Project \`${project}\` has no directory in the workspace, so source files were not searched. Check the name with \`list_projects\`.`);
+        }
+        if (grep.outcome === 'other-container') {
+            const dot = name.lastIndexOf('.');
+            lines.push(`\`${name.slice(dot + 1)}\` is indexed, but not under \`${name.slice(0, dot)}\`, so source files were not searched.`);
+        }
+        if (similar.names.length > 0) {
+            lines.push('Similar indexed names:', ...similar.names.map(n => `  → \`${n}\``));
+            if (similar.truncated)
+                lines.push(`*(truncated to ${similar.names.length} results)*`);
+            lines.push(GREP_ADVICE);
+        }
+        return lines;
+    }
 }
 exports.FindSymbolTool = FindSymbolTool;

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

@@ -1,10 +1,18 @@
-import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
-import type { ISearcher } from '../interfaces/ISearcher';
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { IToolPaths } from '../interfaces/IToolPaths';
+import type { ICallGraph } from '../interfaces/ICallGraph';
 import type { ILogger } from '../interfaces/ILogger';
-export declare class GetCallersTool implements IMcpToolHandler {
-    private searcher;
-    private logger;
-    constructor(searcher: ISearcher, logger: ILogger);
-    definition(): ToolDefinition;
-    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{
+    symbol: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    project: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    callee_file: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export declare class GetCallersTool extends McpTool<typeof ARGS> {
+    private paths;
+    private calls;
+    constructor(paths: IToolPaths, calls: ICallGraph, logger: ILogger);
+    protected run({ symbol, project, callee_file: input }: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/GetCallersTool.js

@@ -1,59 +1,89 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetCallersTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
-class GetCallersTool {
-    searcher;
-    logger;
-    constructor(searcher, logger) {
-        this.searcher = searcher;
-        this.logger = logger;
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
+const symbol_name_1 = require("../symbol-name");
+function truncationMarker(shown, truncated) {
+    return truncated ? [`*(truncated to ${shown} results)*`] : [];
+}
+function renderCause(project, calleeFile, cause) {
+    switch (cause.kind) {
+        case 'no-call-graph':
+            return [`Project \`${project}\` has no call graph. Check the name with \`list_projects\`. If the project is not indexed yet, run \`rag-index --project ${project}\`; an indexed project without internal calls has no graph to show.`];
+        case 'unknown-symbol':
+            return [
+                'No such symbol is indexed in this project.',
+                ...(cause.suggestions.length > 0 ? ['Similar indexed names:', ...cause.suggestions.map(q => `  → \`${q}\``)] : []),
+                ...truncationMarker(cause.suggestions.length, cause.truncated),
+                'Look a name up with `find_symbol`. The index may be behind the source, so check with Grep before concluding the symbol does not exist.',
+            ];
+        case 'no-recorded-calls': {
+            const recorded = calleeFile ? `No calls to \`${calleeFile}\` are recorded in this project` : 'No calls are recorded in this project';
+            const lastReasons = calleeFile ? 'or it is passed as a callback' : 'it is passed as a callback, or it is unused';
+            return [
+                'Defined at:',
+                ...cause.definitions.map(d => `  → \`${d.qualified}\` \`${d.filePath}\`${d.line != null ? ` line ${d.line}` : ''}`),
+                ...truncationMarker(cause.definitions.length, cause.truncated),
+                `${recorded}, because the call graph holds direct calls only, per calling project. ` +
+                    'Possibly it is called from another project, a framework invokes it (decorators, dependency injection), ' +
+                    'a call goes through an interface-typed receiver and is recorded under the interface member, ' +
+                    `it is instantiated with \`new\`, ${lastReasons}.`,
+                'Find importers with `get_dependents` and retry `get_callers` with the project that owns an importer\'s path, as `list_projects` shows, or use Grep.',
+            ];
+        }
+        case 'lookup-failed':
+            return ['The cause could not be determined.'];
     }
-    definition() {
-        return {
+}
+function renderNoCallers(symbol, project, calleeFile, cause) {
+    return [
+        `No call sites found for \`${symbol}\` in project \`${project}\`.`,
+        ...renderCause(project, calleeFile, cause),
+        ...(calleeFile ? ['Retry without `callee_file` to match calls to any definition.'] : []),
+    ].join('\n');
+}
+const ARGS = zod_1.z.object({
+    symbol: (0, tool_args_1.requiredText)('Bare or qualified (Class.method) function/method name (case-sensitive)'),
+    project: (0, tool_args_1.requiredText)('Project name (from list_projects)'),
+    callee_file: (0, tool_args_1.optionalPathArg)(`Optional: only calls to the definition in this file, to disambiguate overloaded names. ${(0, format_helpers_1.pathArgDescription)()}`),
+});
+class GetCallersTool extends McpTool_1.McpTool {
+    paths;
+    calls;
+    constructor(paths, calls, logger) {
+        super({
             name: 'get_callers',
             description: 'Find all call sites of a function or method by exact name. Accepts a bare name (every call site with that ' +
                 'callee name) or a qualified name (`Class.method`, from find_symbol output) to disambiguate same-named methods ' +
                 'of different classes. Uses the call graph index — faster and more precise than grep. A call through an ' +
                 'interface-typed receiver is recorded under the interface member (e.g. `IEmbedder.embedBatch`), not the ' +
                 'implementing class. Use after find_symbol to trace where a symbol is actually called.',
-            inputSchema: {
-                type: 'object',
-                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: only calls to the definition in this file, to disambiguate overloaded names. ${(0, format_helpers_1.pathArgDescription)()}` },
-                },
-                required: ['symbol', 'project'],
-            },
-        };
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.calls = calls;
     }
-    async handle(args) {
-        const symbol = String(args.symbol ?? '');
-        const project = String(args.project ?? '');
-        const rawCallee = args.callee_file;
+    async run({ symbol, project, callee_file: input }) {
+        if (!(0, symbol_name_1.parseCallerSymbol)(symbol))
+            return (0, format_helpers_1.errorResponse)('Invalid symbol name');
         let calleeFile = null;
-        if (rawCallee != null && rawCallee !== '') {
-            const input = String(rawCallee);
-            const resolved = await this.searcher.resolveToolPath(input);
+        if (input !== undefined) {
+            const resolved = await this.paths.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);
+            const failure = await this.paths.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);
-        }
-        catch (err) {
-            return (0, format_helpers_1.errorResponse)(err.message);
-        }
+        const rows = await this.calls.getCallers(symbol, project, calleeFile);
         const lines = [];
         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'));
+            const cause = await this.calls.explainNoCallers(symbol, project);
+            return (0, format_helpers_1.textResponse)(renderNoCallers(symbol, project, calleeFile, cause));
         }
         lines.push(`**Call sites of \`${symbol}\`** (${rows.length} found)\n`);
         for (const r of rows) {

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

@@ -1,10 +1,18 @@
-import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
-import type { ISearcher } from '../interfaces/ISearcher';
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { IToolPaths } from '../interfaces/IToolPaths';
+import type { IDependencyGraph } from '../interfaces/IDependencyGraph';
 import type { ILogger } from '../interfaces/ILogger';
-export declare class GetDependenciesTool implements IMcpToolHandler {
-    private searcher;
-    private logger;
-    constructor(searcher: ISearcher, logger: ILogger);
-    definition(): ToolDefinition;
-    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{
+    file_path: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    symbol: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    transitive: z.ZodType<boolean | undefined, unknown, z.core.$ZodTypeInternals<boolean | undefined, unknown>>;
+}, z.core.$strip>;
+export declare class GetDependenciesTool extends McpTool<typeof ARGS> {
+    private paths;
+    private dependencies;
+    constructor(paths: IToolPaths, dependencies: IDependencyGraph, logger: ILogger);
+    protected run(args: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/GetDependenciesTool.js

@@ -1,45 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetDependenciesTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
-class GetDependenciesTool {
-    searcher;
-    logger;
-    constructor(searcher, logger) {
-        this.searcher = searcher;
-        this.logger = logger;
-    }
-    definition() {
-        return {
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
+const ARGS = zod_1.z.object({
+    file_path: (0, tool_args_1.pathArg)((0, format_helpers_1.pathArgDescription)()),
+    symbol: (0, tool_args_1.optionalText)('Filter direct dependencies to named imports of this name (optional). Only named imports match, so default, namespace, side-effect and `export *` imports never match it; indirect (transitive) rows are not filtered by it.'),
+    transitive: (0, tool_args_1.flag)('Include transitive (indirect) dependencies. Default: false.'),
+});
+class GetDependenciesTool extends McpTool_1.McpTool {
+    paths;
+    dependencies;
+    constructor(paths, dependencies, logger) {
+        super({
             name: 'get_dependencies',
-            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: (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'],
-            },
-        };
+            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. The direct section prints one line per imported file, with the names imported from it.',
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.dependencies = dependencies;
     }
-    async handle(args) {
-        const input = args.file_path == null ? '' : String(args.file_path);
-        const symbol = args.symbol ? String(args.symbol) : null;
-        const transitive = Boolean(args.transitive);
-        const resolved = await this.searcher.resolveToolPath(input);
+    async run(args) {
+        const input = args.file_path;
+        const symbol = args.symbol ?? null;
+        const transitive = args.transitive ?? false;
+        const resolved = await this.paths.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);
+        const rows = await this.dependencies.getDependencies(filePath, symbol, transitive);
         if (rows.length === 0) {
-            const failure = await this.searcher.checkGraphPath(filePath);
+            const failure = await this.paths.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));
+        if (symbol && !rows.some(r => (r.depth ?? 1) === 1)) {
+            const unfiltered = await this.dependencies.getDependencies(filePath, null, false);
+            if (unfiltered.length > 0) {
+                const miss = (0, format_helpers_1.formatDependenciesFilterMiss)(filePath, symbol, unfiltered);
+                const indirect = (0, format_helpers_1.formatTransitiveSection)(rows, symbol, 'dependencies');
+                return (0, format_helpers_1.textResponse)(indirect ? `${miss}\n\n${indirect}` : miss);
+            }
+        }
+        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, symbol));
     }
 }
 exports.GetDependenciesTool = GetDependenciesTool;

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

@@ -1,10 +1,22 @@
-import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
-import type { ISearcher } from '../interfaces/ISearcher';
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { IToolPaths } from '../interfaces/IToolPaths';
+import type { IDependencyGraph } from '../interfaces/IDependencyGraph';
+import type { IProjectRoots } from '../interfaces/IProjectRoots';
+import type { ISymbolLookup } from '../interfaces/ISymbolLookup';
 import type { ILogger } from '../interfaces/ILogger';
-export declare class GetDependentsTool implements IMcpToolHandler {
-    private searcher;
-    private logger;
-    constructor(searcher: ISearcher, logger: ILogger);
-    definition(): ToolDefinition;
-    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{
+    file_path: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    symbol: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    transitive: z.ZodType<boolean | undefined, unknown, z.core.$ZodTypeInternals<boolean | undefined, unknown>>;
+}, z.core.$strip>;
+export declare class GetDependentsTool extends McpTool<typeof ARGS> {
+    private paths;
+    private dependencies;
+    private roots;
+    private symbols;
+    constructor(paths: IToolPaths, dependencies: IDependencyGraph, roots: IProjectRoots, symbols: ISymbolLookup, logger: ILogger);
+    protected run(args: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/GetDependentsTool.js

@@ -1,53 +1,67 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GetDependentsTool = void 0;
+const zod_1 = require("zod");
+const symbol_name_1 = require("../symbol-name");
 const format_helpers_1 = require("./format-helpers");
-class GetDependentsTool {
-    searcher;
-    logger;
-    constructor(searcher, logger) {
-        this.searcher = searcher;
-        this.logger = logger;
-    }
-    definition() {
-        return {
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
+const ARGS = zod_1.z.object({
+    file_path: (0, tool_args_1.pathArg)((0, format_helpers_1.pathArgDescription)()),
+    symbol: (0, tool_args_1.optionalText)('Exported symbol name. Two behaviors: (1) narrows direct graph dependents to named imports of this symbol — only named imports match, so default, namespace, side-effect and `export *` imports never match it, and indirect (transitive) rows are not filtered by it; (2) if no graph row remains after the filter, 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: (0, tool_args_1.flag)('Include transitive (indirect) dependents. Default: false.'),
+});
+class GetDependentsTool extends McpTool_1.McpTool {
+    paths;
+    dependencies;
+    roots;
+    symbols;
+    constructor(paths, dependencies, roots, symbols, logger) {
+        super({
             name: 'get_dependents',
-            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: (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'],
-            },
-        };
+            description: 'Show which files import a given file (reverse graph), in any project. Use before refactoring to find all callers and avoid breaking changes. The direct section prints one line per importing file, with the names imported and the enclosing declarations that use them — only those resolved unambiguously, so the list can be partial or absent.',
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.dependencies = dependencies;
+        this.roots = roots;
+        this.symbols = symbols;
     }
-    async handle(args) {
-        const input = args.file_path == null ? '' : String(args.file_path);
-        const symbol = args.symbol ? String(args.symbol) : null;
-        const transitive = Boolean(args.transitive);
-        const resolved = await this.searcher.resolveToolPath(input);
+    async run(args) {
+        const input = args.file_path;
+        const symbol = args.symbol ?? null;
+        const transitive = args.transitive ?? false;
+        if (symbol && symbol.length > symbol_name_1.MAX_GREPPED_NAME_LEN)
+            return (0, format_helpers_1.errorResponse)('Invalid symbol name');
+        const resolved = await this.paths.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_1.formatDependents)(filePath, rows, transitive));
+        const rows = await this.dependencies.getDependents(filePath, symbol, transitive);
+        if (rows.length === 0) {
+            const failure = await this.paths.checkGraphPath(filePath);
+            if (failure)
+                return (0, format_helpers_1.pathErrorResponse)(this.logger, 'get_dependents', 'file_path', input, filePath, failure);
+        }
+        let header = `**Dependents of** \`${filePath}\`\n\n**Direct:** No direct import dependents found.`;
+        if (symbol && !rows.some(r => (r.depth ?? 1) === 1)) {
+            const unfiltered = await this.dependencies.getDependents(filePath, null, false);
+            if (unfiltered.length > 0)
+                header = (0, format_helpers_1.formatDependentsFilterMiss)(filePath, symbol, unfiltered);
+            const indirect = (0, format_helpers_1.formatTransitiveSection)(rows, symbol, 'dependents');
+            if (indirect && unfiltered.length > 0)
+                return (0, format_helpers_1.textResponse)(`${header}\n\n${indirect}`);
         }
-        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 (rows.length > 0)
+            return (0, format_helpers_1.textResponse)((0, format_helpers_1.formatDependents)(filePath, rows, transitive, symbol));
         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 rootDir = this.searcher.fallbackRoot(filePath);
+        const rootDir = this.roots.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);
+        const grep = await this.symbols.grepSymbol(symbol, rootDir, filePath);
         if (!grep.ok) {
             return (0, format_helpers_1.textResponse)(`${header}\n\n${fallbackHeader} failed`);
         }

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

@@ -1,10 +1,18 @@
-import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
-import type { ISearcher } from '../interfaces/ISearcher';
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { IToolPaths } from '../interfaces/IToolPaths';
+import type { IWorkspaceFiles } from '../interfaces/IWorkspaceFiles';
 import type { ILogger } from '../interfaces/ILogger';
-export declare class ListFilesTool implements IMcpToolHandler {
-    private searcher;
-    private logger;
-    constructor(searcher: ISearcher, logger: ILogger);
-    definition(): ToolDefinition;
-    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{
+    path: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    depth: z.ZodType<number, unknown, z.core.$ZodTypeInternals<number, unknown>>;
+    pattern: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export declare class ListFilesTool extends McpTool<typeof ARGS> {
+    private paths;
+    private files;
+    constructor(paths: IToolPaths, files: IWorkspaceFiles, logger: ILogger);
+    protected run({ path: input, depth, pattern }: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};