code-graph-context 1.0.0 → 2.0.0

package/dist/mcp/tools/start-watch-project.tool.js

@@ -0,0 +1,100 @@
+/**
+ * Start Watch Project Tool
+ * Starts file watching for incremental graph updates
+ */
+import { constants as fsConstants } from 'fs';
+import { access, stat } from 'fs/promises';
+import { resolve } from 'path';
+import { z } from 'zod';
+import { resolveProjectId } from '../../core/utils/project-id.js';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { watchManager } from '../services/watch-manager.js';
+import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+const inputSchema = z.object({
+    projectPath: z.string().describe('Path to the TypeScript project root directory'),
+    tsconfigPath: z.string().describe('Path to TypeScript project tsconfig.json file'),
+    projectId: z.string().optional().describe('Optional project ID override (auto-generated from path if omitted)'),
+    debounceMs: z.number().optional().default(1000).describe('Debounce delay in milliseconds (default: 1000)'),
+});
+export const createStartWatchProjectTool = (server) => {
+    server.registerTool(TOOL_NAMES.startWatchProject, {
+        title: TOOL_METADATA[TOOL_NAMES.startWatchProject].title,
+        description: TOOL_METADATA[TOOL_NAMES.startWatchProject].description,
+        inputSchema: inputSchema.shape,
+    }, async (args) => {
+        try {
+            const { projectPath, tsconfigPath, debounceMs } = args;
+            await debugLog('Starting file watcher', { projectPath, tsconfigPath, debounceMs });
+            // Validate project path exists and is a directory
+            const resolvedProjectPath = resolve(projectPath);
+            try {
+                await access(resolvedProjectPath, fsConstants.R_OK);
+                const projectStats = await stat(resolvedProjectPath);
+                if (!projectStats.isDirectory()) {
+                    return createErrorResponse(new Error(`Project path exists but is not a directory: ${resolvedProjectPath}`));
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return createErrorResponse(new Error(`Project path does not exist: ${resolvedProjectPath}`));
+                }
+                throw error;
+            }
+            // Validate tsconfig exists and is a file
+            const resolvedTsconfigPath = resolve(tsconfigPath);
+            try {
+                await access(resolvedTsconfigPath, fsConstants.R_OK);
+                const tsconfigStats = await stat(resolvedTsconfigPath);
+                if (!tsconfigStats.isFile()) {
+                    return createErrorResponse(new Error(`tsconfig path exists but is not a file: ${resolvedTsconfigPath}`));
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return createErrorResponse(new Error(`tsconfig.json not found at: ${resolvedTsconfigPath}`));
+                }
+                throw error;
+            }
+            // Resolve project ID
+            const projectId = args.projectId ?? (await resolveProjectId(resolvedProjectPath));
+            // Check if project has been indexed
+            const neo4jService = new Neo4jService();
+            try {
+                const result = await neo4jService.run('MATCH (p:Project {projectId: $projectId}) RETURN p.projectId AS projectId', { projectId });
+                if (result.length === 0) {
+                    return createErrorResponse(new Error(`Project has not been indexed yet. Run parse_typescript_project first to create the initial graph, then start the watcher for incremental updates.`));
+                }
+            }
+            finally {
+                await neo4jService.close();
+            }
+            // Start watching
+            const watcherInfo = await watchManager.startWatching({
+                projectPath: resolvedProjectPath,
+                projectId,
+                tsconfigPath: resolvedTsconfigPath,
+                debounceMs,
+            });
+            await debugLog('File watcher started', { projectId, status: watcherInfo.status });
+            const output = [
+                `File watcher started successfully!`,
+                ``,
+                `Project: ${watcherInfo.projectPath}`,
+                `Project ID: ${watcherInfo.projectId}`,
+                `Status: ${watcherInfo.status}`,
+                `Debounce: ${watcherInfo.debounceMs}ms`,
+                ``,
+                `The graph will be automatically updated when TypeScript files change.`,
+                `Use stop_watch_project to stop watching.`,
+                `Use list_watchers to see all active watchers.`,
+            ].join('\n');
+            return createSuccessResponse(output);
+        }
+        catch (error) {
+            console.error('Start watch project error:', error);
+            await debugLog('Start watch project error', { error });
+            return createErrorResponse(error);
+        }
+    });
+};

package/dist/mcp/tools/stop-watch-project.tool.js

