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

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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Tools

View all tools

An enterprise-grade Model Context Protocol server that provides comprehensive GitHub repository analysis and AI-powered development assistance through 11 streamlined tools.

Related MCP Servers

GitHub MCP Server
PoliTwit1984
A
security
F
license
A
quality
A Model Context Protocol server that enables AI models to interact with GitHub's API, allowing for repository creation and management with descriptions, topics, and website URLs through natural language commands.
Last updated -
GitHub MCP Server
renantrendt
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to perform GitHub operations including repository management, file operations, issue tracking, and pull request creation.
Last updated -
1
GitHub MCP Bridge
vipink1203
-
security
A
license
-
quality
A Model Context Protocol server that enables AI agents to securely access and interact with GitHub Enterprise data, providing access to enterprise users, organizations, emails, and license information.
Last updated -
MIT License
GitHub Tools MCP Server
arjunkmrm
-
security
F
license
-
quality
Model Context Protocol server that enables interaction with GitHub repositories, issues, pull requests, and search functionality through natural language.
Last updated -
1

View all related MCP servers