code-query-mcp

多语言 / 多框架 / 多项目的代码分析 MCP 服务：用自然语言搜 API 端点，沿 Controller→Service→Mapper/SQL→外部服务追踪调用链，做影响分析与可达性检查；也可生成供开发与测试消费的四层统一代码扫描产物。

code-query-mcp 把代码库解析成一张 符号 + 调用边 + 端点 的图，落在一个 SQLite 库里，再通过 MCP（Model Context Protocol） 暴露给 AI 客户端（Qoder / Claude Desktop / 任意 MCP 兼容工具）。

核心定位：输出精确的、可复核的代码事实（零幻觉），把自然语言解释和渲染留给调用方 AI。

它能回答什么问题

| 问题 | 工具 | | --- | --- | | "实现 XX 业务的接口在哪个服务/哪个 Controller？" | search_endpoint / search_all_endpoints | | "这个接口的完整调用流程是什么？" | trace_endpoint（explain=true 输出分层流程摘要） | | "改动这个方法/SQL 会影响哪些对外接口？" | impact_analysis | | "A 能不能调用到 B？路径是什么？" | check_reachability | | "谁调用了这个方法？往下又调了什么？" | trace_upstream / trace_symbol | | "按关键字定位类/方法/字段/SQL" | search_symbol | | "某 MQ topic / URL / 配置键这个字符串出现在哪、被哪些服务引用？" | search_literal（省略 project 即跨全库） | | "为一个变更生成接口契约、调用流、需求映射与覆盖缺口" | generate_unified_scan_model |

核心特性

• 自然语言语义搜端点：基于 ollama embedding（qwen3-embedding:0.6b）做向量相似度搜索；ollama 不可用时自动降级为文本匹配，功能不中断。
• 跨项目分析：多个微服务仓库索引进同一个库，支持跨项目端点搜索，以及 Feign / HTTP 调用 / MQ（producer→topic→consumer）的跨服务连边。
• 增量索引：基于 git diff 只重解析改动文件（无 git 时按内容 hash 兜底），分支切换感知。
• 零幻觉的流程解释：explain=true 的分层流程摘要（入口/服务/数据/外部依赖 + SQL 统计）全部由调用图规则推导，不含 LLM 猜测。
• 四层统一扫描产物：针对一个 OpenSpec 变更，生成版本化的接口契约、代码结构、业务规则与可追溯性模型，以及摘要和 manifest。静态无法确定的 AC 映射明确保留为 coverage gap，不伪造覆盖。
• 配置中心回填：支持将 ${config_center/...} 类占位符回填为真实值（如 MQ topic），参与跨项目连边；敏感 KEY 自动掩码。
• 两种部署模式：本地 stdio（个人使用）或中心机托管 HTTP MCP 服务（团队共享，客户端不搬库）。

支持的语言 / 框架

