planexhq/codedeep-mcp

# codedeep-mcp [](https://github.com/planexhq/codedeep-mcp/actions/workflows/ci.yml) [](https://www.npmjs.com/package/codedeep-mcp) [](https://modelcontextprotocol.io/specification/2025-11-25) [](./LICENSE) [](https://nodejs.org) 一个为 AI 编码代理赋予代码库结构化理解能力的 MCP 服务器。 **一次工具调用即可替代 5-10 次 Grep-Read 循环。** codedeep-mcp 使用 [tree-sitter](https://tree-sitter.github.io/tree-sitter/) 解析你的代码，构建符号索引，并通过 [Model Context Protocol](https://modelcontextprotocol.io/) 暴露 10 个工具：包含 6 个只读结构化工具，可直接回答问题（查找符号、追踪调用者、评估影响范围、按结构搜索）；一个包含 3 个工具的代理策划知识层（`remember` / `recall` / `forget`），其笔记会针对你的源代码进行**过期追踪** —— 当锚定的代码发生改变时，笔记会被标记出来，而不是默默地失效；以及 `changes`，它可以通过一次调用审查你的 git 工作集：哪些会崩溃，以及你的哪些笔记刚刚过期。 ## 为什么需要 AI 编码代理使用文本工具（grep、文件读取）探索代码库。这虽然可行，但成本很高： - “查找 X 的所有调用者”需要 5 次以上的 grep-read 循环，并且会返回误报 - “如果我更改这个会破坏什么？”需要进行详尽的手动搜索 - Grep 无法区分作为变量的 `user`、作为类的 `User` 和作为函数的 `user()` codedeep-mcp 通过将代码解析为符号和关系来解决这个问题，然后在一次调用中回答结构化问题。 ## 工具 | 工具 | 用途 | 示例 | |------|---------|---------| | `overview` | 在不熟悉的代码库中进行定位 | 语言分类、入口点、结构 | | `find_symbol` | 感知 AST 的符号查找 | 按名称查找函数 — 匹配定义，而不是文本 | | `get_context` | 符号的完整上下文 | 函数体 + 调用者/被调用者 + 导入 + 共同变更与复杂度 | | `find_references` | 跨文件使用情况搜索 | 谁调用了这个函数，以及从哪里调用的？ | | `impact` | 深度为 N 的影响范围 | 传递性的上游调用者，按跳数分组 | | `search_structure` | 关键词与结构化搜索 | 按名称/签名查找（所有语言），或通过 AST 模式查找 (TS/JS) | | `remember` | 存储持久化、锚定的笔记 | 跨文件的不变量、隐患、决策 — 锚定到文件/符号 | | `recall` | 带有新鲜度检测的笔记检索 | 每个笔记都会通过重新检查其锚点，标记为 ✓ 新鲜 / ⚠ 过期 | | `forget` | 删除笔记 | 移除被取代或错误的知识 | | `changes` | 工作集审查 | 会破坏什么 + 哪些笔记已过期，按每个修改过的文件列出 | ## 快速开始 ### Claude Code 添加到 `~/.claude/settings.json`： ``` { "mcpServers": { "codedeep-mcp": { "command": "npx", "args": ["codedeep-mcp"] } } } ``` ### Cursor / Windsurf / 其他 MCP 客户端 任何支持 stdio 传输的 MCP 客户端都可以使用。将其配置为运行 `npx codedeep-mcp`。 ## 工作原理 ``` Your Code ──> tree-sitter (parse) ──> In-Memory Index ──> MCP Tools │ Git (optional) ``` **结构化索引（始终开启，即时完成）：** tree-sitter 将每个文件解析为一个 AST。符号、调用关系和导入将被提取并索引在内存中 — 针对每种语言的调用解析都经过精度调整（以明确的“零错误类型边”为目标），而不仅仅是文本匹配。无需任何配置即可在任何代码库中工作。 **复杂度指标（支持全部 14 种语言）：** 在索引时计算每个符号的圈复杂度（cyclomatic complexity）和认知复杂度（cognitive complexity），并固定行为基准以与 McCabe / 认知复杂度白皮书 / 开源分析器（SonarJS, sonar-java, gocyclo+gocognit, rust-code-analysis, …）保持可比性。显示在 `find_symbol` / `get_context` 中。 **Git 增强（当处于 git 仓库中时）：** 提交频率用于识别热点文件；共同变更分析揭示行为耦合（一起更改的文件）；而风险评分（变动率 × 耦合度 × 复杂度）对最容易发生变动、最错综复杂的枢纽进行排名。 **代理策划的知识层（已追踪过期状态）：** `remember` 将持久化笔记锚定到文件/符号，并对内容基线进行快照；`recall` 会根据当前源代码重新检查每个锚点，并将每个笔记标记为 ✓ 新鲜 / ⚠ 过期 / ✗ 缺失 — 这样，代理积累的知识在读取时即会被验证，而不是默默失效。锚定的笔记也会**内联（inline）**展示：`get_context` 会渲染锚定到正在读取的符号或文件的笔记（检查过期状态，有数量上限），而 `overview` 会报告存储了多少知识 — 代理会在它已经在查看的地方遇到自己的笔记，而无需额外询问。笔记存储在本地 `.codedeep` 缓存中，绝不会写入你的源代码。 **诚实的置信度，精心设计：** 跨文件的边是带有置信度等级的、派生自 AST 的名称匹配，而不是编译器验证的引用 — 每一行近似结果都会被打上标签（例如 `[name match, unverified]`、`[behavioral]`），以便代理知道在做出断言之前应该信任什么以及应该验证什么。 ## 示例 ``` > find_symbol({ name: "authenticate" }) src/auth/middleware.ts:42-67 | function | exported async function authenticate(req: Request, res: Response, next: NextFunction): Promise Validates the JWT token and attaches user to request References: ~5 Fan-out: 2 Complexity: cyc 3 / cog 1 [structural] > get_context({ file: "src/auth/middleware.ts", symbol: "authenticate" }) src/auth/middleware.ts:42-67 | function | exported async function authenticate(req: Request, res: Response, next: NextFunction): Promise Validates the JWT token and attaches user to request ### Body ```typescript async function authenticate(req: Request, res: Response, next: NextFunction): Promise { const token = extractToken(req); const payload = verify(token); req.user = payload as User; next(); } ``` ### Callers - src/routes/api.ts:67 — handleRequest() [structural] - src/routes/webhook.ts:23 — verifyWebhook() [structural] (get_context also emits ### Callees and ### Coupling sections here, omitted for brevity) ### Imports - jsonwebtoken: verify, decode - ./types: User, AuthToken ### Co-change Partners (2 behavioral) - src/auth/types.ts 78% confidence (9 shared commits) - tests/auth.test.ts 64% confidence (7 shared commits) ``` ## 支持的语言 **14 种语言**，每种语言都包含 tree-sitter 符号/引用提取**以及**圈复杂度 + 认知复杂度计算： TypeScript / JS · Python · Java · Go · Rust · Swift · Kotlin · Dart · C# · PHP · Ruby · C++ · C · Objective-C 跨文件引用是带有每行置信度标签的 AST 名称匹配（参见*工作原理*） — 针对每种语言基于真实的代码库语料库进行了精度调整，以实现明确的“零错误类型边”为目标。 ## 配置 项目根目录下可选的 `.codedeep/config.json`： ``` { "exclude": ["vendor/**", "generated/**"], "languages": ["typescript", "python"], "maxFiles": 100000, "maxFileSize": 1048576, "watch": true, "gitEnabled": true, "gitWindow": 180 } ``` 所有字段均为可选。没有配置文件也能正常工作。 将 `.codedeep/` 添加到你的 `.gitignore` 中 — 索引缓存存储在那里。 环境变量：`CODEDEEP_CACHE_DIR`、`CODEDEEP_EXCLUDE`、`CODEDEEP_GIT`、`CODEDEEP_GIT_WINDOW`、`CODEDEEP_WATCH`、`CODEDEEP_DEBUG`。 ## 开发 ``` npm install npm run build npm test ``` ## 许可证 MIT — 详见 [LICENSE](./LICENSE)。

标签：AI编程助手, MCP, MITM代理, SOC Prime, Tree-sitter, 代码分析, 代码理解, 凭证管理, 开发工具, 网络安全研究, 自动化攻击