codesearch-mcp 0.0.17-alpha.1 → 0.1.0-alpha

package/dist/src/setup.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.dockerPromptDefault = dockerPromptDefault;
 exports.runSetup = runSetup;
 const readline = __importStar(require("readline"));
 const fs = __importStar(require("fs"));
@@ -42,12 +43,16 @@ const child_process_1 = require("child_process");
 const constants_1 = require("./constants");
 const config_store_1 = require("./config-store");
 const config_1 = require("./config");
+const InfinityEmbedder_1 = require("./services/InfinityEmbedder");
 const DEFAULT_LOG_DIR = path.join(config_store_1.CONFIG_DIR, 'logs');
 const _projectRoot = fs.existsSync(path.join(__dirname, '..', 'package.json'))
     ? path.join(__dirname, '..')
     : path.join(__dirname, '..', '..');
 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');
+const DEFAULT_INFINITY_RERANK_MODEL = 'Alibaba-NLP/gte-reranker-modernbert-base';
 function ask(rl, question) {
     return new Promise(resolve => rl.question(question, resolve));
 }
@@ -60,6 +65,79 @@ function expandHome(p) {
         return path.join(os.homedir(), p.slice(2));
     return p;
 }
+const PROVIDER_DEFAULTS = {
+    'ollama': { baseURL: 'http://localhost:11434', model: constants_1.DEFAULT_EMBED_MODEL, envVar: '' },
+    '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-3', envVar: 'VOYAGE_API_KEY' },
+    'infinity': { baseURL: 'http://localhost:7997', model: 'jinaai/jina-embeddings-v2-base-code', envVar: '' },
+};
+/** Providers that run a local inference backend we can probe / provision. */
+function isLocalBackend(p) {
+    return p === 'ollama' || p === 'infinity';
+}
+/**
+ * Probe whether the embedding backend is already reachable, so the "start
+ * Docker?" prompt can default to no (mirrors the DB `checkRemoteDb` flow).
+ * Cloud providers have no local backend → always "reachable" (nothing to start).
+ */
+async function checkEmbeddingBackend(provider, baseURL) {
+    if (!isLocalBackend(provider))
+        return true;
+    if (provider === 'infinity')
+        return (0, InfinityEmbedder_1.probeInfinityHealth)(baseURL);
+    // ollama — probe /api/tags
+    try {
+        const http = await Promise.resolve().then(() => __importStar(require('http')));
+        await new Promise((resolve, reject) => {
+            const req = http.get(`${baseURL.replace(/\/+$/, '')}/api/tags`, res => {
+                res.resume();
+                res.statusCode === 200 ? resolve() : reject(new Error(`status ${res.statusCode}`));
+            });
+            req.on('error', reject);
+            req.setTimeout(2000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Default answer for the "start Docker containers?" prompt: no only when both
+ * the database and the embedding backend are already reachable. Pure — exported
+ * for unit testing.
+ */
+function dockerPromptDefault(dbReachable, embReachable) {
+    return (dbReachable && embReachable) ? 'n' : 'y';
+}
+/** True when an NVIDIA GPU + `nvidia-smi` is available on this host. */
+function hasNvidiaGpu() {
+    try {
+        return (0, child_process_1.spawnSync)('nvidia-smi', ['-L'], { stdio: 'ignore' }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write (or replace) a single `KEY=VALUE` line in `~/.config/codesearch-mcp/.env`,
+ * chmod 600. API keys live here — never in config.json — referenced as `env:KEY`.
+ */
+function writeEnvKey(name, value) {
+    fs.mkdirSync(config_store_1.CONFIG_DIR, { recursive: true });
+    let existing = '';
+    try {
+        existing = fs.readFileSync(config_store_1.ENV_FILE, 'utf-8');
+    }
+    catch { /* absent */ }
+    const kept = existing.split(/\r?\n/).filter(l => l.trim() && !l.trim().startsWith(`${name}=`));
+    kept.push(`${name}=${value}`);
+    fs.writeFileSync(config_store_1.ENV_FILE, kept.join('\n') + '\n', { mode: 0o600 });
+    try {
+        fs.chmodSync(config_store_1.ENV_FILE, 0o600);
+    }
+    catch { /* best effort */ }
+}
 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;
@@ -79,7 +157,7 @@ async function waitForDb(host, port, user, pass, db, maxWaitSec = 60, logger, st
     }
     const reason = 'PostgreSQL did not become ready in time.';
     console.error(`\n${reason}`);
-    logger?.error('waitForDb: timeout', { reason, steps });
+    logger?.error('waitForDb: timeout', { reason, steps: JSON.stringify(steps) });
     process.exit(1);
 }
 async function waitForOllama(host, maxWaitSec = 60, logger, steps) {
@@ -106,9 +184,34 @@ async function waitForOllama(host, maxWaitSec = 60, logger, steps) {
     }
     const reason = 'Ollama did not become ready in time.';
     console.error(`\n${reason}`);
-    logger?.error('waitForOllama: timeout', { reason, steps });
+    logger?.error('waitForOllama: timeout', { reason, steps: JSON.stringify(steps) });
     process.exit(1);
 }
+/**
+ * Poll Infinity's `/health` until ready. Unlike the DB/Ollama waiters this is
+ * NON-fatal: on CPU the first boot downloads the model set AND runs a lengthy
+ * per-model warmup (a reranker warmup batch alone can take minutes), so a
+ * timeout here does not mean failure — the container is usually just still
+ * warming up. Returns whether it became ready; the caller keeps going and
+ * writes the (valid) config either way. Generous default (30 min) for CPU.
+ */
+async function waitForInfinity(baseURL, maxWaitSec = 1800, logger, steps) {
+    const deadline = Date.now() + maxWaitSec * 1000;
+    process.stdout.write('Waiting for Infinity to be ready (first boot downloads + warms up the model set, this can take several minutes on CPU)');
+    while (Date.now() < deadline) {
+        if (await (0, InfinityEmbedder_1.probeInfinityHealth)(baseURL)) {
+            console.log(' ready.');
+            return true;
+        }
+        process.stdout.write('.');
+        await new Promise(r => setTimeout(r, 3000));
+    }
+    const reason = 'Infinity did not answer /health in time — it is likely still warming up.';
+    console.warn(`\n${reason}`);
+    console.warn(`  The container is running; check "docker logs codesearch-mcp-infinity-1" and, once /health responds, run: rag-index`);
+    logger?.warn('waitForInfinity: timeout (non-fatal)', { reason, steps: JSON.stringify(steps) });
+    return false;
+}
 async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
     try {
         const { Client } = await Promise.resolve().then(() => __importStar(require('pg')));
@@ -120,11 +223,12 @@ async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.error(`  Connection failed: ${msg}`);
-        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps });
+        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps: JSON.stringify(steps) });
         return false;
     }
 }
-async function startDockerContainers(ollamaHost, dbPort, dbUser, dbPass, logger, steps) {
+async function startDockerContainers(opts) {
+    const { provider, ollamaHost, embBaseURL, dbPort, dbUser, dbPass, embModel, rerankModel, startDb, startBackend, logger, steps } = opts;
     console.log('\nWriting docker-compose.yml to', DOCKER_COMPOSE_DST);
     const yamlQuote = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
     let composeContent = fs.readFileSync(DOCKER_COMPOSE_SRC, 'utf-8');
@@ -134,33 +238,77 @@ async function startDockerContainers(ollamaHost, dbPort, dbUser, dbPass, logger,
         .replace('"5433:5432"', `"${dbPort}:5432"`);
     fs.mkdirSync(config_store_1.CONFIG_DIR, { recursive: true });
     fs.writeFileSync(DOCKER_COMPOSE_DST, composeContent, 'utf-8');
-    console.log('\nStarting Docker containers...');
-    const upResult = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'up', '-d'], { stdio: 'inherit' });
-    if (upResult.status !== 0) {
-        const reason = 'Failed to start Docker containers. Make sure Docker is running.';
-        console.error(reason);
-        logger?.error('startDockerContainers: docker startup failed', { reason, steps });
-        process.exit(1);
+    // The GPU override is copied verbatim so the managed Infinity path can layer it.
+    try {
+        fs.copyFileSync(DOCKER_GPU_OVERRIDE_SRC, DOCKER_GPU_OVERRIDE_DST);
     }
-    await waitForDb('localhost', parseInt(dbPort), dbUser, dbPass, 'postgres', 60, logger, steps);
-    await waitForOllama(ollamaHost, 60, logger, steps);
-    const ollamaId = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'ps', '-q', 'ollama'], { encoding: 'utf-8' })
-        .stdout?.trim();
-    if (!ollamaId) {
-        const reason = 'Could not resolve ollama container ID from compose. Pull the model manually:';
+    catch { /* absent → CPU only */ }
+    const dockerFail = (reason) => {
         console.error(reason);
-        console.error(`  docker exec <ollama-container> ollama pull ${constants_1.DEFAULT_EMBED_MODEL}`);
-        logger?.error('startDockerContainers: ollama container not found', { reason, steps });
+        logger?.error('startDockerContainers: docker startup failed', { reason, steps: JSON.stringify(steps) });
         process.exit(1);
+    };
+    // --- Database ---
+    if (startDb) {
+        console.log('\nStarting the database container...');
+        const r = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'up', '-d', 'db'], { stdio: 'inherit' });
+        if (r.status !== 0)
+            dockerFail('Failed to start the database container. Make sure Docker is running.');
+        await waitForDb('localhost', parseInt(dbPort), dbUser, dbPass, 'postgres', 60, logger, steps);
+    }
+    // --- Embedding backend ---
+    if (!startBackend) {
+        if (isLocalBackend(provider))
+            console.log(`${provider} is already reachable — not starting a managed container.`);
+        else
+            console.log('Cloud embedding provider — no local backend to start.');
+        return;
+    }
+    if (provider === 'ollama') {
+        console.log('\nStarting the Ollama container...');
+        const r = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'up', '-d', 'ollama'], { stdio: 'inherit' });
+        if (r.status !== 0)
+            dockerFail('Failed to start the Ollama container. Make sure Docker is running.');
+        await waitForOllama(ollamaHost, 60, logger, steps);
+        const ollamaId = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'ps', '-q', 'ollama'], { encoding: 'utf-8' })
+            .stdout?.trim();
+        if (!ollamaId) {
+            const reason = 'Could not resolve ollama container ID from compose. Pull the model manually:';
+            console.error(reason);
+            console.error(`  docker exec <ollama-container> ollama pull ${embModel}`);
+            logger?.error('startDockerContainers: ollama container not found', { reason, steps: JSON.stringify(steps) });
+            process.exit(1);
+        }
+        console.log(`Pulling ${embModel} model (this may take a while)...`);
+        // `-t` allocates a pseudo-TTY so `ollama pull` renders its live progress bar;
+        // only when our stdout is itself a TTY (docker refuses `-t` without one).
+        const ttyFlag = process.stdout.isTTY ? ['-t'] : [];
+        (0, child_process_1.spawnSync)('docker', ['exec', ...ttyFlag, ollamaId, 'ollama', 'pull', embModel], { stdio: 'inherit' });
+        return;
+    }
+    if (provider === 'infinity') {
+        // Both models are bound at boot via a ";"-separated INFINITY_MODEL_ID.
+        const modelIds = [embModel, ...(rerankModel ? [rerankModel] : [])].join(';');
+        // Only layer the GPU override when it actually exists on disk — otherwise a
+        // GPU host whose override copy failed would get `-f <missing>` → hard failure
+        // instead of the intended CPU fallback.
+        const gpu = hasNvidiaGpu() && fs.existsSync(DOCKER_GPU_OVERRIDE_DST);
+        const files = ['-f', DOCKER_COMPOSE_DST, ...(gpu ? ['-f', DOCKER_GPU_OVERRIDE_DST] : [])];
+        console.log(`\nStarting the Infinity container (${gpu ? 'GPU' : 'CPU'}) serving: ${modelIds}`);
+        // `--force-recreate` so a changed model set recreates the container (D7) —
+        // Infinity binds its models at startup and won't pick up a new set otherwise.
+        const r = (0, child_process_1.spawnSync)('docker', ['compose', ...files, 'up', '-d', '--force-recreate', 'infinity'], { stdio: 'inherit', env: { ...process.env, INFINITY_MODEL_ID: modelIds } });
+        if (r.status !== 0)
+            dockerFail('Failed to start the Infinity container. Make sure Docker is running.');
+        await waitForInfinity(embBaseURL, 1800, logger, steps);
+        return;
     }
