codesearch-mcp 0.3.0-alpha → 0.4.0-alpha

package/dist/src/setup.js

@@ -34,8 +34,15 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMBEDDING_PROVIDER_CHOICES = void 0;
+exports.recordedStep = recordedStep;
+exports.setupStepLogger = setupStepLogger;
 exports.dockerPromptDefault = dockerPromptDefault;
 exports.rerankerChoices = rerankerChoices;
+exports.voyageEmbeddingModels = voyageEmbeddingModels;
+exports.promptModelChoice = promptModelChoice;
+exports.promptVoyageSetup = promptVoyageSetup;
+exports.promptSearchThreshold = promptSearchThreshold;
+exports.searchThresholdBlock = searchThresholdBlock;
 exports.promptReranker = promptReranker;
 exports.prepareComposeAndStartDb = prepareComposeAndStartDb;
 exports.provisionInfinity = provisionInfinity;
@@ -57,6 +64,18 @@ const DOCKER_COMPOSE_SRC = path.join(_projectRoot, 'docker', 'docker-compose.yml
 const DOCKER_COMPOSE_DST = path.join(config_store_1.CONFIG_DIR, 'docker-compose.yml');
 const DOCKER_GPU_OVERRIDE_SRC = path.join(_projectRoot, 'docker', 'docker-compose.infinity-gpu.yml');
 const DOCKER_GPU_OVERRIDE_DST = path.join(config_store_1.CONFIG_DIR, 'docker-compose.infinity-gpu.yml');
+function recordedStep(question, raw) {
+    const q = question.split('\n').find(l => l.trim())?.trim() ?? question.trim();
+    const a = /password|key|secret|token/i.test(q) ? '***' : raw.trim();
+    return { q, a };
+}
+function setupStepLogger(logger, steps) {
+    return (question, raw) => {
+        const step = recordedStep(question, raw);
+        logger?.debug('setup: prompt', step);
+        steps.push(step);
+    };
+}
 function ask(rl, question) {
     return new Promise(resolve => rl.question(question, resolve));
 }
@@ -71,7 +90,6 @@ function expandHome(p) {
 }
 const PROVIDER_DEFAULTS = {
     'openai-compatible': { baseURL: 'https://api.openai.com/v1', model: 'text-embedding-3-small', envVar: 'OPENAI_API_KEY' },
-    'voyage': { baseURL: 'https://api.voyageai.com/v1', model: 'voyage-code-4', envVar: 'VOYAGE_API_KEY' },
     'infinity': { baseURL: 'http://localhost:7997', model: 'jinaai/jina-embeddings-v2-base-code', envVar: '' },
 };
 exports.EMBEDDING_PROVIDER_CHOICES = ['infinity', 'openai-compatible', 'voyage'];
@@ -79,7 +97,7 @@ function isLocalBackend(p) {
     return p === 'infinity';
 }
 async function checkEmbeddingBackend(provider, baseURL) {
-    if (!isLocalBackend(provider))
+    if (!isLocalBackend(provider) || !baseURL)
         return true;
     return (0, infinity_provisioning_1.probeInfinityHealth)(baseURL);
 }
@@ -101,23 +119,78 @@ function writeEnvKey(name, value) {
     }
     catch { }
 }
+const VOYAGE_API_ENV = 'VOYAGE_API_KEY';
 const VOYAGE_RERANK_ENV = 'VOYAGE_RERANK_API_KEY';
 const RERANKER_ENV = 'RERANKER_API_KEY';
 function rerankerChoices(embProvider) {
     if (embProvider === 'infinity')
         return ['infinity', 'voyage', 'openai-compatible', 'none'];
-    if (embProvider === 'voyage')
-        return ['voyage', 'openai-compatible', 'none'];
     return ['none', 'voyage', 'openai-compatible'];
 }
