codecompass-mcp

TheAlchemist6/codecompass-mcp

3.3

If you are the rightful owner of codecompass-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

CodeCompass MCP is an enterprise-grade Model Context Protocol server designed for intelligent repository analysis and AI-powered development assistance.

Tools
11
Resources
0
Prompts
0

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

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

  • - Installation and configuration instructions
  • - Complete tool documentation with examples
  • - Container deployment and management
  • - Observability and performance monitoring
  • - Technical architecture and patterns

Examples and Templates

  • - Real-world usage patterns and templates
  • - MCP client integration examples
  • - Production-ready configuration examples

šŸ¤ Contributing

We welcome contributions! Please see our 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 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
  • Docker Issues: Check
  • Performance: Review

šŸš€ 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.