CodeCompass

CodeCompass MCP is an enterprise-grade server that analyzes GitHub repositories and provides AI-powered development assistance through a suite of tools. It helps you gain deep insights into code structure, dependencies, and architecture, while enabling AI-driven reviews, real-time monitoring, and production-ready deployment via containers.

How to use

Connect your MCP client to CodeCompass MCP to start analyzing repositories and performing AI-assisted reviews. You can use a local, inline (stdio) deployment or a remote MCP server configuration within your client. Typical usage patterns include analyzing a repository to extract its structure and dependencies, requesting AI-guided code reviews focused on security and performance, and streaming results in chunks for large projects.

How to install

Prerequisites: you need Docker installed on your machine and Node.js available if you plan to build from source or run local scripts. You will also configure API keys for GitHub and OpenRouter to enable data access and AI capabilities.

# Step 1: Clone the project
git clone https://github.com/TheAlchemist6/codecompass-mcp.git
cd codecompass-mcp

# Step 2: Create and configure environment file
cp .env.example .env
# Edit .env with your real API keys
# Use a text editor to update the following values
# GITHUB_TOKEN=ghp_your_actual_github_token_here
# OPENROUTER_API_KEY=sk-or-v1-your_actual_openrouter_key_here

Step 3: Build and run the production container using the provided scripts. This will build the Docker image and start the MCP server with your environment variables loaded.

./scripts/docker-build.sh
./scripts/docker-run.sh --env-file .env

Step 4: Verify the server started correctly by checking the health status or logs. You should see a healthy health check and operational API limits when the server is running.

Configuration and connectivity notes

Key configuration items you will manage include the following environment variables. They enable GitHub access and OpenRouter AI capabilities.

GITHUB_TOKEN=ghp_your_github_token_here
OPENROUTER_API_KEY=sk-or-v1-your_key_here
NODE_ENV=production

Integration with MCP clients

CodeCompass MCP is designed to be integrated with MCP clients via a standard stdio transport. A representative local runtime uses a docker-based setup that runs a Node.js entry point inside the container. You can configure your client to invoke the internal runtime through a docker exec call, passing the appropriate environment variables.

For Claude Desktop users, you can configure an MCP server as shown in the example configuration, which runs the runtime inside a container and exposes the required environment variables.

Available tools

get_repository_info

Fetch repository metadata, statistics, and key information to understand project scope and health.

get_file_tree

Retrieve the complete directory structure and file listings with filtering options.

search_repository

Perform advanced searches with regex patterns and filtering across the repository.

get_file_content

Process and retrieve file contents in batches with security validation and metadata.

analyze_dependencies

Analyze the dependency graph and detect potential vulnerabilities.

analyze_codebase

Provide a comprehensive analysis of structure, architecture, and metrics.

review_code

AI-powered code review focusing on security, performance, and maintainability.

explain_code

Generate natural language explanations of code and documentation.

suggest_improvements

Offer intelligent refactoring recommendations and modernization strategies.

transform_code

Assist with code modernization and migrations.

health_check

Monitor system health and performance metrics.