code-graph-context 0.1.0 → 1.1.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/embeddings/natural-language-to-cypher.service.js

@@ -7,10 +7,11 @@ export class NaturalLanguageToCypherService {
     messageInstructions = `
 The schema file (neo4j-apoc-schema.json) contains two sections:
 1. rawSchema: Complete Neo4j APOC schema with all node labels, properties, and relationships in the graph
-2. domainContext: Framework-specific semantics including:
-   - nodeTypes: Descriptions and example queries for each node type
-   - relationships: How nodes connect with context about relationship properties
-   - commonQueryPatterns: Pre-built example queries for common use cases
+2. discoveredSchema: Dynamically discovered graph structure including:
+   - nodeTypes: Array of {label, count, properties} for each node type in the graph
+   - relationshipTypes: Array of {type, count, connections} showing relationship types and what they connect
+   - semanticTypes: Array of {type, count} showing semantic node classifications (e.g., Service, Controller)
+   - commonPatterns: Array of {from, relationship, to, count} showing frequent relationship patterns
 
 Your response must be a valid JSON object with this exact structure:
 {
@@ -20,19 +21,17 @@ Your response must be a valid JSON object with this exact structure:
 }
 
 Query Generation Process:
-1. CHECK DOMAIN CONTEXT: Look at domainContext.nodeTypes to understand available node types and their properties
-2. REVIEW EXAMPLES: Check domainContext.commonQueryPatterns for similar query examples
-3. CHECK RELATIONSHIPS: Look at domainContext.relationships to understand how nodes connect
-4. EXAMINE NODE PROPERTIES: Use rawSchema to see exact property names and types
-5. HANDLE JSON PROPERTIES: If properties or relationship context are stored as JSON strings, use apoc.convert.fromJsonMap() to parse them
+1. CHECK NODE TYPES: Look at discoveredSchema.nodeTypes to see available node labels and their properties
+2. CHECK RELATIONSHIPS: Look at discoveredSchema.relationshipTypes to understand how nodes connect
+3. CHECK SEMANTIC TYPES: Look at discoveredSchema.semanticTypes for higher-level node classifications
+4. REVIEW PATTERNS: Check discoveredSchema.commonPatterns for frequent relationship patterns in the graph
+5. EXAMINE PROPERTIES: Use rawSchema for exact property names and types
 6. GENERATE QUERY: Write the Cypher query using only node labels, relationships, and properties that exist in the schema
 
 Critical Rules:
 - Use the schema information from the file_search tool - do not guess node labels or relationships
-- Use ONLY node labels and properties found in rawSchema
-- For nested JSON data in properties, use: apoc.convert.fromJsonMap(node.propertyName) or apoc.convert.fromJsonMap(relationship.context)
-- Check domainContext for parsing instructions specific to certain node types (e.g., some nodes may store arrays of objects in JSON format)
-- Follow the example queries in commonQueryPatterns for proper syntax patterns
+- Use ONLY node labels and properties found in the schema
+- For nested JSON data in properties, use: apoc.convert.fromJsonMap(node.propertyName)
 - Use parameterized queries with $ syntax for any dynamic values
 - Return only the data relevant to the user's request
 

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,7 @@ 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,10 +167,18 @@ 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);
+                const SKELETONIZE_TYPES = new Set([
+                    CoreNodeType.METHOD_DECLARATION,
+                    CoreNodeType.FUNCTION_DECLARATION,
+                    CoreNodeType.PROPERTY_DECLARATION,
+                ]);
+                if (SKELETONIZE_TYPES.has(type)) {
+                    this.skeletonizeChildInParent(parentNode, coreNode);
+                }
                 const childNodeConfig = this.coreSchema.nodeTypes[type];
                 if (childNodeConfig) {
                     this.queueRelationshipNodes(childNodeConfig, coreNode, child);
@@ -130,6 +187,15 @@ export class TypeScriptParser {
             }
         }
     }
+    skeletonizeChildInParent(parent, child) {
+        const childText = child.properties.sourceCode;
+        const bodyStart = childText.indexOf('{');
+        if (bodyStart > -1) {
+            const signature = childText.substring(0, bodyStart).trim();
+            const placeholder = `${signature} { /* NodeID: ${child.id} */ }`;
+            parent.properties.sourceCode = parent.properties.sourceCode.replace(childText, placeholder);
+        }
+    }
     /**
      * Queue relationship edges for deferred processing
      * These are resolved after all nodes are parsed since the target may not exist yet
@@ -169,8 +235,12 @@ export class TypeScriptParser {
             return target.getName();
         if (Node.isInterfaceDeclaration(target))
             return target.getName();
-        if (Node.isExpressionWithTypeArguments(target))
-            return target.getExpression().getText();
+        if (Node.isExpressionWithTypeArguments(target)) {
+            const expression = target.getExpression();
+            const text = expression.getText();
+            const genericIndex = text.indexOf('<');
+            return genericIndex > 0 ? text.substring(0, genericIndex) : text;
+        }
         return undefined;
     }
     /**
@@ -182,6 +252,11 @@ export class TypeScriptParser {
                 return node;
             }
         }
+        for (const node of this.existingNodes.values()) {
+            if (node.coreType === coreType && node.properties.name === name) {
+                return node;
+            }
+        }
         return undefined;
     }
     /**
@@ -205,14 +280,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 +295,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 +310,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 +327,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 +344,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 +352,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 +368,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 +378,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 +391,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 +464,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 +599,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 +626,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 +743,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/constants.js

@@ -21,6 +21,7 @@ export const TOOL_NAMES = {
     traverseFromNode: 'traverse_from_node',
     parseTypescriptProject: 'parse_typescript_project',
     testNeo4jConnection: 'test_neo4j_connection',
+    impactAnalysis: 'impact_analysis',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -39,7 +40,6 @@ Start with default parameters for richest context in a single call. Most queries
 
 Parameters:
 - query: Natural language description of what you're looking for
-- limit (default: 10): Number of initial vector search results to consider
 
 **Token Optimization (Only if needed)**:
 Use these parameters ONLY if you encounter token limit errors (>25,000 tokens):
@@ -87,10 +87,27 @@ Best practices:
         title: 'Test Neo4j Connection & APOC',
         description: 'Test connection to Neo4j database and verify APOC plugin is available',
     },
+    [TOOL_NAMES.impactAnalysis]: {
+        title: 'Impact Analysis',
+        description: `Analyze the impact of modifying a code node. Shows what depends on this node and helps assess risk before making changes.
+
+Returns:
+- Risk level (LOW/MEDIUM/HIGH/CRITICAL) based on dependency count and relationship types
+- Direct dependents: nodes that directly reference the target
+- Transitive dependents: nodes affected through dependency chains
+- Affected files: list of files that would need review
+- Critical paths: high-risk dependency chains
+
+Parameters:
+- nodeId: Node ID from search_codebase or traverse_from_node results
+- filePath: Alternative - analyze all exports from a file
+- maxDepth: How far to trace transitive dependencies (default: 4)
+
+Use this before refactoring to understand blast radius of changes.`,
+    },
 };
 // Default Values
 export const DEFAULTS = {
-    searchLimit: 10,
     traversalDepth: 3,
     skipOffset: 0,
     batchSize: 500,

package/dist/mcp/mcp.server.js

@@ -6,8 +6,8 @@
  */
 // Load environment variables from .env file
 import dotenv from 'dotenv';
-import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Go up two levels from dist/mcp/mcp.server.js to the root