Technical Briefing: CodeGraphContext

The Problem

AI assistants need structured code context to provide meaningful assistance, but indexing local repositories into queryable graphs requires significant engineering effort. CodeGraphContext addresses this by building an MCP server and CLI toolkit that parses codebases and stores them in a graph database for AI consumption. The project supports 10+ languages via tree-sitter parsers and produces a navigable import/dependency graph.

What This Does

CodeGraphContext indexes local code into Neo4j (via kuzu/falkordb backends) to provide context to AI assistants. The core pipeline runs from src/codegraphcontext/server.py and src/codegraphcontext/cli/main.py, parsing source files through language-specific tree-sitter parsers (Python, JavaScript/TSX, TypeScript, PHP, Shell, C, Dart) and persisting entities (functions, classes, imports) into a graph database. The website (website/) and VS Code extension (extensions/vscode/) consume the MCP interface.

Key files:

  • src/codegraphcontext/server.py — MCP server entry point, defines add_code_to_graph_tool (reaches 381 functions) and add_package_to_graph_tool (reaches 381 functions)
  • src/codegraphcontext/cli/main.py — CLI entry point, defines add_package (reaches 400 functions)
  • src/codegraphcontext/tools/tree_sitter_parser/ — Parsers for multiple languages; src/codegraphcontext/tools/tree_sitter_parser is the most connected module (Ca=1, Ce=24, instability=0.96)
  • src/codegraphcontext/core/database.py — Database layer (19 functions, 3 classes); src/codegraphcontext/core/database_kuzu.py (46 functions, 5 classes) implements kuzu-specific operations
  • src/codegraphcontext/tools/indexing/persistence/writer.py — Persistence writer (67 functions); large file with deep nesting (max indent 7)

The import graph contains 335 internal modules and 289 edges, with 4 modules in circular dependencies (src/codegraphcontext/cli/cli_helpers, src/codegraphcontext/tools/graph_builder).

How It Is Wired

Execution starts at the CLI (src/codegraphcontext/cli/main.py:2808, main reaches 24 functions) or the MCP server (src/codegraphcontext/server.py:606, run reaches 112 functions). The most frequently called functions are resolve (168 call sites), parse (96), and session (92). _get_node_text is the deepest dependency, called from 75 places and central to parsing across all language modules.

Traced paths from entry points:

  • run → debug_log [filesystem via Path(debug_file).parent.mkdir]
  • main → load_json [filesystem via path.read_text(encoding="utf-8", errors="ignore").strip]
  • add_package → _load_credentials → ensure_config_dir [filesystem via path.mkdir]

The module hub is src/codegraphcontext/utils/debug_log.py (24 dependents, 0 outgoing calls, instability 0). High branching density and deep nesting across config_manager.py, code_finder.py, and writer.py make changes ripple widely—config_manager.py has 948 lines with max indentation depth 7.

How To Use It

Setup: Install with pip install codegraphcontext or build from source via the Dockerfile (base image python:3.12-slim). The VS Code extension (extensions/vscode/package.json) provides the local MCP client.

Configuration: Required env vars are managed through src/codegraphcontext/cli/config_manager.py (ensure_config_dir, load_config). The .cgcignore file controls which paths are excluded from indexing. Database credentials and connection strings are loaded from config in src/codegraphcontext/core/database.py.

Running it:

  • CLI: python -m codegraphcontext.cli add-package <path> (invokes main.py:1480)
  • Server: Start the MCP server via src/codegraphcontext/server.py; the add_code_to_graph_tool endpoint indexes a codebase into the graph.

Environment setup requires populating config dirs and ensuring the database driver is available. The Dockerfile and docker-compose.template.yml provide containerized deployment.

Real-World Use

An AI IDE integrated via MCP can call add_code_to_graph_tool to index a user's repository on-demand. The server parses the code, builds the import graph, and stores function/class signatures in Neo4j/kuzu. When the assistant needs to answer a question about code structure, it queries the graph for related functions, call chains, and dependencies—avoiding full-text search and leveraging the structured graph for precise answers. The VS Code extension (extensions/vscode/src/extension.ts) surfaces this graph in the editor sidebar.

Code Health & Issues

Measured findings (181 total): 52 high, 128 medium, 1 low

  • [HIGH/cognitive_load] Deep nesting x40 — src/codegraphcontext/cli/config_manager.py, src/codegraphcontext/tools/code_finder.py, src/codegraphcontext/tools/indexing/persistence/writer.py. Max indentation depth 7; control flow hard to follow. Fix: flatten with early returns/guard clauses.
  • [HIGH/cognitive_load] Oversized files x4 — Same three files. 948 code lines in config_manager.py; hard to hold in one head. Fix: split into cohesive units by responsibility.
  • [HIGH/cognitive_load] Broad exception handling x12 — src/codegraphcontext/utils/debug_log.py, src/codegraphcontext/cli/config_manager.py, src/codegraphcontext/core/database.py. Bare except swallows errors indiscriminately. Fix: catch specific exceptions; re-raise or log the rest.
  • [HIGH/soundness] Import cycle member — src/codegraphcontext/cli/cli_helpers.py. Participates in circular import dependency. Fix: break the cycle by extracting shared types or inverting a dependency.
  • [MEDIUM/resource_safety] File opened without context manager — src/codegraphcontext/cli/cli_helpers.py. open(...) not wrapped in with; handle may leak on error. Fix: use with open(...) as f:.
  • [MEDIUM/clarity] Hub module — src/codegraphcontext/utils/debug_log.py. 24 modules depend on it; churn is high-blast-radius. Fix: keep stable and small; move volatile logic out.

SDLC observations: Committed secrets detected in tests/fixtures/sample_projects/sample_project/edge_cases/hardcoded_secrets.py. License present. CI: GitHub Actions (16 workflows). Dockerfile yes. Lockfile absent for pyproject.toml (no committed lockfile). 3 blobs over 5MB in images/ (install&cli.gif 9.2MB, Usecase.gif 7.3MB).

The Bottom Line

CodeGraphContext is a functional MCP server + CLI that successfully indexes local code into a queryable graph database, supporting multiple languages and producing usable context for AI assistants. The engineering is substantial—338 of 338 code files analyzed, 2362 functions and 286 classes parsed via tree-sitter. However, the codebase carries significant technical debt: 4 circular import dependencies, 4 oversized files exceeding 900 lines, and 12 high-severity code health findings including unpinning GitHub Actions, missing lockfile, wildcard CORS with credentials, and absent Dependabot. Teams should plan to address the lockfile and action pinning immediately; the nesting and exception-handling issues require refactoring effort proportional to the file sizes. This is best suited for teams needing custom code-graph integration with AI and who have capacity to manage the identified health debt.