Metadata-Version: 2.4
Name: code-graph-mcp
Version: 1.0.6
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>
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.
License-File: LICENSE
Keywords: ast,claude-code,code-analysis,code-quality,complexity-analysis,graph,intelligence,mcp,python,static-analysis
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: anyio>=4.0.0
Requires-Dist: ast-grep-py>=0.39.0
Requires-Dist: click>=8.0.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 --scope project code-graph-mcp code-graph-mcp
```

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

For **user-wide** configuration:
```bash
# This configures across all your projects
claude mcp add --scope user code-graph-mcp uv run code-graph-mcp
```

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