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

package/dist/src/tools/ListFilesTool.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListFilesTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ListFilesTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'list_files',
+            description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'Directory path relative to the project root (e.g. "src/components" or "." for root)' },
+                    project: { type: 'string', description: 'Project name (from list_projects)' },
+                    depth: { type: 'number', description: 'Tree depth: 1 = immediate children only, up to 5. Default: 2.' },
+                    pattern: { type: 'string', description: 'Optional filename filter (substring or extension like ".ts"). Only matching files are shown.' },
+                },
+                required: ['path', 'project'],
+            },
+        };
+    }
+    async handle(args) {
+        const relPath = String(args.path ?? '.');
+        const project = String(args.project ?? '');
+        const rawDepth = Number(args.depth);
+        const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
+        const pattern = args.pattern ? String(args.pattern) : null;
+        const { tree, error } = this.searcher.listFiles(relPath, project, depth, pattern);
+        if (error) {
+            return (0, format_helpers_1.textResponse)(`list_files error: ${error}`);
+        }
+        return (0, format_helpers_1.textResponse)(`**${project}/${relPath}**\n\`\`\`\n${tree}\n\`\`\``);
+    }
+}
+exports.ListFilesTool = ListFilesTool;

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

@@ -0,0 +1,8 @@
+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>;
+}

package/dist/src/tools/ListProjectsTool.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListProjectsTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ListProjectsTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'list_projects',
+            description: 'List all indexed projects with their chunk counts and metadata (description, stack, notes, relations from .ragmeta.json).',
+            inputSchema: { type: 'object', properties: {} },
+        };
+    }
+    async handle(_args) {
+        const rows = await this.searcher.listProjects();
+        if (rows.length === 0) {
+            return (0, format_helpers_1.textResponse)('No indexed projects found.');
+        }
+        return (0, format_helpers_1.textResponse)(rows.map(r => {
+            const lines = [`${r.serviceName}: ${r.chunks} chunks`];
+            if (r.packageName)
+                lines.push(`  package: ${r.packageName}`);
+            if (r.type)
+                lines.push(`  type: ${r.type}`);
+            if (r.description)
+                lines.push(`  description: ${r.description}`);
+            if (r.stack)
+                lines.push(`  stack: ${r.stack}`);
+            if (r.notes)
+                lines.push(`  notes: ${r.notes}`);
+            if (r.relations) {
+                for (const [key, val] of Object.entries(r.relations)) {
+                    const list = Array.isArray(val) ? val.join(', ') : val;
+                    lines.push(`  ${key}: ${list}`);
+                }
+            }
+            return lines.join('\n');
+        }).join('\n\n'));
+    }
+}
+exports.ListProjectsTool = ListProjectsTool;

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

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

package/dist/src/tools/ReadFileRangeTool.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileRangeTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ReadFileRangeTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'read_file_range',
+            description: 'Read a specific line range from an indexed source file. Use this when a search result looks incomplete — read the surrounding lines to get full context.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'File path as returned by search_codebase' },
+                    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'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path);
+        const startLine = Math.max(1, Number(args.start_line) || 1);
+        const endLine = Number(args.end_line) || startLine + 99;
+        const range = await this.searcher.readFileRange(filePath, startLine, endLine);
+        if (!range.ok) {
+            const message = range.reason === 'invalid_path' ? `Invalid file path (outside workspace): ${filePath}` :
+                range.reason === 'not_indexed' ? `File is not indexed: ${filePath}. Run indexing first.` :
+                    `File was deleted from disk after indexing: ${filePath}. Re-run indexing to update.`;
+            return (0, format_helpers_1.textResponse)(message);
+        }
+        const numbered = range.lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+        let text = `**File:** ${range.filePath}\n**Lines:** ${range.startLine}–${range.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+        if (range.hasMore) {
+            text += `\n\n[file has more lines — call read_file_range again with start_line: ${range.endLine + 1}]`;
+        }
+        return (0, format_helpers_1.textResponse)(text);
+    }
+}
+exports.ReadFileRangeTool = ReadFileRangeTool;

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

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

package/dist/src/tools/ReadFileTool.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileTool = void 0;
+const format_helpers_1 = require("./format-helpers");
+class ReadFileTool {
+    searcher;
+    constructor(searcher) {
+        this.searcher = searcher;
+    }
+    definition() {
+        return {
+            name: 'read_file',
+            description: 'Read a file by absolute path. Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    file_path: { type: 'string', description: 'Absolute path to the file. Note: search_codebase returns relative paths — construct the absolute path from your workspace root.' },
+                    max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
+                },
+                required: ['file_path'],
+            },
+        };
+    }
+    async handle(args) {
+        const filePath = String(args.file_path ?? '');
+        const rawMax = Number(args.max_lines);
+        const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
+        const result = await this.searcher.readFileAbsolute(filePath, maxLines);
+        if (!result.ok) {
+            const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
+                `File not found on disk: ${filePath}`;
+            return (0, format_helpers_1.textResponse)(message);
+        }
+        const numbered = result.lines.map((line, i) => `${i + 1}: ${line}`).join('\n');
+        let text = `**File:** ${result.filePath}\n**Lines:** 1–${result.endLine}\n\`\`\`\n${numbered}\n\`\`\``;
+        if (result.hasMore) {
+            text += `\n\n[truncated: file has more lines — use read_file_range with file_path: "${result.filePath}", start_line: ${result.endLine + 1} to continue]`;
+        }
+        return (0, format_helpers_1.textResponse)(text);
+    }
+}
+exports.ReadFileTool = ReadFileTool;

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

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

