Skip to main content
Glama

CodeCompass MCP

by TheAlchemist6
GitHub
TypeScript
MIT License
2
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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:

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

Examples and Templates

🤝 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

🚀 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
A
security – no known vulnerabilities
A
license - permissive license
A
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.

  1. ✨ Features
    1. 🚀 Quick Start
      1. Step-by-Step Docker Setup (Recommended)
      2. Platform Support
      3. Alternative Installation Methods
    2. 🔧 Configuration
      1. Required Environment Variables
      2. Optional Configuration
    3. 🛠️ Available Tools
      1. Core Data Tools (6 tools)
      2. AI-Enhanced Tools (3 tools)
      3. Transformation Tools (1 tool)
      4. Utility Tools (1 tool)
    4. 🐳 Docker Integration
      1. Production Deployment
      2. Docker Compose
      3. MCP Client Integration
    5. 📊 Monitoring & Observability
      1. Real-time Dashboard
      2. Performance Metrics
      3. Health Monitoring
    6. 🔍 Usage Examples
      1. Repository Analysis
      2. AI Code Review
      3. Batch File Processing
    7. 🏗️ Architecture
      1. Service-Oriented Design
      2. Key Components
    8. 🔒 Security Features
      1. Input Validation
      2. Container Security
    9. 🎯 Performance Optimization
      1. Intelligent Response Management
      2. Resource Management
    10. 📚 Documentation
      1. Complete Documentation Suite
      2. Examples and Templates
    11. 🤝 Contributing
      1. Development Setup
    12. 🔄 Roadmap
      1. Current Version (1.0.0)
      2. Future Enhancements
    13. 📄 License
      1. 🙏 Acknowledgments
        1. 🆘 Support
          1. Getting Help
          2. Common Issues
        2. 🚀 Built With

          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
            • Linux
            • Apple

          • 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

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/TheAlchemist6/codecompass-mcp'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server