关键词

AI代码助手代码仓库导航代码上下文代码搜索智能问题分析

项目简介

CodeCompass 是一个基于 Model Context Protocol (MCP) 构建的应用后端（MCP 服务器），旨在将您的本地 Git 代码仓库转化为AI助手可深度理解的知识库。它连接像 Claude、Cursor 等兼容 MCP 的 AI 客户端到您的代码，通过提供精确的代码上下文信息，极大地增强AI在代码调试、功能实现和代码探索方面的能力。CodeCompass 既可以配合本地运行的 Ollama 模型保护隐私，也可以配置使用 OpenAI 等云端模型以获得更强性能。

主要功能点

CodeCompass 作为 MCP 服务器，通过以下核心功能为 AI 助手提供服务：

  • 代码搜索 ('search_code'): 基于自然语言查询在仓库中进行语义搜索，返回相关的代码片段及其所在文件和摘要。
  • 仓库上下文 ('get_repository_context'): 根据查询提供仓库的高层级上下文信息，包括相关文件列表、近期代码变动等。
  • 代码建议 ('generate_suggestion')：根据您的问题和仓库上下文，生成详细的代码实现建议或改进方案。（需要配置并成功加载 LLM 模型）
  • 智能问题分析 ('analyze_code_problem'): 引导AI对代码问题进行多步分析，包括识别根本原因和制定实施计划。（需要配置并成功加载 LLM 模型）
  • AI 代理查询 ('agent_query'): 启动一个智能代理，它能够根据您的复杂查询，自主决定并调用 CodeCompass 内部的其他工具来收集信息并提供综合性答案。
  • 获取 Changelog ('get_changelog'): 读取仓库的 CHANGELOG.md 文件，帮助AI和您了解项目的近期版本更新。
  • 获取仓库结构 ('repo://structure'): 返回仓库中的文件列表。
  • 访问文件内容 ('repo://files/*'): 允许AI按需读取指定文件的内容。
  • 会话历史 ('get_session_history'): 查看与 CodeCompass 交互的查询和建议历史记录。
  • 提供反馈 ('provide_feedback'): 允许用户对AI生成的建议提供评分和评论，用于未来的模型优化。（需要配置并成功加载 LLM 模型）
  • 获取服务器状态 ('repo://health'): 检查 CodeCompass 服务的健康状况。
  • 获取性能指标 ('repo://metrics'): 查看 CodeCompass 的运行性能数据。
  • 获取版本信息 ('repo://version'): 获取 CodeCompass 的当前版本号。

安装步骤

  1. 安装前置条件:

    • Node.js (v20+)。
    • TypeScript (v5+)。
    • Docker（用于运行 Qdrant 向量数据库）。
    • 根据您选择的AI提供商：
      • 本地 Ollama: 安装 Ollama 并拉取所需的模型 ('nomic-embed-text:v1.5', 'llama3.1:8b' 或更高版本推荐）。
      • 云端 OpenAI: 获取 OpenAI API Key。
    • 一个本地 Git 仓库。

  2. 启动 Qdrant 数据库:

    docker run -d -p 127.0.0.1:6333:6333 qdrant/qdrant

  3. 设置 AI 模型:

    • 本地 Ollama: 启动 Ollama 服务 ('ollama serve') 并确保已拉取必要的模型 ('ollama pull nomic-embed-text:v1.5', 'ollama pull llama3.1:8b')。
    • 云端 OpenAI: 准备好您的 OpenAI API Key。

  4. 安装 CodeCompass: 您可以通过以下两种方式安装：

    • 克隆并安装: 
      git clone https://github.com/alvinveroy/CodeCompass.git
cd CodeCompass
npm install
npm run build
    • 使用 npx (推荐): 无需全局安装，直接运行 CodeCompass 命令即可： 
      npx @alvinveroy/codecompass@latest [您的代码仓库路径，默认为当前目录]

服务器配置

MCP 客户端（如 VSCode 扩展、AI 助手应用）需要通过配置来启动并连接到 CodeCompass 服务器。典型的 MCP 客户端配置通常是一个 JSON 对象，包含启动服务器所需的命令和参数。CodeCompass 通过命令行参数指定仓库路径，并通过环境变量进行其他配置。

以下是配置 MCP 客户端时可能用到的 CodeCompass 启动信息和相关环境变量说明：

  • MCP 客户端配置示例（JSON 格式，用于客户端启动服务器）:

    {
  "server name": "CodeCompass",
  "command": "npx",
  "args": ["@alvinveroy/codecompass@latest", "."] // 第二个参数 "." 表示当前目录，可以替换为您的代码仓库绝对或相对路径
  // 其他可能的客户端配置项...
}

    请注意：MCP 客户端的具体配置方式取决于您使用的客户端软件。上述JSON是客户端内部配置服务器启动命令的一种常见形式。

  • CodeCompass 服务器运行时环境变量 (需要在启动 CodeCompass 的环境中设置):

    • 'LLM_PROVIDER': 指定使用的 AI 提供商，可选值为 'ollama' 或 'openai' (默认: 'ollama')。
    • 'OLLAMA_HOST': Ollama 服务地址 (仅当 'LLM_PROVIDER=ollama' 时需要) (默认: 'http://localhost:11434')。
    • 'OPENAI_API_KEY': OpenAI API 密钥 (仅当 'LLM_PROVIDER=openai' 时需要)。
    • 'QDRANT_HOST': Qdrant 服务地址 (默认: 'http://localhost:6333')。
    • 'EMBEDDING_MODEL': Ollama 嵌入模型名称 (默认: 'nomic-embed-text:v1.5')。
    • 'SUGGESTION_MODEL': Ollama 推理模型名称 (默认: 'llama3.1:8b')。
    • 'OPENAI_EMBEDDING_MODEL': OpenAI 嵌入模型名称 (默认: 'text-embedding-ada-002')。
    • 'OPENAI_SUGGESTION_MODEL': OpenAI 推理模型名称 (默认: 'gpt-4o')。
    • 'MCP_PORT': MCP 服务器监听端口 (默认: '3000')。
    • 'LOG_LEVEL': 日志级别 (默认: 'info')。

    您可以通过 '.env' 文件或直接在启动 CodeCompass 的 shell 环境中设置这些变量。

基本使用方法

  1. 确保 Qdrant 和您选择的 AI 模型服务正在运行。
  2. 通过您的 MCP 客户端（AI 助手应用或 IDE 扩展）启动并连接到 CodeCompass 服务器。 客户端将使用您配置的命令（例如 'npx @alvinveroy/codecompass@latest /path/to/your/repo'）来启动服务器进程。请在启动命令或环境变量中指定您要CodeCompass服务的代码仓库路径。
  3. 在 AI 助手中提出与代码相关的问题或指令。 例如：
    • "search for the user authentication logic" (搜索用户认证逻辑)
    • "explain how error handling works in the API" (解释API中的错误处理机制)
    • "suggest how to implement OAuth login" (建议如何实现 OAuth 登录)
    • "analyze the bug in this file" (分析这个文件中的bug)
  4. AI 助手会通过 MCP 协议调用 CodeCompass 的相应工具和资源。 CodeCompass 会处理请求，查询代码仓库，与 AI 模型交互（如果需要），并将结果返回给 AI 助手。
  5. AI 助手根据 CodeCompass 提供的信息生成更准确、上下文更相关的回答。

通过这种方式，CodeCompass 将您的本地代码仓库无缝地集成到您的AI开发工作流中。

信息

分类

开发者工具

访问项目