code-graph-mcp

entrepeneur4lyf/code-graph-mcp

3.5

If you are the rightful owner of code-graph-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Code Graph MCP Server is a Model Context Protocol server that provides comprehensive code analysis, navigation, and quality assessment capabilities across 25+ programming languages.

Tools
8
Resources
0
Prompts
0

Code Graph MCP Server

Model Context Protocol server providing comprehensive code analysis, navigation, and quality assessment capabilities across 25+ programming languages.

Features

šŸŽÆ Enhanced Tool Guidance & AI Optimization ⭐ NEW in v1.2.0

  • Comprehensive Usage Guide - Built-in get_usage_guide tool with workflows, best practices, and examples
  • Rich Tool Descriptions - Visual hierarchy with šŸŽÆ PURPOSE, šŸ”§ USAGE, ⚔ PERFORMANCE, šŸ”„ WORKFLOW, šŸ’” TIP sections
  • Performance-Aware Design - Clear expectations for Fast (<3s), Moderate (3-15s), and Expensive (10-60s) operations
  • Workflow Orchestration - Optimal tool sequences for Code Exploration, Refactoring Analysis, and Architecture Analysis
  • AI Model Optimization - Reduces trial-and-error, improves tool orchestration, enables strategic usage patterns

šŸŒ Multi-Language Support

  • 25+ Programming Languages: JavaScript, TypeScript, Python, Java, C#, C++, C, Rust, Go, Kotlin, Scala, Swift, Dart, Ruby, PHP, Elixir, Elm, Lua, HTML, CSS, SQL, YAML, JSON, XML, Markdown, Haskell, OCaml, F#
  • Intelligent Language Detection: Extension-based, MIME type, shebang, and content signature analysis
  • Framework Recognition: React, Angular, Vue, Django, Flask, Spring, and 15+ more
  • Universal AST Abstraction: Language-agnostic code analysis and graph structures

šŸ” Advanced Code Analysis

  • Complete codebase structure analysis with metrics across all languages
  • Universal AST parsing with ast-grep backend and intelligent caching
  • Cyclomatic complexity calculation with language-specific patterns
  • Project health scoring and maintainability indexing
  • Code smell detection: long functions, complex logic, duplicate patterns
  • Cross-language similarity analysis and pattern matching

🧭 Navigation & Search

  • Symbol definition lookup across mixed-language codebases
  • Reference tracking across files and languages
  • Function caller/callee analysis with cross-language calls
  • Dependency mapping and circular dependency detection
  • Call graph generation across entire project

⚔ Performance Optimized

  • Debounced File Watcher - Automatic re-analysis when files change with 2-second intelligent debouncing
  • Real-time Updates - Code graph automatically updates during active development
  • Aggressive LRU caching with 50-90% speed improvements on repeated operations
  • Cache sizes optimized for 500+ file codebases (up to 300K entries)
  • Sub-microsecond response times on cache hits
  • Memory-efficient universal graph building

šŸ¢ Enterprise Ready

  • Production-quality error handling across all languages
  • Comprehensive logging and monitoring with language context
  • UV package management with ast-grep integration

Installation

Quick Start (PyPI)

pip install code-graph-mcp ast-grep-py rustworkx

MCP Host Integration

Claude Desktop

Method 1: Using Claude CLI (Recommended)

For PyPI installation:

# Project-specific installation
claude mcp add --scope project code-graph-mcp code-graph-mcp

# User-wide installation  
claude mcp add --scope user code-graph-mcp code-graph-mcp

For development installation:

# Project-specific installation
claude mcp add --scope project code-graph-mcp uv run code-graph-mcp

# User-wide installation  
claude mcp add --scope user code-graph-mcp uv run code-graph-mcp

Verify installation:

claude mcp list
Method 2: Manual Configuration

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp"
    }
  }
}

Cline (VS Code Extension)

Add to your Cline MCP settings in VS Code:

  1. Open VS Code Settings (Ctrl/Cmd + ,)
  2. Search for "Cline MCP"
  3. Add server configuration:
{
  "cline.mcp.servers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp"
    }
  }
}

Continue (VS Code Extension)

Add to your ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "code-graph-mcp",
      "command": "code-graph-mcp",
      "env": {}
    }
  ]
}

Cursor

Add to Cursor's MCP configuration:

  1. Open Cursor Settings
  2. Navigate to Extensions → MCP
  3. Add server:
{
  "name": "code-graph-mcp",
  "command": "code-graph-mcp"
}

Zed Editor

Add to your Zed settings.json:

{
  "assistant": {
    "mcp_servers": {
      "code-graph-mcp": {
        "command": "code-graph-mcp"
      }
    }
  }
}

