code-graph-mcp

Name	code-graph-mcp JSON
Version	1.2.4 JSON
	download
home_page	None
Summary	MCP server for multi-language code graph intelligence and analysis across 25+ programming languages
upload_time	2025-07-26 16:41:01
maintainer	None
docs_url	None
author	None
requires_python	>=3.12
license	MIT License Copyright (c) 2025 Shawn McAllister @entrepeneur4lyf Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	ast claude-code code-analysis code-quality complexity-analysis graph intelligence mcp python static-analysis
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 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)

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

## MCP Host Integration

### Claude Desktop

#### Method 1: Using Claude CLI (Recommended)

**For PyPI installation:**
```bash
# 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:**
```bash
# 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:**
```bash
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`

```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:

```json
{
  "cline.mcp.servers": {
    "code-graph-mcp": {
      "command": "code-graph-mcp"
    }
  }
}
```

### Continue (VS Code Extension)

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

```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:

```json
{
  "name": "code-graph-mcp",
  "command": "code-graph-mcp"
}
```

### Zed Editor

Add to your Zed `settings.json`:

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

### Zencoder ⭐

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

```json
{
  "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:

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

### Aider

Use with Aider AI coding assistant:

```bash
aider --mcp-server code-graph-mcp
```

### Open WebUI

For Open WebUI integration, add to your MCP configuration:

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

### Generic MCP Client

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

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

### Docker Integration

Run as a containerized MCP server:

```dockerfile
FROM python:3.12-slim
RUN pip install code-graph-mcp ast-grep-py rustworkx
WORKDIR /workspace
CMD ["code-graph-mcp"]
```

```bash
docker run -v $(pwd):/workspace code-graph-mcp
```

### Development Installation

For contributing or custom builds:

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

**Add to Claude Code (development):**
```bash
# 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:**
```json
{
  "command": "uv",
  "args": ["run", "code-graph-mcp"]
}
```

## Configuration Options

### Command Line Arguments

```bash
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

```bash
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
   ```bash
   pip install --upgrade code-graph-mcp
   which code-graph-mcp
   ```

2. **"ast-grep not found"**: Install the required dependency
   ```bash
   pip install ast-grep-py
   ```

3. **Permission errors**: Use virtual environment
   ```bash
   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
   ```bash
   code-graph-mcp --verbose
   ```

#### Debug Mode

Enable verbose logging for troubleshooting:

```bash
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**
| Tool | Description | Key Features |
|------|-------------|--------------|
| `get_usage_guide` | **NEW** - Comprehensive guidance with workflows, best practices, and examples | Complete documentation, workflow patterns, performance guidelines |

