CodeCompass MCP

CodeCompass MCP

企业级模型上下文协议（MCP）服务器，用于智能存储库分析和人工智能驱动的开发辅助。

通过11个简化的工具、增强的错误处理、实时监控和生产就绪部署，将您的开发工具连接到全面的GitHub存储库分析。

✨ 特性

• 🔍 全面的存储库分析 -深入了解代码结构、依赖关系和架构
• 🤖 AI驱动的代码审查 -集成OpenRouter的智能代码分析（400多种型号）
• 🚀 生产就绪部署 -具有安全最佳实践的Docker容器
• 📊 实时监控 -性能指标、健康检查和可观察性
• 🛡️ 企业安全 -输入验证、路径遍历预防和安全处理
• ⚡ 高性能 -智能分块、并发处理和响应优化
• 🔧 开发者体验 -全面的文档、示例和调试工具

🚀 快速开始

分步Docker设置（推荐）

1. 克隆和导航

git clone https://github.com/TheAlchemist6/codecompass-mcp.git
cd codecompass-mcp

预期产量：

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. 配置环境

cp .env.example .env
# Edit .env with your real API keys
nano .env  # or use your preferred editor

必填项 .env 文件：

GITHUB_TOKEN=ghp_your_actual_github_token_here
OPENROUTER_API_KEY=sk-or-v1-your_actual_openrouter_key_here

🔑 获取API密钥的位置：

• GitHub代币: → 生成新令牌（经典）→ 选择 repo 范围
• OpenRouter密钥: openrouter.ai/keys → 创建新的API密钥

3. 构建并运行

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

预期产量：

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

平台支持

• ✅ Linux （Ubuntu 18.04+， CentOS 7+）
• ✅ macOS （10.14+，英特尔和苹果硅）
• ✅ 视窗 （10/11使用Docker桌面）

替代安装方法

地方发展

# 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

全球安装

npm install -g codecompass-mcp
codecompass-mcp --help

🔧 配置

所需的环境变量

GITHUB_TOKEN=ghp_your_github_token_here        # GitHub API access
OPENROUTER_API_KEY=sk-or-v1-your_key_here     # OpenRouter API access

可选配置

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

🛠️ 可用工具

核心数据工具（6个工具）

• get_repository_info -存储库元数据、统计数据和关键信息
• get_file_tree -具有过滤功能的完整目录结构和文件列表
• search_repository -使用正则表达式模式和过滤进行高级搜索
• get_file_content -具有安全验证和元数据的批处理文件
• analyze_dependencies -依赖图分析和漏洞检测
• analyze_codebase -全面的结构、架构和指标分析

AI增强工具（3个工具）

• review_code -基于人工智能的代码审查，具有安全性、性能和可维护性方面的见解
• explain_code -自然语言代码解释和文档生成
• suggest_improvements -智能重构建议和现代化策略

转换工具（1个工具）

• transform_code -代码转换、现代化和迁移援助

实用工具（1个工具）

• health_check -系统健康监测和性能指标

🐳 Docker集成

生产部署

# 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客户端集成

Claude桌面配置

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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"
      }
    }
  }
}

然后重新启动克劳德桌面 您将在UI中看到CodeCompass工具。

Claude代码CLI集成

# Add MCP server to Claude Code
claude mcp add codecompass-docker -s user -- \
  docker exec -i codecompass-mcp node build/index.js

其他MCP客户端

• 克莱恩 （VS代码）：添加到MCP配置
• 继续 （VS Code/JetBrains）：配置为MCP提供者
• 定制客户：使用 stdio 运输与 node build/index.js

测试集成

# 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

📊 监测和可观察性

实时仪表盘

# Interactive monitoring dashboard
./scripts/monitor.js --watch

# Export metrics
./scripts/monitor.js --export > metrics.json

# Health check
curl -X POST http://localhost:3000/health

性能指标

