星战科技xingzhan.cloud
返回市场
代码指南针-mcp

代码指南针-mcp

作者：TheAlchemist62 星标更新：2025-07-18
安装使用来源：spider==github.com

项目介绍

CodeCompass MCP

License: MIT Node.js Version Docker TypeScript

企业级模型上下文协议（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密钥的位置：

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容器准备水平扩展

📚 文档

完整的文档套件

示例和模板

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南了解详情：

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

开发设置

# 克隆并设置
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

常见问题

🚀 构建于

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

由Myron Labs精心打造

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