bartolli/codanna

Codanna – 面向 AI 编程代理的本地代码智能服务器

它是什么 – Codanna 是一个基于 Rust 的工具，可在你自己的机器上为代码库构建可搜索的语义索引。然后它通过 MCP（Model-Client-Protocol） 暴露这些知识；这是一种轻量协议，供 Claude Code、Google Gemini、OpenAI Codex、Cursor 和 Windsurf 等 AI 编程助手使用。在一次 MCP 调用中，你可以获取某个符号的定义、文档、调用者和被调用者，以及影响分析（如果该符号变更会造成的“爆炸半径”）。整个过程都在本地运行；除非你明确启用远程嵌入模型，否则不会将任何源代码或查询发送到外部服务。

工作原理

• 索引 – codanna init 会创建 .codanna/ 目录，然后 codanna index <path> 会解析文件（支持 15 种语言），并存储符号、调用图边以及用于语义搜索的嵌入。
• MCP 接口 – 有两种方式与 Codanna 通信：
  1. 常驻服务器（codanna serve / codanna serve --http），在整个开发会话中持续运行。
  2. 一次性 CLI（codanna mcp …），可从 shell 脚本、CI 流水线，或直接由 AI 助手技能调用。
• 主要命令 – codanna mcp semantic_search_with_context 会针对每个匹配项返回符号 ID、签名、docstring、调用者列表、被调用者列表（含精确调用位置），以及递归影响分析。输出可以是纯文本或 JSON（--json）。

主要功能

功能	你能获得什么
语义搜索	对代码和 markdown 文档进行自然语言查询；按意图而非仅按名称查找函数。
关系追踪	调用图、实现和跨模块依赖，支持“这个函数在哪里被调用？”和“如果我改它会影响什么？”等查询。
文档 RAG	索引项目文档（markdown、文本），让 AI 代理能连同代码一起检索相关文档。
MCP 协议	可直接兼容 Claude、Gemini、Codex、Cursor、Windsurf，或任何能调用外部命令的客户端。
配置 / 技能	针对不同项目类型预打包的命令集；可通过插件市场加入 Claude Code。
本地优先	所有索引和嵌入都在设备端进行；可选的远程 OpenAI 兼容嵌入仅限主动启用。
性能	解析速度最高约每秒 250k 个符号；热查询低于 10 ms；索引构建后语义查询只需几毫秒。

典型工作流

# 安装（macOS/Linux/WSL）– 一行命令或 Homebrew/Nix/PowerShell
curl -fsSL https://install.codanna.sh | sh

# 初始化工作区
codanna init
codanna index src            # 为你的源代码树构建索引

# 向 AI 助手（或 CLI）询问上下文
codanna mcp semantic_search_with_context query:"extract function calls" limit:1

# 为 RAG 添加项目文档
codanna documents add-collection docs ./docs
codanna documents index
codanna mcp search_documents query:"authentication flow"

CLI 输出包含 file:line 位置、符号 ID，以及一段简短指引提示，让代理能串联后续查询。

集成 – 在项目根目录添加 .mcp.json 文件，让 Claude Code、Cursor 或其他兼容 MCP 的工具自动启动 Codanna：

{ "mcpServers": { "codanna": { "command": "codanna", "args": ["--config", ".codanna/settings.toml", "serve", "--watch"] } } }

传输方式可以是 stdio、HTTP 或 HTTPS。

安装选项

• 一行脚本（curl … | sh）
• Homebrew（brew install codanna）
• Nix（nix run github:bartolli/codanna）
• Windows 的 PowerShell 脚本（实验性支持）
• 使用 Rust 1.85+ 从源码构建，并执行 cargo install codanna

系统要求

• 默认 ONNX 嵌入模型约需下载 150 MiB。
• macOS：仅支持 Apple Silicon（当前 ONNX Runtime 构建不支持 Intel）。
• Linux：glibc 2.38+ 和 GCC 13+ 运行时库（预构建二进制以 Ubuntu 24.04 为目标）。
• Windows：实验性。

许可证 – Apache 2.0（需保留署名）。欢迎通过常规 GitHub 流程贡献。

---

总结 – Codanna 为 AI 编程助手提供快速、本地且结构丰富的代码库视图，将常见的“先 grep 再读”循环，转变为单个、具备上下文感知的 MCP 请求。对于需要回答“这个函数在哪里被使用？”、“如果我修改 X 会影响什么？”或“找到认证逻辑”等问题，且不想将任何专有代码发送到云端的代理特别有用。