Code Graph DB

A Python tool for analyzing codebases using graph database techniques. Parse source code into a graph structure and query relationships between code elements. Includes an MCP server for AI-powered code analysis with Claude Desktop.

Features

• MCP Server Integration: Connect to Claude Desktop for AI-powered code analysis through natural language
• Parse Python codebases into a graph structure
• Store code elements (files, classes, functions, imports) as graph nodes
• Track relationships (contains, imports, calls) as graph edges
• Query the graph to find dependencies, dependents, and paths between elements
• Detect circular dependencies
• Export and import graph databases for reuse
• Command-line interface and Python API

Installation

For Users (Recommended)

Install directly from GitHub using pip:

pip install git+https://github.com/bursonic/code-graph-db.git

That's it! The code-graph-db command is now available.

For Development

If you want to contribute or modify the code:

# Clone the repository
git clone https://github.com/bursonic/code-graph-db.git
cd code-graph-db

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Quick Start

1. Parse your codebase:

   code-graph-db parse /path/to/your/project -o myproject.db

2. Query it:

   code-graph-db query myproject.db --stats

3. Use with Claude Desktop (optional):

   See MCP Server Setup below for AI-powered code analysis.

Usage

Command Line Interface

Parse a codebase:

code-graph-db parse /path/to/codebase -o codebase.db

Query the database:

# Show statistics
code-graph-db query codebase.db --stats

# Find nodes by name
code-graph-db query codebase.db --find "MyClass"

# Filter by type
code-graph-db query codebase.db --find "MyClass" --type class

Python API

from code_graph_db import CodeGraph, CodeParser, QueryEngine

# Create a graph and parse code
graph = CodeGraph()
parser = CodeParser()
parser.parse_directory("/path/to/codebase", graph)

# Query the graph
engine = QueryEngine(graph)

# Find all classes
classes = graph.get_nodes_by_type("class")

# Find dependencies
deps = engine.find_dependencies(node_id)

# Find dependents
dependents = engine.find_dependents(node_id)

# Detect circular dependencies
cycles = engine.find_cycles()

# Get statistics
stats = engine.get_statistics()

# Save the graph
graph.save("codebase.db")

# Load a saved graph
graph.load("codebase.db")

MCP Server Setup

The MCP (Model Context Protocol) server lets AI assistants like Claude analyze your codebase through natural language queries.

Step 1: Install the tool

pip install git+https://github.com/bursonic/code-graph-db.git

Step 2: Parse your codebase

code-graph-db parse /path/to/your/project -o ~/myproject.db

Step 3: Configure Claude Desktop

Add this to your Claude Desktop config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "code-graph-db": {
      "command": "code-graph-db",
      "args": ["mcp", "--database", "/absolute/path/to/your/myproject.db"]
    }
  }
}

Important: Replace /absolute/path/to/your/myproject.db with the actual absolute path to your database file.

Step 4: Restart Claude Desktop

The MCP server will now be available in Claude Desktop. You can ask Claude to:

• "What classes are in my codebase?"
• "Show me all dependencies of MyClass"
• "Find circular dependencies"
• "What functions call calculate_total?"

Available MCP Tools

The server exposes 13 tools for code analysis:

• parse_codebase - Parse and create graph database
• load_database_tool - Load existing database
• get_statistics - Get node/edge counts
• find_by_name - Search for code elements
• find_dependencies - Find what a node depends on
• find_dependents - Find what depends on a node
• find_path - Find path between two nodes
• find_cycles - Detect circular dependencies
• get_node - Get detailed node information
• get_nodes_by_type - Get all nodes of a type
• get_neighbors - Get adjacent nodes
• search_by_attribute - Search by any attribute
• get_all_nodes - List all nodes

Troubleshooting MCP Setup

Command not found:

• Make sure the tool is installed: pip install git+https://github.com/bursonic/code-graph-db.git
• Verify installation: which code-graph-db (should show path to executable)
• If using a virtual environment, use absolute path: "command": "/path/to/venv/bin/code-graph-db"

Server not appearing in Claude Desktop:

• Check the config file JSON syntax is valid
• Ensure you've restarted Claude Desktop completely
• Look for errors in Claude Desktop's logs (Help → View Logs)

Database path issues:

• Always use absolute paths, not relative paths
• Expand ~ to full path: /Users/yourname/myproject.db not ~/myproject.db
• Ensure the database file exists and is readable

Architecture

The tool consists of three main components:

1. CodeGraph (graph.py): Core graph database using NetworkX

   • Add/retrieve nodes and edges
   • Save/load graph to disk
   • Navigate relationships

2. CodeParser (parser.py): Parse source code using Tree-sitter

   • Extract code structure (classes, functions, imports)
   • Build graph representation
   • Support for Python (extensible to other languages)

3. QueryEngine (query.py): Query and analyze the graph

   • Find nodes by name or attributes
   • Traverse dependencies
   • Detect cycles
   • Calculate statistics

Development

All development should be done within the virtual environment:

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

Run tests:

venv/bin/pytest  # or just `pytest` if venv is activated

Format code:

venv/bin/black code_graph_db tests

Lint code:

venv/bin/ruff check code_graph_db tests

Type check:

venv/bin/mypy code_graph_db

Roadmap

• Support for more programming languages (JavaScript, Java, Go, etc.)
• Function call graph analysis
• Advanced query language
• Visualization tools
• Integration with IDEs
• Performance optimizations for large codebases
• Export to various graph formats (GraphML, DOT, etc.)

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.