Codecompass MCP

🚀 CodeCompass MCP

CodeCompass MCP 是一款企业级的模型上下文协议（MCP）服务器，可用于智能仓库分析和由 AI 驱动的开发辅助。它能将你的开发工具与全面的 GitHub 仓库分析相连接，提供 11 个简化工具、增强的错误处理、实时监控以及可用于生产环境的部署方案。

🚀 快速开始

逐步进行 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
# 使用你真实的 API 密钥编辑 .env 文件
nano .env  # 或者使用你喜欢的编辑器

.env 文件中必需的配置：

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

🔑 获取 API 密钥的位置：

• GitHub 令牌：github.com/settings/tokens → 生成新的经典令牌 → 选择 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. 测试安装

# 使用健康检查进行测试
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+，支持 Intel 和 Apple Silicon）
• ✅ Windows（10/11 搭配 Docker Desktop）

其他安装方法

本地开发

# 安装依赖
npm install

# 设置环境变量
export GITHUB_TOKEN=your_github_token
export OPENROUTER_API_KEY=your_openrouter_key

# 构建并运行
npm run build && npm run dev

全局安装

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

✨ 主要特性

• 🔍 全面的仓库分析 - 深入洞察代码结构、依赖关系和架构
• 🤖 AI 驱动的代码审查 - 通过集成 OpenRouter（支持 400 多个模型）进行智能代码分析
• 🚀 可用于生产环境的部署 - 使用遵循安全最佳实践的 Docker 容器
• 📊 实时监控 - 提供性能指标、健康检查和可观测性
• 🛡️ 企业级安全 - 输入验证、防止路径遍历和安全处理
• ⚡ 高性能 - 智能分块、并发处理和响应优化
• 🔧 良好的开发者体验 - 提供全面的文档、示例和调试工具

🔧 配置

必需的环境变量

GITHUB_TOKEN=ghp_your_github_token_here        # 用于访问 GitHub API
OPENROUTER_API_KEY=sk-or-v1-your_key_here     # 用于访问 OpenRouter API

可选配置

AI_MODEL=anthropic/claude-3.5-sonnet          # 默认的 AI 模型
MAX_RESPONSE_TOKENS=25000                      # 响应大小限制
LOG_LEVEL=info                                 # 日志级别
NODE_ENV=production                            # 环境模式

🛠️ 可用工具

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

• get_repository_info - 获取仓库元数据、统计信息和关键信息
• get_file_tree - 获取完整的目录结构和文件列表，并支持过滤
• search_repository - 使用正则表达式模式和过滤进行高级搜索
• get_file_content - 批量处理文件，包含安全验证和元数据
• analyze_dependencies - 分析依赖关系图并检测漏洞
• analyze_codebase - 全面分析代码结构、架构和指标

AI 增强工具（3 个工具）

• review_code - AI 驱动的代码审查，提供安全、性能和可维护性方面的洞察
• explain_code - 用自然语言解释代码并生成文档
• suggest_improvements - 提供智能重构建议和现代化策略

转换工具（1 个工具）

• transform_code - 提供代码转换、现代化和迁移辅助

实用工具（1 个工具）

• health_check - 监控系统健康状况和性能指标

🐳 Docker 集成

生产环境部署

# 构建生产环境镜像
./scripts/docker-build.sh

# 使用环境文件运行
./scripts/docker-run.sh --env-file .env

# 查看日志
./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 桌面端配置文件中添加以下内容：

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

然后重启 Claude 桌面端，你将在 UI 中看到 CodeCompass 工具。

Claude 代码 CLI 集成

# 将 MCP 服务器添加到 Claude 代码中
claude mcp add codecompass-docker -s user -- \
  docker exec -i codecompass-mcp node build/index.js

其他 MCP 客户端

• Cline（VS Code）：添加到 MCP 配置中
• Continue（VS Code/JetBrains）：配置为 MCP 提供者
• 自定义客户端：使用 stdio 传输方式，调用 node build/index.js

测试集成

# 测试连接
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | docker exec -i codecompass-mcp node build/index.js

# 应该返回 11 个工具的列表

📊 监控与可观测性

实时仪表盘

# 交互式监控仪表盘
./scripts/monitor.js --watch

# 导出指标
./scripts/monitor.js --export > metrics.json

# 健康检查
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 客户端 → MCP 服务器 → 服务层 → 外部 API
            ↓
         监控与日志记录

关键组件

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

🔒 安全特性

输入验证

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

容器安全

• 非根用户执行：所有容器以非特权用户身份运行
• 只读文件系统：采用注重安全的容器配置
• 资源限制：设置内存和 CPU 约束以确保稳定性
• 健康检查：自动进行健康监控和恢复

🎯 性能优化

智能响应管理

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

资源管理

• 内存效率：优化内存使用并自动清理
• 请求跟踪：使用关联 ID 进行分布式跟踪
• 性能洞察：自动进行性能分析并提供建议
• 可扩展性：使用 Docker 容器支持水平扩展

📚 详细文档

完整的文档套件

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

示例和模板

• 使用示例 - 实际使用模式和模板
• 集成示例 - MCP 客户端集成示例
• 配置模板 - 可用于生产环境的配置示例

🤝 贡献

我们欢迎贡献！请查看我们的 贡献指南，了解以下详细信息：

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

开发设置

# 克隆并设置项目
git clone https://github.com/your-org/codecompass-mcp.git
cd codecompass-mcp

# 安装依赖
npm install

# 运行测试
npm test

# 启动开发服务器
npm run dev:watch

🔄 路线图

当前版本（1.0.0）

• ✅ 11 个简化的原子工具，职责明确
• ✅ 可用于生产环境的 Docker 部署
• ✅ 实时监控和可观测性
• ✅ 企业级安全特性
• ✅ 完整的文档套件

未来增强功能

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

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• OpenRouter MCP - 提供架构模式和最佳实践灵感
• MCP 协议 - 作为工具集成和通信的基础
• Anthropic - 支持 Claude AI 集成和开发
• GitHub - 用于仓库分析和 API 集成
• Docker - 提供容器化和部署基础设施

🆘 支持

获取帮助

• 文档：查看 docs/ 目录下的全面文档
• 问题反馈：在 GitHub Issues 上报告错误和请求功能
• 讨论：加入 GitHub Discussions 参与社区讨论

常见问题

• API 密钥设置：参阅 设置指南
• Docker 问题：查看 Docker 指南
• 性能问题：参考 监控指南

🚀 构建工具

• TypeScript - 类型安全的 JavaScript 开发
• Node.js - JavaScript 运行时环境
• Docker - 容器化平台
• Zod - 基于 TypeScript 的模式验证
• MCP SDK - 模型上下文协议实现

由 Myron Labs 用心打造 💜

借助智能仓库分析和 AI 驱动的代码洞察，改变你的开发工作流程。