codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

package/dist/src/tools/ListFilesTool.js

@@ -1,38 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ListFilesTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
-class ListFilesTool {
-    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({
+    path: (0, tool_args_1.pathArg)((0, format_helpers_1.pathArgDescription)('directory'), 'directory'),
+    depth: (0, tool_args_1.intInRange)('Tree depth: 1 = immediate children only, up to 5. Default: 2.', { min: 1, max: 5, fallback: 2 }),
+    pattern: (0, tool_args_1.optionalText)('Optional filename filter (substring or extension like ".ts"). Only matching files are shown.'),
+});
+class ListFilesTool extends McpTool_1.McpTool {
+    paths;
+    files;
+    constructor(paths, files, logger) {
+        super({
             name: 'list_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: (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'],
-            },
-        };
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.files = files;
     }
-    async handle(args) {
-        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 resolved = await this.searcher.resolveToolPath(input);
+    async run({ path: input, depth, pattern }) {
+        const resolved = await this.paths.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);
+        const result = await this.files.listFiles(resolved.relPath, depth, pattern ?? null);
         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\`\`\``);

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

@@ -1,8 +1,12 @@
-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>;
+import { z } from 'zod';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { IProjectCatalog } from '../interfaces/IProjectCatalog';
+import type { ILogger } from '../interfaces/ILogger';
+import { McpTool } from './McpTool';
+declare const ARGS: z.ZodObject<{}, z.core.$strip>;
+export declare class ListProjectsTool extends McpTool<typeof ARGS> {
+    private catalog;
+    constructor(catalog: IProjectCatalog, logger?: ILogger);
+    protected run(): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/ListProjectsTool.js

@@ -1,21 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ListProjectsTool = void 0;
+const zod_1 = require("zod");
+const LoggerService_1 = require("../services/LoggerService");
 const format_helpers_1 = require("./format-helpers");
-class ListProjectsTool {
-    searcher;
-    constructor(searcher) {
-        this.searcher = searcher;
-    }
-    definition() {
-        return {
+const McpTool_1 = require("./McpTool");
+const ARGS = zod_1.z.object({});
+class ListProjectsTool extends McpTool_1.McpTool {
+    catalog;
+    constructor(catalog, logger = LoggerService_1.LoggerService.silent()) {
+        super({
             name: 'list_projects',
             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: {} },
-        };
+            args: ARGS,
+        }, logger);
+        this.catalog = catalog;
     }
-    async handle(_args) {
-        const rows = await this.searcher.listProjects();
+    async run() {
+        const rows = await this.catalog.listProjects();
         if (rows.length === 0) {
             return (0, format_helpers_1.textResponse)('No indexed projects found.');
         }

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

@@ -0,0 +1,17 @@
+import type { z } from 'zod';
+import type { IMcpToolHandler, ToolDefinition, ToolResponse } from '../interfaces/IMcpToolHandler';
+import type { ILogger } from '../interfaces/ILogger';
+export interface McpToolSpec<S extends z.ZodObject> {
+    name: string;
+    description: string;
+    args: S;
+}
+export declare abstract class McpTool<S extends z.ZodObject> implements IMcpToolHandler {
+    private readonly spec;
+    protected readonly logger: ILogger;
+    private cachedDefinition?;
+    constructor(spec: McpToolSpec<S>, logger: ILogger);
+    definition(): ToolDefinition;
+    handle(raw: Record<string, unknown>): Promise<ToolResponse>;
+    protected abstract run(args: z.output<S>): Promise<ToolResponse>;
+}

package/dist/src/tools/McpTool.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+const tool_args_1 = require("./tool-args");
+class McpTool {
+    spec;
+    logger;
+    cachedDefinition;
+    constructor(spec, logger) {
+        this.spec = spec;
+        this.logger = logger;
+    }
+    definition() {
+        const { name, description, args } = this.spec;
+        return this.cachedDefinition ??= { name, description, inputSchema: (0, tool_args_1.toInputSchema)(args) };
+    }
+    async handle(raw) {
+        const parsed = (0, tool_args_1.parseToolArgs)(this.spec.args, raw);
+        if (parsed.ok)
+            return this.run(parsed.args);
+        const { failure } = parsed;
+        return failure.kind === 'missing-path'
+            ? (0, format_helpers_1.pathErrorResponse)(this.logger, this.spec.name, failure.arg, '', '', { ok: false, reason: 'invalid', missing: true }, failure.pathKind)
+            : (0, format_helpers_1.errorResponse)(failure.text);
+    }
+}
+exports.McpTool = McpTool;

package/dist/src/tools/ReadFileRangeTool.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 ReadFileRangeTool 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>>;
+    start_line: z.ZodType<number, unknown, z.core.$ZodTypeInternals<number, unknown>>;
+    end_line: z.ZodType<number | undefined, unknown, z.core.$ZodTypeInternals<number | undefined, unknown>>;
+}, z.core.$strip>;
+export declare class ReadFileRangeTool extends McpTool<typeof ARGS> {
+    private paths;
+    private files;
+    constructor(paths: IToolPaths, files: IWorkspaceFiles, logger: ILogger);
+    protected run(args: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/ReadFileRangeTool.js

@@ -1,37 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadFileRangeTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
-class ReadFileRangeTool {
-    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)()),
+    start_line: (0, tool_args_1.intInRange)('First line to read (1-based). Use the **Line** number from search_codebase results. Default: 1.', { min: 1, fallback: 1 }),
+    end_line: (0, tool_args_1.intInRange)('Last line to read (1-based, inclusive). Default: start_line + 99.'),
+});
+class ReadFileRangeTool extends McpTool_1.McpTool {
+    paths;
+    files;
+    constructor(paths, files, logger) {
+        super({
             name: 'read_file_range',
             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: (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.' },
-                },
-                required: ['file_path'],
-            },
-        };
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.files = files;
     }
-    async handle(args) {
-        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 resolved = await this.searcher.resolveToolPath(input);
+    async run(args) {
+        const input = args.file_path;
+        const startLine = args.start_line;
+        const endLine = args.end_line ?? startLine + 99;
+        const resolved = await this.paths.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);
+        const range = await this.files.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');

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

@@ -1,10 +1,17 @@
-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 ReadFileTool 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>>;
+    max_lines: z.ZodType<number, unknown, z.core.$ZodTypeInternals<number, unknown>>;
+}, z.core.$strip>;
+export declare class ReadFileTool extends McpTool<typeof ARGS> {
+    private paths;
+    private files;
+    constructor(paths: IToolPaths, files: IWorkspaceFiles, logger: ILogger);
+    protected run({ file_path: input, max_lines: maxLines }: z.output<typeof ARGS>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/ReadFileTool.js

@@ -1,36 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReadFileTool = void 0;
+const zod_1 = require("zod");
 const format_helpers_1 = require("./format-helpers");
-class ReadFileTool {
-    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)()),
+    max_lines: (0, tool_args_1.intInRange)('Maximum lines to return (default 300, max 1000)', { min: 1, max: 1000, fallback: 300 }),
+});
+class ReadFileTool extends McpTool_1.McpTool {
+    paths;
+    files;
+    constructor(paths, files, logger) {
+        super({
             name: 'read_file',
             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: (0, format_helpers_1.pathArgDescription)() },
-                    max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
-                },
-                required: ['file_path'],
-            },
-        };
+            args: ARGS,
+        }, logger);
+        this.paths = paths;
+        this.files = files;
     }
-    async handle(args) {
-        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 resolved = await this.searcher.resolveToolPath(input);
+    async run({ file_path: input, max_lines: maxLines }) {
+        const resolved = await this.paths.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);
+        const result = await this.files.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');

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

@@ -1,13 +1,25 @@
-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 { IChunkSearch } from '../interfaces/IChunkSearch';
+import type { IDependencyGraph } from '../interfaces/IDependencyGraph';
 import type { ILogger } from '../interfaces/ILogger';
-export declare class SearchCodebaseTool implements IMcpToolHandler {
-    private searcher;
-    private defaultLimit;
-    private maxLimit;
+import { McpTool } from './McpTool';
+declare function searchArgs(defaultLimit: number, maxLimit: number, defaultThreshold: number): z.ZodObject<{
+    query: z.ZodType<string, unknown, z.core.$ZodTypeInternals<string, unknown>>;
+    limit: z.ZodType<number, unknown, z.core.$ZodTypeInternals<number, unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    include_neighbors: z.ZodType<boolean | undefined, unknown, z.core.$ZodTypeInternals<boolean | undefined, unknown>>;
+    include_graph_context: z.ZodType<boolean | undefined, unknown, z.core.$ZodTypeInternals<boolean | undefined, unknown>>;
+    threshold: z.ZodType<number | undefined, unknown, z.core.$ZodTypeInternals<number | undefined, unknown>>;
+    per_file: z.ZodType<number, unknown, z.core.$ZodTypeInternals<number, unknown>>;
+    rerank: z.ZodType<boolean | undefined, unknown, z.core.$ZodTypeInternals<boolean | undefined, unknown>>;
+}, z.core.$strip>;
+type SearchArgs = ReturnType<typeof searchArgs>;
+export declare class SearchCodebaseTool extends McpTool<SearchArgs> {
+    private chunks;
+    private dependencies;
     private defaultThreshold;
-    private logger;
-    constructor(searcher: ISearcher, defaultLimit: number, maxLimit: number, defaultThreshold: number, logger: ILogger);
-    definition(): ToolDefinition;
-    handle(args: Record<string, unknown>): Promise<ToolResponse>;
+    constructor(chunks: IChunkSearch, dependencies: IDependencyGraph, defaultLimit: number, maxLimit: number, defaultThreshold: number, logger: ILogger);
+    protected run(args: z.output<SearchArgs>): Promise<ToolResponse>;
 }
+export {};

package/dist/src/tools/SearchCodebaseTool.js

@@ -1,73 +1,94 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SearchCodebaseTool = void 0;
+const zod_1 = require("zod");
 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;
+const McpTool_1 = require("./McpTool");
+const tool_args_1 = require("./tool-args");
+const result_shaping_1 = require("../search/result-shaping");
+const constants_1 = require("../constants");
+function searchArgs(defaultLimit, maxLimit, defaultThreshold) {
+    const shown = (0, constants_1.formatThreshold)(defaultThreshold);
+    const stricter = defaultThreshold > 0 ? ' Use a stricter value a little below the default for precise technical queries.' : '';
+    const raise = defaultThreshold < 1 ? ' Raise it (up to 1.0) when a search finds nothing.' : '';
+    return zod_1.z.object({
+        query: (0, tool_args_1.requiredText)(),
+        limit: (0, tool_args_1.intInRange)(`Max results (default ${defaultLimit}, max ${maxLimit})`, { min: 1, max: maxLimit, fallback: defaultLimit }),
+        project: (0, tool_args_1.optionalText)('Filter by project name (optional). Use list_projects to see available names.'),
+        include_neighbors: (0, tool_args_1.flag)('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: (0, tool_args_1.flag)('Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.'),
+        threshold: (0, tool_args_1.numberInRange)(`Max cosine distance (0–1). Lower = stricter. Default: ${shown}.${stricter}${raise}`, { min: 0, max: 1 }),
+        per_file: (0, tool_args_1.intInRange)(`Max results from one file (integer ≥ 1, default ${result_shaping_1.DEFAULT_PER_FILE}). Skipped results are backfilled from the next candidates. Raise it when one file is expected to hold several answers (e.g. several methods of one class).`, { min: 1, fallback: result_shaping_1.DEFAULT_PER_FILE }),
+        rerank: (0, tool_args_1.flag)('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 (fine for conceptual/architectural queries, where reranking is roughly neutral).'),
+    });
+}
+const DISTANCE_NOTE = '> Lower distance = closer match. Results may be reranked, so their order need not follow the distance.';
+function renderNoResults(cause, project, threshold) {
+    const first = 'No relevant results found.';
+    switch (cause) {
+        case 'empty-scope':
+            return `${first}\n${project
+                ? `Project \`${project}\` has no indexed chunks. Check the name with \`list_projects\`.`
+                : 'The index holds no chunks. Run `rag-index`.'}`;
+        case 'no-candidates': {
+            const steps = ['rephrase the query', 'use `find_symbol` for a known name'];
+            if (project)
+                steps.push('drop `project`');
+            if (threshold < 1)
+                steps.push('pass a higher `threshold`');
+            const last = steps.pop();
+            return `${first}\nNo chunk ${project ? `of project \`${project}\` ` : ''}came within the distance threshold, which does not show the code is absent. Next: ${steps.join(', ')}, or ${last}.`;
+        }
+        case 'lookup-failed':
+            return `${first}\nThe cause could not be determined, so this does not show the code is absent.`;
     }
-    definition() {
-        return {
+}
+class SearchCodebaseTool extends McpTool_1.McpTool {
+    chunks;
+    dependencies;
+    defaultThreshold;
+    constructor(chunks, dependencies, defaultLimit, maxLimit, defaultThreshold, logger) {
+        super({
             name: 'search_codebase',
-            description: 'Search local project codebase by semantic similarity. Each result shows File, Project, an optional Symbol breadcrumb (owning declaration, e.g. `IndexerService.ingestFile`), Line, the code, and Relevance.',
-            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.` },
-                    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'],
-            },
-        };
+            description: 'Search local project codebase by semantic similarity. Each result shows File, Project, an optional Symbol breadcrumb (owning declaration, e.g. `IndexerService.ingestFile`), Line, the code, and Distance (cosine distance: lower is closer).',
+            args: searchArgs(defaultLimit, maxLimit, defaultThreshold),
+        }, logger);
+        this.chunks = chunks;
+        this.dependencies = dependencies;
+        this.defaultThreshold = defaultThreshold;
     }
