code-graph-context CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Code Graph Context is an MCP (Model Context Protocol) server that builds code graphs to provide rich context to LLMs. It parses TypeScript codebases using AST analysis (ts-morph), stores the graph in Neo4j with vector embeddings, and provides semantic search and graph traversal tools.

Build & Development Commands

npm run build          # Compile TypeScript to dist/
npm run dev            # Watch mode compilation
npm run mcp            # Run MCP server: node dist/mcp/mcp.server.js
npm run lint           # ESLint with auto-fix
npm run format         # Prettier formatting

Architecture

Data Flow

TypeScript Project → AST Parser (ts-morph) → Graph Nodes/Edges → Neo4j + Vector Embeddings → MCP Tools

Key Directories

• src/mcp/ - MCP server entry point and tools
  • mcp.server.ts - Server initialization
  • tools/ - 7 MCP tools (search_codebase, traverse_from_node, impact_analysis, etc.)
  • handlers/ - Business logic for graph generation and traversal
• src/core/ - Core business logic
  • parsers/typescript-parser.ts - Main AST parser (~1000 lines)
  • config/schema.ts - Core graph schema definitions
  • config/nestjs-framework-schema.ts - NestJS semantic patterns
  • embeddings/ - OpenAI embeddings and NL-to-Cypher services
• src/storage/neo4j/ - Neo4j driver and queries

Dual-Schema System

The parser uses two schema layers:

1. Core Schema (AST-level): ClassDeclaration, MethodDeclaration, PropertyDeclaration, ImportDeclaration, etc.
2. Framework Schema (Semantic): Controller, Service, Module, Guard, Repository, etc. (NestJS patterns)

Nodes have both coreType (AST) and semanticType (framework interpretation).

Multi-Project Support

The system supports multiple projects in a single Neo4j database through project isolation:

• Project ID Format: proj_<12-hex-chars> (e.g., proj_a1b2c3d4e5f6)
• Auto-generation: If not provided, projectId is generated deterministically from the project path
• Explicit Override: Pass projectId to parse_typescript_project to use a custom ID
• Isolation: All queries are automatically scoped to the project - nodes from different projects never interfere