SETUP.mdā¢13.6 kB
# CodeCompass MCP Setup Guide
## š **Quick Start**
### **Option 1: Docker Deployment (Recommended)**
```bash
# Clone the repository
git clone https://github.com/your-org/codecompass-mcp.git
cd codecompass-mcp
# Set up environment variables
cp .env.example .env
# Edit .env with your API keys
# Build and run with Docker
./scripts/docker-build.sh
./scripts/docker-run.sh --env-file .env
```
### **Option 2: Local Development**
```bash
# Install dependencies
npm install
# Set up environment
export GITHUB_TOKEN=your_github_token
export OPENROUTER_API_KEY=your_openrouter_key
# Build and run
npm run build
npm run dev
```
### **Option 3: Global Installation**
```bash
# Install globally for system-wide access
npm install -g codecompass-mcp
# Run from anywhere
codecompass-mcp --help
```
## š§ **Configuration**
### **Required Environment Variables**
```bash
# GitHub API access (required for repository analysis)
GITHUB_TOKEN=ghp_your_github_token_here
# OpenRouter API access (required for AI-powered tools)
OPENROUTER_API_KEY=sk-or-v1-your_openrouter_key_here
```
### **Optional Configuration**
```bash
# AI Model Configuration
OPENAI_MODEL=anthropic/claude-3.5-sonnet # Default AI model
OPENROUTER_API_URL=https://openrouter.ai/api/v1 # Custom API endpoint
# Response Management
MAX_RESPONSE_TOKENS=25000 # Maximum response size
MAX_FILE_CONTENT_LENGTH=5000 # Maximum file content per response
CHUNK_SIZE=medium # Chunking strategy (small/medium/large)
# Performance Tuning
MAX_CONCURRENT_REQUESTS=10 # Concurrent processing limit
MAX_FILE_SIZE=10485760 # Maximum file size (10MB)
RATE_LIMIT_REQUESTS=1000 # Rate limit per window
RATE_LIMIT_WINDOW=3600000 # Rate limit window (1 hour)
# Logging Configuration
LOG_LEVEL=info # Logging level (debug/info/warn/error)
NODE_ENV=production # Environment mode
```
### **Configuration File (Optional)**
Create a `config.json` file for persistent configuration:
```json
{
"github": {
"token": "your_github_token",
"apiUrl": "https://api.github.com"
},
"openrouter": {
"apiKey": "your_openrouter_key",
"defaultModel": "anthropic/claude-3.5-sonnet"
},
"response": {
"maxTokens": 25000,
"maxFileContentLength": 5000,
"chunkSizes": {
"small": { "filesPerChunk": 5, "fileContent": 1000 },
"medium": { "filesPerChunk": 10, "fileContent": 2000 },
"large": { "filesPerChunk": 20, "fileContent": 5000 }
}
},
"logging": {
"level": "info",
"enableTimestamps": true,
"enableColors": true
}
}
```
## š **API Key Setup**
### **GitHub Token**
1. Go to [GitHub Settings ā Developer settings ā Personal access tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Set expiration and select scopes:
- `repo` (for private repositories)
- `public_repo` (for public repositories)
- `read:org` (for organization repositories)
4. Copy the token and set as `GITHUB_TOKEN`
**Rate Limits:**
- **Authenticated**: 5,000 requests/hour
- **Unauthenticated**: 60 requests/hour
### **OpenRouter API Key**
1. Go to [OpenRouter](https://openrouter.ai/)
2. Sign up/login and go to [API Keys](https://openrouter.ai/keys)
3. Create a new API key
4. Copy the key and set as `OPENROUTER_API_KEY`
**Available Models:**
- `anthropic/claude-3.5-sonnet` (recommended)
- `openai/gpt-4`
- `google/gemini-pro`
- `switchpoint/router` (automatic model selection)
## š³ **Docker Deployment**
### **Docker Compose (Recommended)**
```yaml
# docker-compose.yml
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
- LOG_LEVEL=info
ports:
- "3000:3000"
volumes:
- ./data:/app/data:ro
healthcheck:
test: ["CMD", "node", "-e", "console.log('Health check')"]
interval: 30s
timeout: 10s
retries: 3
```
### **Docker Build Options**
```bash
# Production build
./scripts/docker-build.sh
# Development build with hot reload
./scripts/docker-build.sh --dev
# Custom tag and registry
./scripts/docker-build.sh -t v1.0.0 -r your-registry.com --push
# With build arguments
./scripts/docker-build.sh --build-arg NODE_ENV=production
```
### **Docker Run Options**
```bash
# Basic run
./scripts/docker-run.sh
# With environment file
./scripts/docker-run.sh --env-file .env
# Interactive mode
./scripts/docker-run.sh --interactive
# With custom configuration
./scripts/docker-run.sh \
-e GITHUB_TOKEN=your_token \
-e OPENROUTER_API_KEY=your_key \
-e LOG_LEVEL=debug
```
## š„ļø **MCP Client Integration**
### **Claude Desktop Integration**
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"codecompass": {
"command": "docker",
"args": [
"exec", "-i", "codecompass-mcp",
"node", "build/index.js"
],
"env": {
"GITHUB_TOKEN": "your_github_token",
"OPENROUTER_API_KEY": "your_openrouter_key"
}
}
}
}
```
### **Claude Code Integration**
```bash
# 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**
The server is compatible with any MCP client that supports the JSON-RPC protocol:
- **Cline**: VS Code extension
- **Continue**: VS Code/JetBrains extension
- **Custom clients**: Using the MCP SDK
## š **Verification**
### **Health Check**
```bash
# Test server health
curl -X POST http://localhost:3000/health \
-H "Content-Type: application/json" \
-d '{"name": "health_check", "arguments": {"options": {"include_metrics": true}}}'
# Or using the monitoring script
./scripts/monitor.js
```
### **Tool Testing**
```bash
# Test repository analysis
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "fetch_repository_data", "arguments": {"url": "https://github.com/microsoft/typescript"}}}' | \
docker exec -i codecompass-mcp node build/index.js
```
### **Performance Testing**
```bash
# Run performance tests
npm run test:performance
# Monitor resource usage
docker stats codecompass-mcp
# Check logs
./scripts/docker-logs.sh -f --timestamps
```
## š **Monitoring Setup**
### **Real-time Dashboard**
```bash
# Start monitoring dashboard
./scripts/monitor.js --watch
# Export metrics
./scripts/monitor.js --export > metrics.json
# View specific metrics
./scripts/monitor.js --export | jq '.metrics.toolUsage'
```
### **Health Monitoring**
```bash
# Comprehensive health check
{
"name": "health_check",
"arguments": {
"checks": ["api-limits", "monitoring", "configuration"],
"options": {
"include_metrics": true,
"include_insights": true,
"include_logs": true
}
}
}
```
### **Log Analysis**
```bash
# View structured logs
docker logs codecompass-mcp | jq .
# Filter by log level
docker logs codecompass-mcp | jq 'select(.level == "ERROR")'
# Search for specific events
docker logs codecompass-mcp | jq 'select(.message | contains("Request started"))'
```
## š ļø **Development Setup**
### **Local Development**
```bash
# Clone and setup
git clone https://github.com/your-org/codecompass-mcp.git
cd codecompass-mcp
# Install dependencies
npm install
# Set up environment
cp .env.example .env
# Edit .env with your configuration
# Start development server
npm run dev
# Run tests
npm run test
# Type checking
npm run type-check
# Linting
npm run lint
```
### **Hot Reload Development**
```bash
# Start with hot reload
npm run dev:watch
# Or with Docker
./scripts/docker-build.sh --dev
./scripts/docker-run.sh --interactive -v $(pwd):/app
```
### **Testing**
```bash
# Run all tests
npm test
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance
# Test coverage
npm run test:coverage
```
## š§ **Troubleshooting**
### **Common Error Messages & Solutions**
#### **1. "API key missing" or "Neither GITHUB_TOKEN nor OPENROUTER_API_KEY is set"**
**Cause**: Environment variables not properly configured.
**Solution**:
```bash
# Check if your .env file exists and has content
cat .env
# Verify tokens are set correctly
echo $GITHUB_TOKEN | cut -c1-10 # Should show: ghp_xxxxxx
echo $OPENROUTER_API_KEY | cut -c1-10 # Should show: sk-or-v1-x
# Fix: Edit your .env file with real tokens
nano .env
```
**Expected .env content:**
```bash
GITHUB_TOKEN=ghp_your_actual_40_character_token_here
OPENROUTER_API_KEY=sk-or-v1-your_actual_key_here
```
#### **2. "repository 'https://github.com/...' not found" (404 Error)**
**Cause**: Repository is private or doesn't exist.
**Solution**:
```bash
# Test GitHub token permissions
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
# Expected response: Your GitHub user info
# If error: Check token has 'repo' scope at github.com/settings/tokens
```
#### **3. "Container codecompass-mcp not found"**
**Cause**: Docker container not running.
**Solution**:
```bash
# Check container status
docker ps -a
# If not running, start it
./scripts/docker-run.sh --env-file .env
# If failed to start, check logs
docker logs codecompass-mcp
```
#### **4. "Permission denied" or "EACCES" errors**
**Cause**: File permissions issue.
**Solution**:
```bash
# Fix script permissions
chmod +x scripts/*.sh
# Fix Docker permissions (Linux)
sudo usermod -aG docker $USER
newgrp docker
```
#### **5. "Port already in use" or "EADDRINUSE"**
**Cause**: Port 3000 already occupied.
**Solution**:
```bash
# Check what's using port 3000
lsof -i :3000
# Kill the process or use different port
export MCP_PORT=3001
./scripts/docker-run.sh --env-file .env
```
#### **6. "Request timeout" errors**
**Cause**: Large repository or slow network.
**Solution**:
```bash
# Increase timeouts in .env
echo "REQUEST_TIMEOUT=60000" >> .env
# Use chunking for large repos
echo "CHUNK_MODE=true" >> .env
```
#### **7. "Docker build failed" or "npm install failed"**
**Cause**: Network issues or missing dependencies.
**Solution**:
```bash
# Clear Docker cache and rebuild
docker system prune -f
./scripts/docker-build.sh --no-cache
# For local development
rm -rf node_modules package-lock.json
npm install
```
### **Debug Mode**
```bash
# Enable verbose logging
export LOG_LEVEL=debug
# Run with debug output
DEBUG=codecompass:* ./scripts/docker-run.sh --env-file .env
# Check logs location
./scripts/docker-logs.sh -f --timestamps
```
### **Health Check Commands**
```bash
# Quick health check
curl -X POST http://localhost:3000/health
# Detailed health check with metrics
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "health_check", "arguments": {"options": {"include_metrics": true}}}}' | docker exec -i codecompass-mcp node build/index.js
```
### **Getting Help**
If you're still having issues:
1. **Check GitHub Issues**: [github.com/TheAlchemist6/codecompass-mcp/issues](https://github.com/TheAlchemist6/codecompass-mcp/issues)
2. **Include in your issue**:
- Operating system and version
- Docker version (`docker --version`)
- Node.js version (`node --version`)
- Complete error message
- Steps to reproduce
3. **Useful diagnostic commands**:
```bash
# System info
docker --version
node --version
npm --version
# Container logs
docker logs codecompass-mcp --tail 50
# Environment check
env | grep -E "(GITHUB|OPENROUTER|MCP)"
```
### **Debug Mode**
```bash
# Enable debug logging
export LOG_LEVEL=debug
# Run with debug output
DEBUG=codecompass:* npm run dev
# Docker debug mode
./scripts/docker-run.sh -e LOG_LEVEL=debug
```
### **Performance Optimization**
```bash
# Optimize for large repositories
export CHUNK_MODE=true
export CHUNK_SIZE=large
export MAX_CONCURRENT_REQUESTS=20
# Reduce response sizes
export MAX_RESPONSE_TOKENS=15000
export MAX_FILE_CONTENT_LENGTH=2000
```
## š **Updates and Maintenance**
### **Updating**
```bash
# Pull latest changes
git pull origin main
# Rebuild and restart
./scripts/docker-build.sh
./scripts/docker-run.sh --remove-existing
```
### **Backup Configuration**
```bash
# Backup environment configuration
cp .env .env.backup
# Export Docker configuration
docker inspect codecompass-mcp > container-config.json
```
### **Monitoring Health**
```bash
# Set up automated health checks
echo "*/5 * * * * curl -f http://localhost:3000/health || echo 'Health check failed'" | crontab -
# Monitor logs for errors
tail -f $(docker inspect codecompass-mcp | jq -r '.[0].LogPath') | grep ERROR
```
## šÆ **Next Steps**
1. **Test the setup** with a small repository
2. **Configure monitoring** for your environment
3. **Integrate with your MCP client** (Claude Desktop, VS Code, etc.)
4. **Customize configuration** for your specific needs
5. **Set up automated backups** for important data
## š **Additional Resources**
- [API Documentation](API.md) - Complete tool reference
- [Docker Guide](DOCKER.md) - Advanced Docker configuration
- [Monitoring Guide](MONITORING.md) - Observability setup
- [Contributing Guide](../CONTRIBUTING.md) - Development guidelines
- [Examples](../examples/) - Usage examples and templates
For support, please check the [Issues](https://github.com/your-org/codecompass-mcp/issues) page or create a new issue with detailed information about your setup and the problem you're experiencing.