-    console.log(`Pulling ${constants_1.DEFAULT_EMBED_MODEL} model (this may take a while)...`);
-    (0, child_process_1.spawnSync)('docker', ['exec', ollamaId, 'ollama', 'pull', constants_1.DEFAULT_EMBED_MODEL], { stdio: 'inherit' });
 }
 async function runSetup(logger) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const steps = [];
     function logStep(q, raw) {
-        const a = /password/i.test(q) ? '***' : raw.trim();
+        const a = /password|key|secret|token/i.test(q) ? '***' : raw.trim();
         logger?.debug('setup: prompt', { q, a });
         steps.push({ q, a });
     }
@@ -191,23 +339,78 @@ async function runSetup(logger) {
             console.log('  Path is required.');
     } while (!workspaceInput.trim());
     const workspaceRoot = expandHome(workspaceInput.trim());
-    const ollamaHost = await loggedPrompt('Ollama API URL', 'http://localhost:11434');
+    console.log('\n--- Embedding backend ---');
+    console.log('  ollama            — local, zero-setup (default)');
+    console.log('  infinity          — local, one container serves embeddings + reranking (GPU/CPU)');
+    console.log('  openai-compatible — OpenAI cloud, or a local Infinity/TEI/vLLM server');
+    console.log('  voyage            — Voyage AI cloud');
+    const validProviders = ['ollama', 'infinity', 'openai-compatible', 'voyage'];
+    let embProvider;
+    do {
+        embProvider = (await loggedPrompt('Provider (ollama/infinity/openai-compatible/voyage)', 'ollama'));
+        if (!validProviders.includes(embProvider))
+            console.log(`  Invalid provider. Choose: ${validProviders.join(', ')}`);
+    } while (!validProviders.includes(embProvider));
+    const pd = PROVIDER_DEFAULTS[embProvider];
+    const embBaseURL = await loggedPrompt('Base URL', pd.baseURL);
+    const embModel = await loggedPrompt('Embedding model', pd.model);
+    // Infinity serves a reranker from the same container — offer to provision one.
+    let rerankModel = '';
+    if (embProvider === 'infinity') {
+        rerankModel = (await loggedPrompt(`Reranker model (served by the same Infinity container; blank to disable)`, DEFAULT_INFINITY_RERANK_MODEL)).trim();
+    }
+    // API keys go into .env (chmod 600); config.json only stores the env: reference.
+    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}`);
+        }
+    }
+    // Ollama host used by the Docker helper below (only meaningful for ollama).
+    const ollamaHost = embProvider === 'ollama' ? embBaseURL : 'http://localhost:11434';
     console.log('\n--- Database ---');
     const dbHost = await loggedPrompt('DB host', 'localhost');
     const dbPort = await loggedPrompt('DB port', '5433');
     const dbUser = await loggedPrompt('DB user', 'dev');
     const dbPass = await loggedPrompt('DB password', 'dev');
     process.stdout.write('\nTesting connection...');
-    const alreadyConnected = await checkRemoteDb(dbHost, dbPort, dbUser, dbPass, 'postgres', logger, steps);
-    if (alreadyConnected)
+    const dbReachable = await checkRemoteDb(dbHost, dbPort, dbUser, dbPass, 'postgres', logger, steps);
+    if (dbReachable)
         console.log('  Database is already reachable.');
-    const dockerDefault = alreadyConnected ? 'n' : 'y';
+    // Symmetric to the DB probe: a reachable embedding backend defaults "start
+    // Docker?" to no. Cloud providers have no local backend to start.
+    process.stdout.write('Checking embedding backend...');
+    const embReachable = await checkEmbeddingBackend(embProvider, embBaseURL);
+    if (isLocalBackend(embProvider)) {
+        console.log(embReachable ? `  ${embProvider} is already reachable.` : `  ${embProvider} is not reachable — it can be started via Docker.`);
+    }
+    else {
+        console.log('  cloud provider (no local backend to start).');
+    }
+    const dockerDefault = dockerPromptDefault(dbReachable, embReachable);
     const startDockerRaw = await loggedAsk(`Start Docker containers automatically? (y/n) (${dockerDefault}): `);
     const startDocker = (startDockerRaw.trim().toLowerCase() || dockerDefault) === 'y';
     if (startDocker) {
-        await startDockerContainers(ollamaHost, dbPort, dbUser, dbPass, logger, steps);
+        await startDockerContainers({
+            provider: embProvider,
+            ollamaHost,
+            embBaseURL,
+            dbPort, dbUser, dbPass,
+            embModel,
+            rerankModel: rerankModel || undefined,
+            startDb: !dbReachable,
+            startBackend: isLocalBackend(embProvider) && !embReachable,
+            logger, steps,
+        });
     }
-    else if (!alreadyConnected) {
+    else if (!dbReachable) {
         while (true) {
             console.log('\nTesting connection...');
             const ok = await checkRemoteDb(dbHost, dbPort, dbUser, dbPass, 'postgres', logger, steps);
@@ -242,10 +445,25 @@ async function runSetup(logger) {
             user: dbVars.user,
             password: dbVars.password,
         },
-        ollama: { host: ollamaHost },
+        embedding: {
+            provider: embProvider,
+            baseURL: embBaseURL,
+            model: embModel,
+            ...(apiKeyRef ? { apiKey: apiKeyRef } : {}),
+        },
         logging: { level: logLevel },
         workspaceRoot,
     };
+    // Infinity serves the reranker from the same container — auto-wire reranker.*
+    // to that server. `url` derives from provider + baseURL in the Config constructor.
+    if (embProvider === 'infinity' && rerankModel) {
+        cfg.reranker = {
+            enabled: true,
+            provider: 'openai-compatible',
+            baseURL: embBaseURL,
+            model: rerankModel,
+        };
+    }
     if (logDir)
         cfg.logging.dir = logDir;
     (0, config_store_1.writeConfigJson)(cfg);
@@ -266,11 +484,11 @@ async function runSetup(logger) {
     }
     if (initError) {
         console.error(`Database schema init failed: ${initError.message}`);
-        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps });
+        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps: JSON.stringify(steps) });
         process.exit(1);
     }
     console.log('\nSetup complete!');
     console.log('\nNext steps:');
-    console.log(`  rag-index ${workspaceRoot}`);
+    console.log('  rag-index');
     console.log('  claude mcp add codesearch-mcp -s user -- rag-mcp');
 }

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

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

package/dist/src/tools/FindSymbolTool.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FindSymbolTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+const VALID_KINDS = ['function', 'class', 'type', 'interface', 'variable', 'method', 'all'];
+class FindSymbolTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'find_symbol',
+            description: 'Find TypeScript/JavaScript symbol definitions (functions, classes, types, interfaces, variables, methods) by exact name. Use when you know the symbol name and want its definition location fast.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Exact symbol name (case-sensitive, whole-word match)' },
+                    project: { type: 'string', description: 'Limit search to this project (optional). Use list_projects to find names.' },
+                    kind: { type: 'string', enum: VALID_KINDS, description: 'Symbol kind filter. Default: all.' },
+                },
+                required: ['name'],
+            },
+        };
+    }
+    async handle(args) {
+        const name = String(args.name ?? '');
+        const project = args.project ? String(args.project) : null;
+        const rawKind = args.kind;
+        const kind = VALID_KINDS.includes(rawKind) ? rawKind : 'all';
+        const { hits, truncated } = await this.searcher.findSymbol(name, project, kind);
+        if (hits.length === 0) {
+            return (0, format_helpers_1.textResponse)(`No definitions found for symbol: ${name}`);
+        }
+        const lines = [];
+        if (truncated)
+            lines.push(`*(truncated to ${hits.length} results)*\n`);
+        for (const h of hits) {
+            lines.push(`**${h.kind}** \`${h.filePath}\` line ${h.line}, col ${h.column}`);
+            lines.push(`\`\`\`\n${h.signature}\n\`\`\``);
+        }
+        return (0, format_helpers_1.textResponse)(lines.join('\n'));
+    }
+}
+exports.FindSymbolTool = FindSymbolTool;

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

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

