code-graph-context 0.1.0 → 1.0.0

package/README.md

@@ -1,5 +1,6 @@
 # Code Graph Context MCP Server
 
+[![npm version](https://badge.fury.io/js/code-graph-context.svg)](https://www.npmjs.com/package/code-graph-context)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-007ACC?logo=typescript&logoColor=white)](https://typescriptlang.org/)
 [![Neo4j](https://img.shields.io/badge/Neo4j-5.0+-018bff?logo=neo4j&logoColor=white)](https://neo4j.com/)
@@ -147,6 +148,84 @@ Then configure in your MCP config file (`~/.config/claude/config.json`):
 
 **Note:** The env vars can be configured for any Neo4j instance - local, Docker, cloud (Aura), or enterprise.
 
+### Verify Installation
+
+After installation, verify everything is working:
+
+1. **Check Neo4j is running:**
+```bash
+# Open Neo4j Browser
+open http://localhost:7474
+# Login: neo4j / PASSWORD
+```
+
+2. **Test APOC plugin:**
+```cypher
+CALL apoc.help("apoc")
+```
+Should return a list of APOC functions.
+
+3. **Test MCP server connection:**
+```bash
+claude mcp list
+```
+Should show: `code-graph-context: ✓ Connected`
+
+### Troubleshooting
+
+**"APOC plugin not found"**
+```bash
+# Check Neo4j logs
+docker logs code-graph-neo4j
+
+# Verify APOC loaded
+docker exec code-graph-neo4j cypher-shell -u neo4j -p PASSWORD "CALL apoc.help('apoc')"
+
+# Restart if needed
+docker restart code-graph-neo4j
+```
+
+**"OPENAI_API_KEY environment variable is required"**
+- Get your API key from: https://platform.openai.com/api-keys
+- Add to Claude Code MCP config `env` section
+- Verify with: `echo $OPENAI_API_KEY` (if using shell env)
+
+**"Connection refused bolt://localhost:7687"**
+```bash
+# Check Neo4j is running
+docker ps | grep neo4j
+
+# Check ports are not in use
+lsof -i :7687
+
+# Start Neo4j if stopped
+docker start code-graph-neo4j
+
+# Check Neo4j logs
+docker logs code-graph-neo4j
+```
+
+**"Neo4j memory errors"**
+```bash
+# Increase memory in docker-compose.yml or docker run:
+-e NEO4J_server_memory_heap_max__size=8G
+-e NEO4J_dbms_memory_transaction_total_max=8G
+
+docker restart code-graph-neo4j
+```
+
+**"MCP server not responding"**
+```bash
+# Check Claude Code logs
+cat ~/Library/Logs/Claude/mcp*.log
+
+# Test server directly
+node /path/to/code-graph-context/dist/mcp/mcp.server.js
+
+# Rebuild if needed
+npm run build
+```
+
 ## Tool Usage Guide & Sequential Workflows
 
 ### Sequential Tool Usage Patterns

package/dist/constants.js

@@ -1 +1,22 @@
 export const MAX_TRAVERSAL_DEPTH = 5;
+// Shared exclude patterns for file parsing and change detection
+// Regex patterns (escaped dots, anchored to end)
+export const EXCLUDE_PATTERNS_REGEX = [
+    'node_modules/',
+    'dist/',
+    'build/',
+    'coverage/',
+    '\\.d\\.ts$',
+    '\\.spec\\.ts$',
+    '\\.test\\.ts$',
+];
+// Glob patterns for use with glob library
+export const EXCLUDE_PATTERNS_GLOB = [
+    'node_modules/**',
+    'dist/**',
+    'build/**',
+    'coverage/**',
+    '**/*.d.ts',
+    '**/*.spec.ts',
+    '**/*.test.ts',
+];

package/dist/core/config/nestjs-framework-schema.js

@@ -1,5 +1,6 @@
 /* eslint-disable prefer-arrow/prefer-arrow-functions */
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
 import { CoreNodeType, SemanticNodeType, SemanticEdgeType, } from './schema.js';
 // ============================================================================
 // NESTJS HELPER FUNCTIONS
@@ -888,7 +889,7 @@ export const NESTJS_FRAMEWORK_SCHEMA = {
 // ============================================================================
 export const NESTJS_PARSE_OPTIONS = {
     includePatterns: ['**/*.ts', '**/*.tsx'],
-    excludePatterns: ['node_modules/', 'dist/', 'coverage/', '.d.ts', '.spec.ts', '.test.ts'],
+    excludePatterns: EXCLUDE_PATTERNS_REGEX,
     maxFiles: 1000,
     frameworkSchemas: [NESTJS_FRAMEWORK_SCHEMA],
 };

package/dist/core/config/schema.js

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 // graph.ts - Optimized for Neo4j performance with context-based framework properties
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
 // ============================================================================
 // CORE ENUMS
 // ============================================================================
@@ -792,7 +793,7 @@ export const CORE_TYPESCRIPT_SCHEMA = {
 };
 export const DEFAULT_PARSE_OPTIONS = {
     includePatterns: ['**/*.ts', '**/*.tsx'],
-    excludePatterns: ['node_modules/', 'dist/', 'coverage/', '.d.ts', '.spec.ts', '.test.ts'],
+    excludePatterns: EXCLUDE_PATTERNS_REGEX,
     maxFiles: 1000,
     coreSchema: CORE_TYPESCRIPT_SCHEMA,
     frameworkSchemas: [],

package/dist/core/parsers/parser-factory.js

@@ -2,6 +2,7 @@
  * Parser Factory
  * Creates TypeScript parsers with appropriate framework schemas
  */
+import { EXCLUDE_PATTERNS_REGEX } from '../../constants.js';
 import { FAIRSQUARE_FRAMEWORK_SCHEMA } from '../config/fairsquare-framework-schema.js';
 import { NESTJS_FRAMEWORK_SCHEMA } from '../config/nestjs-framework-schema.js';
 import { CORE_TYPESCRIPT_SCHEMA, CoreNodeType } from '../config/schema.js';
@@ -19,7 +20,7 @@ export class ParserFactory {
      */
     static createParser(options) {
         const { workspacePath, tsConfigPath = 'tsconfig.json', projectType = ProjectType.NESTJS, // Default to NestJS (use auto-detect for best results)
-        customFrameworkSchemas = [], excludePatterns = ['node_modules', 'dist', 'build', '.spec.', '.test.'], excludedNodeTypes = [CoreNodeType.PARAMETER_DECLARATION], } = options;
+        customFrameworkSchemas = [], excludePatterns = EXCLUDE_PATTERNS_REGEX, excludedNodeTypes = [CoreNodeType.PARAMETER_DECLARATION], } = options;
         // Select framework schemas based on project type
         const frameworkSchemas = this.selectFrameworkSchemas(projectType, customFrameworkSchemas);
         console.log(`📦 Creating parser for ${projectType} project`);
@@ -68,7 +69,9 @@ export class ParserFactory {
                 ...packageJson.devDependencies,
             };
             const hasNestJS = '@nestjs/common' in deps || '@nestjs/core' in deps;
-            const hasFairSquare = '@fairsquare/core' in deps || '@fairsquare/server' in deps;
+            const hasFairSquare = '@fairsquare/core' in deps ||
+                '@fairsquare/server' in deps ||
+                packageJson.name === '@fairsquare/source';
             if (hasFairSquare && hasNestJS) {
                 return ProjectType.BOTH;
             }

package/dist/core/parsers/typescript-parser.js

@@ -1,8 +1,24 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import crypto from 'crypto';
+import fs from 'fs/promises';
 import path from 'node:path';
 import { minimatch } from 'minimatch';
 import { Project, Node } from 'ts-morph';
-import { v4 as uuidv4 } from 'uuid';
+/**
+ * Generate a deterministic node ID based on stable properties.
+ * This ensures the same node gets the same ID across reparses.
+ *
+ * Identity is based on: coreType + filePath + name (+ parentId for nested nodes)
+ * This is stable because when it matters (one side of edge not reparsed),
+ * names are guaranteed unchanged (or imports would break, triggering reparse).
+ */
+const generateDeterministicId = (coreType, filePath, name, parentId) => {
+    const parts = parentId ? [coreType, filePath, parentId, name] : [coreType, filePath, name];
+    const identity = parts.join('::');
+    const hash = crypto.createHash('sha256').update(identity).digest('hex').substring(0, 16);
+    return `${coreType}:${hash}`;
+};
+import { hashFile } from '../../utils/file-utils.js';
 import { NESTJS_FRAMEWORK_SCHEMA } from '../config/nestjs-framework-schema.js';
 import { CoreNodeType, CORE_TYPESCRIPT_SCHEMA, DEFAULT_PARSE_OPTIONS, CoreEdgeType, } from '../config/schema.js';
 export class TypeScriptParser {
@@ -14,6 +30,7 @@ export class TypeScriptParser {
     frameworkSchemas;
     parsedNodes = new Map();
     parsedEdges = new Map();
+    existingNodes = new Map(); // Nodes from Neo4j for edge target matching
     deferredEdges = [];
     sharedContext = new Map(); // Shared context for custom data
     constructor(workspacePath, tsConfigPath = 'tsconfig.json', coreSchema = CORE_TYPESCRIPT_SCHEMA, frameworkSchemas = [NESTJS_FRAMEWORK_SCHEMA], parseConfig = DEFAULT_PARSE_OPTIONS) {
@@ -22,7 +39,6 @@ export class TypeScriptParser {
         this.coreSchema = coreSchema;
         this.frameworkSchemas = frameworkSchemas;
         this.parseConfig = parseConfig;
-        // Initialize with proper compiler options for NestJS
         this.project = new Project({
             tsConfigFilePath: tsConfigPath,
             skipAddingFilesFromTsConfig: false,
@@ -36,25 +52,53 @@ export class TypeScriptParser {
         });
         this.project.addSourceFilesAtPaths(path.join(workspacePath, '**/*.ts'));
     }
-    async parseWorkspace() {
-        const sourceFiles = this.project.getSourceFiles();
-        // Phase 1: Core parsing for ALL files
+    /**
+     * Set existing nodes from Neo4j for edge target matching during incremental parsing.
+     * These nodes will be available as targets for edge detection but won't be exported.
+     */
+    setExistingNodes(nodes) {
+        this.existingNodes.clear();
+        for (const node of nodes) {
+            // Convert to ParsedNode format (without AST)
+            const parsedNode = {
+                id: node.id,
+                coreType: node.coreType,
+                semanticType: node.semanticType,
+                labels: node.labels,
+                properties: {
+                    id: node.id,
+                    name: node.name,
+                    coreType: node.coreType,
+                    filePath: node.filePath,
+                    semanticType: node.semanticType,
+                },
+                // No sourceNode - these are from Neo4j, not parsed
+            };
+            this.existingNodes.set(node.id, parsedNode);
+        }
+        console.log(`📦 Loaded ${nodes.length} existing nodes for edge detection`);
+    }
+    async parseWorkspace(filesToParse) {
+        let sourceFiles;
+        if (filesToParse && filesToParse.length > 0) {
+            sourceFiles = filesToParse
+                .map((filePath) => this.project.getSourceFile(filePath))
+                .filter((sf) => sf !== undefined);
+        }
+        else {
+            sourceFiles = this.project.getSourceFiles();
+        }
         for (const sourceFile of sourceFiles) {
             if (this.shouldSkipFile(sourceFile))
                 continue;
             await this.parseCoreTypeScriptV2(sourceFile);
         }
-        // Phase 1.5: Resolve deferred relationship edges (EXTENDS, IMPLEMENTS)
         this.resolveDeferredEdges();
-        // Phase 2: Apply context extractors
         await this.applyContextExtractors();
-        // Phase 3: Framework enhancements
         if (this.frameworkSchemas.length > 0) {
             await this.applyFrameworkEnhancements();
         }
-        // Phase 4: Edge enhancements
         await this.applyEdgeEnhancements();
-        // Convert to Neo4j format
         const neo4jNodes = Array.from(this.parsedNodes.values()).map(this.toNeo4jNode);
         const neo4jEdges = Array.from(this.parsedEdges.values()).map(this.toNeo4jEdge);
         return { nodes: neo4jNodes, edges: neo4jEdges };
@@ -77,17 +121,22 @@ export class TypeScriptParser {
         return false;
     }
     async parseCoreTypeScriptV2(sourceFile) {
-        const sourceFileNode = this.createCoreNode(sourceFile, CoreNodeType.SOURCE_FILE);
+        const filePath = sourceFile.getFilePath();
+        const stats = await fs.stat(filePath);
+        const fileTrackingProperties = {
+            size: stats.size,
+            mtime: stats.mtimeMs,
+            contentHash: await hashFile(filePath),
+        };
+        const sourceFileNode = this.createCoreNode(sourceFile, CoreNodeType.SOURCE_FILE, fileTrackingProperties);
         this.addNode(sourceFileNode);
-        // Parse configured children
-        this.parseChildNodes(this.coreSchema.nodeTypes[CoreNodeType.SOURCE_FILE], sourceFileNode, sourceFile);
-        // Special handling: Parse variable declarations if framework schema specifies patterns
+        await this.parseChildNodes(this.coreSchema.nodeTypes[CoreNodeType.SOURCE_FILE], sourceFileNode, sourceFile);
         if (this.shouldParseVariables(sourceFile.getFilePath())) {
             for (const varStatement of sourceFile.getVariableStatements()) {
                 for (const varDecl of varStatement.getDeclarations()) {
                     if (this.shouldSkipChildNode(varDecl))
                         continue;
-                    const variableNode = this.createCoreNode(varDecl, CoreNodeType.VARIABLE_DECLARATION);
+                    const variableNode = this.createCoreNode(varDecl, CoreNodeType.VARIABLE_DECLARATION, {}, sourceFileNode.id);
                     this.addNode(variableNode);
                     const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, variableNode.id);
                     this.addEdge(containsEdge);
@@ -118,7 +167,7 @@ export class TypeScriptParser {
             for (const child of children) {
                 if (this.shouldSkipChildNode(child))
                     continue;
-                const coreNode = this.createCoreNode(child, type);
+                const coreNode = this.createCoreNode(child, type, {}, parentNode.id);
                 this.addNode(coreNode);
                 const coreEdge = this.createCoreEdge(edgeType, parentNode.id, coreNode.id);
                 this.addEdge(coreEdge);
@@ -205,14 +254,14 @@ export class TypeScriptParser {
             this.addNode(sourceFileNode);
             // Parse classes
             for (const classDecl of sourceFile.getClasses()) {
-                const classNode = this.createCoreNode(classDecl, CoreNodeType.CLASS_DECLARATION);
+                const classNode = this.createCoreNode(classDecl, CoreNodeType.CLASS_DECLARATION, {}, sourceFileNode.id);
                 this.addNode(classNode);
                 // File contains class relationship
                 const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, classNode.id);
                 this.addEdge(containsEdge);
                 // Parse class decorators
                 for (const decorator of classDecl.getDecorators()) {
-                    const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR);
+                    const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR, {}, classNode.id);
                     this.addNode(decoratorNode);
                     // Class decorated with decorator relationship
                     const decoratedEdge = this.createCoreEdge(CoreEdgeType.DECORATED_WITH, classNode.id, decoratorNode.id);
@@ -220,14 +269,14 @@ export class TypeScriptParser {
                 }
                 // Parse methods
                 for (const method of classDecl.getMethods()) {
-                    const methodNode = this.createCoreNode(method, CoreNodeType.METHOD_DECLARATION);
+                    const methodNode = this.createCoreNode(method, CoreNodeType.METHOD_DECLARATION, {}, classNode.id);
                     this.addNode(methodNode);
                     // Class has method relationship
                     const hasMethodEdge = this.createCoreEdge(CoreEdgeType.HAS_MEMBER, classNode.id, methodNode.id);
                     this.addEdge(hasMethodEdge);
                     // Parse method decorators
                     for (const decorator of method.getDecorators()) {
-                        const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR);
+                        const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR, {}, methodNode.id);
                         this.addNode(decoratorNode);
                         // Method decorated with decorator relationship
                         const decoratedEdge = this.createCoreEdge(CoreEdgeType.DECORATED_WITH, methodNode.id, decoratorNode.id);
@@ -235,14 +284,14 @@ export class TypeScriptParser {
                     }
                     // Parse method parameters
                     for (const param of method.getParameters()) {
-                        const paramNode = this.createCoreNode(param, CoreNodeType.PARAMETER_DECLARATION);
+                        const paramNode = this.createCoreNode(param, CoreNodeType.PARAMETER_DECLARATION, {}, methodNode.id);
                         this.addNode(paramNode);
                         // Method has parameter relationship
                         const hasParamEdge = this.createCoreEdge(CoreEdgeType.HAS_PARAMETER, methodNode.id, paramNode.id);
                         this.addEdge(hasParamEdge);
                         // Parse parameter decorators
                         for (const decorator of param.getDecorators()) {
-                            const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR);
+                            const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR, {}, paramNode.id);
                             this.addNode(decoratorNode);
                             // Parameter decorated with decorator relationship
                             const decoratedEdge = this.createCoreEdge(CoreEdgeType.DECORATED_WITH, paramNode.id, decoratorNode.id);
@@ -252,14 +301,14 @@ export class TypeScriptParser {
                 }
                 // Parse properties
                 for (const property of classDecl.getProperties()) {
-                    const propertyNode = this.createCoreNode(property, CoreNodeType.PROPERTY_DECLARATION);
+                    const propertyNode = this.createCoreNode(property, CoreNodeType.PROPERTY_DECLARATION, {}, classNode.id);
                     this.addNode(propertyNode);
                     // Class has property relationship
                     const hasPropertyEdge = this.createCoreEdge(CoreEdgeType.HAS_MEMBER, classNode.id, propertyNode.id);
                     this.addEdge(hasPropertyEdge);
                     // Parse property decorators
                     for (const decorator of property.getDecorators()) {
-                        const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR);
+                        const decoratorNode = this.createCoreNode(decorator, CoreNodeType.DECORATOR, {}, propertyNode.id);
                         this.addNode(decoratorNode);
                         // Property decorated with decorator relationship
                         const decoratedEdge = this.createCoreEdge(CoreEdgeType.DECORATED_WITH, propertyNode.id, decoratorNode.id);
@@ -269,7 +318,7 @@ export class TypeScriptParser {
             }
             // Parse interfaces
             for (const interfaceDecl of sourceFile.getInterfaces()) {
-                const interfaceNode = this.createCoreNode(interfaceDecl, CoreNodeType.INTERFACE_DECLARATION);
+                const interfaceNode = this.createCoreNode(interfaceDecl, CoreNodeType.INTERFACE_DECLARATION, {}, sourceFileNode.id);
                 this.addNode(interfaceNode);
                 // File contains interface relationship
                 const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, interfaceNode.id);
@@ -277,14 +326,14 @@ export class TypeScriptParser {
             }
             // Parse functions
             for (const funcDecl of sourceFile.getFunctions()) {
-                const functionNode = this.createCoreNode(funcDecl, CoreNodeType.FUNCTION_DECLARATION);
+                const functionNode = this.createCoreNode(funcDecl, CoreNodeType.FUNCTION_DECLARATION, {}, sourceFileNode.id);
                 this.addNode(functionNode);
                 // File contains function relationship
                 const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, functionNode.id);
                 this.addEdge(containsEdge);
                 // Parse function parameters
                 for (const param of funcDecl.getParameters()) {
-                    const paramNode = this.createCoreNode(param, CoreNodeType.PARAMETER_DECLARATION);
+                    const paramNode = this.createCoreNode(param, CoreNodeType.PARAMETER_DECLARATION, {}, functionNode.id);
                     this.addNode(paramNode);
                     // Function has parameter relationship
                     const hasParamEdge = this.createCoreEdge(CoreEdgeType.HAS_PARAMETER, functionNode.id, paramNode.id);
@@ -293,7 +342,7 @@ export class TypeScriptParser {
             }
             // Parse imports
             for (const importDecl of sourceFile.getImportDeclarations()) {
-                const importNode = this.createCoreNode(importDecl, CoreNodeType.IMPORT_DECLARATION);
+                const importNode = this.createCoreNode(importDecl, CoreNodeType.IMPORT_DECLARATION, {}, sourceFileNode.id);
                 this.addNode(importNode);
                 // File contains import relationship
                 const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, importNode.id);
@@ -303,7 +352,7 @@ export class TypeScriptParser {
             if (this.shouldParseVariables(sourceFile.getFilePath())) {
                 for (const varStatement of sourceFile.getVariableStatements()) {
                     for (const varDecl of varStatement.getDeclarations()) {
-                        const variableNode = this.createCoreNode(varDecl, CoreNodeType.VARIABLE_DECLARATION);
+                        const variableNode = this.createCoreNode(varDecl, CoreNodeType.VARIABLE_DECLARATION, {}, sourceFileNode.id);
                         this.addNode(variableNode);
                         // File contains variable relationship
                         const containsEdge = this.createCoreEdge(CoreEdgeType.CONTAINS, sourceFileNode.id, variableNode.id);
@@ -316,18 +365,21 @@ export class TypeScriptParser {
             console.error(`Error parsing file ${sourceFile.getFilePath()}:`, error);
         }
     }
-    createCoreNode(astNode, coreType) {
-        const nodeId = `${coreType}:${uuidv4()}`;
+    createCoreNode(astNode, coreType, baseProperties = {}, parentId) {
+        const name = this.extractNodeName(astNode, coreType);
+        const filePath = astNode.getSourceFile().getFilePath();
+        const nodeId = generateDeterministicId(coreType, filePath, name, parentId);
         // Extract base properties using schema
         const properties = {
             id: nodeId,
-            name: this.extractNodeName(astNode, coreType),
+            name,
             coreType,
-            filePath: astNode.getSourceFile().getFilePath(),
+            filePath,
             startLine: astNode.getStartLineNumber(),
             endLine: astNode.getEndLineNumber(),
             sourceCode: astNode.getText(),
             createdAt: new Date().toISOString(),
+            ...baseProperties,
         };
         // Extract schema-defined properties
         const coreNodeDef = this.coreSchema.nodeTypes[coreType];
@@ -386,8 +438,12 @@ export class TypeScriptParser {
         // Get the weight from the core schema
         const coreEdgeSchema = CORE_TYPESCRIPT_SCHEMA.edgeTypes[relationshipType];
         const relationshipWeight = coreEdgeSchema?.relationshipWeight ?? 0.5;
+        // Generate deterministic edge ID based on type + source + target
+        const edgeIdentity = `${relationshipType}::${sourceNodeId}::${targetNodeId}`;
+        const edgeHash = crypto.createHash('sha256').update(edgeIdentity).digest('hex').substring(0, 16);
+        const edgeId = `${relationshipType}:${edgeHash}`;
         return {
-            id: `${relationshipType}:${uuidv4()}`,
+            id: edgeId,
             relationshipType,
             sourceNodeId,
             targetNodeId,
@@ -517,8 +573,14 @@ export class TypeScriptParser {
     }
     async applyEdgeEnhancement(edgeEnhancement) {
         try {
+            // Combine parsed nodes and existing nodes for target matching
+            // Sources must be parsed (have AST), targets can be either
+            const allTargetNodes = new Map([...this.parsedNodes, ...this.existingNodes]);
             for (const [sourceId, sourceNode] of this.parsedNodes) {
-                for (const [targetId, targetNode] of this.parsedNodes) {
+                // Skip if source doesn't have AST (shouldn't happen for parsedNodes, but be safe)
+                if (!sourceNode.sourceNode)
+                    continue;
+                for (const [targetId, targetNode] of allTargetNodes) {
                     if (sourceId === targetId)
                         continue;
                     if (edgeEnhancement.detectionPattern(sourceNode, targetNode, this.parsedNodes, this.sharedContext)) {
@@ -538,7 +600,10 @@ export class TypeScriptParser {
         }
     }
     createFrameworkEdge(semanticType, relationshipType, sourceNodeId, targetNodeId, context = {}, relationshipWeight = 0.5) {
-        const edgeId = `${semanticType}:${uuidv4()}`;
+        // Generate deterministic edge ID based on type + source + target
+        const edgeIdentity = `${semanticType}::${sourceNodeId}::${targetNodeId}`;
+        const edgeHash = crypto.createHash('sha256').update(edgeIdentity).digest('hex').substring(0, 16);
+        const edgeId = `${semanticType}:${edgeHash}`;
         const properties = {
             coreType: semanticType, // This might need adjustment based on schema
             semanticType,
@@ -652,7 +717,6 @@ export class TypeScriptParser {
         const excludedPatterns = this.parseConfig.excludePatterns ?? [];
         for (const pattern of excludedPatterns) {
             if (filePath.includes(pattern) || filePath.match(new RegExp(pattern))) {
-                console.log(`⏭️ Skipping excluded file: ${filePath}`);
                 return true;
             }
         }

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

@@ -3,12 +3,16 @@
  * Parses TypeScript/NestJS projects and builds Neo4j graph
  */
 import { writeFileSync } from 'fs';
-import { join } from 'path';
+import { stat } from 'fs/promises';
+import { join, resolve } from 'path';
+import { glob } from 'glob';
 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 { Neo4jService } from '../../storage/neo4j/neo4j.service.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 { GraphGeneratorHandler } from '../handlers/graph-generator.handler.js';
 import { createErrorResponse, createSuccessResponse, formatParseSuccess, formatParsePartialSuccess, debugLog, } from '../utils.js';
@@ -38,58 +42,39 @@ export const createParseTypescriptProjectTool = (server) => {
                 clearExisting,
                 projectType,
             });
-            // Create parser with auto-detection or specified type
-            let parser;
-            if (projectType === 'auto') {
-                parser = await ParserFactory.createParserWithAutoDetection(projectPath, tsconfigPath);
-            }
-            else {
-                parser = ParserFactory.createParser({
-                    workspacePath: projectPath,
-                    tsConfigPath: tsconfigPath,
-                    projectType: projectType,
-                });
-            }
-            // Parse the workspace
-            const { nodes, edges } = await parser.parseWorkspace();
-            const { nodes: cleanNodes, edges: cleanEdges } = parser.exportToJson();
-            console.log(`Parsed ${cleanNodes.length} nodes / ${cleanEdges.length} edges`);
-            await debugLog('Parsing completed', {
-                nodeCount: cleanNodes.length,
-                edgeCount: cleanEdges.length,
+            const neo4jService = new Neo4jService();
+            const embeddingsService = new EmbeddingsService();
+            const graphGeneratorHandler = new GraphGeneratorHandler(neo4jService, embeddingsService);
+            const graphData = await parseProject({
+                neo4jService,
+                tsconfigPath,
+                projectPath,
+                clearExisting,
+                projectType,
             });
-            // Create graph JSON output
+            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 outputPath = join(projectPath, FILE_PATHS.graphOutput);
-            // Get detected framework schemas from parser
-            const frameworkSchemas = parser['frameworkSchemas']?.map((s) => s.name) ?? ['Auto-detected'];
-            const graphData = {
-                nodes: cleanNodes,
-                edges: cleanEdges,
-                metadata: {
-                    coreSchema: CORE_TYPESCRIPT_SCHEMA.name,
-                    frameworkSchemas,
-                    projectType,
-                    generated: new Date().toISOString(),
-                },
-            };
             writeFileSync(outputPath, JSON.stringify(graphData, null, LOG_CONFIG.jsonIndentation));
             console.log(`Graph data written to ${outputPath}`);
-            // Attempt to import to Neo4j
             try {
-                const neo4jService = new Neo4jService();
-                const embeddingsService = new EmbeddingsService();
-                const graphGeneratorHandler = new GraphGeneratorHandler(neo4jService, embeddingsService);
                 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 });
+                    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);
-                const successMessage = formatParseSuccess(cleanNodes.length, cleanEdges.length, result);
-                return createSuccessResponse(successMessage);
+                return createSuccessResponse(formatParseSuccess(nodes.length, edges.length, result));
             }
             catch (neo4jError) {
                 console.error('Neo4j import failed:', neo4jError);
                 await debugLog('Neo4j import failed', neo4jError);
-                const partialSuccessMessage = formatParsePartialSuccess(cleanNodes.length, cleanEdges.length, outputPath, neo4jError.message);
-                return createSuccessResponse(partialSuccessMessage);
+                return createSuccessResponse(formatParsePartialSuccess(nodes.length, edges.length, outputPath, neo4jError.message));
             }
         }
         catch (error) {
@@ -99,3 +84,98 @@ export const createParseTypescriptProjectTool = (server) => {
         }
     });
 };
+const parseProject = async (options) => {
+    const { neo4jService, tsconfigPath, projectPath, clearExisting = true, projectType = 'auto' } = options;
+    const parser = projectType === 'auto'
+        ? await ParserFactory.createParserWithAutoDetection(projectPath, tsconfigPath)
+        : ParserFactory.createParser({
+            workspacePath: projectPath,
+            tsConfigPath: tsconfigPath,
+            projectType: projectType,
+        });
+    let incrementalStats;
+    let savedCrossFileEdges = [];
+    if (clearExisting) {
+        // Full rebuild: parse all files
+        await parser.parseWorkspace();
+    }
+    else {
+        // Incremental: detect changes and parse only affected files
+        const { filesToReparse, filesToDelete } = await detectChangedFiles(projectPath, neo4jService);
+        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);
+            await debugLog('Saved cross-file edges', { count: savedCrossFileEdges.length, edges: savedCrossFileEdges });
+            await deleteSourceFileSubgraphs(neo4jService, filesToRemoveFromGraph);
+        }
+        if (filesToReparse.length > 0) {
+            await debugLog('Incremental parse starting', { filesChanged: filesToReparse.length, filesDeleted: filesToDelete.length });
+            // Load existing nodes from Neo4j for edge target matching
+            const existingNodes = await loadExistingNodesForEdgeDetection(neo4jService, filesToRemoveFromGraph);
+            await debugLog('Loaded existing nodes for edge detection', { count: existingNodes.length });
+            parser.setExistingNodes(existingNodes);
+            await parser.parseWorkspace(filesToReparse);
+        }
+        else {
+            await debugLog('Incremental parse: no changes detected');
+        }
+    }
+    const { nodes, edges } = parser.exportToJson();
+    const frameworkSchemas = parser['frameworkSchemas']?.map((s) => s.name) ?? ['Auto-detected'];
+    return {
+        nodes,
+        edges,
+        savedCrossFileEdges,
+        metadata: {
+            coreSchema: CORE_TYPESCRIPT_SCHEMA.name,
+            frameworkSchemas,
+            projectType,
+            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/utils.js

@@ -2,22 +2,8 @@
  * MCP Server Utility Functions
  * Common utility functions used across the MCP server
  */
-import fs from 'fs/promises';
-import path from 'path';
-import { FILE_PATHS, LOG_CONFIG, MESSAGES } from './constants.js';
-/**
- * Debug logging utility
- */
-export const debugLog = async (message, data) => {
-    const timestamp = new Date().toISOString();
-    const logEntry = `[${timestamp}] ${message}\n${data ? JSON.stringify(data, null, LOG_CONFIG.jsonIndentation) : ''}\n${LOG_CONFIG.logSeparator}\n`;
-    try {
-        await fs.appendFile(path.join(process.cwd(), FILE_PATHS.debugLog), logEntry);
-    }
-    catch (error) {
-        console.error('Failed to write debug log:', error);
-    }
-};
+import { MESSAGES } from './constants.js';
+export { debugLog } from '../utils/file-utils.js';
 /**
  * Standard error response format for MCP tools
  */

package/dist/storage/neo4j/neo4j.service.js

@@ -81,15 +81,70 @@ export const QUERIES = {
   RETURN {
     id: node.id,
     labels: labels(node),
-    properties: apoc.map.removeKeys(properties(node), ['embedding'])
+    properties: apoc.map.removeKeys(properties(node), ['embedding', 'contentHash', 'mtime', 'size'])
   } as node, score
   ORDER BY score DESC
 `,
     // Check if index exists
     CHECK_VECTOR_INDEX: `
-    SHOW INDEXES YIELD name, type 
+    SHOW INDEXES YIELD name, type
     WHERE name = 'node_embedding_idx' AND type = 'VECTOR'
     RETURN count(*) > 0 as exists
+  `,
+    GET_SOURCE_FILE_TRACKING_INFO: `
+    MATCH (sf:SourceFile)
+    RETURN sf.filePath AS filePath, sf.mtime AS mtime, sf.size AS size, sf.contentHash AS contentHash
+  `,
+    // Get cross-file edges before deletion (edges where one endpoint is outside the subgraph)
+    // These will be recreated after import using deterministic IDs
+    GET_CROSS_FILE_EDGES: `
+    MATCH (sf:SourceFile)
+    WHERE sf.filePath IN $filePaths
+    OPTIONAL MATCH (sf)-[*]->(child)
+    WITH collect(DISTINCT sf) + collect(DISTINCT child) AS nodesToDelete
+    UNWIND nodesToDelete AS n
+    MATCH (n)-[r]-(other)
+    WHERE NOT other IN nodesToDelete
+    RETURN DISTINCT
+      startNode(r).id AS startNodeId,
+      endNode(r).id AS endNodeId,
+      type(r) AS edgeType,
+      properties(r) AS edgeProperties
+  `,
+    // Delete source file subgraphs (nodes and all their edges)
+    DELETE_SOURCE_FILE_SUBGRAPHS: `
+    MATCH (sf:SourceFile)
+    WHERE sf.filePath IN $filePaths
+    OPTIONAL MATCH (sf)-[*]->(child)
+    DETACH DELETE sf, child
+  `,
+    // Recreate cross-file edges after import (uses deterministic IDs)
+    RECREATE_CROSS_FILE_EDGES: `
+    UNWIND $edges AS edge
+    MATCH (startNode {id: edge.startNodeId})
+    MATCH (endNode {id: edge.endNodeId})
+    CALL apoc.create.relationship(startNode, edge.edgeType, edge.edgeProperties, endNode) YIELD rel
+    RETURN count(rel) AS recreatedCount
+  `,
+    // Clean up dangling edges (edges pointing to non-existent nodes)
+    // Run after incremental parse to remove edges to renamed/deleted nodes
+    CLEANUP_DANGLING_EDGES: `
+    MATCH ()-[r]->()
+    WHERE startNode(r) IS NULL OR endNode(r) IS NULL
+    DELETE r
+    RETURN count(r) AS deletedCount
+  `,
+    // Get existing nodes (excluding files being reparsed) for edge target matching
+    // Returns minimal info needed for edge detection: id, name, coreType, semanticType
+    GET_EXISTING_NODES_FOR_EDGE_DETECTION: `
+    MATCH (sf:SourceFile)-[*]->(n)
+    WHERE NOT sf.filePath IN $excludeFilePaths
+    RETURN n.id AS id,
+           n.name AS name,
+           n.coreType AS coreType,
+           n.semanticType AS semanticType,
+           labels(n) AS labels,
+           sf.filePath AS filePath
   `,
     EXPLORE_ALL_CONNECTIONS: (maxDepth = MAX_TRAVERSAL_DEPTH, direction = 'BOTH', relationshipTypes) => {
         const safeMaxDepth = Math.min(Math.max(maxDepth, 1), MAX_TRAVERSAL_DEPTH);
@@ -123,7 +178,7 @@ export const QUERIES = {
         RETURN {
           id: connected.id,
           labels: labels(connected),
-          properties: apoc.map.removeKeys(properties(connected), ['embedding'])
+          properties: apoc.map.removeKeys(properties(connected), ['embedding', 'contentHash', 'mtime', 'size'])
         } as node,
         depth,
         [rel in relationships(path) | {
@@ -148,7 +203,7 @@ export const QUERIES = {
         startNode: {
           id: start.id,
           labels: labels(start),
-          properties: apoc.map.removeKeys(properties(start), ['embedding'])
+          properties: apoc.map.removeKeys(properties(start), ['embedding', 'contentHash', 'mtime', 'size'])
         },
         connections: connections,
         totalConnections: size(allConnections),
@@ -156,7 +211,7 @@ export const QUERIES = {
           nodes: [conn in connections | conn.node] + [{
             id: start.id,
             labels: labels(start),
-            properties: apoc.map.removeKeys(properties(start), ['embedding'])
+            properties: apoc.map.removeKeys(properties(start), ['embedding', 'contentHash', 'mtime', 'size'])
           }],
           relationships: reduce(rels = [], conn in connections | rels + conn.relationshipChain)
         }
@@ -252,7 +307,7 @@ export const QUERIES = {
         node: {
           id: neighbor.id,
           labels: labels(neighbor),
-          properties: apoc.map.removeKeys(properties(neighbor), ['embedding'])
+          properties: apoc.map.removeKeys(properties(neighbor), ['embedding', 'contentHash', 'mtime', 'size'])
         },
         relationship: {
           type: type(rel),

package/dist/utils/file-utils.js

@@ -0,0 +1,20 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+const DEBUG_LOG_FILE = 'debug-search.log';
+const LOG_SEPARATOR = '---';
+const JSON_INDENT = 2;
+export const hashFile = async (filePath) => {
+    const content = await fs.readFile(filePath);
+    return crypto.createHash('sha256').update(content).digest('hex');
+};
+export const debugLog = async (message, data) => {
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${message}\n${data ? JSON.stringify(data, null, JSON_INDENT) : ''}\n${LOG_SEPARATOR}\n`;
+    try {
+        await fs.appendFile(path.join(process.cwd(), DEBUG_LOG_FILE), logEntry);
+    }
+    catch (error) {
+        console.error('Failed to write debug log:', error);
+    }
+};

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "code-graph-context",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "MCP server that builds code graphs to provide rich context to LLMs",
   "type": "module",
+  "homepage": "https://github.com/drewdrewH/code-graph-context#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/drewdrewH/code-graph-context.git"