# CodeCompass MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-18%2B-brightgreen)](https://nodejs.org/)
[![Docker](https://img.shields.io/badge/docker-supported-blue)](https://www.docker.com/)
[![TypeScript](https://img.shields.io/badge/typescript-5.8%2B-blue)](https://www.typescriptlang.org/)

**Enterprise-grade Model Context Protocol (MCP) Server for intelligent repository analysis and AI-powered development assistance.**

Connect your development tools to comprehensive GitHub repository analysis with 11 streamlined tools, enhanced error handling, real-time monitoring, and production-ready deployment.

## ✨ **Features**

- 🔍 **Comprehensive Repository Analysis** - Deep insights into code structure, dependencies, and architecture
- 🤖 **AI-Powered Code Review** - Intelligent code analysis with OpenRouter integration (400+ models)
- 🚀 **Production-Ready Deployment** - Docker containers with security best practices
- 📊 **Real-time Monitoring** - Performance metrics, health checks, and observability
- 🛡️ **Enterprise Security** - Input validation, path traversal prevention, and secure processing
- ⚡ **High Performance** - Intelligent chunking, concurrent processing, and response optimization
- 🔧 **Developer Experience** - Comprehensive documentation, examples, and debugging tools

## 🚀 **Quick Start**

### **Step-by-Step Docker Setup (Recommended)**

#### 1. **Clone and Navigate**
```bash
git clone https://github.com/TheAlchemist6/codecompass-mcp.git
cd codecompass-mcp
```
**Expected output:**
```
Cloning into 'codecompass-mcp'...
remote: Enumerating objects: 53, done.
remote: Total 53 (delta 0), reused 0 (delta 0), pack-reused 53
Receiving objects: 100% (53/53), 259.84 KiB | 1.85 MiB/s, done.
```

#### 2. **Configure Environment**
```bash
cp .env.example .env
# Edit .env with your real API keys
nano .env  # or use your preferred editor
```

**Required in `.env` file:**
```bash
GITHUB_TOKEN=ghp_your_actual_github_token_here
OPENROUTER_API_KEY=sk-or-v1-your_actual_openrouter_key_here
```

**🔑 Where to get API keys:**
- **GitHub Token**: [github.com/settings/tokens](https://github.com/settings/tokens) → Generate new token (classic) → Select `repo` scope
- **OpenRouter Key**: [openrouter.ai/keys](https://openrouter.ai/keys) → Create new API key

#### 3. **Build and Run**
```bash
./scripts/docker-build.sh
./scripts/docker-run.sh --env-file .env
```
**Expected output:**
```
✅ Build successful
Image information:
REPOSITORY        TAG       IMAGE ID       CREATED         SIZE
codecompass-mcp   latest    a1b2c3d4e5f6   2 seconds ago   278MB

🚀 Starting CodeCompass MCP server...
✅ Server started successfully
Health check: healthy
API limits: 5000/hour remaining
```

#### 4. **Test Installation**
```bash
# Test with health check
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "health_check"}}' | docker exec -i codecompass-mcp node build/index.js
```

### **Platform Support**
- ✅ **Linux** (Ubuntu 18.04+, CentOS 7+)
- ✅ **macOS** (10.14+, Intel & Apple Silicon)
- ✅ **Windows** (10/11 with Docker Desktop)

### **Alternative Installation Methods**

#### **Local Development**
```bash
# Install dependencies
npm install

# Set environment variables
export GITHUB_TOKEN=your_github_token
export OPENROUTER_API_KEY=your_openrouter_key

# Build and run
npm run build && npm run dev
```

#### **Global Installation**
```bash
npm install -g codecompass-mcp
codecompass-mcp --help
```

## 🔧 **Configuration**

### **Required Environment Variables**
```bash
GITHUB_TOKEN=ghp_your_github_token_here        # GitHub API access
OPENROUTER_API_KEY=sk-or-v1-your_key_here     # OpenRouter API access
```

### **Optional Configuration**
```bash
AI_MODEL=anthropic/claude-3.5-sonnet          # Default AI model
MAX_RESPONSE_TOKENS=25000                      # Response size limit
LOG_LEVEL=info                                 # Logging level
NODE_ENV=production                            # Environment mode
```

## 🛠️ **Available Tools**

### **Core Data Tools (6 tools)**
- **`get_repository_info`** - Repository metadata, statistics, and key information
- **`get_file_tree`** - Complete directory structure and file listing with filtering
- **`search_repository`** - Advanced search with regex patterns and filtering
- **`get_file_content`** - Batch file processing with security validation and metadata
- **`analyze_dependencies`** - Dependency graph analysis and vulnerability detection
- **`analyze_codebase`** - Comprehensive structure, architecture, and metrics analysis

### **AI-Enhanced Tools (3 tools)**
- **`review_code`** - AI-powered code review with security, performance, and maintainability insights
- **`explain_code`** - Natural language code explanations and documentation generation
- **`suggest_improvements`** - Intelligent refactoring recommendations and modernization strategies

### **Transformation Tools (1 tool)**
- **`transform_code`** - Code transformation, modernization, and migration assistance

### **Utility Tools (1 tool)**
- **`health_check`** - System health monitoring and performance metrics

## 🐳 **Docker Integration**

### **Production Deployment**
```bash
# Build production image
./scripts/docker-build.sh

# Run with environment file
./scripts/docker-run.sh --env-file .env

# View logs
./scripts/docker-logs.sh -f --timestamps
```

### **Docker Compose**
```yaml
version: '3.8'
services:
  codecompass-mcp:
    build: .
    container_name: codecompass-mcp
    restart: unless-stopped
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "node", "-e", "console.log('Health check')"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### **MCP Client Integration**

#### **Claude Desktop 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": {
    "codecompass": {
      "command": "docker",
      "args": [
        "exec", "-i", "codecompass-mcp", 
        "node", "build/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "OPENROUTER_API_KEY": "your_openrouter_key_here"
      }
    }
  }
}
```

**Then restart Claude Desktop** and you'll see CodeCompass tools available in the UI.

#### **Claude Code CLI Integration**
```bash
# Add MCP server to Claude Code
claude mcp add codecompass-docker -s user -- \
  docker exec -i codecompass-mcp node build/index.js
```

#### **Other MCP Clients**
- **Cline** (VS Code): Add to MCP configuration
- **Continue** (VS Code/JetBrains): Configure as MCP provider
- **Custom clients**: Use `stdio` transport with `node build/index.js`

#### **Testing Integration**
```bash
# Test the connection
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i codecompass-mcp node build/index.js

# Should return list of 11 tools
```

## 📊 **Monitoring & Observability**

### **Real-time Dashboard**
```bash
# Interactive monitoring dashboard
./scripts/monitor.js --watch

# Export metrics
./scripts/monitor.js --export > metrics.json

# Health check
curl -X POST http://localhost:3000/health
```

### **Performance Metrics**
- **Response Times**: <100ms for health checks, 2-10s for repository analysis
- **Memory Usage**: 50-200MB depending on repository size
- **Concurrent Processing**: Configurable limits with automatic scaling
- **Error Tracking**: Comprehensive error monitoring with contextual suggestions

### **Health Monitoring**
```json
{
  "name": "health_check",
  "arguments": {
    "checks": ["api-limits", "monitoring", "configuration"],
    "options": {
      "include_metrics": true,
      "include_insights": true
    }
  }
}
```

## 🔍 **Usage Examples**

### **Repository Analysis**
```json
{
  "name": "fetch_repository_data",
  "arguments": {
    "url": "https://github.com/microsoft/typescript",
    "options": {
      "include_structure": true,
      "include_dependencies": true,
      "max_files": 100,
      "chunk_mode": true
    }
  }
}
```

### **AI Code Review**
```json
{
  "name": "ai_code_review",
  "arguments": {
    "url": "https://github.com/your-org/your-repo",
    "file_paths": ["src/main.ts", "src/utils/"],
    "review_focus": ["security", "performance", "maintainability"],
    "options": {
      "ai_model": "anthropic/claude-3.5-sonnet",
      "severity_threshold": "medium"
    }
  }
}
```

### **Batch File Processing**
```json
{
  "name": "get_file_content",
  "arguments": {
    "url": "https://github.com/your-org/your-repo",
    "file_paths": ["src/", "docs/", "tests/"],
    "options": {
      "max_concurrent": 10,
      "include_metadata": true,
      "continue_on_error": true
    }
  }
}
```

## 🏗️ **Architecture**

### **Service-Oriented Design**
```
MCP Client → MCP Server → Service Layer → External APIs
            ↓
         Monitoring & Logging
```

### **Key Components**
- **MCP Server**: JSON-RPC protocol handling with 11 streamlined tools
- **Service Layer**: GitHub API, OpenRouter integration, and business logic
- **Configuration**: Centralized, type-safe configuration with Zod validation
- **Monitoring**: Real-time performance tracking and health monitoring
- **Security**: Input validation, path traversal prevention, and secure processing

## 🔒 **Security Features**

### **Input Validation**
- **Zod Schema Validation**: Type-safe input validation for all tools
- **Path Traversal Prevention**: Comprehensive file path security checks
- **Rate Limiting**: Configurable request rate limiting and throttling
- **API Key Management**: Secure environment variable handling

### **Container Security**
- **Non-root Execution**: All containers run as unprivileged users
- **Read-only Filesystems**: Security-focused container configuration
- **Resource Limits**: Memory and CPU constraints for stability
- **Health Checks**: Automated health monitoring and recovery

## 🎯 **Performance Optimization**

### **Intelligent Response Management**
- **Chunking**: Large responses split into manageable chunks
- **Truncation**: Smart truncation preserving data structure
- **Concurrent Processing**: Parallel file processing with configurable limits
- **Caching**: Intelligent caching strategies for frequently accessed data

### **Resource Management**
- **Memory Efficiency**: Optimized memory usage with automatic cleanup
- **Request Tracking**: Correlation IDs for distributed tracing
- **Performance Insights**: Automated performance analysis and recommendations
- **Scalability**: Horizontal scaling ready with Docker containers

## 📚 **Documentation**

### **Complete Documentation Suite**
- **[Setup Guide](docs/SETUP.md)** - Installation and configuration instructions
- **[API Reference](docs/API.md)** - Complete tool documentation with examples
- **[Docker Guide](docs/DOCKER.md)** - Container deployment and management
- **[Monitoring Guide](docs/MONITORING.md)** - Observability and performance monitoring
- **[Architecture Guide](docs/README.md)** - Technical architecture and patterns

### **Examples and Templates**
- **[Usage Examples](examples/)** - Real-world usage patterns and templates
- **[Integration Examples](examples/integrations/)** - MCP client integration examples
- **[Configuration Templates](examples/configs/)** - Production-ready configuration examples

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
- Development setup and workflow
- Code style and testing requirements
- Pull request process and guidelines
- Bug reporting and feature requests

### **Development Setup**
```bash
# Clone and setup
git clone https://github.com/your-org/codecompass-mcp.git
cd codecompass-mcp

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev:watch
```

## 🔄 **Roadmap**

### **Current Version (1.0.0)**
- ✅ 11 streamlined, atomic tools with clear responsibilities
- ✅ Production-ready Docker deployment
- ✅ Real-time monitoring and observability
- ✅ Enterprise security features
- ✅ Complete documentation suite

### **Future Enhancements**
- 🔮 **Conversational Context Management** - Session state and conversation history
- 🔮 **Advanced Caching** - Redis-based caching with intelligent invalidation
- 🔮 **Plugin System** - Extensible architecture for custom tools
- 🔮 **Multi-language Support** - Expanded language support beyond TypeScript/JavaScript
- 🔮 **Kubernetes Integration** - Native Kubernetes deployment with Helm charts

## 📄 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 **Acknowledgments**

- **OpenRouter MCP** - Architecture patterns and best practices inspiration
- **MCP Protocol** - Foundation for tool integration and communication
- **Anthropic** - Claude AI integration and development support
- **GitHub** - Repository analysis and API integration
- **Docker** - Containerization and deployment infrastructure

## 🆘 **Support**

### **Getting Help**
- **Documentation**: Check our comprehensive documentation in the `docs/` directory
- **Issues**: Report bugs and request features on [GitHub Issues](https://github.com/your-org/codecompass-mcp/issues)
- **Discussions**: Join community discussions on [GitHub Discussions](https://github.com/your-org/codecompass-mcp/discussions)

### **Common Issues**
- **API Key Setup**: See [Setup Guide](docs/SETUP.md#api-key-setup)
- **Docker Issues**: Check [Docker Guide](docs/DOCKER.md#troubleshooting)
- **Performance**: Review [Monitoring Guide](docs/MONITORING.md#performance-optimization)

## 🚀 **Built With**

- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript development
- **[Node.js](https://nodejs.org/)** - JavaScript runtime environment
- **[Docker](https://www.docker.com/)** - Containerization platform
- **[Zod](https://zod.dev/)** - TypeScript-first schema validation
- **[MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)** - Model Context Protocol implementation

---

**Made with 💜 by Myron Labs**

*Transform your development workflow with intelligent repository analysis and AI-powered code insights.*