package/dist/src/tools/SearchCodebaseTool.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchCodebaseTool = void 0;
+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;
+    }
+    definition() {
+        return {
+            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.` },
+                },
+                required: ['query'],
+            },
+        };
+    }
+    async handle(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 { query, translated } = await this.searcher.prepareQuery(raw);
+        const results = await this.searcher.searchChunks(query, limit, project, threshold);
+        this.logger.debug('SearchCodebaseTool: handle', {
+            query: raw.slice(0, 120), project, threshold: threshold ?? this.defaultThreshold,
+            limit, translated, count: results.length, ms: Date.now() - t0,
+        });
+        if (results.length === 0) {
+            return (0, format_helpers_1.textResponse)('No relevant results found.');
+        }
+        const header = translated ? `> Query translated: "${raw}" → "${query}"\n\n` : '';
+        let graphCtx = null;
+        if (includeGraphContext) {
+            graphCtx = await this.searcher.fetchGraphContext(results);
+        }
+        if (includeNeighbors) {
+            const withNeighbors = await this.searcher.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))}`);
+                if (nextChunk)
+                    parts.push((0, format_helpers_1.formatChunk)(nextChunk, 'next chunk'));
+                return parts.join('\n\n');
+            });
+            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))}`)
+            .join('\n\n---\n\n');
+        return (0, format_helpers_1.textResponse)(header + text);
+    }
+}
+exports.SearchCodebaseTool = SearchCodebaseTool;

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

@@ -0,0 +1,8 @@
+import type { ChunkRow, DependencyRow, GraphContext } from '../services/SearcherService';
+import type { ToolResponse } from '../interfaces/IMcpToolHandler';
+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;

package/dist/src/tools/format-helpers.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textResponse = textResponse;
+exports.errorResponse = errorResponse;
+exports.formatChunk = formatChunk;
+exports.formatGraphContext = formatGraphContext;
+exports.formatDependencies = formatDependencies;
+exports.formatDependents = formatDependents;
+function textResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function errorResponse(text) {
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+function formatChunk(r, label) {
+    const symbolLine = r.ownerPath ? `**Symbol:** ${r.ownerPath}\n` : '';
+    return `${label ? `*(${label})*\n` : ''}**File:** ${r.filePath}\n**Project:** ${r.serviceName}\n${symbolLine}**Line:** ${r.startLine}\n\`\`\`\n${r.content}\n\`\`\``;
+}
+function formatGraphContext(ctx) {
+    const parts = [];
+    if (ctx?.imports.length)
+        parts.push(`**Imports:** ${ctx.imports.join(' · ')}`);
+    if (ctx?.usedBy.length)
+        parts.push(`**Used by:** ${ctx.usedBy.join(' · ')}`);
+    return parts.length > 0 ? '\n' + parts.join('\n') : '';
+}
+function formatDependencies(filePath, rows, transitive) {
+    const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
+    const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
+    const lines = [`**Dependencies of** \`${filePath}\`\n`, '**Direct:**'];
+    for (const r of direct) {
+        const sym = r.toSymbol ? ` (${r.depType} \`${r.toSymbol}\`)` : ` (${r.depType})`;
+        lines.push(`  → \`${r.toFile}\`${sym}`);
+    }
+    if (indirect.length > 0) {
+        lines.push('\n**Transitive:**');
+        for (const r of indirect) {
+            lines.push(`  → \`${r.toFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
+        }
+    }
+    return lines.join('\n');
+}
+function formatDependents(filePath, rows, transitive) {
+    const direct = rows.filter(r => !transitive || (r.depth ?? 1) === 1);
+    const indirect = transitive ? rows.filter(r => (r.depth ?? 1) > 1) : [];
+    const lines = [`**Dependents of** \`${filePath}\`\n`, '**Direct:**'];
+    for (const r of direct) {
+        const sym = r.fromSymbol ? ` (in \`${r.fromSymbol}\`)` : '';
+        lines.push(`  ← \`${r.fromFile}\`${sym}`);
+    }
+    if (indirect.length > 0) {
+        lines.push('\n**Transitive:**');
+        for (const r of indirect) {
+            lines.push(`  ← \`${r.fromFile}\` (depth ${r.depth}, via \`${r.via}\`)`);
+        }
+    }
+    return lines.join('\n');
+}

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

@@ -0,0 +1,9 @@
+export { ListProjectsTool } from './ListProjectsTool';
+export { SearchCodebaseTool } from './SearchCodebaseTool';
+export { ReadFileRangeTool } from './ReadFileRangeTool';
+export { GetDependenciesTool } from './GetDependenciesTool';
+export { GetDependentsTool } from './GetDependentsTool';
+export { FindSymbolTool } from './FindSymbolTool';
+export { GetCallersTool } from './GetCallersTool';
+export { ListFilesTool } from './ListFilesTool';
+export { ReadFileTool } from './ReadFileTool';

package/dist/src/tools/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReadFileTool = exports.ListFilesTool = exports.GetCallersTool = exports.FindSymbolTool = exports.GetDependentsTool = exports.GetDependenciesTool = exports.ReadFileRangeTool = exports.SearchCodebaseTool = exports.ListProjectsTool = void 0;
+var ListProjectsTool_1 = require("./ListProjectsTool");
+Object.defineProperty(exports, "ListProjectsTool", { enumerable: true, get: function () { return ListProjectsTool_1.ListProjectsTool; } });
+var SearchCodebaseTool_1 = require("./SearchCodebaseTool");
+Object.defineProperty(exports, "SearchCodebaseTool", { enumerable: true, get: function () { return SearchCodebaseTool_1.SearchCodebaseTool; } });
+var ReadFileRangeTool_1 = require("./ReadFileRangeTool");
+Object.defineProperty(exports, "ReadFileRangeTool", { enumerable: true, get: function () { return ReadFileRangeTool_1.ReadFileRangeTool; } });
+var GetDependenciesTool_1 = require("./GetDependenciesTool");
+Object.defineProperty(exports, "GetDependenciesTool", { enumerable: true, get: function () { return GetDependenciesTool_1.GetDependenciesTool; } });
+var GetDependentsTool_1 = require("./GetDependentsTool");
+Object.defineProperty(exports, "GetDependentsTool", { enumerable: true, get: function () { return GetDependentsTool_1.GetDependentsTool; } });
+var FindSymbolTool_1 = require("./FindSymbolTool");
+Object.defineProperty(exports, "FindSymbolTool", { enumerable: true, get: function () { return FindSymbolTool_1.FindSymbolTool; } });
+var GetCallersTool_1 = require("./GetCallersTool");
+Object.defineProperty(exports, "GetCallersTool", { enumerable: true, get: function () { return GetCallersTool_1.GetCallersTool; } });
+var ListFilesTool_1 = require("./ListFilesTool");
+Object.defineProperty(exports, "ListFilesTool", { enumerable: true, get: function () { return ListFilesTool_1.ListFilesTool; } });
+var ReadFileTool_1 = require("./ReadFileTool");
+Object.defineProperty(exports, "ReadFileTool", { enumerable: true, get: function () { return ReadFileTool_1.ReadFileTool; } });

package/dist/src/web/dashboard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Renders the RAG dashboard as a single self-contained HTML page (inline CSS +
+ * JS), mirroring the approach in graph.ts. The page is schema-driven: it fetches
+ * /api/schema (from buildJsonSchema — the same source as Step 1's editor support)
+ * and /api/config, then renders a typed form. The Graph tab embeds the full
+ * standalone graph page (GET /graph — same buildHtml as project-graph.html) in
+ * an iframe rather than re-implementing the network here.
+ */
+export declare function renderDashboardHtml(): string;