-async function askRequired(io, question) {
+function voyageEmbeddingModels() {
+    return Object.entries(constants_1.MODEL_REGISTRY).filter(([, info]) => info.provider === 'voyage').map(([name]) => name);
+}
+async function askRequired(io, question, required = '  A value is required.') {
     for (;;) {
         const answer = (await io.ask(question)).trim();
         if (answer)
             return answer;
-        io.log('  A value is required.');
+        io.log(required);
+    }
+}
+async function promptModelChoice(io, label, models) {
+    models.forEach((m, i) => io.log(`  ${i + 1}) ${m}${i === 0 ? ' (default)' : ''}`));
+    for (;;) {
+        const answer = (await io.ask(`${label} (1-${models.length} or a model name) (1): `)).trim();
+        if (!answer)
+            return models[0];
+        if (!/^\d+$/.test(answer))
+            return answer;
+        const n = parseInt(answer, 10);
+        if (n >= 1 && n <= models.length)
+            return models[n - 1];
+        io.log(`  Enter a number from 1-${models.length}, or a model name.`);
     }
 }
+async function promptVoyageSetup(io) {
+    const key = await askRequired(io, `Voyage API key (stored in ${config_store_1.ENV_FILE} as ${VOYAGE_API_ENV}): `, '  The Voyage API key is required.');
+    io.writeEnvKey(VOYAGE_API_ENV, key);
+    io.log(`  Saved API key to ${config_store_1.ENV_FILE} as ${VOYAGE_API_ENV}.`);
+    const apiKey = `env:${VOYAGE_API_ENV}`;
+    const model = await promptModelChoice(io, 'Embedding model', voyageEmbeddingModels());
+    const embedding = { provider: 'voyage', model, apiKey };
+    io.log('\n--- Reranker ---');
+    let enable;
+    for (;;) {
+        enable = (await io.prompt('Enable Voyage reranker? (y/n)', 'y')).trim().toLowerCase();
+        if (enable === 'y' || enable === 'n')
+            break;
+        io.log('  Answer y or n.');
+    }
+    if (enable === 'n')
+        return { embedding, reranker: { enabled: false } };
+    const rerankModel = await promptModelChoice(io, 'Reranker model', constants_1.VOYAGE_RERANK_MODELS);
+    return { embedding, reranker: { enabled: true, provider: 'voyage', model: rerankModel, apiKey } };
+}
+async function promptSearchThreshold(io, model) {
+    const recommended = constants_1.MODEL_REGISTRY[model]?.defaultThreshold;
+    io.log('\n--- Search threshold ---');
+    io.log(recommended !== undefined
+        ? `  Recommended for ${model}: ${(0, constants_1.formatThreshold)(recommended)}`
+        : `  ${model} has no recommended value; left blank, only unrelated results are filtered out.`);
+    for (;;) {
+        const answer = (await io.ask('Similarity threshold: max cosine distance 0-1, lower is stricter (blank to follow the model): ')).trim();
+        if (!answer)
+            return undefined;
+        const value = Number(answer);
+        if (value >= 0 && value <= 1)
+            return value;
+        io.log('  Enter a number from 0 to 1, or leave it blank.');
+    }
+}
+function searchThresholdBlock(threshold) {
+    return threshold === undefined ? {} : { search: { similarityThreshold: threshold } };
+}
 function isHttpUrl(value) {
     try {
         const { protocol, username, password } = new URL(value);
@@ -181,6 +254,31 @@ async function promptReranker(embProvider, embBaseURL, io) {
         ...(key ? { apiKey: `env:${RERANKER_ENV}` } : {}),
     };
 }
+async function promptGenericBackend(embProvider, io) {
+    const pd = PROVIDER_DEFAULTS[embProvider];
+    const embBaseURL = await io.prompt('Base URL', pd.baseURL);
+    const embModel = await io.prompt('Embedding model', pd.model);
+    let apiKeyRef = '';
+    if (!isLocalBackend(embProvider)) {
+        const key = (await io.ask(`API key (stored in ${config_store_1.ENV_FILE}, leave blank to set later): `)).trim();
+        apiKeyRef = `env:${pd.envVar}`;
+        if (key) {
+            io.writeEnvKey(pd.envVar, key);
+            io.log(`  Saved API key to ${config_store_1.ENV_FILE} as ${pd.envVar} (config references env:${pd.envVar}).`);
+        }
+        else {
+            io.log(`  No key entered — set it later: echo '${pd.envVar}=sk-…' >> ${config_store_1.ENV_FILE}`);
+        }
+    }
+    const reranker = await promptReranker(embProvider, embBaseURL, io);
+    const embedding = {
+        provider: embProvider,
+        baseURL: embBaseURL,
+        model: embModel,
+        ...(apiKeyRef ? { apiKey: apiKeyRef } : {}),
+    };
+    return { embedding, reranker };
+}
 async function waitForDb(host, port, user, pass, db, maxWaitSec = 60, logger, steps) {
     const { Client } = await Promise.resolve().then(() => __importStar(require('pg')));
     const deadline = Date.now() + maxWaitSec * 1000;
@@ -309,15 +407,10 @@ async function provisionInfinity(savedConfig, startDocker, logger, deps = {}, co
 async function runSetup(logger) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const steps = [];
-    function logStep(q, raw) {
-        const a = /password|key|secret|token/i.test(q) ? '***' : raw.trim();
-        logger?.debug('setup: prompt', { q, a });
-        steps.push({ q, a });
-    }
+    const logStep = setupStepLogger(logger, steps);
     const loggedAsk = async (question) => {
         const answer = await ask(rl, question);
-        const key = question.split('\n').find(l => l.trim())?.trim() ?? question.trim();
-        logStep(key, answer);
+        logStep(question, answer);
         return answer;
     };
     const loggedPrompt = async (label, def) => {
@@ -351,25 +444,11 @@ async function runSetup(logger) {
         if (!exports.EMBEDDING_PROVIDER_CHOICES.includes(embProvider))
             console.log(`  Invalid provider. Choose: ${exports.EMBEDDING_PROVIDER_CHOICES.join(', ')}`);
     } while (!exports.EMBEDDING_PROVIDER_CHOICES.includes(embProvider));
-    const pd = PROVIDER_DEFAULTS[embProvider];
-    const embBaseURL = await loggedPrompt('Base URL', pd.baseURL);
-    const embModel = await loggedPrompt('Embedding model', pd.model);
-    let apiKeyRef = '';
-    if (!isLocalBackend(embProvider)) {
-        const key = (await loggedAsk(`API key (stored in ${config_store_1.ENV_FILE}, leave blank to set later): `)).trim();
-        if (key) {
-            writeEnvKey(pd.envVar, key);
-            apiKeyRef = `env:${pd.envVar}`;
-            console.log(`  Saved API key to ${config_store_1.ENV_FILE} as ${pd.envVar} (config references env:${pd.envVar}).`);
-        }
-        else {
-            apiKeyRef = `env:${pd.envVar}`;
-            console.log(`  No key entered — set it later: echo '${pd.envVar}=sk-…' >> ${config_store_1.ENV_FILE}`);
-        }
-    }
-    const reranker = await promptReranker(embProvider, embBaseURL, {
-        prompt: loggedPrompt, ask: loggedAsk, writeEnvKey, log: msg => console.log(msg),
-    });
+    const promptIO = { prompt: loggedPrompt, ask: loggedAsk, writeEnvKey, log: msg => console.log(msg) };
+    const { embedding, reranker } = embProvider === 'voyage'
+        ? await promptVoyageSetup(promptIO)
+        : await promptGenericBackend(embProvider, promptIO);
+    const searchThreshold = await promptSearchThreshold(promptIO, embedding.model ?? config_store_1.CONFIG_DEFAULTS['embedding.model']);
     console.log('\n--- Database ---');
     const dbHost = await loggedPrompt('DB host', 'localhost');
     const dbPort = await loggedPrompt('DB port', '5433');
@@ -380,7 +459,7 @@ async function runSetup(logger) {
     if (dbReachable)
         console.log('  Database is already reachable.');
     process.stdout.write('Checking embedding backend...');
-    const embReachable = await checkEmbeddingBackend(embProvider, embBaseURL);
+    const embReachable = await checkEmbeddingBackend(embProvider, embedding.baseURL);
     if (isLocalBackend(embProvider)) {
         console.log(embReachable ? `  ${embProvider} is already reachable.` : `  ${embProvider} is not reachable — it can be started via Docker.`);
     }
@@ -432,13 +511,9 @@ async function runSetup(logger) {
             user: dbVars.user,
             password: dbVars.password,
         },
-        embedding: {
-            provider: embProvider,
-            baseURL: embBaseURL,
-            model: embModel,
-            ...(apiKeyRef ? { apiKey: apiKeyRef } : {}),
-        },
+        embedding,
         reranker,
+        ...searchThresholdBlock(searchThreshold),
         logging: { level: logLevel },
         workspaceRoot,
     };
@@ -452,7 +527,7 @@ async function runSetup(logger) {
     }
     console.log('\nInitializing database schema...');
     const { DatabaseService } = await Promise.resolve().then(() => __importStar(require('./services/DatabaseService')));
-    const dbService = new DatabaseService(new config_1.Config());
+    const dbService = new DatabaseService(new config_1.Config(), logger);
     let initError = null;
     try {
         await dbService.initDbWithSchema();

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

@@ -1,5 +1,6 @@
 export declare const BARE_NAME_RE: RegExp;
 export declare const QUALIFIED_NAME_RE: RegExp;
+export declare const MAX_GREPPED_NAME_LEN = 256;
 export type FindSymbolQuery = {
     form: 'bare';
     name: string;

package/dist/src/symbol-name.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QUALIFIED_NAME_RE = exports.BARE_NAME_RE = void 0;
+exports.MAX_GREPPED_NAME_LEN = exports.QUALIFIED_NAME_RE = exports.BARE_NAME_RE = void 0;
 exports.splitQualified = splitQualified;
 exports.parseFindSymbolName = parseFindSymbolName;
 exports.parseCallerSymbol = parseCallerSymbol;
@@ -10,7 +10,7 @@ exports.QUALIFIED_NAME_RE = /^#?[\w$]+(\.#?[\w$]+)+$/;
 const PFX_SRC = '(?:#?[\\w$]+(?:\\.#?[\\w$]+)*\\.)?';
 const QUOTED_RE = new RegExp(`^(${PFX_SRC})('[^'\\r\\n]+'|"[^"\\r\\n]+")$`);
 const COMPUTED_RE = new RegExp(`^(${PFX_SRC})(\\[[^\\]\\r\\n]+\\])$`);
-const MAX_QUOTED_COMPUTED_LEN = 256;
+exports.MAX_GREPPED_NAME_LEN = 256;
 function stripTrailingDot(prefix) {
     if (!prefix)
         return null;
@@ -21,15 +21,15 @@ function splitQualified(input) {
     return { container: input.slice(0, idx), name: input.slice(idx + 1) };
 }
 function parseFindSymbolName(input) {
-    if (input.length <= MAX_QUOTED_COMPUTED_LEN) {
-        const quoted = input.match(QUOTED_RE);
-        if (quoted) {
-            return { form: 'quoted', container: stripTrailingDot(quoted[1]), name: quoted[2].slice(1, -1) };
-        }
-        const computed = input.match(COMPUTED_RE);
-        if (computed) {
-            return { form: 'computed', container: stripTrailingDot(computed[1]), name: computed[2].replace(/\s+/g, '') };
-        }
+    if (input.length > exports.MAX_GREPPED_NAME_LEN)
+        return null;
+    const quoted = input.match(QUOTED_RE);
+    if (quoted) {
+        return { form: 'quoted', container: stripTrailingDot(quoted[1]), name: quoted[2].slice(1, -1) };
+    }
+    const computed = input.match(COMPUTED_RE);
+    if (computed) {
+        return { form: 'computed', container: stripTrailingDot(computed[1]), name: computed[2].replace(/\s+/g, '') };
     }
     if (exports.QUALIFIED_NAME_RE.test(input)) {
         const { container, name } = splitQualified(input);
@@ -40,8 +40,12 @@ function parseFindSymbolName(input) {
     }
     return null;
 }
+function isQualifiedName(input) {
+    const segments = input.split('.');
+    return segments.length >= 2 && segments.every(segment => exports.BARE_NAME_RE.test(segment));
+}
 function parseCallerSymbol(input) {
-    if (exports.QUALIFIED_NAME_RE.test(input)) {
+    if (isQualifiedName(input)) {
         const { container, name } = splitQualified(input);
         return { form: 'qualified', container, name };
     }

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