| 语言 | 端点/框架提取 | | --- | --- | | Java | Spring MVC、Feign、MyBatis（注解 + XML mapper）、RocketMQ/Kafka、Swagger/OpenAPI 注解、Javadoc | | Go | gin / echo / net-http，swaggo 注释 | | Python | FastAPI / Flask 装饰器 | | TS/JS | 符号与调用图、React/TSX 组件（箭头函数、HOC 包裹、JSX 渲染边）、静态 HTTP 调用（fetch、Axios 与常见 request/http/api/client 封装）；扫描模型中标为 frontend_client，并按 HTTP 方法与路径静态关联到后端端点。前端路由（react-router 配置对象 / JSX <Route>、vue-router routes）索引为 kind="route" 符号；UI 数据绑定（antd Form.Item name、Table dataIndex、data-testid）索引为 kind="binding" 符号 | | Kotlin（Android） | Retrofit 接口（@GET/@POST 等，标为 frontend-http 参与跨项目连边）、路由注解（@RouterUri/@Route → android-route 端点）、Room @Dao（@Query/@Insert 等 → SQL 符号 + mapper_sql 边）、点击回调 lambda 与 startActivity 跳转边、data-binding（Kotlin binding.x.text = bean.field 与 res/layout/*.xml 的 @+id/@{}/android:onClick） | | Swift / Objective-C（iOS） | UIKit 绑定（@IBOutlet/@IBAction、self.x.text = user.field 赋值 → UI↔字段双向 references 边；Storyboard/XIB 的 <outlet>/<action>/<segue> XML 解析 → 控件符号、action calls 边、kind="route" 路由符号）、Alamofire / URLSession 调用 → frontend-http 端点参与跨项目连边、performSegue/instantiateViewController 导航索引 | | Dart（Flutter） | StatefulWidget/StatelessWidget 与 State<X> 结构图；Widget↔State 字段双向 references 绑定（kind="binding" 符号）、onPressed:/onChanged: 闭包合成 <lambda:N> 方法符号 + calls 边、GoRouter/Navigator.pushNamed/路由表 Map literal → kind="route" 符号、dio / package:http 调用 → frontend-http 端点 | | TS/JS（Taro 小程序） | app.config.ts 路由注册（pages/subpackages/tabBar）→ kind="route" 符号；Taro.navigateTo/redirectTo/reLaunch/switchTab({url}) 跳转 → 路由符号 + references 边；HttpRequest.get/post/del/put/formPost 与 Taro.request → frontend-http 端点（handler 精确解析到 API 函数，支持跨项目连边） |

快速开始

环境要求：Node.js ≥ 22（推荐 24+），依赖 Node 内置 node:sqlite（Node 22.x 需加 --experimental-sqlite 标志）。

方式一：npm 包（免源码）

npm install -g code-query-mcp

安装时配套的 CodeBuddy skill 会自动装到用户级 ~/.codebuddy/skills/code-query-mcp/（全项目可用）。若要把 skill 装进当前项目供 agent 使用，在项目根目录执行 code-query-mcp install-skill --project；跳过自动安装可设 CODE_MCP_SKIP_SKILL_INSTALL=1。

MCP 客户端配置：

{
  "mcpServers": {
    "code-query-mcp": {
      "command": "code-query-mcp",
      "env": {
        "CODE_MCP_DB": "/abs/path/.code-mcp/index.db"
      }
    }
  }
}

方式二：源码安装

git clone <repo-url> && cd code-mcp
npm install && npm run build

MCP 客户端配置：

{
  "mcpServers": {
    "code-query-mcp": {
      "command": "node",
      "args": ["<repo-root>/dist/server/index.js"],
      "env": {
        "CODE_MCP_DB": "<repo-root>/.code-mcp/index.db"
      }
    }
  }
}

索引与查询

在 MCP 客户端里依次调用：

1. project_register(name, path) — 注册项目（绝对路径，自动探测 git）
2. index_build(project) — 首次全量索引
3. search_endpoint(project, "用户登录", explain=true) — 自然语言搜端点 + 流程解释
4. 日常改代码后 index_update(project) 增量刷新

生成开发与测试扫描产物

在变更对应代码完成索引后，调用 generate_unified_scan_model。它会读取已批准的 OpenSpec spec.md（可选 design.md），并写入默认目录 <specPath 所在目录>/test-artifacts/：

{
  "project": "demo",
  "specPath": "D:/repo/openspec/changes/add-user/spec.md",
  "designPath": "D:/repo/openspec/changes/add-user/design.md",
  "endpointPaths": ["/api/users"],
  "traceDepth": 5
}

返回值给出三个可交接文件：unified-scan-model.v1.json（四层模型）、scan-summary.json（计数与门禁摘要）、scan-manifest.json（产物索引）。先查看 qualityGate.status：pass 可直接交接；conditional_pass 必须处理返回的 gaps；blocked 则先修复输入或索引问题后重跑。详见 四层统一扫描模型规范。

也可以用 CLI 免客户端验证（源码模式）：

npm run cli -- register demo /path/to/your/repo
npm run cli -- build demo
npm run cli -- search-endpoint demo "用户登录" --limit=5

HTTP 托管（云端 / 团队共享）

一台中心机构建索引并托管 HTTP MCP 服务，全团队共用查询，客户端不搬库：

# 独立 HTTP 入口（云端部署推荐，读 PORT 环境变量）
CODE_MCP_DB=/abs/path/index.db node dist/server/http.js

# 或 CLI 子命令
CODE_MCP_DB=/abs/path/index.db node dist/cli.js serve --http --port=3100

客户端用 Streamable HTTP 传输连 http://<中心机>:3100/mcp 即可。

配置

所有配置通过环境变量完成，常用项：

| 变量 | 作用 | 默认值 | | --- | --- | --- | | CODE_MCP_DB | 共享 SQLite 库的绝对路径（多项目共用同一库） | ./.code-mcp/index.db | | CODE_MCP_OLLAMA_URL | 语义搜索 embedding 接口 | http://localhost:11434/api/embed | | CODE_MCP_SKIP_EMBED | 非空则跳过向量生成（无 ollama 时批量索引用） | 未设 | | CODE_MCP_CONFIG_CENTER | 配置中心 key→value 映射源（文件或 URL） | ./.code-mcp/config-center.json | | CODE_MCP_SKIP_SKILL_INSTALL | 非空则跳过 npm 安装时的 skill 自动安装（保留本地改动） | 未设 |

完整变量清单与说明见 .env.sample。

已知限制

• Windows 上解析 Swift 文件后进程退出会崩溃（exit 3）：tree-sitter-swift.wasm 在进程 teardown 阶段触发 V8 后台线程的 Fatal process out of memory: Zone，属上游 grammar 的 bug。索引结果本身正确且已落库；常驻的 MCP server 不受影响（进程不退出），仅 CLI/一次性脚本会拿到非零退出码。规避：在命令行末尾追加 || true，或使用 MCP 工具而非 CLI。
• 非 Windows 平台（Linux/macOS）未复现该问题。
• 大项目索引会走分批子进程（默认每批 6 个文件，CODE_MCP_INDEX_CHUNK 可调）：web-tree-sitter 的 wasm 内存不会归还给 OS，长进程连续解析约 20 个文件后会在 Windows/Node 24 上触发同样的 V8 Zone OOM。分批后每个 worker 在崩溃前完成并提交，父进程按完成标记续批，因此索引结果完整、可重复执行。worker 退出码可能非 0，属预期。

文档导航

• INSTALL.md — 完整安装与接入指南（环境变量、MCP 客户端配置、增量保鲜、远程模式）
• skills/code-index/SKILL.md — 使用指南（全部 MCP 工具说明、工作流、常见配方）
• docs/UNIFIED-SCAN-MODEL-SPEC.md — 四层扫描产物、接口契约与质量门禁规范
• docs/VISION.md — 产品愿景
• docs/ROADMAP.md — 路线图与迭代记录