-    async handle(args) {
+    async run(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 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, rerank);
+        const raw = args.query;
+        const limit = args.limit;
+        const project = args.project ?? null;
+        const includeNeighbors = args.include_neighbors ?? false;
+        const includeGraphContext = args.include_graph_context ?? false;
+        const threshold = args.threshold;
+        const rerank = args.rerank;
+        const perFile = args.per_file;
+        const { query, translated } = await this.chunks.prepareQuery(raw);
+        const results = await this.chunks.searchChunks(query, limit, project, threshold, rerank, perFile);
         this.logger.debug('SearchCodebaseTool: handle', {
             query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
-            limit, translated, count: results.length, ms: Date.now() - t0,
+            limit, perFile, translated, count: results.length, ms: Date.now() - t0,
         });
         if (results.length === 0) {
-            return (0, format_helpers_1.textResponse)('No relevant results found.');
+            const cause = await this.chunks.explainNoResults(project);
+            return (0, format_helpers_1.textResponse)(renderNoResults(cause, project, threshold ?? this.defaultThreshold));
         }
-        const header = translated ? `> Query translated: "${raw}" → "${query}"\n\n` : '';
+        const header = `${translated ? `> Query translated: "${raw}" → "${query}"\n` : ''}${DISTANCE_NOTE}\n\n`;
         let graphCtx = null;
         if (includeGraphContext) {
-            graphCtx = await this.searcher.fetchGraphContext(results);
+            graphCtx = await this.dependencies.fetchGraphContext(results);
         }
         if (includeNeighbors) {
-            const withNeighbors = await this.searcher.fetchNeighbors(results);
+            const withNeighbors = await this.chunks.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))}`);
+                parts.push(`${(0, format_helpers_1.formatChunk)(result)}\n**Distance:** ${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');
@@ -75,7 +96,7 @@ class SearchCodebaseTool {
             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))}`)
+            .map(r => `${(0, format_helpers_1.formatChunk)(r)}\n**Distance:** ${r.score}${(0, format_helpers_1.formatGraphContext)(graphCtx?.get(r.filePath))}`)
             .join('\n\n---\n\n');
         return (0, format_helpers_1.textResponse)(header + text);
     }

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

@@ -1,23 +1,23 @@
-import type { ChunkRow, DependencyRow, GraphContext, FileRangeResult, PathFailure, PathRefusal } from '../services/SearcherService';
+import type { ChunkRow } from '../interfaces/IChunkSearch';
+import type { DependencyRow, GraphContext } from '../interfaces/IDependencyGraph';
+import type { FileRangeResult } from '../interfaces/IWorkspaceFiles';
+import type { PathFailure, PathRefusal } from '../interfaces/IToolPaths';
 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 declare function formatDependencies(filePath: string, rows: DependencyRow[], transitive: boolean, symbol?: string | null): string;
+export declare function formatDependents(filePath: string, rows: DependencyRow[], transitive: boolean, symbol?: string | null): string;
+export declare function formatTransitiveSection(rows: DependencyRow[], symbol: string | null, side: 'dependencies' | 'dependents'): string;
+export declare function formatDependenciesFilterMiss(filePath: string, symbol: string, unfiltered: DependencyRow[]): string;
+export declare function formatDependentsFilterMiss(filePath: string, symbol: string, unfiltered: DependencyRow[]): 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;