code-graph-context 1.1.0 → 2.0.0

package/dist/mcp/tools/parse-typescript-project.tool.js

@@ -3,19 +3,66 @@
  * Parses TypeScript/NestJS projects and builds Neo4j graph
  */
 import { writeFileSync } from 'fs';
-import { stat } from 'fs/promises';
-import { join, resolve } from 'path';
-import { glob } from 'glob';
+import { constants as fsConstants } from 'fs';
+import { stat, access, realpath } from 'fs/promises';
+import { dirname, join, resolve, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { Worker } from 'worker_threads';
 import { z } from 'zod';
-import { EXCLUDE_PATTERNS_GLOB } from '../../constants.js';
 import { CORE_TYPESCRIPT_SCHEMA } from '../../core/config/schema.js';
 import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
 import { ParserFactory } from '../../core/parsers/parser-factory.js';
+import { resolveProjectId, getProjectName, UPSERT_PROJECT_QUERY, UPDATE_PROJECT_STATUS_QUERY, } from '../../core/utils/project-id.js';
 import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
-import { hashFile } from '../../utils/file-utils.js';
 import { TOOL_NAMES, TOOL_METADATA, DEFAULTS, FILE_PATHS, LOG_CONFIG } from '../constants.js';
+import { deleteSourceFileSubgraphs, loadExistingNodesForEdgeDetection, getCrossFileEdges, } from '../handlers/cross-file-edge.helpers.js';
+import { detectChangedFiles } from '../../core/utils/file-change-detection.js';
 import { GraphGeneratorHandler } from '../handlers/graph-generator.handler.js';
+import { StreamingImportHandler } from '../handlers/streaming-import.handler.js';
+import { jobManager } from '../services/job-manager.js';
+import { watchManager } from '../services/watch-manager.js';
 import { createErrorResponse, createSuccessResponse, formatParseSuccess, formatParsePartialSuccess, debugLog, } from '../utils.js';
+// Threshold for using streaming import (files)
+const STREAMING_THRESHOLD = 100;
+// Worker thread timeout (30 minutes)
+const WORKER_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * Validates that a path exists and is accessible
+ * @throws Error if path doesn't exist or isn't accessible
+ */
+const validatePathExists = async (path, pathType) => {
+    try {
+        await access(path, fsConstants.R_OK);
+        const stats = await stat(path);
+        if (pathType === 'directory' && !stats.isDirectory()) {
+            throw new Error(`Path exists but is not a directory: ${path}`);
+        }
+        if (pathType === 'file' && !stats.isFile()) {
+            throw new Error(`Path exists but is not a file: ${path}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Path does not exist: ${path}`);
+        }
+        throw error;
+    }
+};
+/**
+ * Validates that a resolved file path stays within the project directory
+ * to prevent path traversal attacks via symlinks
+ * @throws Error if path escapes project directory
+ */
+const _validatePathWithinProject = async (filePath, projectPath) => {
+    const realProjectPath = await realpath(projectPath);
+    const realFilePath = await realpath(filePath);
+    // Ensure file path is within project directory
+    if (!realFilePath.startsWith(realProjectPath + sep) && realFilePath !== realProjectPath) {
+        throw new Error(`SECURITY: Path traversal detected - file "${filePath}" resolves outside project directory`);
+    }
+};
+// Export for potential use by other modules
+export { _validatePathWithinProject as validatePathWithinProject };
 export const createParseTypescriptProjectTool = (server) => {
     server.registerTool(TOOL_NAMES.parseTypescriptProject, {
         title: TOOL_METADATA[TOOL_NAMES.parseTypescriptProject].title,
@@ -23,7 +70,11 @@ export const createParseTypescriptProjectTool = (server) => {
         inputSchema: {
             projectPath: z.string().describe('Path to the TypeScript project root directory'),
             tsconfigPath: z.string().describe('Path to TypeScript project tsconfig.json file'),
-            clearExisting: z.boolean().optional().describe('Clear existing graph data first'),
+            projectId: z
+                .string()
+                .optional()
+                .describe('Optional project ID override. If not provided, auto-generated from projectPath'),
+            clearExisting: z.boolean().optional().describe('Clear existing graph data for this project first'),
             excludeNodeTypes: z
                 .array(z.string())
                 .optional()
@@ -33,49 +84,293 @@ export const createParseTypescriptProjectTool = (server) => {
                 .optional()
                 .default('auto')
                 .describe('Project framework type (auto-detect by default)'),
+            chunkSize: z
+                .number()
+                .optional()
+                .default(50)
+                .describe('Files per chunk for streaming import (default: 50). Set to 0 to disable streaming.'),
+            useStreaming: z
+                .enum(['auto', 'always', 'never'])
+                .optional()
+                .default('auto')
+                .describe('When to use streaming import: auto (>100 files), always, or never'),
+            async: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Run parsing in background and return job ID immediately. Use check_parse_status to monitor.'),
+            watch: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Start file watching after parse completes. Only works with async: false.'),
+            watchDebounceMs: z
+                .number()
+                .optional()
+                .default(1000)
+                .describe('Debounce delay for watch mode in milliseconds (default: 1000)'),
         },
-    }, async ({ tsconfigPath, projectPath, clearExisting, projectType = 'auto' }) => {
+    }, async ({ tsconfigPath, projectPath, projectId, clearExisting, projectType = 'auto', chunkSize = 100, useStreaming = 'auto', async: asyncMode = false, watch = false, watchDebounceMs = 1000, }) => {
         try {
+            // SECURITY: Validate input paths before processing
+            await validatePathExists(projectPath, 'directory');
+            await validatePathExists(tsconfigPath, 'file');
+            // Note: tsconfig can be outside project in monorepo setups, so we just validate it exists
             await debugLog('TypeScript project parsing started', {
                 projectPath,
                 tsconfigPath,
                 clearExisting,
                 projectType,
+                chunkSize,
+                useStreaming,
+                asyncMode,
             });
+            // Reject conflicting parameters: watch only works with sync mode
+            if (asyncMode && watch) {
+                return createErrorResponse(new Error('Invalid parameter combination: watch=true cannot be used with async=true. ' +
+                    'File watching requires synchronous parsing. Either set async=false or watch=false.'));
+            }
+            // Resolve projectId early
+            const resolvedProjectId = resolveProjectId(projectPath, projectId);
+            // Handle async mode - return job ID immediately and process in Worker thread
+            if (asyncMode) {
+                const jobId = jobManager.createJob(projectPath, resolvedProjectId);
+                jobManager.startJob(jobId);
+                // Get path to worker script
+                const __filename = fileURLToPath(import.meta.url);
+                const __dirname = dirname(__filename);
+                const workerPath = join(__dirname, '..', 'workers', 'parse-worker.js');
+                // Create Worker thread to run parsing without blocking MCP server
+                const worker = new Worker(workerPath, {
+                    workerData: {
+                        projectPath,
+                        tsconfigPath,
+                        projectId: resolvedProjectId,
+                        projectType,
+                        chunkSize: chunkSize > 0 ? chunkSize : 50,
+                    },
+                    resourceLimits: {
+                        maxOldGenerationSizeMb: 8192, // 8GB heap for large monorepos
+                        maxYoungGenerationSizeMb: 1024,
+                    },
+                });
+                // Worker cleanup function
+                const terminateWorker = async (reason) => {
+                    try {
+                        await worker.terminate();
+                        await debugLog('Worker terminated', { jobId, reason });
+                    }
+                    catch (terminateError) {
+                        console.warn('Error terminating worker:', terminateError);
+                    }
+                };
+                // Set timeout for worker execution (30 minutes)
+                const timeoutId = setTimeout(async () => {
+                    const job = jobManager.getJob(jobId);
+                    if (job && job.status === 'running') {
+                        jobManager.failJob(jobId, `Worker timed out after ${WORKER_TIMEOUT_MS / 60000} minutes`);
+                        await terminateWorker('timeout');
+                    }
+                }, WORKER_TIMEOUT_MS);
+                // Handle progress messages from worker
+                worker.on('message', (msg) => {
+                    if (msg.type === 'progress') {
+                        jobManager.updateProgress(jobId, msg.data);
+                    }
+                    else if (msg.type === 'complete') {
+                        clearTimeout(timeoutId);
+                        jobManager.completeJob(jobId, msg.data);
+                        debugLog('Async parsing completed', { jobId, result: msg.data });
+                        terminateWorker('complete');
+                    }
+                    else if (msg.type === 'error') {
+                        clearTimeout(timeoutId);
+                        jobManager.failJob(jobId, msg.error);
+                        debugLog('Async parsing failed', { jobId, error: msg.error });
+                        terminateWorker('error');
+                    }
+                });
+                // Handle worker errors
+                worker.on('error', (err) => {
+                    clearTimeout(timeoutId);
+                    jobManager.failJob(jobId, err.message ?? String(err));
+                    console.error('Worker thread error:', err);
+                    terminateWorker('worker-error');
+                });
+                // Handle worker exit
+                worker.on('exit', (code) => {
+                    clearTimeout(timeoutId);
+                    if (code !== 0) {
+                        const job = jobManager.getJob(jobId);
+                        if (job && job.status === 'running') {
+                            jobManager.failJob(jobId, `Worker stopped with exit code ${code}`);
+                        }
+                    }
+                });
+                return createSuccessResponse(`Background parsing started in Worker thread.\n` +
+                    `Job ID: ${jobId}\n` +
+                    `Project ID: ${resolvedProjectId}\n\n` +
+                    `Use check_parse_status({ jobId: "${jobId}" }) to monitor progress.`);
+            }
             const neo4jService = new Neo4jService();
             const embeddingsService = new EmbeddingsService();
             const graphGeneratorHandler = new GraphGeneratorHandler(neo4jService, embeddingsService);
+            // Determine if we should use streaming import
+            const parser = projectType === 'auto'
+                ? await ParserFactory.createParserWithAutoDetection(projectPath, tsconfigPath, resolvedProjectId)
+                : ParserFactory.createParser({
+                    workspacePath: projectPath,
+                    tsConfigPath: tsconfigPath,
+                    projectType: projectType,
+                    projectId: resolvedProjectId,
+                });
+            const totalFiles = parser.getSourceFilePaths().length;
+            const shouldUseStreaming = useStreaming === 'always' || (useStreaming === 'auto' && totalFiles > STREAMING_THRESHOLD && chunkSize > 0);
+            console.log(`📊 Project has ${totalFiles} files. Streaming: ${shouldUseStreaming ? 'enabled' : 'disabled'}`);
+            if (shouldUseStreaming && clearExisting !== false) {
+                // Use streaming import for large projects
+                console.log(`🚀 Using streaming import with chunk size ${chunkSize}`);
+                await debugLog('Using streaming import', { totalFiles, chunkSize });
+                // Create Project node BEFORE starting import (status: parsing)
+                const projectName = await getProjectName(projectPath);
+                await neo4jService.run(UPSERT_PROJECT_QUERY, {
+                    projectId: resolvedProjectId,
+                    name: projectName,
+                    path: resolve(projectPath),
+                    status: 'parsing',
+                });
+                await debugLog('Project node created with parsing status', { projectId: resolvedProjectId });
+                try {
+                    // Clear existing project data first
+                    graphGeneratorHandler.setProjectId(resolvedProjectId);
+                    await neo4jService.run(QUERIES.CLEAR_PROJECT, { projectId: resolvedProjectId });
+                    const streamingHandler = new StreamingImportHandler(graphGeneratorHandler);
+                    const result = await streamingHandler.importProjectStreaming(parser, {
+                        chunkSize,
+                        projectId: resolvedProjectId,
+                    });
+                    await debugLog('Streaming import completed', result);
+                    // Update Project node status to complete
+                    await neo4jService.run(UPDATE_PROJECT_STATUS_QUERY, {
+                        projectId: resolvedProjectId,
+                        status: 'complete',
+                        nodeCount: result.nodesImported,
+                        edgeCount: result.edgesImported,
+                    });
+                    await debugLog('Project status updated to complete', { projectId: resolvedProjectId });
+                    return createSuccessResponse(`Successfully imported project using streaming mode:\n` +
+                        `- Project: ${projectName}\n` +
+                        `- Files processed: ${result.filesProcessed}\n` +
+                        `- Nodes imported: ${result.nodesImported}\n` +
+                        `- Edges imported: ${result.edgesImported}\n` +
+                        `- Chunks: ${result.chunksProcessed}\n` +
+                        `- Time: ${(result.elapsedMs / 1000).toFixed(2)}s\n` +
+                        `- Project ID: ${resolvedProjectId}\n\n` +
+                        `Tip: Use "${projectName}" instead of "${resolvedProjectId}" in other tools.`);
+                }
+                catch (streamingError) {
+                    // Update Project node status to failed
+                    await neo4jService.run(UPDATE_PROJECT_STATUS_QUERY, {
+                        projectId: resolvedProjectId,
+                        status: 'failed',
+                        nodeCount: 0,
+                        edgeCount: 0,
+                    });
+                    await debugLog('Project status updated to failed', { projectId: resolvedProjectId, error: streamingError });
+                    throw streamingError;
+                }
+            }
+            // Standard non-streaming import
+            // Create Project node BEFORE starting import (status: parsing)
+            const projectName = await getProjectName(projectPath);
+            await neo4jService.run(UPSERT_PROJECT_QUERY, {
+                projectId: resolvedProjectId,
+                name: projectName,
+                path: resolve(projectPath),
+                status: 'parsing',
+            });
+            await debugLog('Project node created with parsing status', { projectId: resolvedProjectId });
             const graphData = await parseProject({
                 neo4jService,
                 tsconfigPath,
                 projectPath,
+                projectId,
                 clearExisting,
                 projectType,
             });
-            const { nodes, edges, savedCrossFileEdges } = graphData;
-            console.log(`Parsed ${nodes.length} nodes / ${edges.length} edges`);
-            await debugLog('Parsing completed', { nodeCount: nodes.length, edgeCount: edges.length });
+            const { nodes, edges, savedCrossFileEdges, resolvedProjectId: finalProjectId } = graphData;
+            console.log(`Parsed ${nodes.length} nodes / ${edges.length} edges for project ${finalProjectId}`);
+            await debugLog('Parsing completed', {
+                nodeCount: nodes.length,
+                edgeCount: edges.length,
+                projectId: finalProjectId,
+            });
             const outputPath = join(projectPath, FILE_PATHS.graphOutput);
             writeFileSync(outputPath, JSON.stringify(graphData, null, LOG_CONFIG.jsonIndentation));
             console.log(`Graph data written to ${outputPath}`);
             try {
+                // Set projectId for project-scoped operations (clear, indexes)
+                graphGeneratorHandler.setProjectId(finalProjectId);
                 const result = await graphGeneratorHandler.generateGraph(outputPath, DEFAULTS.batchSize, clearExisting);
                 // Recreate cross-file edges after incremental parse
                 if (!clearExisting && savedCrossFileEdges.length > 0) {
                     await debugLog('Recreating cross-file edges', { edgesToRecreate: savedCrossFileEdges.length });
                     const recreateResult = await neo4jService.run(QUERIES.RECREATE_CROSS_FILE_EDGES, {
                         edges: savedCrossFileEdges,
+                        projectId: finalProjectId,
                     });
                     const recreatedCount = recreateResult[0]?.recreatedCount ?? 0;
                     await debugLog('Cross-file edges recreated', { recreatedCount, expected: savedCrossFileEdges.length });
                 }
                 console.log('Graph generation completed:', result);
                 await debugLog('Neo4j import completed', result);
-                return createSuccessResponse(formatParseSuccess(nodes.length, edges.length, result));
+                // Update Project node status to complete
+                await neo4jService.run(UPDATE_PROJECT_STATUS_QUERY, {
+                    projectId: finalProjectId,
+                    status: 'complete',
+                    nodeCount: result.nodesImported,
+                    edgeCount: result.edgesImported,
+                });
+                await debugLog('Project status updated to complete', { projectId: finalProjectId });
+                // Start file watcher if requested (only in synchronous mode)
+                let watchMessage = '';
+                if (watch && !asyncMode) {
+                    try {
+                        const watcherInfo = await watchManager.startWatching({
+                            projectPath,
+                            projectId: finalProjectId,
+                            tsconfigPath,
+                            debounceMs: watchDebounceMs,
+                        });
+                        await debugLog('File watcher started', { projectId: finalProjectId, status: watcherInfo.status });
+                        watchMessage = `\n\nFile watcher started (debounce: ${watchDebounceMs}ms). Graph will auto-update on file changes.`;
+                    }
+                    catch (watchError) {
+                        console.error('Failed to start file watcher:', watchError);
+                        await debugLog('File watcher failed to start', { error: watchError });
+                        watchMessage = `\n\nWarning: Failed to start file watcher: ${watchError instanceof Error ? watchError.message : String(watchError)}`;
+                    }
+                }
+                // Add watcher tip if not already watching
+                const watcherTip = watch && !asyncMode
+                    ? ''
+                    : `\n\nTip: Use start_watch_project to automatically update the graph when files change.`;
+                return createSuccessResponse(formatParseSuccess(nodes.length, edges.length, result) +
+                    `\n\nTip: Use "${projectName}" instead of "${finalProjectId}" in other tools.` +
+                    watcherTip +
+                    watchMessage);
             }
             catch (neo4jError) {
                 console.error('Neo4j import failed:', neo4jError);
                 await debugLog('Neo4j import failed', neo4jError);
+                // Update Project node status to failed
+                await neo4jService.run(UPDATE_PROJECT_STATUS_QUERY, {
+                    projectId: finalProjectId,
+                    status: 'failed',
+                    nodeCount: 0,
+                    edgeCount: 0,
+                });
+                await debugLog('Project status updated to failed', { projectId: finalProjectId });
                 return createSuccessResponse(formatParsePartialSuccess(nodes.length, edges.length, outputPath, neo4jError.message));
             }
         }
@@ -87,13 +382,16 @@ export const createParseTypescriptProjectTool = (server) => {
     });
 };
 const parseProject = async (options) => {
-    const { neo4jService, tsconfigPath, projectPath, clearExisting = true, projectType = 'auto' } = options;
+    const { neo4jService, tsconfigPath, projectPath, projectId, clearExisting = true, projectType = 'auto' } = options;
+    // Resolve projectId early - needed for incremental queries before parser is created
+    const resolvedId = resolveProjectId(projectPath, projectId);
     const parser = projectType === 'auto'
-        ? await ParserFactory.createParserWithAutoDetection(projectPath, tsconfigPath)
+        ? await ParserFactory.createParserWithAutoDetection(projectPath, tsconfigPath, resolvedId)
         : ParserFactory.createParser({
             workspacePath: projectPath,
             tsConfigPath: tsconfigPath,
             projectType: projectType,
+            projectId: resolvedId,
         });
     let incrementalStats;
     let savedCrossFileEdges = [];
@@ -103,15 +401,15 @@ const parseProject = async (options) => {
     }
     else {
         // Incremental: detect changes and parse only affected files
-        const { filesToReparse, filesToDelete } = await detectChangedFiles(projectPath, neo4jService);
+        const { filesToReparse, filesToDelete } = await detectChangedFiles(projectPath, neo4jService, resolvedId);
         incrementalStats = { filesReparsed: filesToReparse.length, filesDeleted: filesToDelete.length };
         await debugLog('Incremental change detection', { filesToReparse, filesToDelete });
         const filesToRemoveFromGraph = [...filesToDelete, ...filesToReparse];
         if (filesToRemoveFromGraph.length > 0) {
             // Save cross-file edges before deletion (they'll be recreated after import)
-            savedCrossFileEdges = await getCrossFileEdges(neo4jService, filesToRemoveFromGraph);
+            savedCrossFileEdges = await getCrossFileEdges(neo4jService, filesToRemoveFromGraph, resolvedId);
             await debugLog('Saved cross-file edges', { count: savedCrossFileEdges.length, edges: savedCrossFileEdges });
-            await deleteSourceFileSubgraphs(neo4jService, filesToRemoveFromGraph);
+            await deleteSourceFileSubgraphs(neo4jService, filesToRemoveFromGraph, resolvedId);
         }
         if (filesToReparse.length > 0) {
             await debugLog('Incremental parse starting', {
@@ -119,7 +417,7 @@ const parseProject = async (options) => {
                 filesDeleted: filesToDelete.length,
             });
             // Load existing nodes from Neo4j for edge target matching
-            const existingNodes = await loadExistingNodesForEdgeDetection(neo4jService, filesToRemoveFromGraph);
+            const existingNodes = await loadExistingNodesForEdgeDetection(neo4jService, filesToRemoveFromGraph, resolvedId);
             await debugLog('Loaded existing nodes for edge detection', { count: existingNodes.length });
             parser.setExistingNodes(existingNodes);
             await parser.parseWorkspace(filesToReparse);
@@ -130,57 +428,19 @@ const parseProject = async (options) => {
     }
     const { nodes, edges } = parser.exportToJson();
     const frameworkSchemas = parser['frameworkSchemas']?.map((s) => s.name) ?? ['Auto-detected'];
+    const resolvedProjectId = parser.getProjectId();
     return {
         nodes,
         edges,
         savedCrossFileEdges,
+        resolvedProjectId,
         metadata: {
             coreSchema: CORE_TYPESCRIPT_SCHEMA.name,
             frameworkSchemas,
             projectType,
+            projectId: resolvedProjectId,
             generated: new Date().toISOString(),
             ...(incrementalStats && { incremental: incrementalStats }),
         },
     };
 };
-const deleteSourceFileSubgraphs = async (neo4jService, filePaths) => {
-    await neo4jService.run(QUERIES.DELETE_SOURCE_FILE_SUBGRAPHS, { filePaths });
-};
-const loadExistingNodesForEdgeDetection = async (neo4jService, excludeFilePaths) => {
-    const queryResult = await neo4jService.run(QUERIES.GET_EXISTING_NODES_FOR_EDGE_DETECTION, { excludeFilePaths });
-    return queryResult;
-};
-const getCrossFileEdges = async (neo4jService, filePaths) => {
-    const queryResult = await neo4jService.run(QUERIES.GET_CROSS_FILE_EDGES, { filePaths });
-    return queryResult;
-};
-const detectChangedFiles = async (projectPath, neo4jService) => {
-    const relativeFiles = await glob('**/*.ts', { cwd: projectPath, ignore: EXCLUDE_PATTERNS_GLOB });
-    const currentFiles = new Set(relativeFiles.map((f) => resolve(projectPath, f)));
-    const queryResult = await neo4jService.run(QUERIES.GET_SOURCE_FILE_TRACKING_INFO);
-    const indexedFiles = queryResult;
-    const indexedMap = new Map(indexedFiles.map((f) => [f.filePath, f]));
-    const filesToReparse = [];
-    const filesToDelete = [];
-    for (const absolutePath of currentFiles) {
-        const indexed = indexedMap.get(absolutePath);
-        if (!indexed) {
-            filesToReparse.push(absolutePath);
-            continue;
-        }
-        const fileStats = await stat(absolutePath);
-        if (fileStats.mtimeMs === indexed.mtime && fileStats.size === indexed.size) {
-            continue;
-        }
-        const currentHash = await hashFile(absolutePath);
-        if (currentHash !== indexed.contentHash) {
-            filesToReparse.push(absolutePath);
-        }
-    }
-    for (const indexedPath of indexedMap.keys()) {
-        if (!currentFiles.has(indexedPath)) {
-            filesToDelete.push(indexedPath);
-        }
-    }
-    return { filesToReparse, filesToDelete };
-};

package/dist/mcp/tools/search-codebase.tool.js

@@ -5,14 +5,15 @@
 import { z } from 'zod';
 import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
 import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
-import { TOOL_NAMES, TOOL_METADATA, DEFAULTS, MESSAGES } from '../constants.js';
+import { TOOL_NAMES, TOOL_METADATA, DEFAULTS } from '../constants.js';
 import { TraversalHandler } from '../handlers/traversal.handler.js';
-import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+import { createErrorResponse, createSuccessResponse, debugLog, sanitizeNumericInput, resolveProjectIdOrError, } from '../utils.js';
 export const createSearchCodebaseTool = (server) => {
     server.registerTool(TOOL_NAMES.searchCodebase, {
         title: TOOL_METADATA[TOOL_NAMES.searchCodebase].title,
         description: TOOL_METADATA[TOOL_NAMES.searchCodebase].description,
         inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
             query: z.string().describe('Natural language query to search the codebase'),
             maxDepth: z
                 .number()
@@ -38,47 +39,83 @@ export const createSearchCodebaseTool = (server) => {
                 .optional()
                 .describe(`Length of code snippets to include (default: ${DEFAULTS.codeSnippetLength})`)
                 .default(DEFAULTS.codeSnippetLength),
+            minSimilarity: z
+                .number()
+                .optional()
+                .describe('Minimum similarity score threshold (0.0-1.0). Results below this are filtered out. Default: 0.65')
+                .default(0.65),
             useWeightedTraversal: z
                 .boolean()
                 .optional()
                 .describe('Use weighted traversal strategy that scores each node for relevance (default: false)')
                 .default(true),
         },
-    }, async ({ query, maxDepth = DEFAULTS.traversalDepth, maxNodesPerChain = 5, skip = 0, includeCode = true, snippetLength = DEFAULTS.codeSnippetLength, useWeightedTraversal = true, }) => {
+    }, async ({ projectId, query, maxDepth = DEFAULTS.traversalDepth, maxNodesPerChain = 5, skip = 0, includeCode = true, snippetLength = DEFAULTS.codeSnippetLength, minSimilarity = 0.65, useWeightedTraversal = true, }) => {
+        const neo4jService = new Neo4jService();
         try {
-            await debugLog('Search codebase started', { query });
-            const neo4jService = new Neo4jService();
+            // Resolve project ID from name, path, or ID
+            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            if (!projectResult.success)
+                return projectResult.error;
+            const resolvedProjectId = projectResult.projectId;
+            // Sanitize numeric inputs to ensure integers (Neo4j LIMIT requires integers)
+            const sanitizedMaxDepth = sanitizeNumericInput(maxDepth, DEFAULTS.traversalDepth, 10);
+            const sanitizedMaxNodesPerChain = sanitizeNumericInput(maxNodesPerChain, 5);
+            const sanitizedSkip = sanitizeNumericInput(skip, 0);
+            const sanitizedSnippetLength = sanitizeNumericInput(snippetLength, DEFAULTS.codeSnippetLength);
+            await debugLog('Search codebase started', { projectId: resolvedProjectId, query });
             const embeddingsService = new EmbeddingsService();
             const traversalHandler = new TraversalHandler(neo4jService);
             const embedding = await embeddingsService.embedText(query);
             const vectorResults = await neo4jService.run(QUERIES.VECTOR_SEARCH, {
                 limit: 1,
                 embedding,
+                projectId: resolvedProjectId,
+                fetchMultiplier: 10,
+                minSimilarity,
             });
             if (vectorResults.length === 0) {
-                await debugLog('No relevant code found', { query });
-                return createSuccessResponse(MESSAGES.errors.noRelevantCode);
+                await debugLog('No relevant code found', { projectId: resolvedProjectId, query, minSimilarity });
+                return createSuccessResponse(`No code found with similarity >= ${minSimilarity}. ` +
+                    `Try rephrasing your query or lowering the minSimilarity threshold. Query: "${query}"`);
             }
             const startNode = vectorResults[0].node;
             const nodeId = startNode.properties.id;
+            const similarityScore = vectorResults[0].score;
+            // Check if best match meets threshold - prevents traversing low-relevance results
+            if (similarityScore < minSimilarity) {
+                await debugLog('Best match below similarity threshold', {
+                    projectId: resolvedProjectId,
+                    query,
+                    score: similarityScore,
+                    threshold: minSimilarity,
+                });
+                return createSuccessResponse(`No sufficiently relevant code found. Best match score: ${similarityScore.toFixed(3)} ` +
+                    `(threshold: ${minSimilarity}). Try rephrasing your query.`);
+            }
             await debugLog('Vector search completed, starting traversal', {
+                projectId: resolvedProjectId,
                 nodeId,
+                similarityScore,
                 resultsCount: vectorResults.length,
-                maxDepth,
-                maxNodesPerChain,
-                skip,
+                maxDepth: sanitizedMaxDepth,
+                maxNodesPerChain: sanitizedMaxNodesPerChain,
+                skip: sanitizedSkip,
                 includeCode,
-                snippetLength,
+                snippetLength: sanitizedSnippetLength,
             });
+            // Include similarity score in the title so users can see relevance
+            const scoreDisplay = typeof similarityScore === 'number' ? similarityScore.toFixed(3) : 'N/A';
             return await traversalHandler.traverseFromNode(nodeId, embedding, {
-                maxDepth,
+                projectId: resolvedProjectId,
+                maxDepth: sanitizedMaxDepth,
                 direction: 'BOTH', // Show both incoming (who calls this) and outgoing (what this calls)
                 includeCode,
-                maxNodesPerChain,
-                skip,
+                maxNodesPerChain: sanitizedMaxNodesPerChain,
+                skip: sanitizedSkip,
                 summaryOnly: false,
-                snippetLength,
-                title: `Exploration from Node: ${nodeId}`,
+                snippetLength: sanitizedSnippetLength,
+                title: `Search Results (similarity: ${scoreDisplay}) - Starting from: ${nodeId}`,
                 useWeightedTraversal,
             });
         }
@@ -87,5 +124,8 @@ export const createSearchCodebaseTool = (server) => {
             await debugLog('Search codebase error', error);
             return createErrorResponse(error);
         }
+        finally {
+            await neo4jService.close();
+        }
     });
 };