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 驅動的代碼洞察，改變你的開發工作流程。