代码指南针-mcp

Name: 代码指南针-mcp
Author: TheAlchemist6

作者：TheAlchemist62 星标更新：2025-07-18

安装使用来源：spider==github.com

项目介绍

CodeCompass MCP

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

连接您的开发工具到全面的GitHub仓库分析，包括11个精简工具、增强的错误处理、实时监控和生产就绪部署。

✨ 特性

🔍 全面的仓库分析 - 对代码结构、依赖关系和架构的深入洞察
🤖 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
# 使用您的真实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 Token: github.com/settings/tokens → 生成新的令牌（经典）→ 选择repo范围
OpenRouter Key: openrouter.ai/keys → 创建新的API密钥

3. 构建并运行

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

预期输出：

✅ 构建成功
镜像信息：
REPOSITORY        TAG       IMAGE ID       CREATED         SIZE
codecompass-mcp   latest    a1b2c3d4e5f6   2秒前           278MB

🚀 启动CodeCompass MCP服务器...
✅ 服务器启动成功
健康检查：健康
API限制：每小时剩余5000次

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

🔧 配置

必需的环境变量

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('健康检查')"]
      interval: 30s
      timeout: 10s
      retries: 3

MCP客户端集成

Claude Desktop配置

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

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 Desktop，您将在UI中看到CodeCompass工具。

Claude Code CLI集成

# 将MCP服务器添加到Claude Code
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服务器: 处理11个精简工具的JSON-RPC协议
服务层: GitHub API、OpenRouter集成和业务逻辑
配置: 中央化、类型安全配置，带有Zod验证
监控: 实时性能追踪和健康监控
安全性: 输入验证、防止路径遍历和安全处理

🔒 安全特性

输入验证

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

容器安全

非root执行: 所有容器以无特权用户运行
只读文件系统: 安全导向的容器配置
资源限制: 内存和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驱动的代码洞察，转变您的开发工作流程。