Metadata-Version: 2.4
Name: code-graph-mcp
Version: 1.0.0
Summary: MCP server for multi-language code graph intelligence and analysis across 25+ programming languages
Project-URL: Homepage, https://github.com/entrepeneur4lyf/code-graph-mcp
Project-URL: Repository, https://github.com/entrepeneur4lyf/code-graph-mcp
Project-URL: Documentation, https://github.com/entrepeneur4lyf/code-graph-mcp#readme
Project-URL: Changelog, https://github.com/entrepeneur4lyf/code-graph-mcp/releases
Project-URL: Issues, https://github.com/entrepeneur4lyf/code-graph-mcp/issues
Author-email: entrepeneur4lyf <shawn.payments@gmail.com>
Keywords: ast,ast-grep,claude-code,code-analysis,cpp,cross-language,go,graph,intelligence,java,javascript,mcp,multi-language,python,rust,typescript,universal-parser
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.12
Requires-Dist: ast-grep-py>=0.39.0
Requires-Dist: mcp>=1.12.2
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Code Graph MCP Server

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

## Features

🌍 **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**
- Multi-language AST caching with mtime invalidation
- Intelligent file discovery with language-aware filtering
- Memory-efficient universal graph building
- Parallel processing for multi-language projects
- Comprehensive cache statistics and monitoring

🏢 **Enterprise Ready**
- Production-quality error handling across all languages
- Comprehensive logging and monitoring with language context
- UV package management with ast-grep integration
- 10.00/10 pylint score with comprehensive test coverage

## Installation

### Method 1: Install from PyPI (Recommended)

1. **Install the package with multi-language support:**
```bash
pip install code-graph-mcp ast-grep-py
```

2. **Add to Claude Code using CLI:**
```bash
claude mcp add code-graph-mcp code-graph-mcp --project-root $(pwd) --verbose
```

3. **Verify installation:**
```bash
claude mcp list
code-graph-mcp --help
```

### Method 2: Install from Source

1. **Clone and setup the project:**
```bash
git clone <repository-url>
cd code-graph-mcp
uv sync  # Install dependencies including ast-grep-py
```

2. **Add to your Claude Code configuration:**

For **local project** configuration (recommended):
```bash
# This creates/updates .mcp.json in your current project
claude mcp add --scope project code-graph-mcp uv run code-graph-mcp --project-root $(pwd) --verbose
```

For **user-wide** configuration:
```bash
# This configures across all your projects
claude mcp add --scope user code-graph-mcp uv run code-graph-mcp --project-root $(pwd) --verbose
```

3. **Restart Claude Code**

### Method 3: Development Installation

For contributing to the project:

```bash
git clone <repository-url>
cd code-graph-mcp
uv sync --dev
uv build  # Creates wheel and source distribution
```

## Available Tools

The MCP server provides 8 comprehensive analysis tools that work across all 25+ supported languages:

| Tool | Description | Multi-Language Features |
|------|-------------|------------------------|
| `analyze_codebase` | Complete project analysis with structure metrics and complexity assessment | Language detection, framework identification, cross-language dependency mapping |
| `find_definition` | Locate symbol definitions with detailed metadata and documentation | Universal AST traversal, language-agnostic symbol resolution |  
| `find_references` | Find all references to symbols throughout the codebase | Cross-file and cross-language reference tracking |
| `find_callers` | Identify all functions that call a specified function | Multi-language call graph analysis |
| `find_callees` | List all functions called by a specified function | Universal function call detection across languages |
| `complexity_analysis` | Analyze code complexity with refactoring recommendations | Language-specific complexity patterns, universal metrics |
| `dependency_analysis` | Generate module dependency graphs and import relationships | Cross-language dependency detection, circular dependency analysis |
| `project_statistics` | Comprehensive project health metrics and statistics | Multi-language project profiling, maintainability indexing |

## Usage Examples

Once installed, you can use the tools directly in Claude Code for multi-language projects:

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

## Configuration Options

The server accepts these command-line arguments:

- `--project-root`: Project directory to analyze (defaults to current directory)
- `--verbose`: Enable detailed logging for debugging

## Development

### Requirements
- Python 3.12+
- UV package manager
- MCP SDK
- ast-grep-py (for multi-language support)

### Running locally
```bash
# Install dependencies
uv sync

# Run the server directly
uv run code-graph-mcp --project-root /path/to/your/project --verbose

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

### Performance Features

- **Multi-Language AST Caching**: 50-90% faster repeated analysis with `@lru_cache(maxsize=256)` across all 25+ languages
- **Intelligent File Discovery**: Language-aware file discovery with framework detection and .gitignore support
- **Universal Graph Building**: Memory-efficient incremental graph construction for mixed-language codebases
- **Parallel Processing**: Concurrent analysis of multiple languages with intelligent routing
- **Statistics**: Comprehensive cache hit/miss monitoring with language-specific breakdowns

## 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** - 10.00/10 pylint score, comprehensive error handling, defensive security