chadbohannan/py-mcp-code-rag

# 代码检索 针对本地代码库的语义代码搜索，提供 REST API 和 [模型上下文协议](https://modelcontextprotocol.io/) 服务器。专为导航复杂、庞大的代码库而设计——挖掘架构意图而非匹配表面文本。 ## 工作原理 原始源代码难以与自然语言查询形成良好嵌入。开发者询问"认证如何工作？"与实现认证的代码在嵌入空间中几乎没有重叠。 **代码检索**使用语义代理索引：文件被解析为具有语言感知的单元（函数、类、方法、SQL、Markdown章节），每个单元由 Claude 进行摘要，然后嵌入的是*摘要*而非原始源码。原始源码会随匹配结果一同存储并返回。 ``` source file → semantic parser → semantic units │ semantic summary (file path + unit type as context) │ fastembed → vector index raw source stored alongside, returned on match ``` 这意味着像"令牌过期如何工作？"这样的查询会匹配到一个摘要，例如*"验证 JWT 并根据可配置容差检查时钟偏移"*——这是原始源码嵌入无法做到的。 ## 环境要求 - Python >= 3.12 - [uv](https://github.com/astral-sh/uv) 包管理器 - 安装了 gemma4:e2b 的 [Ollama](https://ollama.com/) ## 快速开始 ``` # 安装 dependencies make install # 索引 codebase make index SRC=../my-project DB=./index.db # 启动 REST API + web UI（主要界面） make webui DB=./index.db # 在另一个终端中，启动 MCP server 并指向 web UI make mcp ``` ## 安装说明 ``` git clone cd py-mcp-code-rag make install ``` ## 使用说明 ### 命令行界面 ``` code-rag index [paths...] [options] Build or update the index code-rag webui [options] Start the REST API + web UI code-rag-cli.py SUBCOMMAND [args] Stdlib CLI client to a running web UI code-rag-mcp.py [options] MCP server proxying tools to the web UI ``` ### 索引 索引一个或多个目录。默认增量处理——仅重新处理已更改的文件。 ``` # 索引当前目录 code-rag index . # 将 specific directories 索引到单个 DB code-rag index /path/to/backend /path/to/frontend # 使用自定义 database path code-rag index --db myproject.db ../my-project # 更改 embed model 后重建 embeddings（保留 summaries） code-rag index --reindex . # 使用 Ollama 进行摘要，而不是 Anthropic API code-rag index --summarizer ollama --ollama-model gemma3 . ``` **索引选项：** | 标志 | 默认值 | 描述 | |---|---|---| | `--reindex` | 关闭 | 重建向量表；保留未更改单元的摘要 | | `--embed-model MODEL` | `nomic-ai/nomic-embed-text-v1.5-Q` | 嵌入模型 (fastembed) | | `--db PATH` | `./index.db` | 索引文件位置 | | `--summarizer {anthropic,ollama}` | `ollama` | 摘要后端 | | `--ollama-model MODEL` | — | Ollama 模型名称 | | `--ollama-host HOST` | — | Ollama API 主机 | ### Web 用户界面（REST API） 主要界面。提供 REST API（文档见 `SKILL.md`）和浏览器用户界面。 ``` code-rag webui --db index.db --port 8081 ``` **Web UI 选项：** | 标志 | 默认值 | 描述 | |---|---|---| | `--db PATH` | `./index.db` | 索引文件位置 | | `--host HOST` | `0.0.0.0` | 绑定地址 | | `--port N` | `8080` | 监听端口 | | `--embed-model MODEL` | （来自数据库） | 覆盖嵌入模型 | | `--summarizer {anthropic,ollama}` | `ollama` | 用于通过 Web UI 触发的重新索引作业的摘要后端 | ### MCP 服务器 一个独立脚本，通过 REST 将 MCP 工具调用代理到正在运行的 Web UI。默认使用标准输入/输出；传入 `--http` 以使用流式 HTTP 传输。 ``` # Stdio MCP server（默认 — 用于直接 agent stdin/stdout 集成） python code-rag-mcp.py --base-url http://localhost:8081 # 或通过 env var CODE_RAG_URL=http://localhost:8081 python code-rag-mcp.py ``` **MCP 服务器选项：** | 标志 | 默认值 | 描述 | |---|---|---| | `--base-url URL` | `http://localhost:8081` | 要通信的 Web UI（环境变量：`CODE_RAG_URL`） | | `--http` | 关闭 | 以流式 HTTP MCP 服务器模式在 `127.0.0.1` 上运行 | | `--port N` | `8000` | `--http` 模式的端口 | ### 独立命令行客户端 用于 shell 脚本和人工使用，`code-rag-cli.py` 将 REST API 封装为纯文本输出： ``` python code-rag-cli.py search "how does authentication work?" python code-rag-cli.py --json repos | jq '.[].name' python code-rag-cli.py index /path/to/repo --wait ``` 子命令：`search`、`unit`、`fetch`、`units`、`files`、`repos`、`status`、`browse`、`index`、`index-status`、`index-cancel`、`clear-repo`、`staleness`、`ls`。顶层的 `--json` 标志可输出任何子命令的原始 JSON。 ### 代理集成 将 `code-rag-mcp.py` 注册到你选择的代理。两个命令都接受 `BASE_URL=` 以指向非默认的 Web UI。 | 代理 | 注册 | 注销 | |---|---|---| | Claude Code | `make add-claude-mcp` | `make remove-claude-mcp` | | pi-agent | `make add-pi-mcp` | `make remove-pi-mcp` | Web UI 必须正在运行 MCP 服务器才能工作——先在拥有索引的主机上启动一次，然后将代理指向它。 #### 系统提示 为获得最佳效果，请在你代理的系统提示或人格配置中包含以下内容： ## Make 目标 所有操作源代码目录的目标都接受 `SRC=`（默认为 `.`）。使用索引数据库的目标接受 `DB=`（默认为 `index.db`）。 | 目标 | 描述 | 示例 | |---|---|---| | `install` | 安装所有依赖 | `make install` | | `index` | 索引目录（增量） | `make index SRC=../repo DB=my.db` | | `reindex` | 从头开始重建嵌入 | `make reindex SRC=../repo` | | `mcp` | 启动 MCP 服务器（标准输入/输出） | `make mcp BASE_URL=http://host:8081` | | `webui` | 启动 REST API + Web UI | `make webui DB=my.db PORT=8081` | | `test` | 运行完整测试套件 | `make test` | | `test-unit` | 仅运行单元测试 | `make test-unit` | | `test-integration` | 运行集成测试 | `make test-integration` | | `lint` | 检查代码风格 | `make lint` | | `format` | 自动格式化代码 | `make format` | | `add-claude-mcp` | 注册到 Claude Code | `make add-claude-mcp` | | `remove-claude-mcp` | 从 Claude Code 注销 | `make remove-claude-mcp` | | `add-pi-mcp` | 注册到 pi-agent | `make add-pi-mcp` | | `remove-pi-mcp` | 从 pi-agent 注销 | `make remove-pi-mcp` | | `clean` | 移除 index.db 和 WAL 文件 | `make clean` | ## 支持的文件类型 | 扩展名 | 解析器 | 单元边界 | |---|---|---| | `.py` | 标准库 `ast` | 模块级函数、类、方法 | | `.go` | tree-sitter (Go) | 函数、方法、结构体、接口 | | `.c`, `.h` | tree-sitter (C) | 函数、结构体、枚举 | | `.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp`, `.hxx`, `.ino` | tree-sitter (C++) | 函数、方法、类、结构体、枚举 | | `.js`, `.jsx`, `.mjs`, `.cjs` | tree-sitter (JavaScript) | 函数、类、方法、箭头函数 | | `.ts`, `.tsx`, `.mts`, `.cts` | tree-sitter (TypeScript) | 函数、类、方法、接口、类型、枚举 | | `.java` | tree-sitter (Java) | 类、接口、枚举、方法、构造函数 | | `.tf` | HCL 块分割器 | resource、variable、output、module、data、locals、… | | `.tfvars` | 文档级 | 整个文件 | | `.md`, `.mdx` | 标题分割器 | 标题章节 | | `.sql` | 文档级 | 整个文件（若超过 4 KB 则跳过） | 会自动检测并跳过二进制文件。无法识别的扩展名会被静默跳过。 ## MCP 工具 `code-rag-mcp.py` 暴露 10 个工具，全部代理到 `SKILL.md` 中记录的 REST API： | 工具 | 用途 | |---|---| | `search` | 自然语言向量搜索；返回排名的单元摘要 | | `get_unit` | 获取一个或多个限定路径的完整源代码 | | `list_units` | 列出已索引的单元，可选 glob 过滤器 | | `list_files` | 列出已索引的文件，可选 glob 过滤器 | | `list_repos` | 列出已索引的代码仓库 | | `index_status` | 每个代码仓库的文件/单元计数和最后索引时间戳 | | `staleness` | 每个代码仓库的索引新鲜度对比其 git HEAD | | `index_start` | 将路径加入索引队列（立即返回） | | `index_job_status` | 轮询正在运行的索引作业 | | `index_cancel` | 发送信号取消正在运行的作业 | 完整的参数和响应 schema 见 `SKILL.md`（从实时 OpenAPI 规范生成）。 ## 架构 ## 许可证 详情参见[许可证](LICENSE)。

标签：AI风险缓解, API服务, Claude AI, gemma模型, LLM评估, MCP服务器, Ollama, Python, REST API, uv包管理器, 代码分析, 代码导航, 代码库管理, 代码搜索引擎, 代码检索, 代码解析, 凭证管理, 向量数据库, 向量索引, 威胁情报, 开发者工具, 开发辅助工具, 摘要生成, 无后门, 检索增强生成, 语义代理索引, 语义单元, 语义嵌入, 语义搜索, 逆向工具