• 响应时间：健康检查\<100ms，存储库分析2-10s
• 内存使用：50-200MB，具体取决于存储库大小
• 并发处理：具有自动缩放功能的可配置限制
• 错误跟踪：通过上下文建议进行全面的错误监控

健康监测

{
  "name": "health_check",
  "arguments": {
    "checks": ["api-limits", "monitoring", "configuration"],
    "options": {
      "include_metrics": true,
      "include_insights": true
    }
  }
}

🔍 使用示例

存储库分析

{
  "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代码审查

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

批处理文件

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

🏗️ 建筑

面向服务的设计

MCP Client → MCP Server → Service Layer → External APIs
            ↓
         Monitoring & Logging

关键组件

• MCP服务器：使用11个简化工具处理JSON-RPC协议
• 服务层：GitHub API、OpenRouter集成、业务逻辑
• 配置：具有Zod验证的集中式、类型安全配置
• 监控：实时性能跟踪和健康监测
• 安全：输入验证、路径遍历预防和安全处理

🔒 安全功能

输入验证

• Zod模式验证：所有工具的类型安全输入验证
• 路径穿越预防：全面的文件路径安全检查
• 速率限制：可配置的请求速率限制和节流
• API密钥管理：安全的环境变量处理

集装箱安全

• 非根执行：所有容器都以无特权用户身份运行
• 只读文件系统：以安全为重点的容器配置
• 资源限制：内存和CPU的稳定性限制
• 健康检查：自动健康监测和恢复

🎯 性能优化

智能响应管理

• 组块：大型响应分为可管理的块
• 截断：智能截断保留数据结构
• 并发处理：具有可配置限制的并行文件处理
• 缓存：针对频繁访问数据的智能缓存策略

资源管理

• 内存效率：通过自动清理优化内存使用
• 请求跟踪：分布式跟踪的相关ID
• 性能洞察：自动性能分析和建议
• 可扩展性：Docker容器支持水平扩展

📚 文档

完整的文档套件

• 安装指南 -安装和配置说明
• api参考 -完整的工具文档和示例
• **** -容器部署和管理
• 监控指南 -可观察性和性能监控
• 架构指南 -技术架构和模式

示例和模板

• 使用示例 -真实世界的使用模式和模板
• 集成示例 -MCP客户端集成示例
• 配置模板 -生产就绪配置示例

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 开发设置和工作流程
• 代码风格和测试要求
• 拉取请求流程和指南
• Bug报告和功能请求

开发设置

# 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

🔄 路线图

当前版本（1.0.0）

• ✅ 11个精简的原子工具，责任明确
• ✅ 生产就绪的Docker部署
• ✅ 实时监控和可观察性
• ✅ 企业安全功能
• ✅ 完整的文档套件

未来的增强功能

• 🔮 会话上下文管理 -会话状态和会话历史记录
• 🔮 高级缓存 -基于Redis的智能失效缓存
• 🔮 插件系统 -自定义工具的可扩展架构
• 🔮 多语言支持 -超越Types/JavaScript的扩展语言支持
• 🔮 Kubernetes集成 -使用Helm charts进行原生Kubernetes部署

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• OpenRouter MCP -架构模式和最佳实践灵感
• MCP协议 -工具集成和通信基础
• Anthropic -Claude AI集成和开发支持
• GitHub -存储库分析和API集成
• 码头工人 -集装箱化和部署基础设施

🆘 支持

获取帮助

• 文档：请查看我们的综合文档 docs/ 目录
• 问题：报告错误并请求功能
• 讨论：加入社区讨论

常见问题

• API密钥设置：参见 安装指南
• Docker问题：检查
• 演出：评论 监控指南

🚀 构建于

• TypeScript -类型安全的JavaScript开发
• **** -JavaScript运行时环境
• 码头工人 -集装箱化平台
• 萨德 -TypeScript第一模式验证
• MCP-SDK -模型上下文协议实现

______________________________________________________________________

由以下材料制成💜 Myron Labs

*通过智能存储库分析和AI驱动的代码洞察，改变您的开发工作流程。*