@@ -0,0 +1,49 @@
+/**
+ * Stop Watch Project Tool
+ * Stops file watching for a project
+ */
+import { z } from 'zod';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { watchManager } from '../services/watch-manager.js';
+import { createErrorResponse, createSuccessResponse, debugLog } from '../utils.js';
+const inputSchema = z.object({
+    projectId: z.string().describe('Project ID to stop watching'),
+});
+export const createStopWatchProjectTool = (server) => {
+    server.registerTool(TOOL_NAMES.stopWatchProject, {
+        title: TOOL_METADATA[TOOL_NAMES.stopWatchProject].title,
+        description: TOOL_METADATA[TOOL_NAMES.stopWatchProject].description,
+        inputSchema: inputSchema.shape,
+    }, async (args) => {
+        try {
+            const { projectId } = args;
+            await debugLog('Stopping file watcher', { projectId });
+            // Get watcher info before stopping (for response)
+            const watcherInfo = watchManager.getWatcherInfo(projectId);
+            if (!watcherInfo) {
+                return createErrorResponse(new Error(`No active watcher found for project: ${projectId}. Use list_watchers to see active watchers.`));
+            }
+            // Stop watching
+            const stopped = await watchManager.stopWatching(projectId);
+            if (!stopped) {
+                return createErrorResponse(new Error(`Failed to stop watcher for project: ${projectId}`));
+            }
+            await debugLog('File watcher stopped', { projectId });
+            const output = [
+                `File watcher stopped successfully!`,
+                ``,
+                `Project: ${watcherInfo.projectPath}`,
+                `Project ID: ${watcherInfo.projectId}`,
+                ``,
+                `The graph will no longer be automatically updated for this project.`,
+                `Use start_watch_project to start watching again.`,
+            ].join('\n');
+            return createSuccessResponse(output);
+        }
+        catch (error) {
+            console.error('Stop watch project error:', error);
+            await debugLog('Stop watch project error', { error });
+            return createErrorResponse(error);
+        }
+    });
+};

package/dist/mcp/tools/traverse-from-node.tool.js

@@ -7,13 +7,21 @@ import { MAX_TRAVERSAL_DEPTH } from '../../constants.js';
 import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
 import { TOOL_NAMES, TOOL_METADATA, DEFAULTS } from '../constants.js';
 import { TraversalHandler } from '../handlers/traversal.handler.js';