package/dist/src/tools/GetCallersTool.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetCallersTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class GetCallersTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'get_callers',
+            description: 'Find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called. Returns empty if rag-index backfill --calls has not been run.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    symbol: { type: 'string', description: 'Exact function or method name (case-sensitive)' },
+                    project: { type: 'string', description: 'Project name (from list_projects)' },
+                    callee_file: { type: 'string', description: 'Optional: filter by definition file path (as returned by find_symbol) to disambiguate overloaded names' },
+                },
+                required: ['symbol', 'project'],
+            },
+        };
+    }
+    async handle(args) {
+        const symbol = String(args.symbol ?? '');
+        const project = String(args.project ?? '');
+        const calleeFile = args.callee_file ? String(args.callee_file) : null;
+        const rows = await this.searcher.getCallers(symbol, project, calleeFile);
+        if (rows.length === 0) {
+            return (0, format_helpers_1.textResponse)(`No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index backfill --calls\` if the call graph has not been populated yet.`);
+        }
+        const lines = [`**Call sites of \`${symbol}\`** (${rows.length} found)\n`];
+        for (const r of rows) {
+            const loc = r.line != null ? ` line ${r.line}` : '';
+            const ctx = r.fromSymbol ? `, in \`${r.fromSymbol}\`` : '';
+            lines.push(`  → \`${r.fromFile}\`${loc}${ctx}`);
+        }
+        return (0, format_helpers_1.textResponse)(lines.join('\n'));
+    }
+}
+exports.GetCallersTool = GetCallersTool;

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

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

package/dist/src/tools/GetDependenciesTool.js

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

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

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

package/dist/src/tools/GetDependentsTool.js

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

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

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