Zencoder ⭐

The best AI coding tool! Add to your Zencoder MCP configuration:

{
  "mcpServers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp",
      "env": {},
      "description": "Multi-language code analysis with 25+ language support"
    }
  }
}

Pro Tip: Zencoder's advanced AI capabilities work exceptionally well with Code Graph MCP's comprehensive multi-language analysis. Perfect combination for professional development! šŸš€

Windsurf

Add to Windsurf's MCP configuration:

{
  "mcpServers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp"
    }
  }
}

Aider

Use with Aider AI coding assistant:

aider --mcp-server code-graph-mcp

Open WebUI

For Open WebUI integration, add to your MCP configuration:

{
  "mcp_servers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp",
      "env": {}
    }
  }
}

Generic MCP Client

For any MCP-compatible client, use these connection details:

{
  "name": "code-graph-mcp",
  "command": "code-graph-mcp",
  "env": {}
}

Docker Integration

Run as a containerized MCP server:

FROM python:3.12-slim
RUN pip install code-graph-mcp ast-grep-py rustworkx
WORKDIR /workspace
CMD ["code-graph-mcp"]
docker run -v $(pwd):/workspace code-graph-mcp

Development Installation

For contributing or custom builds:

git clone <repository-url>
cd code-graph-mcp
uv sync --dev
uv build

Add to Claude Code (development):

# Project-specific
claude mcp add --scope project code-graph-mcp uv run code-graph-mcp

# User-wide
claude mcp add --scope user code-graph-mcp uv run code-graph-mcp

For other MCP clients, use:

{
  "command": "uv",
  "args": ["run", "code-graph-mcp"]
}

Configuration Options

Command Line Arguments

code-graph-mcp --help

Available options:

  • --project-root PATH: Root directory of your project (optional, defaults to current directory)
  • --verbose: Enable detailed logging
  • --no-file-watcher: Disable automatic file change detection

Environment Variables

export CODE_GRAPH_MCP_LOG_LEVEL=DEBUG
export CODE_GRAPH_MCP_CACHE_SIZE=500000
export CODE_GRAPH_MCP_MAX_FILES=10000
export CODE_GRAPH_MCP_FILE_WATCHER=true
export CODE_GRAPH_MCP_DEBOUNCE_DELAY=2.0

File Watcher (v1.1.0+)

The server includes an intelligent file watcher that automatically updates the code graph when files change:

  • Automatic Detection: Monitors all supported file types in your project
  • Smart Debouncing: 2-second delay prevents excessive re-analysis during rapid changes
  • Efficient Filtering: Respects .gitignore patterns and only watches relevant files
  • Thread-Safe: Runs in background without blocking analysis operations
  • Zero Configuration: Starts automatically after first analysis

File Watcher Features:

  • Real-time graph updates during development
  • Batch processing of multiple rapid changes
  • Duplicate change prevention
  • Graceful error recovery
  • Resource cleanup on shutdown

Troubleshooting

Common Issues
  1. "Command not found": Ensure code-graph-mcp is in your PATH

    pip install --upgrade code-graph-mcp
    which code-graph-mcp
    
  2. "ast-grep not found": Install the required dependency

    pip install ast-grep-py
    
  3. Permission errors: Use virtual environment

    python -m venv venv
    source venv/bin/activate  # Linux/Mac
    # or
    venv\Scripts\activate     # Windows
    pip install code-graph-mcp ast-grep-py rustworkx
    
  4. Large project performance: Use verbose mode for debugging

    code-graph-mcp --verbose
    
Debug Mode

Enable verbose logging for troubleshooting:

code-graph-mcp --verbose
Supported File Types

The server automatically detects and analyzes these file extensions:

  • Web: .js, .ts, .jsx, .tsx, .html, .css
  • Backend: .py, .java, .cs, .cpp, .c, .rs, .go
  • Mobile: .swift, .dart, .kt
  • Scripting: .rb, .php, .lua, .pl
  • Config: .json, .yaml, .yml, .toml, .xml
  • Docs: .md, .rst, .txt

Available Tools

The MCP server provides 9 comprehensive analysis tools with enhanced guidance that work across all 25+ supported languages:

šŸŽÆ Enhanced Tool Experience ⭐ NEW in v1.2.0

Each tool now includes rich guidance with visual hierarchy:

  • šŸŽÆ PURPOSE - Clear explanation of what the tool does
  • šŸ”§ USAGE - When and how to use the tool effectively
  • ⚔ PERFORMANCE - Speed expectations and caching information
  • šŸ”„ WORKFLOW - Optimal tool sequencing recommendations
  • šŸ’” TIP - Pro tips for maximum effectiveness

