CodeCompass: AI-Powered Codebase Navigation
2025.05.07
2
TypeScript代码导航AI 驱动开发者工具开发效率
CodeCompass 是一个基于 TypeScript 的 MCP 服务器，能够将 Git 仓库转化为 AI 驱动的知识库。它使用 Qdrant 进行向量存储，并利用 Ollama 的 nomic-embed-text:v1.5 和 llama3.1:8b 模型进行嵌入和建议生成。CodeCompass 能够索引代码库和文档，为 LLMs（如 Claude 或 Cursor）提供上下文感知的提示。
View on GitHub
Overview
基本能力
产品定位
CodeCompass 是一个 AI 驱动的代码库导航工具，旨在帮助开发者更高效地理解和操作代码库。
核心功能
- 代码库分析：索引 Git 仓库，将代码和文档存储在 Qdrant 中。
- AI 驱动上下文：生成包含代码摘要、文档和元数据的简洁提示。
- 差异跟踪：包含仓库更新时间戳以跟踪变更。
- 开发者工具：提供资源（如
repo://structure,repo://files/*）和工具（如search_code,generate_suggestion,get_repository_context）。 - 完全可配置：通过环境变量或客户端配置自定义 Ollama 和 Qdrant 端点。
- 自动目录检测：无需手动指定，自动使用当前工作目录。
适用场景
- 代码库导航和理解
- 代码搜索和上下文生成
- 开发者工具集成
工具列表
search_code：搜索代码库中的特定内容。generate_suggestion：生成代码建议。get_repository_context：获取代码库的上下文信息。get_changelog：获取变更日志信息。reset_metrics：重置指标。get_session_history：查看会话历史。analyze_code_problem：分析代码问题。
常见问题解答
- 如何配置 Ollama 和 Qdrant 端点？ 通过环境变量或客户端配置进行设置。
- 如何自动检测目录？ 无需手动指定，自动使用当前工作目录。
使用教程
使用依赖
- Node.js (v20+)
- TypeScript (v5+)
- Docker (for Qdrant)
- Ollama (with nomic-embed-text:v1.5 and llama3.1:8b models)
- 本地 Git 仓库
安装教程
选项 1: 克隆并安装
- 克隆仓库:
bash git clone https://github.com/alvinveroy/codecompass.git cd codecompass - 安装依赖:
bash npm install - 构建项目:
bash npm run build
选项 2: 使用 npx 安装并运行
npx @alvinveroy/codecompass
设置指令
启动 Qdrant:
docker run -d -p 127.0.0.1:6333:6333 qdrant/qdrant
启动 Ollama:
- 安装 Ollama (docs).
- 拉取模型:
bash ollama pull nomic-embed-text:v1.5 ollama pull llama3.1:8b - 运行 Ollama:
bash ollama serve
调试方式
构建并运行 MCP 服务器:
npm run build
node dist/index.js
或使用 npx:
npx @alvinveroy/codecompass
检查当前版本:
npx @alvinveroy/codecompass --version
获取完整变更日志:
npx @alvinveroy/codecompass --changelog