code-graph-context 0.1.0

package/dist/mcp/utils.js

@@ -0,0 +1,152 @@
+/**
+ * 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);
+    }
+};
+/**
+ * Standard error response format for MCP tools
+ */
+export const createErrorResponse = (error) => {
+    const errorMessage = error instanceof Error ? error.message : error;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${MESSAGES.errors.genericError} ${errorMessage}`,
+            },
+        ],
+    };
+};
+/**
+ * Standard success response format for MCP tools
+ */
+export const createSuccessResponse = (text) => {
+    return {
+        content: [
+            {
+                type: 'text',
+                text,
+            },
+        ],
+    };
+};
+/**
+ * Format node information as structured data
+ */
+export const formatNodeInfo = (value, key) => {
+    if (value && typeof value === 'object' && value.labels && value.properties) {
+        // Return structured node data
+        const result = {
+            id: value.properties.id,
+            type: value.labels[0] ?? 'Unknown',
+            filePath: value.properties.filePath,
+        };
+        if (value.properties.name) {
+            result.name = value.properties.name;
+        }
+        // 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;
+            }
+        }
+        return result;
+    }
+    else if (value && typeof value === 'object' && value.type) {
+        // Return structured relationship data
+        return {
+            relationshipType: value.type,
+            properties: value.properties,
+        };
+    }
+    else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        // Handle record objects (e.g., {rd.filePath: "...", rd.name: "..."})
+        const formatted = {};
+        Object.keys(value).forEach((k) => {
+            formatted[k] = formatNodeInfo(value[k], k);
+        });
+        return formatted;
+    }
+    else {
+        // Return primitive as-is
+        return value;
+    }
+};
+/**
+ * Format results for the natural language to cypher tool
+ */
+export const formatQueryResults = (results, query, cypherResult) => {
+    const formattedResults = results.map((record) => formatNodeInfo(record, 'result'));
+    return {
+        query,
+        cypher: cypherResult.cypher,
+        parameters: cypherResult.parameters ?? {},
+        explanation: cypherResult.explanation,
+        totalResults: results.length,
+        results: formattedResults,
+    };
+};
+/**
+ * Validate and sanitize numeric inputs
+ */
+export const sanitizeNumericInput = (value, defaultValue, max) => {
+    const parsed = typeof value === 'string' ? parseInt(value, 10) : value;
+    if (isNaN(parsed) || parsed < 0) {
+        return defaultValue;
+    }
+    if (max !== undefined && parsed > max) {
+        return max;
+    }
+    return parsed;
+};
+/**
+ * Safe JSON parse with fallback
+ */
+export const safeJsonParse = (json, fallback = null) => {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+};
+/**
+ * Format success message for parsing results
+ */
+export const formatParseSuccess = (nodeCount, edgeCount, result) => {
+    let message = `${MESSAGES.success.parseSuccess} Parsed ${nodeCount} nodes and ${edgeCount} edges. Graph imported to Neo4j.`;
+    if (result) {
+        message += ` Result: ${JSON.stringify(result)}`;
+    }
+    return message;
+};
+/**
+ * Format partial success message for parsing results
+ */
+export const formatParsePartialSuccess = (nodeCount, edgeCount, outputPath, errorMessage) => {
+    return `${MESSAGES.success.partialSuccess} Parsed ${nodeCount} nodes and ${edgeCount} edges. JSON saved to ${outputPath}. Neo4j import failed: ${errorMessage}`;
+};

package/dist/parsers/cypher-result.parser.js

@@ -0,0 +1,44 @@
+export class CypherResultParser {
+    static parseCypherResult(result) {
+        if (!result || result.length === 0) {
+            return 'No results found.';
+        }
+        const parsedResults = {};
+        // Parse nodes
+        if (result[0].nodes) {
+            parsedResults.nodes = result[0].nodes.map((node) => ({
+                identity: node.identity.toString(),
+                labels: node.labels,
+                properties: node.properties,
+            }));
+        }
+        // Parse relationships
+        if (result[0].relationships) {
+            parsedResults.relationships = result[0].relationships.map((rel) => ({
+                identity: rel.identity.toString(),
+                type: rel.type,
+                properties: rel.properties,
+                start: rel.start.toString(),
+                end: rel.end.toString(),
+            }));
+        }
+        // Parse paths
+        if (result[0].paths) {
+            parsedResults.paths = result[0].paths.map((path) => ({
+                start: path.start,
+                end: path.end,
+                segments: path.segments,
+                length: path.length,
+            }));
+        }
+        // Parse data
+        if (result[0].data) {
+            parsedResults.data = result[0].data;
+        }
+        // Parse summary
+        if (result[0].summary) {
+            parsedResults.summary = result[0].summary;
+        }
+        return JSON.stringify(parsedResults, null, 2);
+    }
+}

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

@@ -0,0 +1,277 @@
+import neo4j from 'neo4j-driver';
+import { MAX_TRAVERSAL_DEPTH } from '../../constants.js';
+export class Neo4jService {
+    driver;
+    constructor() {
+        this.driver = this.createDriver();
+    }
+    createDriver() {
+        const uri = process.env.NEO4J_URI ?? 'bolt://localhost:7687';
+        const user = process.env.NEO4J_USER ?? 'neo4j';
+        const password = process.env.NEO4J_PASSWORD ?? 'PASSWORD';
+        return neo4j.driver(uri, neo4j.auth.basic(user, password));
+    }
+    async run(query, params = {}) {
+        const session = this.driver.session();
+        try {
+            const result = await session.run(query, params);
+            return result.records.map((record) => record.toObject());
+        }
+        catch (error) {
+            console.error('Error running query:', error);
+            throw error;
+        }
+        finally {
+            await session.close();
+        }
+    }
+    getDriver() {
+        return this.driver;
+    }
+    async getSchema() {
+        const session = this.driver.session();
+        try {
+            return await session.run(QUERIES.APOC_SCHEMA);
+        }
+        catch (error) {
+            console.error('Error fetching schema:', error);
+            throw error;
+        }
+        finally {
+            await session.close();
+        }
+    }
+}
+export const QUERIES = {
+    APOC_SCHEMA: `
+    CALL apoc.meta.schema() YIELD value
+      RETURN value as schema
+    `,
+    CLEAR_DATABASE: 'MATCH (n) DETACH DELETE n',
+    CREATE_NODE: `
+    UNWIND $nodes AS nodeData
+    CALL apoc.create.node(nodeData.labels, nodeData.properties) YIELD node
+    RETURN count(*) as created
+  `,
+    CREATE_RELATIONSHIP: `
+    UNWIND $edges AS edgeData
+    MATCH (start) WHERE start.id = edgeData.startNodeId
+    MATCH (end) WHERE end.id = edgeData.endNodeId
+    WITH start, end, edgeData
+    CALL apoc.create.relationship(start, edgeData.type, edgeData.properties, end) YIELD rel
+    RETURN count(*) as created
+  `,
+    CREATE_INDEX: (label, property) => `CREATE INDEX IF NOT EXISTS FOR (n:${label}) ON (n.${property})`,
+    GET_STATS: `
+    MATCH (n) 
+    RETURN labels(n)[0] as nodeType, count(*) as count 
+    ORDER BY count DESC
+  `,
+    CREATE_EMBEDDED_VECTOR_INDEX: `
+  CREATE VECTOR INDEX embedded_nodes_idx IF NOT EXISTS
+  FOR (n:Embedded) ON (n.embedding) 
+  OPTIONS {indexConfig: {
+    \`vector.dimensions\`: 3072,
+    \`vector.similarity_function\`: 'cosine'
+  }}
+`,
+    VECTOR_SEARCH: `
+  CALL db.index.vector.queryNodes('embedded_nodes_idx', $limit, $embedding)
+  YIELD node, score
+  RETURN {
+    id: node.id,
+    labels: labels(node),
+    properties: apoc.map.removeKeys(properties(node), ['embedding'])
+  } as node, score
+  ORDER BY score DESC
+`,
+    // Check if index exists
+    CHECK_VECTOR_INDEX: `
+    SHOW INDEXES YIELD name, type 
+    WHERE name = 'node_embedding_idx' AND type = 'VECTOR'
+    RETURN count(*) > 0 as exists
+  `,
+    EXPLORE_ALL_CONNECTIONS: (maxDepth = MAX_TRAVERSAL_DEPTH, direction = 'BOTH', relationshipTypes) => {
+        const safeMaxDepth = Math.min(Math.max(maxDepth, 1), MAX_TRAVERSAL_DEPTH);
+        // Build relationship pattern based on direction
+        let relPattern = '';
+        if (direction === 'OUTGOING') {
+            relPattern = `-[*1..${safeMaxDepth}]->`;
+        }
+        else if (direction === 'INCOMING') {
+            relPattern = `<-[*1..${safeMaxDepth}]-`;
+        }
+        else {
+            relPattern = `-[*1..${safeMaxDepth}]-`;
+        }
+        // Build relationship type filter if specified
+        let relTypeFilter = '';
+        if (relationshipTypes && relationshipTypes.length > 0) {
+            const types = relationshipTypes.map((t) => `'${t}'`).join(', ');
+            relTypeFilter = `AND all(rel in relationships(path) WHERE type(rel) IN [${types}])`;
+        }
+        return `
+      MATCH (start) WHERE start.id = $nodeId
+
+      CALL {
+        WITH start
+        MATCH path = (start)${relPattern}(connected)
+        WHERE connected <> start
+        ${relTypeFilter}
+        WITH path, connected, length(path) as depth
+
+        RETURN {
+          id: connected.id,
+          labels: labels(connected),
+          properties: apoc.map.removeKeys(properties(connected), ['embedding'])
+        } as node,
+        depth,
+        [rel in relationships(path) | {
+          type: type(rel),
+          start: startNode(rel).id,
+          end: endNode(rel).id,
+          properties: properties(rel)
+        }] as relationshipChain
+
+      }
+
+      WITH start, collect({
+        node: node,
+        depth: depth,
+        relationshipChain: relationshipChain
+      }) as allConnections
+
+      WITH start, allConnections,
+           allConnections[$skip..] as connections
+
+      RETURN {
+        startNode: {
+          id: start.id,
+          labels: labels(start),
+          properties: apoc.map.removeKeys(properties(start), ['embedding'])
+        },
+        connections: connections,
+        totalConnections: size(allConnections),
+        graph: {
+          nodes: [conn in connections | conn.node] + [{
+            id: start.id,
+            labels: labels(start),
+            properties: apoc.map.removeKeys(properties(start), ['embedding'])
+          }],
+          relationships: reduce(rels = [], conn in connections | rels + conn.relationshipChain)
+        }
+      } as result
+    `;
+    },
+    /**
+     * DEPTH-BY-DEPTH WEIGHTED TRAVERSAL
+     *
+     * This query is called once per depth level, allowing you to score and prune
+     * at each level before deciding which nodes to explore further.
+     *
+     * Parameters:
+     *   $sourceNodeIds: string[] - Node IDs to explore FROM (starts with just start node)
+     *   $visitedNodeIds: string[] - Node IDs already visited (to avoid cycles)
+     *   $queryEmbedding: number[] - The original query embedding for similarity scoring
+     *   $currentDepth: number - Which depth level we're at (1-indexed)
+     *   $depthDecay: number - Decay factor per depth (e.g., 0.85 means 15% penalty per level)
+     *   $maxNodesPerDepth: number - Maximum nodes to return at this depth
+     *   $direction: 'OUTGOING' | 'INCOMING' | 'BOTH'
+     *
+     * How it works:
+     *
+     * 1. UNWIND $sourceNodeIds - For each node we're exploring FROM
+     * 2. MATCH neighbors - Find all immediate neighbors (1 hop only)
+     * 3. Filter out visited nodes - Avoid cycles
+     * 4. Score each neighbor using:
+     *    - edgeWeight: The relationshipWeight we added to edges (how important is this relationship type?)
+     *    - nodeSimilarity: Cosine similarity between neighbor's embedding and query embedding
+     *    - depthPenalty: Exponential decay based on current depth
+     * 5. Combine: score = edgeWeight * nodeSimilarity * depthPenalty
+     * 6. ORDER BY score DESC, LIMIT to top N
+     * 7. Return scored neighbors - caller decides which to explore at next depth
+     *
+     * Example flow:
+     *   Depth 1: sourceNodeIds=[startNode], returns top 5 neighbors with scores
+     *   Depth 2: sourceNodeIds=[top 3 from depth 1], returns top 5 neighbors of those
+     *   Depth 3: sourceNodeIds=[top 3 from depth 2], returns top 5 neighbors of those
+     *   ...until maxDepth reached or no more neighbors
+     */
+    EXPLORE_DEPTH_LEVEL: (direction = 'BOTH', maxNodesPerDepth = 5) => {
+        // Build relationship pattern based on direction
+        let relPattern = '';
+        if (direction === 'OUTGOING') {
+            relPattern = '-[rel]->';
+        }
+        else if (direction === 'INCOMING') {
+            relPattern = '<-[rel]-';
+        }
+        else {
+            relPattern = '-[rel]-';
+        }
+        return `
+      // Unwind the source nodes we're exploring from
+      UNWIND $sourceNodeIds AS sourceId
+      MATCH (source) WHERE source.id = sourceId
+
+      // Find immediate neighbors (exactly 1 hop)
+      MATCH (source)${relPattern}(neighbor)
+
+      // Filter: skip already visited nodes to avoid cycles
+      WHERE NOT neighbor.id IN $visitedNodeIds
+
+      // Calculate the three scoring components
+      WITH source, neighbor, rel,
+
+           // 1. Edge weight: how important is this relationship type?
+           //    Falls back to 0.5 if not set
+           COALESCE(rel.relationshipWeight, 0.5) AS edgeWeight,
+
+           // 2. Node similarity: how relevant is this node to the query?
+           //    Uses cosine similarity if neighbor has an embedding
+           //    Falls back to 0.5 if no embedding (structural nodes like decorators)
+           CASE
+             WHEN neighbor.embedding IS NOT NULL AND $queryEmbedding IS NOT NULL
+             THEN vector.similarity.cosine(neighbor.embedding, $queryEmbedding)
+             ELSE 0.5
+           END AS nodeSimilarity,
+
+           // 3. Depth penalty: exponential decay
+           //    depth 1: decay^0 = 1.0 (no penalty)
+           //    depth 2: decay^1 = 0.85 (if decay=0.85)
+           //    depth 3: decay^2 = 0.72
+           //    This ensures closer nodes are preferred
+           ($depthDecay ^ ($currentDepth - 1)) AS depthPenalty
+
+      // Combine into final score
+      WITH source, neighbor, rel, edgeWeight, nodeSimilarity, depthPenalty,
+           (edgeWeight * nodeSimilarity * depthPenalty) AS combinedScore
+
+      // Return all neighbor data with scores
+      RETURN {
+        node: {
+          id: neighbor.id,
+          labels: labels(neighbor),
+          properties: apoc.map.removeKeys(properties(neighbor), ['embedding'])
+        },
+        relationship: {
+          type: type(rel),
+          startNodeId: startNode(rel).id,
+          endNodeId: endNode(rel).id,
+          properties: properties(rel)
+        },
+        sourceNodeId: source.id,
+        scoring: {
+          edgeWeight: edgeWeight,
+          nodeSimilarity: nodeSimilarity,
+          depthPenalty: depthPenalty,
+          combinedScore: combinedScore
+        }
+      } AS result
+
+      // Sort by score and limit to top N per depth
+      ORDER BY combinedScore DESC
+      LIMIT ${maxNodesPerDepth}
+    `;
+    },
+};

package/dist/utils/test.js

@@ -0,0 +1,19 @@
+import 'reflect-metadata';
+import { writeFileSync } from 'node:fs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { NESTJS_FRAMEWORK_SCHEMA } from '../core/config/graph-v2';
+import { TypeScriptParser } from '../core/parsers/typescript-parser-v2';
+const workspace = path.join(os.homedir(), 'nestjs/iluvcoffee');
+const tsconfig = path.join(workspace, 'tsconfig.json'); // or tsconfig.build.json etc.
+(async () => {
+    console.log({ workspace, tsconfig, exists: fs.existsSync(tsconfig) });
+    const parser = new TypeScriptParser(workspace, tsconfig, undefined, [NESTJS_FRAMEWORK_SCHEMA]);
+    // 👇  pull in every *.ts file under the repo
+    parser['project'].addSourceFilesAtPaths(path.join(workspace, 'src/**/*.ts'));
+    const { nodes, edges } = await parser.parseWorkspace(); // runs fine now
+    const { nodes: cleanNodes, edges: cleanEdges } = parser.exportToJson();
+    console.log(`Parsed ${cleanNodes.length} nodes / ${cleanEdges.length} edges`);
+    writeFileSync('em-backend-graph.json', JSON.stringify({ nodes: cleanNodes, edges: cleanEdges }, null, 2));
+})();

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "code-graph-context",
+  "version": "0.1.0",
+  "description": "MCP server that builds code graphs to provide rich context to LLMs",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drewdrewH/code-graph-context.git"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "code-graph",
+    "code-analysis",
+    "neo4j",
+    "graph-database",
+    "typescript",
+    "nestjs",
+    "ast-parser",
+    "semantic-search",
+    "openai",
+    "embeddings",
+    "graph-rag",
+    "llm",
+    "claude"
+  ],
+  "author": "Andrew Hernandez",
+  "license": "MIT",
+  "main": "dist/mcp/mcp.server.js",
+  "bin": {
+    "code-graph-context": "dist/mcp/mcp.server.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "mcp": "node dist/mcp/mcp.server.js",
+    "dev": "tsc --watch",
+    "graph:print": "npm run build && node dist/utils/test.js",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "format": "prettier --write \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1",
+    "commander": "^14.0.0",
+    "dotenv": "^17.2.3",
+    "glob": "^11.0.3",
+    "neo4j": "^2.0.0-RC2",
+    "neo4j-driver": "^5.28.1",
+    "openai": "^5.10.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.29.0",
+    "@types/neo4j": "^2.0.6",
+    "@types/node": "^20.19.1",
+    "@typescript-eslint/eslint-plugin": "^8.34.1",
+    "@typescript-eslint/parser": "^8.34.1",
+    "eslint": "^9.29.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prefer-arrow": "^1.2.3",
+    "eslint-plugin-prettier": "^5.5.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "globals": "^16.2.0",
+    "prettier": "^3.5.3",
+    "reflect-metadata": "^0.2.2",
+    "ts-morph": "^26.0.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.1",
+    "uuid": "^11.1.0"
+  }
+}