-import { createErrorResponse, sanitizeNumericInput, debugLog } from '../utils.js';
+import { createErrorResponse, sanitizeNumericInput, debugLog, resolveProjectIdOrError } from '../utils.js';
 export const createTraverseFromNodeTool = (server) => {
     server.registerTool(TOOL_NAMES.traverseFromNode, {
         title: TOOL_METADATA[TOOL_NAMES.traverseFromNode].title,
         description: TOOL_METADATA[TOOL_NAMES.traverseFromNode].description,
         inputSchema: {
-            nodeId: z.string().describe('The node ID to start traversal from'),
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            nodeId: z
+                .string()
+                .optional()
+                .describe('The node ID to start traversal from (required if filePath not provided)'),
+            filePath: z
+                .string()
+                .optional()
+                .describe('File path to start traversal from (alternative to nodeId - finds the SourceFile node)'),
             maxDepth: z
                 .number()
                 .int()
@@ -26,6 +34,12 @@ export const createTraverseFromNodeTool = (server) => {
                 .optional()
                 .describe(`Number of results to skip for pagination (default: ${DEFAULTS.skipOffset})`)
                 .default(DEFAULTS.skipOffset),
+            limit: z
+                .number()
+                .int()
+                .optional()
+                .describe('Maximum results per page (default: 50). Use with skip for pagination.')
+                .default(50),
             direction: z
                 .enum(['OUTGOING', 'INCOMING', 'BOTH'])
                 .optional()
@@ -57,27 +71,68 @@ export const createTraverseFromNodeTool = (server) => {
                 .optional()
                 .describe(`Code snippet character length when includeCode is true (default: ${DEFAULTS.codeSnippetLength})`)
                 .default(DEFAULTS.codeSnippetLength),
+            maxTotalNodes: z
+                .number()
+                .int()
+                .optional()
+                .describe('Maximum total unique nodes to return across all depths (default: 50). Limits output size.')
+                .default(50),
         },
-    }, async ({ nodeId, maxDepth = DEFAULTS.traversalDepth, skip = DEFAULTS.skipOffset, direction = 'BOTH', relationshipTypes, includeCode = true, maxNodesPerChain = 5, summaryOnly = false, snippetLength = DEFAULTS.codeSnippetLength, }) => {
+    }, async ({ projectId, nodeId, filePath, maxDepth = DEFAULTS.traversalDepth, skip = DEFAULTS.skipOffset, limit = 50, direction = 'BOTH', relationshipTypes, includeCode = true, maxNodesPerChain = 5, summaryOnly = false, snippetLength = DEFAULTS.codeSnippetLength, maxTotalNodes = 50, }) => {
+        // Validate that either nodeId or filePath is provided
+        if (!nodeId && !filePath) {
+            return createErrorResponse('Either nodeId or filePath must be provided.');
+        }
+        const neo4jService = new Neo4jService();
         try {
+            // Resolve project ID from name, path, or ID
+            const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+            if (!projectResult.success)
+                return projectResult.error;
+            const resolvedProjectId = projectResult.projectId;
+            const traversalHandler = new TraversalHandler(neo4jService);
+            // If filePath is provided, resolve it to a nodeId
+            let resolvedNodeId = nodeId;
+            if (!resolvedNodeId && filePath) {
+                const fileNodeId = await traversalHandler.resolveNodeIdFromFilePath(filePath, resolvedProjectId);
+                if (!fileNodeId) {
+                    // Try to provide helpful suggestions
+                    const fileName = filePath.split('/').pop() ?? filePath;
+                    return createErrorResponse(`No SourceFile node found for "${filePath}" in project "${resolvedProjectId}".\n\n` +
+                        `Suggestions:\n` +
+                        `- Use the full absolute path (e.g., /Users/.../src/file.ts)\n` +
+                        `- Use just the filename (e.g., "${fileName}")\n` +
+                        `- Use search_codebase to find the correct node ID first\n` +
+                        `- Run list_projects to verify the project exists`);
+                }
+                resolvedNodeId = fileNodeId;
+            }
             const sanitizedMaxDepth = sanitizeNumericInput(maxDepth, DEFAULTS.traversalDepth, MAX_TRAVERSAL_DEPTH);
             const sanitizedSkip = sanitizeNumericInput(skip, DEFAULTS.skipOffset);
             await debugLog('Node traversal started', {
-                nodeId,
+                projectId: resolvedProjectId,
+                nodeId: resolvedNodeId,
+                filePath,
                 maxDepth: sanitizedMaxDepth,
                 skip: sanitizedSkip,
+                limit,
                 direction,
                 relationshipTypes,
                 includeCode,
                 maxNodesPerChain,
                 summaryOnly,
                 snippetLength,
+                maxTotalNodes,
             });
-            const neo4jService = new Neo4jService();
-            const traversalHandler = new TraversalHandler(neo4jService);
-            return await traversalHandler.traverseFromNode(nodeId, [], {
+            // Safety check - resolvedNodeId should be set at this point
+            if (!resolvedNodeId) {
+                return createErrorResponse('Could not resolve node ID from provided parameters.');
+            }
+            return await traversalHandler.traverseFromNode(resolvedNodeId, [], {
+                projectId: resolvedProjectId,
                 maxDepth: sanitizedMaxDepth,
                 skip: sanitizedSkip,
+                limit,
                 direction,
                 relationshipTypes,
                 includeStartNodeDetails: true,
@@ -85,13 +140,17 @@ export const createTraverseFromNodeTool = (server) => {
                 maxNodesPerChain,
                 summaryOnly,
                 snippetLength,
-                title: `Node Traversal from: ${nodeId}`,
+                maxTotalNodes,
+                title: filePath ? `File Traversal from: ${filePath}` : `Node Traversal from: ${resolvedNodeId}`,
             });
         }
         catch (error) {
             console.error('Node traversal error:', error);
-            await debugLog('Node traversal error', { nodeId, error });
+            await debugLog('Node traversal error', { nodeId, filePath, error });
             return createErrorResponse(error);
         }
+        finally {
+            await neo4jService.close();
+        }
     });
 };

package/dist/mcp/utils.js

@@ -2,8 +2,23 @@
  * MCP Server Utility Functions
  * Common utility functions used across the MCP server
  */
+import { resolveProjectIdFromInput } from '../core/utils/project-id.js';
 import { MESSAGES } from './constants.js';
-export { debugLog } from '../utils/file-utils.js';
+export { debugLog } from '../core/utils/file-utils.js';
+/**
+ * Resolve project ID with standardized error handling
+ * Returns either the resolved projectId or an error response ready for tool return
+ */
+export const resolveProjectIdOrError = async (projectId, neo4jService) => {
+    try {
+        const resolved = await resolveProjectIdFromInput(projectId, neo4jService);
+        return { success: true, projectId: resolved };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: createErrorResponse(message) };
+    }
+};
 /**
  * Standard error response format for MCP tools
  */
@@ -31,6 +46,20 @@ export const createSuccessResponse = (text) => {
         ],
     };
 };
+/**
+ * Truncate code to specified max length, showing first and last portions
+ */
+export const truncateCode = (code, maxLength) => {
+    if (code.length <= maxLength) {
+        return { text: code };
+    }
+    const half = Math.floor(maxLength / 2);
+    return {
+        text: code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half),
+        hasMore: true,
+        truncated: code.length - maxLength,
+    };
+};
 /**
  * Format node information as structured data
  */
@@ -47,17 +76,11 @@ export const formatNodeInfo = (value, key) => {
         }
         // Include source code if available and not a SourceFile
         if (value.properties.sourceCode && value.properties.coreType !== 'SourceFile') {
-            const code = value.properties.sourceCode;
-            const maxLength = 1000; // Show max 1000 chars total
-            if (code.length <= maxLength) {
-                result.sourceCode = code;
-            }
-            else {
-                // Show first 500 and last 500 characters
-                const half = Math.floor(maxLength / 2);
-                result.sourceCode = code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half);
-                result.hasMore = true;
-                result.truncated = code.length - maxLength;
+            const truncateResult = truncateCode(value.properties.sourceCode, 1000);
+            result.sourceCode = truncateResult.text;
+            if (truncateResult.hasMore) {
+                result.hasMore = truncateResult.hasMore;
+                result.truncated = truncateResult.truncated;
             }
         }
         return result;

package/dist/mcp/workers/parse-worker.js

@@ -0,0 +1,198 @@
+/**
+ * Parse Worker
+ * Runs TypeScript parsing in a separate thread to avoid blocking the MCP server
+ */
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parentPort, workerData } from 'worker_threads';
+// Load environment variables in worker thread
+import dotenv from 'dotenv';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+dotenv.config({ path: join(__dirname, '..', '..', '..', '.env') });
+import { EmbeddingsService } from '../../core/embeddings/embeddings.service.js';
+import { ParserFactory } from '../../core/parsers/parser-factory.js';
+import { WorkspaceParser } from '../../core/parsers/workspace-parser.js';
+import { getProjectName, UPSERT_PROJECT_QUERY, UPDATE_PROJECT_STATUS_QUERY } from '../../core/utils/project-id.js';
+import { WorkspaceDetector } from '../../core/workspace/index.js';
+import { Neo4jService, QUERIES } from '../../storage/neo4j/neo4j.service.js';
+import { debugLog } from '../../core/utils/file-utils.js';
+import { GraphGeneratorHandler } from '../handlers/graph-generator.handler.js';
+import { StreamingImportHandler } from '../handlers/streaming-import.handler.js';
+const sendMessage = (msg) => {
+    parentPort?.postMessage(msg);
+};
+const runParser = async () => {
+    const config = workerData;
+    const startTime = Date.now();
+    // Declare outside try block so it's available in catch/finally
+    let resolvedProjectId = config.projectId;
+    let neo4jService = null;
+    try {
+        sendMessage({
+            type: 'progress',
+            data: {
+                phase: 'discovery',
+                filesProcessed: 0,
+                filesTotal: 0,
+                nodesImported: 0,
+                edgesImported: 0,
+                currentChunk: 0,
+                totalChunks: 0,
+            },
+        });
+        neo4jService = new Neo4jService();
+        const embeddingsService = new EmbeddingsService();
+        const graphGeneratorHandler = new GraphGeneratorHandler(neo4jService, embeddingsService);
+        // Use lazy loading to avoid OOM on large projects
+        const lazyLoad = true;
+        // Auto-detect workspace (Turborepo, pnpm, yarn, npm workspaces)
+        const workspaceDetector = new WorkspaceDetector();
+        await debugLog('Detecting workspace', { projectPath: config.projectPath });
+        const workspaceConfig = await workspaceDetector.detect(config.projectPath);
+        await debugLog('Workspace detection result', {
+            type: workspaceConfig.type,
+            rootPath: workspaceConfig.rootPath,
+            packageCount: workspaceConfig.packages.length,
+            packages: workspaceConfig.packages.map((p) => p.name),
+        });
+        // Use WorkspaceParser for monorepos, TypeScriptParser for single projects
+        let parser;
+        if (workspaceConfig.type !== 'single' && workspaceConfig.packages.length > 1) {
+            await debugLog('Using WorkspaceParser', {
+                type: workspaceConfig.type,
+                packageCount: workspaceConfig.packages.length,
+            });
+            // for workspaces default to auto for now
+            // TODO: allow worker config to specify projectType array to support multi-framework monorepos
+            parser = new WorkspaceParser(workspaceConfig, config.projectId, lazyLoad, 'auto');
+            resolvedProjectId = parser.getProjectId();
+        }
+        else {
+            await debugLog('Using single project mode', {
+                type: workspaceConfig.type,
+                packageCount: workspaceConfig.packages.length,
+            });
+            parser =
+                config.projectType === 'auto'
+                    ? await ParserFactory.createParserWithAutoDetection(config.projectPath, config.tsconfigPath, config.projectId, lazyLoad)
+                    : ParserFactory.createParser({
+                        workspacePath: config.projectPath,
+                        tsConfigPath: config.tsconfigPath,
+                        projectType: config.projectType,
+                        projectId: config.projectId,
+                        lazyLoad,
+                    });
+            resolvedProjectId = parser.getProjectId();
+        }
+        // Use async file discovery (works in lazy mode)
+        const sourceFiles = await parser.discoverSourceFiles();
+        const totalFiles = sourceFiles.length;
+        sendMessage({
+            type: 'progress',
+            data: {
+                phase: 'parsing',
+                filesProcessed: 0,
+                filesTotal: totalFiles,
+                nodesImported: 0,
+                edgesImported: 0,
+                currentChunk: 0,
+                totalChunks: Math.ceil(totalFiles / config.chunkSize),
+            },
+        });
+        // Clear existing project data first
+        graphGeneratorHandler.setProjectId(resolvedProjectId);
+        await neo4jService.run(QUERIES.CLEAR_PROJECT, { projectId: resolvedProjectId });
+        // Create/update Project node with 'parsing' status
+        const projectName = await getProjectName(config.projectPath);
+        await neo4jService.run(UPSERT_PROJECT_QUERY, {
+            projectId: resolvedProjectId,
+            name: projectName,
+            path: config.projectPath,
+            status: 'parsing',
+        });
+        await debugLog('Project node created', { projectId: resolvedProjectId, name: projectName });
+        const streamingHandler = new StreamingImportHandler(graphGeneratorHandler);
+        const result = await streamingHandler.importProjectStreaming(parser, {
+            chunkSize: config.chunkSize > 0 ? config.chunkSize : 100,
+            projectId: resolvedProjectId,
+            onProgress: async (progress) => {
+                sendMessage({
+                    type: 'progress',
+                    data: {
+                        phase: progress.phase,
+                        filesProcessed: progress.current,
+                        filesTotal: progress.total,
+                        nodesImported: progress.details?.nodesCreated ?? 0,
+                        edgesImported: progress.details?.edgesCreated ?? 0,
+                        currentChunk: progress.details?.chunkIndex ?? 0,
+                        totalChunks: progress.details?.totalChunks ?? 0,
+                    },
+                });
+            },
+        });
+        // Update Project node with 'complete' status and final counts
+        await neo4jService.run(UPDATE_PROJECT_STATUS_QUERY, {
+            projectId: resolvedProjectId,
+            status: 'complete',
+            nodeCount: result.nodesImported,
+            edgeCount: result.edgesImported,
+        });
+        await debugLog('Project node updated', {
+            projectId: resolvedProjectId,
+            status: 'complete',
+            nodeCount: result.nodesImported,
+            edgeCount: result.edgesImported,
+        });
+        sendMessage({
+            type: 'complete',
+            data: {
+                nodesImported: result.nodesImported,
+                edgesImported: result.edgesImported,
+                elapsedMs: Date.now() - startTime,
+            },
+        });
+    }
+    catch (error) {
+        // Try to update Project node with 'failed' status
+        try {
+            // Use existing service if available, otherwise create temporary one
+            const serviceForUpdate = neo4jService ?? new Neo4jService();
+            await serviceForUpdate.run(UPDATE_PROJECT_STATUS_QUERY, {
+                projectId: resolvedProjectId, // Use resolved ID, not config.projectId
+                status: 'failed',
+                nodeCount: 0,
+                edgeCount: 0,
+            });
+            // Close temporary service if we created one
+            if (!neo4jService) {
+                await serviceForUpdate.close();
+            }
+        }
+        catch {
+            // Ignore errors updating project status on failure
+        }
+        sendMessage({
+            type: 'error',
+            error: error.message ?? String(error),
+        });
+    }
+    finally {
+        // Always close the Neo4j connection to prevent resource leaks
+        if (neo4jService) {
+            try {
+                await neo4jService.close();
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+};
+// Run the parser
+runParser().catch((err) => {
+    sendMessage({
+        type: 'error',
+        error: err.message ?? String(err),
+    });
+});