CodeCompass MCP

License: MIT Node.js Version Docker TypeScript

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

Related MCP server: GitHub MCP Server

🚀 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

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

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

# 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 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: 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 - Installation and configuration instructions
API Reference - Complete tool documentation with examples
Docker Guide - Container deployment and management
Monitoring Guide - Observability and performance monitoring
Architecture Guide - Technical architecture and patterns

Examples and Templates

Usage Examples - Real-world usage patterns and templates
Integration Examples - MCP client integration examples
Configuration Templates - 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 - 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 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
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 - Type-safe JavaScript development
Node.js - JavaScript runtime environment
Docker - Containerization platform
Zod - TypeScript-first schema validation
MCP SDK - Model Context Protocol implementation

Made with 💜 by Myron Labs

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