AI导哈

代码探索协议服务器

Cerberus MCP是一个基于AST的智能代码探索协议服务器，提供语义搜索、持久化内存管理和高效令牌使用功能，适用于大型代码库和AI代理工作流。

  • by proxikal
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 proxikal/cerberus-mcp

使用说明

Cerberus MCP

模型上下文协议服务器，用于基于AST的导航和持久会话内存的智能代码探索。

⚠️ 重要通知

Cerberus正处于早期开发阶段，并处于高度实验阶段。 虽然功能齐全，但边缘粗糙：

  • 大型项目绩效： 索引时间随代码库大小呈线性变化（启用语义搜索的6200个文件约为8分钟，未嵌入约为45秒）
  • 内存使用情况： 语义搜索模型需要~400MB RAM（捆绑全MiniLM-L6-v2）
  • 重大变更： 随着我们完善功能，API和工具签名可能会发生变化
  • 有限测试： 并非所有边缘案例都涵盖在内；复杂场景中预期的错误
  • 资源密集型： FAISS+嵌入生成可以加热大型代码库上的笔记本电脑

使用风险自负。不建议用于生产工作流程。

⚡ 核心功能

特性 描述 实际性能
🔍 基于AST的搜索 通过抽象语法树+语义搜索（默认情况下与捆绑模型一起启用）导航代码。语义：相似性得分为0.3-0.5。如果嵌入不可用，则关键字回退。
🧠 持久内存 双层系统：全局偏好（无处不在）和项目决策（特定于上下文）。 SQLite支持的FTS5搜索，每次内存上下文加载约50-200个令牌。
📉 代币效率 骨架化剥离了实现，上下文汇编只获取所需的代码。 衡量：节省60-75% 与读取完整文件相比（不是90%，这被夸大了）。

📊 真实世界基准

在Cerberus上进行了测试 （6206个文件，93643个符号）：

操作 时间 令牌 注释
索引构建（带嵌入） 约8.3分钟 不适用 失败+全MiniLM-L6-v2代
索引构建（无嵌入） 约45秒 不适用 仅限SQLite，关键字搜索回退
语义搜索（5个结果） <1s ~450个标记 包括相似性得分
获取符号（仅限代码） <0.5秒 约1300个令牌 与完整文件读取相比为75%（约5355个令牌）
上下文（含deps） <1s ~2000-4000个令牌 取决于符号复杂度

令牌效率现实检查：

  • 索赔： “节省90%”
  • 现实： 节省60-75% 在典型的工作流程中（仍然很重要！）
  • 为什么少？ 很少需要读取完整文件；比较不是苹果对苹果

🛠️ 技术栈

🚀 快速开始

先决条件： Python 3.10+，~1GB磁盘空间用于索引，500MB RAM用于语义搜索

1.安装MCP服务器

pip install git+https://github.com/proxikal/cerberus-mcp.git

2.配置您的AI代理

添加到您的MCP配置中（例如。， claude_desktop_config.json):

{
  "mcpServers": {
    "cerberus": {
      "command": "cerberus-mcp"
    }
  }
}

3.安装代理技能（推荐）

# Deploys specialized prompts that help agents use Cerberus effectively
mkdir -p ~/.claude/skills/Cerberus
cp -r skill/Cerberus/* ~/.claude/skills/Cerberus/

4.首轮

# In your AI agent (e.g., Claude Code):
# The agent will automatically call index_build on first use
# Expect 1-10 minutes depending on codebase size

🤖 可选：本地LLM摘要

Cerberus支持 零令牌文件摘要 通过以下方式使用本地LLM llm工具链.

安装

# Install llm-toolchain (optional)
pip install llm-toolchain

# Requires Ollama running locally
# Download from: https://ollama.ai

配置

添加到您的 cerberus.toml:

[summarization]
enabled = true
model = "qwen3:8b"  # Best for tool calling (or any Ollama model)
ollama_url = "http://localhost:11434"

它是如何工作的：

  • 如果 llm-toolchain 安装→ 使用零令牌文件操作
  • 如果未安装→ 回退到直接文件读取（标准行为）
  • 如果Ollama不在→ 已优雅地禁用摘要

📚 文档门户

我们在我们的 维基.

第节 内容
🚀 入门指南 安装、配置和第一步。
🛠️ MCP工具 所有56个工具（搜索、分析、内存）的参考。
🧠 存储器系统 双层偏好和决策引擎是如何工作的。
⚡ 效率 真实世界代币储蓄明细。

🌐 语言支持

Cerberus支持多种编程语言 具有不同的功能覆盖范围：

✅ 通用功能 （所有语言）

这些工具适用于Python、TypeScript、JavaScript、Go和其他语言：

  • 核心导航： search, get_symbol, context, blueprint, read_range, file_info, skeletonize
  • 依赖性分析： deps, call_graph, analyze_impact, test_coverage
  • 项目工具： project_summary, smart_update, index_build
  • 存储系统： 所有记忆工具(memory_learn, memory_search, memory_context等等）

🔄 多语言支持

  • find_circular_deps：Python、TypeScript、JavaScript（检测导入周期）

🔄 增强的多语言功能

  • check_pattern：Python+TypeScript/JavaScript模式（Python更成熟）
  • style_check：Python优化（基本TS/JS支持）
  • related_changes：完全支持TypeScript/JavaScript类型

📝 备注

  • 分析器： 使用树形图进行多语言AST解析
  • 语义搜索： 语言无关（适用于所有索引代码）
  • 导入分辨率： 支持Python导入、ES6模块、CommonJS

🎯 何时使用Cerberus

合身：

  • 手动导航速度较慢的大型代码库（>1000个文件）
  • 具有复杂依赖关系图的项目
  • 需要坚持上下文的多会话工作
  • 具有严格代币预算的AI代理工作流程

不适合：

  • 小项目（<100个文件）-设置开销不值得
  • 首次探索-初始索引需要时间
  • 对不熟悉的代码索引进行只读分析可能没有多大帮助
  • 文件结构快速变化的项目-频繁重新索引

🤝 贡献

欢迎投稿！看 问题 对于当前的优先事项。

已知问题：

  • 语义搜索索引在大型代码库上运行缓慢（正在处理）
  • 内存系统需要更好的冲突解决方案
  • 对于较新的语言特性，一些树型解析器是不完整的

开发设置：

git clone https://github.com/proxikal/cerberus-mcp.git
cd cerberus-mcp
pip install -e ".[dev]"
pytest tests/ -v

📜 许可证

该项目根据 MIT许可证.

专为AI代理构建。针对效率进行了优化。天生具有实验性。

相关 MCP