### 🛠️ **Analysis Tools**
| Tool | Description | Multi-Language Features | Performance |
|------|-------------|------------------------|-------------|
| `analyze_codebase` | Complete project analysis with structure metrics and complexity assessment | Language detection, framework identification, cross-language dependency mapping | ⚡ Expensive (10-60s) |
| `find_definition` | Locate symbol definitions with detailed metadata and documentation | Universal AST traversal, language-agnostic symbol resolution | ⚡ Fast (<3s) |
| `find_references` | Find all references to symbols throughout the codebase | Cross-file and cross-language reference tracking | ⚡ Fast (<3s) |
| `find_callers` | Identify all functions that call a specified function | Multi-language call graph analysis | ⚡ Fast (<3s) |
| `find_callees` | List all functions called by a specified function | Universal function call detection across languages | ⚡ Fast (<3s) |
| `complexity_analysis` | Analyze code complexity with refactoring recommendations | Language-specific complexity patterns, universal metrics | ⚡ Moderate (5-15s) |
| `dependency_analysis` | Generate module dependency graphs and import relationships | Cross-language dependency detection, circular dependency analysis | ⚡ Moderate (3-10s) |
| `project_statistics` | Comprehensive project health metrics and statistics | Multi-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
```bash
# 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

| Category | Languages | Count |
|----------|-----------|-------|
| **Web & Frontend** | JavaScript, TypeScript, HTML, CSS | 4 |
| **Backend & Systems** | Python, Java, C#, C++, C, Rust, Go | 7 |
| **JVM Languages** | Java, Kotlin, Scala | 3 |  
| **Functional** | Elixir, Elm | 2 |
| **Mobile** | Swift, Dart | 2 |
| **Scripting** | Ruby, PHP, Lua | 3 |
| **Data & Config** | SQL, YAML, JSON, TOML | 4 |
| **Markup & Docs** | XML, Markdown | 2 |
| **Additional** | Haskell, OCaml, F# | 3 |
| **Total** | | **25+** |

## 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
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "code-graph-mcp",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.12",
    "maintainer_email": null,
    "keywords": "ast, claude-code, code-analysis, code-quality, complexity-analysis, graph, intelligence, mcp, python, static-analysis",
    "author": null,
    "author_email": "entrepeneur4lyf <shawn.payments@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/b3/e6/f44d1b2cf99c110199f5c7c9719e539eb44cf40dd14f6ba4b81c0549b822/code_graph_mcp-1.2.4.tar.gz",
    "platform": null,
    "description": "# Code Graph MCP Server\n\nModel Context Protocol server providing comprehensive code analysis, navigation, and quality assessment capabilities **across 25+ programming languages**.\n\n## Features\n\n\ud83c\udfaf **Enhanced Tool Guidance & AI Optimization** \u2b50 *NEW in v1.2.0*\n- **Comprehensive Usage Guide** - Built-in `get_usage_guide` tool with workflows, best practices, and examples\n- **Rich Tool Descriptions** - Visual hierarchy with \ud83c\udfaf PURPOSE, \ud83d\udd27 USAGE, \u26a1 PERFORMANCE, \ud83d\udd04 WORKFLOW, \ud83d\udca1 TIP sections\n- **Performance-Aware Design** - Clear expectations for Fast (<3s), Moderate (3-15s), and Expensive (10-60s) operations\n- **Workflow Orchestration** - Optimal tool sequences for Code Exploration, Refactoring Analysis, and Architecture Analysis\n- **AI Model Optimization** - Reduces trial-and-error, improves tool orchestration, enables strategic usage patterns\n\n\ud83c\udf0d **Multi-Language Support**\n- **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#\n- **Intelligent Language Detection**: Extension-based, MIME type, shebang, and content signature analysis\n- **Framework Recognition**: React, Angular, Vue, Django, Flask, Spring, and 15+ more\n- **Universal AST Abstraction**: Language-agnostic code analysis and graph structures\n\n\ud83d\udd0d **Advanced Code Analysis**\n- Complete codebase structure analysis with metrics across all languages\n- Universal AST parsing with ast-grep backend and intelligent caching\n- Cyclomatic complexity calculation with language-specific patterns\n- Project health scoring and maintainability indexing\n- Code smell detection: long functions, complex logic, duplicate patterns\n- Cross-language similarity analysis and pattern matching\n\n\ud83e\udded **Navigation & Search**\n- Symbol definition lookup across mixed-language codebases\n- Reference tracking across files and languages\n- Function caller/callee analysis with cross-language calls\n- Dependency mapping and circular dependency detection\n- Call graph generation across entire project\n\n\u26a1 **Performance Optimized**\n- **Debounced File Watcher** - Automatic re-analysis when files change with 2-second intelligent debouncing\n- **Real-time Updates** - Code graph automatically updates during active development\n- Aggressive LRU caching with 50-90% speed improvements on repeated operations\n- Cache sizes optimized for 500+ file codebases (up to 300K entries)\n- Sub-microsecond response times on cache hits\n- Memory-efficient universal graph building\n\n\ud83c\udfe2 **Enterprise Ready**\n- Production-quality error handling across all languages\n- Comprehensive logging and monitoring with language context\n- UV package management with ast-grep integration\n\n## Installation\n\n### Quick Start (PyPI)\n\n```bash\npip install code-graph-mcp ast-grep-py rustworkx\n```\n\n## MCP Host Integration\n\n### Claude Desktop\n\n#### Method 1: Using Claude CLI (Recommended)\n\n**For PyPI installation:**\n```bash\n# Project-specific installation\nclaude mcp add --scope project code-graph-mcp code-graph-mcp\n\n# User-wide installation  \nclaude mcp add --scope user code-graph-mcp code-graph-mcp\n```\n\n**For development installation:**\n```bash\n# Project-specific installation\nclaude mcp add --scope project code-graph-mcp uv run code-graph-mcp\n\n# User-wide installation  \nclaude mcp add --scope user code-graph-mcp uv run code-graph-mcp\n```\n\n**Verify installation:**\n```bash\nclaude mcp list\n```\n\n#### Method 2: Manual Configuration\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"code-graph-mcp\": {\n      \"command\": \"code-graph-mcp\"\n    }\n  }\n}\n```\n\n### Cline (VS Code Extension)\n\nAdd to your Cline MCP settings in VS Code:\n\n1. Open VS Code Settings (Ctrl/Cmd + ,)\n2. Search for \"Cline MCP\"\n3. Add server configuration:\n\n```json\n{\n  \"cline.mcp.servers\": {\n    \"code-graph-mcp\": {\n      \"command\": \"code-graph-mcp\"\n    }\n  }\n}\n```\n\n### Continue (VS Code Extension)\n\nAdd to your `~/.continue/config.json`:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"code-graph-mcp\",\n      \"command\": \"code-graph-mcp\",\n      \"env\": {}\n    }\n  ]\n}\n```\n\n### Cursor\n\nAdd to Cursor's MCP configuration:\n\n1. Open Cursor Settings\n2. Navigate to Extensions \u2192 MCP\n3. Add server:\n\n```json\n{\n  \"name\": \"code-graph-mcp\",\n  \"command\": \"code-graph-mcp\"\n}\n```\n\n### Zed Editor\n\nAdd to your Zed `settings.json`:\n\n```json\n{\n  \"assistant\": {\n    \"mcp_servers\": {\n      \"code-graph-mcp\": {\n        \"command\": \"code-graph-mcp\"\n      }\n    }\n  }\n}\n```\n\n### Zencoder \u2b50\n\n**The best AI coding tool!** Add to your Zencoder MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-graph-mcp\": {\n      \"command\": \"code-graph-mcp\",\n      \"env\": {},\n      \"description\": \"Multi-language code analysis with 25+ language support\"\n    }\n  }\n}\n```\n\n**Pro Tip**: Zencoder's advanced AI capabilities work exceptionally well with Code Graph MCP's comprehensive multi-language analysis. Perfect combination for professional development! \ud83d\ude80\n\n### Windsurf\n\nAdd to Windsurf's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-graph-mcp\": {\n      \"command\": \"code-graph-mcp\"\n    }\n  }\n}\n```\n\n### Aider\n\nUse with Aider AI coding assistant:\n\n```bash\naider --mcp-server code-graph-mcp\n```\n\n### Open WebUI\n\nFor Open WebUI integration, add to your MCP configuration:\n\n```json\n{\n  \"mcp_servers\": {\n    \"code-graph-mcp\": {\n      \"command\": \"code-graph-mcp\",\n      \"env\": {}\n    }\n  }\n}\n```\n\n### Generic MCP Client\n\nFor any MCP-compatible client, use these connection details:\n\n```json\n{\n  \"name\": \"code-graph-mcp\",\n  \"command\": \"code-graph-mcp\",\n  \"env\": {}\n}\n```\n\n### Docker Integration\n\nRun as a containerized MCP server:\n\n```dockerfile\nFROM python:3.12-slim\nRUN pip install code-graph-mcp ast-grep-py rustworkx\nWORKDIR /workspace\nCMD [\"code-graph-mcp\"]\n```\n\n```bash\ndocker run -v $(pwd):/workspace code-graph-mcp\n```\n\n### Development Installation\n\nFor contributing or custom builds:\n\n```bash\ngit clone <repository-url>\ncd code-graph-mcp\nuv sync --dev\nuv build\n```\n\n**Add to Claude Code (development):**\n```bash\n# Project-specific\nclaude mcp add --scope project code-graph-mcp uv run code-graph-mcp\n\n# User-wide\nclaude mcp add --scope user code-graph-mcp uv run code-graph-mcp\n```\n\n**For other MCP clients, use:**\n```json\n{\n  \"command\": \"uv\",\n  \"args\": [\"run\", \"code-graph-mcp\"]\n}\n```\n\n## Configuration Options\n\n### Command Line Arguments\n\n```bash\ncode-graph-mcp --help\n```\n\nAvailable options:\n- `--project-root PATH`: Root directory of your project (optional, defaults to current directory)\n- `--verbose`: Enable detailed logging\n- `--no-file-watcher`: Disable automatic file change detection\n\n### Environment Variables\n\n```bash\nexport CODE_GRAPH_MCP_LOG_LEVEL=DEBUG\nexport CODE_GRAPH_MCP_CACHE_SIZE=500000\nexport CODE_GRAPH_MCP_MAX_FILES=10000\nexport CODE_GRAPH_MCP_FILE_WATCHER=true\nexport CODE_GRAPH_MCP_DEBOUNCE_DELAY=2.0\n```\n\n### File Watcher (v1.1.0+)\n\nThe server includes an intelligent file watcher that automatically updates the code graph when files change:\n\n- **Automatic Detection**: Monitors all supported file types in your project\n- **Smart Debouncing**: 2-second delay prevents excessive re-analysis during rapid changes\n- **Efficient Filtering**: Respects `.gitignore` patterns and only watches relevant files\n- **Thread-Safe**: Runs in background without blocking analysis operations\n- **Zero Configuration**: Starts automatically after first analysis\n\n**File Watcher Features:**\n- Real-time graph updates during development\n- Batch processing of multiple rapid changes\n- Duplicate change prevention\n- Graceful error recovery\n- Resource cleanup on shutdown\n\n### Troubleshooting\n\n#### Common Issues\n\n1. **\"Command not found\"**: Ensure `code-graph-mcp` is in your PATH\n   ```bash\n   pip install --upgrade code-graph-mcp\n   which code-graph-mcp\n   ```\n\n2. **\"ast-grep not found\"**: Install the required dependency\n   ```bash\n   pip install ast-grep-py\n   ```\n\n3. **Permission errors**: Use virtual environment\n   ```bash\n   python -m venv venv\n   source venv/bin/activate  # Linux/Mac\n   # or\n   venv\\Scripts\\activate     # Windows\n   pip install code-graph-mcp ast-grep-py rustworkx\n   ```\n\n4. **Large project performance**: Use verbose mode for debugging\n   ```bash\n   code-graph-mcp --verbose\n   ```\n\n#### Debug Mode\n\nEnable verbose logging for troubleshooting:\n\n```bash\ncode-graph-mcp --verbose\n```\n\n#### Supported File Types\n\nThe server automatically detects and analyzes these file extensions:\n- **Web**: `.js`, `.ts`, `.jsx`, `.tsx`, `.html`, `.css`\n- **Backend**: `.py`, `.java`, `.cs`, `.cpp`, `.c`, `.rs`, `.go`\n- **Mobile**: `.swift`, `.dart`, `.kt`\n- **Scripting**: `.rb`, `.php`, `.lua`, `.pl`\n- **Config**: `.json`, `.yaml`, `.yml`, `.toml`, `.xml`\n- **Docs**: `.md`, `.rst`, `.txt`\n\n## Available Tools\n\nThe MCP server provides **9 comprehensive analysis tools** with enhanced guidance that work across all 25+ supported languages:\n\n### \ud83c\udfaf **Enhanced Tool Experience** \u2b50 *NEW in v1.2.0*\n\nEach tool now includes **rich guidance** with visual hierarchy:\n- **\ud83c\udfaf PURPOSE** - Clear explanation of what the tool does\n- **\ud83d\udd27 USAGE** - When and how to use the tool effectively  \n- **\u26a1 PERFORMANCE** - Speed expectations and caching information\n- **\ud83d\udd04 WORKFLOW** - Optimal tool sequencing recommendations\n- **\ud83d\udca1 TIP** - Pro tips for maximum effectiveness\n\n### \ud83d\udcda **Usage Guide Tool**\n| Tool | Description | Key Features |\n|------|-------------|--------------|\n| `get_usage_guide` | **NEW** - Comprehensive guidance with workflows, best practices, and examples | Complete documentation, workflow patterns, performance guidelines |\n\n### \ud83d\udee0\ufe0f **Analysis Tools**\n| Tool | Description | Multi-Language Features | Performance |\n|------|-------------|------------------------|-------------|\n| `analyze_codebase` | Complete project analysis with structure metrics and complexity assessment | Language detection, framework identification, cross-language dependency mapping | \u26a1 Expensive (10-60s) |\n| `find_definition` | Locate symbol definitions with detailed metadata and documentation | Universal AST traversal, language-agnostic symbol resolution | \u26a1 Fast (<3s) |\n| `find_references` | Find all references to symbols throughout the codebase | Cross-file and cross-language reference tracking | \u26a1 Fast (<3s) |\n| `find_callers` | Identify all functions that call a specified function | Multi-language call graph analysis | \u26a1 Fast (<3s) |\n| `find_callees` | List all functions called by a specified function | Universal function call detection across languages | \u26a1 Fast (<3s) |\n| `complexity_analysis` | Analyze code complexity with refactoring recommendations | Language-specific complexity patterns, universal metrics | \u26a1 Moderate (5-15s) |\n| `dependency_analysis` | Generate module dependency graphs and import relationships | Cross-language dependency detection, circular dependency analysis | \u26a1 Moderate (3-10s) |\n| `project_statistics` | Comprehensive project health metrics and statistics | Multi-language project profiling, maintainability indexing | \u26a1 Fast (<3s) |\n\n## Usage Examples\n\n### \ud83c\udfaf **Getting Started with Enhanced Guidance** \u2b50 *NEW in v1.2.0*\n\n```\nFirst, get comprehensive guidance on using the tools effectively:\nget_usage_guide\n```\n\n### \ud83d\udd0d **Multi-Language Analysis Workflows**\n\n**Code Exploration Workflow:**\n```\n1. analyze_codebase (build the foundation)\n2. project_statistics (get overview)  \n3. find_definition(\"MyClass\") (locate specific symbols)\n4. find_references(\"MyClass\") (understand usage patterns)\n```\n\n**Refactoring Analysis Workflow:**\n```\n1. analyze_codebase\n2. complexity_analysis (threshold=15 for critical issues)\n3. find_callers(\"complex_function\") (impact analysis)\n4. find_callees(\"complex_function\") (dependency analysis)\n```\n\n**Architecture Analysis Workflow:**\n```\n1. analyze_codebase\n2. dependency_analysis (identify circular dependencies)\n3. project_statistics (health metrics)\n4. complexity_analysis (quality assessment)\n```\n\n### \ud83d\udcac **Natural Language Examples**\n\n```\nAnalyze this React/TypeScript frontend with Python backend - show me the overall structure and complexity metrics\n```\n\n```\nFind all references to the function \"authenticate\" across both the Java services and JavaScript frontend\n```\n\n```\nShow me functions with complexity higher than 15 across all languages that need refactoring\n```\n\n```\nGenerate a dependency graph showing how the Python API connects to the React components\n```\n\n```\nDetect code smells and duplicate patterns across the entire multi-language codebase\n```\n\n## Development\n\n### Requirements\n- Python 3.12+\n- UV package manager\n- MCP SDK\n- ast-grep-py (for multi-language support)\n- rustworkx (for high-performance graph operations)\n\n### Running locally\n```bash\n# Install dependencies\nuv sync\n\n# Run the server directly (auto-detects current directory)\nuv run code-graph-mcp --verbose\n\n# Test with help\nuv run code-graph-mcp --help\n```\n\n### Performance Features\n\n- **LRU Caching**: 50-90% speed improvements with cache sizes up to 300K entries for large codebases\n- **High-Performance Analytics**: PageRank at 4.9M nodes/second, Betweenness Centrality at 104K nodes/second\n- **Sub-microsecond Response**: Cache hits deliver sub-microsecond response times for repeated operations\n- **Memory Optimized**: Cache configurations optimized for 500+ file codebases with 500MB memory allocation\n- **Comprehensive Benchmarks**: Performance monitoring with detailed cache effectiveness metrics\n\n## Supported Languages\n\n| Category | Languages | Count |\n|----------|-----------|-------|\n| **Web & Frontend** | JavaScript, TypeScript, HTML, CSS | 4 |\n| **Backend & Systems** | Python, Java, C#, C++, C, Rust, Go | 7 |\n| **JVM Languages** | Java, Kotlin, Scala | 3 |  \n| **Functional** | Elixir, Elm | 2 |\n| **Mobile** | Swift, Dart | 2 |\n| **Scripting** | Ruby, PHP, Lua | 3 |\n| **Data & Config** | SQL, YAML, JSON, TOML | 4 |\n| **Markup & Docs** | XML, Markdown | 2 |\n| **Additional** | Haskell, OCaml, F# | 3 |\n| **Total** | | **25+** |\n\n## Status\n\n\u2705 **Multi-Language Support** - 25+ programming languages with ast-grep backend  \n\u2705 **MCP SDK integrated** - Full protocol compliance across all languages  \n\u2705 **Universal Architecture** - Language-agnostic graph structures and analysis  \n\u2705 **Server architecture complete** - Enterprise-grade multi-language structure  \n\u2705 **Core tools implemented** - 8 comprehensive analysis tools working across all languages  \n\u2705 **Performance optimized** - Multi-language AST caching with intelligent routing  \n\u2705 **Production ready** - comprehensive error handling, defensive security",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2025 Shawn McAllister @entrepeneur4lyf\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE.",
    "summary": "MCP server for multi-language code graph intelligence and analysis across 25+ programming languages",
    "version": "1.2.4",
    "project_urls": {
        "Changelog": "https://github.com/entrepeneur4lyf/code-graph-mcp/releases",
        "Documentation": "https://github.com/entrepeneur4lyf/code-graph-mcp#readme",
        "Homepage": "https://github.com/entrepeneur4lyf/code-graph-mcp",
        "Issues": "https://github.com/entrepeneur4lyf/code-graph-mcp/issues",
        "Repository": "https://github.com/entrepeneur4lyf/code-graph-mcp"
    },
    "split_keywords": [
        "ast",
        " claude-code",
        " code-analysis",
        " code-quality",
        " complexity-analysis",
        " graph",
        " intelligence",
        " mcp",
        " python",
        " static-analysis"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ee57f631fc04a52f03047de0290e676ca94b697741ffac5d0903a126818cde33",
                "md5": "cab893004e6f88b184b9194505642c21",
                "sha256": "705506263dc5e12f433256c3ea9a44c14e930a8adadd60b3cc8c60cf1de37ea8"
            },
            "downloads": -1,
            "filename": "code_graph_mcp-1.2.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cab893004e6f88b184b9194505642c21",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.12",
            "size": 61768,
            "upload_time": "2025-07-26T16:40:59",
            "upload_time_iso_8601": "2025-07-26T16:40:59.797182Z",
            "url": "https://files.pythonhosted.org/packages/ee/57/f631fc04a52f03047de0290e676ca94b697741ffac5d0903a126818cde33/code_graph_mcp-1.2.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "b3e6f44d1b2cf99c110199f5c7c9719e539eb44cf40dd14f6ba4b81c0549b822",
                "md5": "4f59d3ba8ff311e0a3b3efdccc845e7b",
                "sha256": "a5ad615ab1e5e5af834906992aa0f59b39770933d2f0909f336288474cfa07e4"
            },
            "downloads": -1,
            "filename": "code_graph_mcp-1.2.4.tar.gz",
            "has_sig": false,
            "md5_digest": "4f59d3ba8ff311e0a3b3efdccc845e7b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.12",
            "size": 57231,
            "upload_time": "2025-07-26T16:41:01",
            "upload_time_iso_8601": "2025-07-26T16:41:01.307263Z",
            "url": "https://files.pythonhosted.org/packages/b3/e6/f44d1b2cf99c110199f5c7c9719e539eb44cf40dd14f6ba4b81c0549b822/code_graph_mcp-1.2.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-26 16:41:01",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "entrepeneur4lyf",
    "github_project": "code-graph-mcp",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "code-graph-mcp"
}