CodeCompass MCP server for AI agents

CodeCompass MCP is an enterprise-grade Model Context Protocol (MCP) server that provides intelligent repository analysis and AI-powered development assistance. It offers comprehensive GitHub repository analysis with 11 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

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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect