Codecompass MCP

🚀 CodeCompass MCP

Enterprise-grade Model Context Protocol (MCP) Server for intelligent repository analysis and AI-powered development assistance, connecting development tools to comprehensive GitHub repository analysis with streamlined tools, enhanced error handling, real-time monitoring, and production-ready deployment.

🚀 Quick Start

Step-by-Step Docker Setup (Recommended)

1. Clone and Navigate

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

cp .env.example .env
# Edit .env with your real API keys
nano .env  # or use your preferred editor

Required in .env file:

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 → Generate new token (classic) → Select repo scope
• OpenRouter Key: openrouter.ai/keys → Create new API key

3. Build and Run

./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

# 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

# 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

npm install -g codecompass-mcp
codecompass-mcp --help

✨ Features

• 🔍 Comprehensive Repository Analysis - Gain deep insights into code structure, dependencies, and architecture.
• 🤖 AI-Powered Code Review - Conduct intelligent code analysis with OpenRouter integration (400+ models).
• 🚀 Production-Ready Deployment - Utilize Docker containers following security best practices.
• 📊 Real-time Monitoring - Monitor performance metrics, conduct health checks, and ensure observability.
• 🛡️ Enterprise Security - Implement input validation, prevent path traversal, and ensure secure processing.
• ⚡ High Performance - Employ intelligent chunking, concurrent processing, and response optimization.
• 🔧 Developer Experience - Benefit from comprehensive documentation, examples, and debugging tools.

🔧 Configuration

Required Environment Variables

GITHUB_TOKEN=ghp_your_github_token_here        # GitHub API access
OPENROUTER_API_KEY=sk-or-v1-your_key_here     # OpenRouter API access

Optional Configuration

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 - Retrieve repository metadata, statistics, and key information.
• get_file_tree - Obtain the complete directory structure and file listing with filtering.
• search_repository - Perform advanced search using regex patterns and filtering.
• get_file_content - Process batch files with security validation and metadata.
• analyze_dependencies - Analyze the dependency graph and detect vulnerabilities.
• analyze_codebase - Conduct comprehensive structure, architecture, and metrics analysis.

AI-Enhanced Tools (3 tools)

• review_code - Conduct AI-powered code review with insights on security, performance, and maintainability.
• explain_code - Generate natural language code explanations and documentation.
• suggest_improvements - Receive intelligent refactoring recommendations and modernization strategies.

Transformation Tools (1 tool)

• transform_code - Assist with code transformation, modernization, and migration.

Utility Tools (1 tool)

• health_check - Monitor system health and performance metrics.

🐳 Docker Integration

Production Deployment

# 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

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 the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.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

# 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

# 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

# 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

{
  "name": "health_check",
  "arguments": {
    "checks": ["api-limits", "monitoring", "configuration"],
    "options": {
      "include_metrics": true,
      "include_insights": true
    }
  }
}

💻 Usage Examples

Repository Analysis

{
  "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

{
  "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

{
  "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: Handle JSON-RPC protocol with 11 streamlined tools.
• Service Layer: Integrate with GitHub API, OpenRouter, and implement business logic.
• Configuration: Centralize and ensure type-safe configuration with Zod validation.
• Monitoring: Track real-time performance and monitor health.
• Security: Implement input validation, prevent path traversal, and ensure secure processing.

🔒 Security Features

Input Validation

• Zod Schema Validation: Perform type-safe input validation for all tools.
• Path Traversal Prevention: Conduct comprehensive file path security checks.
• Rate Limiting: Configure request rate limiting and throttling.
• API Key Management: Handle secure environment variables.

Container Security

• Non-root Execution: Run all containers as unprivileged users.
• Read-only Filesystems: Configure containers with a security focus.
• Resource Limits: Set memory and CPU constraints for stability.
• Health Checks: Automate health monitoring and recovery.

🎯 Performance Optimization

Intelligent Response Management

• Chunking: Split large responses into manageable chunks.
• Truncation: Perform smart truncation while preserving data structure.
• Concurrent Processing: Process files in parallel with configurable limits.
• Caching: Implement intelligent caching strategies for frequently accessed data.

Resource Management

• Memory Efficiency: Optimize memory usage with automatic cleanup.
• Request Tracking: Use correlation IDs for distributed tracing.
• Performance Insights: Conduct automated performance analysis and receive recommendations.
• Scalability: Be ready for horizontal scaling with Docker containers.

📚 Documentation

Complete Documentation Suite

• Setup Guide - Get installation and configuration instructions.
• API Reference - Access complete tool documentation with examples.
• Docker Guide - Learn about container deployment and management.
• Monitoring Guide - Understand observability and performance monitoring.
• Architecture Guide - Explore the technical architecture and patterns.

Examples and Templates

• Usage Examples - Find real-world usage patterns and templates.
• Integration Examples - See MCP client integration examples.
• Configuration Templates - Get production-ready configuration examples.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development setup and workflow
• Code style and testing requirements
• Pull request process and guidelines
• Bug reporting and feature requests

Development Setup

# 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 - Manage session state and conversation history.
• 🔮 Advanced Caching - Implement Redis-based caching with intelligent invalidation.
• 🔮 Plugin System - Build an extensible architecture for custom tools.
• 🔮 Multi-language Support - Expand language support beyond TypeScript/JavaScript.
• 🔮 Kubernetes Integration - Enable native Kubernetes deployment with Helm charts.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenRouter MCP - Inspired architecture patterns and best practices.
• MCP Protocol - Served as the foundation for tool integration and communication.
• Anthropic - Provided Claude AI integration and development support.
• GitHub - Enabled repository analysis and API integration.
• Docker - Provided 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.
• Discussions: Join community discussions on GitHub Discussions.

Common Issues

• API Key Setup: See Setup Guide.
• Docker Issues: Check Docker Guide.
• Performance: Review Monitoring Guide.

🚀 Built With

• TypeScript - Facilitate type-safe JavaScript development.
• Node.js - Provide a JavaScript runtime environment.
• Docker - Offer a containerization platform.
• Zod - Enable TypeScript-first schema validation.
• MCP SDK - Implement the Model Context Protocol.

Made with 💜 by Myron Labs

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