šŸ“š Usage Guide Tool

ToolDescriptionKey Features
get_usage_guideNEW - Comprehensive guidance with workflows, best practices, and examplesComplete documentation, workflow patterns, performance guidelines

šŸ› ļø Analysis Tools

ToolDescriptionMulti-Language FeaturesPerformance
analyze_codebaseComplete project analysis with structure metrics and complexity assessmentLanguage detection, framework identification, cross-language dependency mapping⚔ Expensive (10-60s)
find_definitionLocate symbol definitions with detailed metadata and documentationUniversal AST traversal, language-agnostic symbol resolution⚔ Fast (<3s)
find_referencesFind all references to symbols throughout the codebaseCross-file and cross-language reference tracking⚔ Fast (<3s)
find_callersIdentify all functions that call a specified functionMulti-language call graph analysis⚔ Fast (<3s)
find_calleesList all functions called by a specified functionUniversal function call detection across languages⚔ Fast (<3s)
complexity_analysisAnalyze code complexity with refactoring recommendationsLanguage-specific complexity patterns, universal metrics⚔ Moderate (5-15s)
dependency_analysisGenerate module dependency graphs and import relationshipsCross-language dependency detection, circular dependency analysis⚔ Moderate (3-10s)
project_statisticsComprehensive project health metrics and statisticsMulti-language project profiling, maintainability indexing⚔ Fast (<3s)

Usage Examples

šŸŽÆ Getting Started with Enhanced Guidance ⭐ NEW in v1.2.0

First, get comprehensive guidance on using the tools effectively:
get_usage_guide

šŸ” Multi-Language Analysis Workflows

Code Exploration Workflow:

1. analyze_codebase (build the foundation)
2. project_statistics (get overview)  
3. find_definition("MyClass") (locate specific symbols)
4. find_references("MyClass") (understand usage patterns)

Refactoring Analysis Workflow:

1. analyze_codebase
2. complexity_analysis (threshold=15 for critical issues)
3. find_callers("complex_function") (impact analysis)
4. find_callees("complex_function") (dependency analysis)

Architecture Analysis Workflow:

1. analyze_codebase
2. dependency_analysis (identify circular dependencies)
3. project_statistics (health metrics)
4. complexity_analysis (quality assessment)

šŸ’¬ Natural Language Examples

Analyze this React/TypeScript frontend with Python backend - show me the overall structure and complexity metrics
Find all references to the function "authenticate" across both the Java services and JavaScript frontend
Show me functions with complexity higher than 15 across all languages that need refactoring
Generate a dependency graph showing how the Python API connects to the React components
Detect code smells and duplicate patterns across the entire multi-language codebase

Development

Requirements

  • Python 3.12+
  • UV package manager
  • MCP SDK
  • ast-grep-py (for multi-language support)
  • rustworkx (for high-performance graph operations)

Running locally

# Install dependencies
uv sync

# Run the server directly (auto-detects current directory)
uv run code-graph-mcp --verbose

# Test with help
uv run code-graph-mcp --help

Performance Features

  • LRU Caching: 50-90% speed improvements with cache sizes up to 300K entries for large codebases
  • High-Performance Analytics: PageRank at 4.9M nodes/second, Betweenness Centrality at 104K nodes/second
  • Sub-microsecond Response: Cache hits deliver sub-microsecond response times for repeated operations
  • Memory Optimized: Cache configurations optimized for 500+ file codebases with 500MB memory allocation
  • Comprehensive Benchmarks: Performance monitoring with detailed cache effectiveness metrics

Supported Languages

CategoryLanguagesCount
Web & FrontendJavaScript, TypeScript, HTML, CSS4
Backend & SystemsPython, Java, C#, C++, C, Rust, Go7
JVM LanguagesJava, Kotlin, Scala3
FunctionalElixir, Elm2
MobileSwift, Dart2
ScriptingRuby, PHP, Lua3
Data & ConfigSQL, YAML, JSON, TOML4
Markup & DocsXML, Markdown2
AdditionalHaskell, OCaml, F#3
Total25+

Status

āœ… Multi-Language Support - 25+ programming languages with ast-grep backend
āœ… MCP SDK integrated - Full protocol compliance across all languages
āœ… Universal Architecture - Language-agnostic graph structures and analysis
āœ… Server architecture complete - Enterprise-grade multi-language structure
āœ… Core tools implemented - 8 comprehensive analysis tools working across all languages
āœ… Performance optimized - Multi-language AST caching with intelligent routing
āœ… Production ready - comprehensive error handling, defensive security