kuberstar/qartez-mcp

## 为什么存在 `grep`、`find`、`cat` 和 `ls` 诞生于 **1970 年代**，初衷是让人在终端中一次查看一个文件。半个世纪后，你的 AI 助手仍在使用它们——逐字节扫描文件、重复读取同一目录、猜测哪些内容重要，并把本不该由这些工具完成的工作浪费你的令牌。 **Qartez 是一种不同种类的工具。** 它不是 `grep` 的封装，而是你代码库的**预计算知识图谱**——包含符号、导入、调用边、爆炸半径、PageRank、Git 共变、圈复杂度——通过 [模型上下文协议](https://modelcontextprotocol.io/) 提供给任意 LLM。代理不再“读取”你的代码库，而是“查询”它。 每次你的 AI 助手触碰代码，以下三件昂贵的事情都会发生： **1. 它反复读取相同的文件。** 没有对代码库的记忆。每个问题都从零开始。你为每个令牌付费——一次又一次。 **2. 它看不到修改会破坏什么。** 助手在不知道的情况下编辑 `utils.ts`，而其他 14 个文件依赖它。你在 CI 中发现问题，或在生产环境才发现。 **3. 它浪费令牌来定位内容。** “`handleRequest` 定义在哪里？”变成在 200 个文件中 Grep、在 5 个候选中阅读、消耗 1,600 个令牌后才找到答案。Qartez 用 50 个令牌给出答案。 解决之道不是更聪明的模型，而是更智能的索引。 ## 快速开始 **平台支持：** macOS 13+、Ubuntu 22.04+（及其他现代 Linux，gnu 或 musl）、Windows（原生 PowerShell 5.1+/7+）和 WSL 2。架构：x86_64 和 arm64。Rust MSRV 为 **1.88**——仅用于不支持的平台或 `--from-source` 逃逸路径。 ### 安装（推荐） ``` curl -sSfL https://qartez.dev/install | sh ``` 安装器会为你的平台下载预构建二进制文件（不到 10 秒），校验与发行版 `SHA256SUMS` 的 SHA-256 校验和，安装三个二进制文件（`qartez`、`qartez-guard`、`qartez-setup`）到 `~/.local/bin/`，并以非交互模式启动 `qartez-setup`。不支持的平台会自动回退到本地 `cargo build`；可通过 `--from-source`（Windows 上为 `-FromSource`）强制使用该路径。设置向导会自动检测机器上所有支持 MCP 的 IDE 并一次性配置完成，包括为 Claude Code 配置修改保护钩子。 Windows（原生 PowerShell）： ``` powershell -ExecutionPolicy Bypass -c "iwr https://qartez.dev/install.ps1 -useb | iex" ``` 在 IDE 中打开任意项目——Qartez 会在会话启动时自动索引它。无需手动步骤。文件监视器会在你编辑时保持索引最新。 ### 通过 Cargo 安装 ``` cargo install qartez-mcp qartez-setup # then run the IDE wizard manually ```

替代方案：从源码安装

``` git clone https://github.com/kuberstar/qartez-mcp.git cd qartez-mcp make deploy ``` 想先查看安装脚本再通过 `sh` 管道执行？可在 GitHub 阅读： [`install.sh`](install.sh)。

交互式安装、定向安装及其他选项

### 适用于 19 个编辑器和代理 单个 Rust 二进制文件（`qartez-setup`）会检测并配置所有支持的编辑器。不需要每个编辑器独立的 Shell 脚本，也不需要复制粘贴 JSON。 ``` make deploy # Configure every detected IDE (non-interactive) make setup # Same, but interactive checkbox prompt qartez-setup --ide cursor,zed # Configure specific IDEs only make uninstall # Remove qartez from every IDE and delete binaries ``` 开箱即用支持：**Claude Code**、**Claude Desktop**、**Gemini**、**Cursor**、**Windsurf**、**Kiro**、**Zed**、**Continue.dev**、**Copilot CLI**、**Amazon Q**、**Amp**、**Cline**、**Roo Code**、**Goose**、**Warp**、**Augment**、**OpenCode**、**Codex CLI**、**Antigravity**。 ### 定向安装 ``` qartez-setup --ide cursor,zed,claude ``` 仅配置指定的 IDE 子集。检测到的路径如下： | IDE | 配置路径 | |---|---| | Claude Code | `~/.claude/settings.json` | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Gemini | `~/.gemini/settings.json` | | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | | Kiro | `~/.kiro/settings/mcp.json` | | Zed | `~/.config/zed/settings.json` | | Continue.dev | `~/.continue/config.yaml` | | Copilot CLI | `~/.copilot/mcp-config.json` | | Amazon Q | `~/.aws/amazonq/mcp.json` | | Amp | `~/.config/amp/settings.json` | | Cline | VS Code 全局存储 `saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | | Roo Code | VS Code 全局存储 `rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json` | | Goose | `~/.config/goose/config.yaml` | | Warp | `~/.warp/mcp_settings.json` | | Augment | `~/.augment/settings.json` | | OpenCode | `~/.config/opencode/opencode.json` | | Codex CLI | `~/.codex/config.toml` | | Antigravity | `~/.gemini/antigravity/mcp_config.json` | 每个安装路径都是幂等的，并会备份现有配置。 ### 在项目中启用 Qartez Qartez 会在会话启动时自动索引。如需手动重新索引： ``` qartez --root /path/to/your/project --reindex ``` ### Claude Desktop（手动） ``` { "mcpServers": { "qartez": { "command": "/absolute/path/to/qartez", "args": [] } } } ``` ### 卸载 ``` make uninstall ``` 从每个已配置的 IDE 中移除 Qartez 并删除二进制文件。

## Qartez 的作用 Qartez 构建一次代码库的**知识图谱**，并通过 MCP 提供给任意 AI 助手。它不再从零开始扫描文件，而是查询一个预计算的索引，该索引已知： - 哪些文件最重要（基于导入图的 PageRank） - 修改一个文件会破坏什么（爆炸半径分析） - 哪些文件总是一起变更（Git 共变挖掘） - 修改哪些函数最危险（圈复杂度 × 耦合 × 变更频率） - 每个符号的定义位置、使用者和调用者 - 哪些代码块是重复的（结构 AST 形状哈希） - 导入违反了哪些架构边界 - 哪些类型实现了某个 trait/接口，反之亦然 结果是：AI 运行更快、消耗更少令牌、安全重构，并且不再对关键文件进行盲目修改。 ### 修改前后对比 | 任务 | 无 Qartez | 有 Qartez | |---|---|---| | “`QartezServer` 定义在哪里？” | Grep 200 个文件，读取候选结果。**1,490 个令牌。** | `qartez_find`。**52 个令牌。** | | “修改 `storage/read.rs` 会破坏什么？” | 从导入出发的 BFS 遍历，深度 2。**9,243 个令牌。** | `qartez_impact`：直接与传递导入者 + 共变。**352 个令牌。** | | “概览 `src/server/mod.rs`（96 个符号）” | 读取完整的 300KB 文件。**77,843 个令牌。** | `qartez_outline` 带签名。**3,009 个令牌。** | | “查找所有废弃导出” | 无法在无工具情况下完成。 | `qartez_unused`：预计算，即时返回。**468 个令牌。** | | “哪些函数最危险？” | 无法查询。 | `qartez_hotspots`：复杂度 × PageRank × 变更频率。 | ## 31 个工具 将它们视为**AI 代码理解的通用标准库**。每个工具都把一个多步骤的人工流程替换为一次、令令牌高效的调用，供代理推理使用。 工具分为**层级**，按需逐步开放。核心工具始终可用。额外层级可通过 `qartez_tools enable: ["analysis"]`（或 `"all"`）按需解锁。 ### 核心（始终可用） | 工具 | 作用 | |---|---| | `qartez_map` | **从这里开始。** 按重要性排序列出项目骨架。PageRank、导出、爆炸半径。可通过文件或关键词聚焦当前工作。 | | `qartez_find` | 按精确名称跳转至符号定义。包含文件、行范围、签名、可见性。无须扫描。 | | `qartez_grep` | 基于 FTS5 在已索引符号中搜索。支持前缀匹配、正则回退，可选搜索函数体。 | | `qartez_read` | 读取一个或多个符号的源代码并带行号。不扫描文件，直接跳转至符号。 | | `qartez_outline` | 任意文件的目录：每种符号按类别分组并附带签名。 | | `qartez_impact` | **在编辑重要文件前调用。** 显示直接导入者、传递依赖项和共变合作伙伴。了解所有可能破坏项。 | | `qartez_deps` | 文件的依赖图：它导入什么、什么导入它。 | | `qartez_stats` | 代码库仪表盘：文件数、符号数、边数，按语言统计，以及最常连接的文件。 | ### 分析（通过 `qartez_tools` 解锁） | 工具 | 作用 | |---|---| | `qartez_refs` | 追踪符号在整个代码库中的所有用法，可选传递链。 | | `qartez_calls` | 调用层级：谁调用此函数、它又调用什么。 | | `qartez_cochange` | Git 历史上一起变更的文件。逻辑耦合在导入图中不可见。 | | `qartez_context` | 智能上下文构造器：给定计划修改的文件，返回应首先阅读的相关文件集。 | | `qartez_unused` | 废弃代码查找器：已导出但无导入者的符号，索引时预计算。 | | `qartez_diff_impact` | **对 Git 差异批处理影响分析。** 传入类似 `main..HEAD` 的修订范围，返回变更文件及其 PageRank、联合爆炸半径和收敛点。一次调用替代 N 次 `qartez_impact` 与 `qartez_cochange`。 | | `qartez_hotspots` | **重构雷达。** 按 **圈复杂度 × PageRank × (1 + 变更频率)** 排名文件和函数，指向代码库中最危险的部分。 | | `qartez_clones` | 通过 AST 形状哈希（忽略标识符、字面量和注释）检测结构重复代码。 | | `qartez_boundaries` | 架构边界强制：在 `.qartez/boundaries.toml` 中声明“这些模块不得导入那些模块”，并获取所有违规边。`suggest=true` 可生成 starter 配置。 | | `qartez_hierarchy` | 类型层级查询：查找实现某 trait/接口的所有类型，或某类型实现的所有 trait/接口。支持 Rust、TypeScript、Java、Python 和 Go。 | | `qartez_trend` | 圈复杂度随 Git 历史的变化趋势：逐提交跟踪函数复杂度，标记为 GROWING、STABLE 或 SHRINKING。 | | `qartez_security` | 内置安全扫描器，13 条规则，基于 PageRank 加权的正则匹配。按严重性（低/中/高/关键）和类别过滤。 | | `qartez_smells` | 代码异味检测器：发现**上帝函数**（高复杂度 + 长函数体）、**长参数列表**、**特征羡慕**（方法更依赖其他类型而非自身）。阈值可配置。 | | `qartez_test_gaps` | 通过导入图进行测试覆盖缺口分析。三种模式：`gaps` 按风险排名未测试源文件，`map` 显示测试与源文件的映射，`suggest` 推荐要运行的测试（针对 Git 差异范围）。 | | `qartez_knowledge` | **团队知识因子分析。** 基于 Git blame 的作者归属，暴露单作者文件和知识集中点。 | | `qartez_semantic` | 语义搜索：使用本地嵌入模型进行自然语言查询，混合 FTS5 + 向量相似度（RRF）。需要 `semantic` Cargo 特性并下载约 270 MB 模型。 | ### 重构（通过 `qartez_tools` 解锁） | 工具 | 作用 | |---|---| | `qartez_rename` | 在整个代码库中重命名符号。包含定义、导入和所有引用。默认预览，`apply=true` 时执行。 | | `qartez_move` | 将符号移动到另一个文件并重写所有导入路径。一次 MCP 调用完成。 | | `qartez_rename_file` | 重命名文件并更新所有指向它的导入。 | ### 元数据（通过 `qartez_tools` 解锁） | 工具 | 作用 | |---|---| | `qartez_project` | 自动检测工具链（Cargo、npm/bun/yarn、Go、Python、Make、Gradle），并通过单一工具运行测试/构建/检查/类型检查。 | | `qartez_wiki` | 使用 Leiden 社区检测生成架构 Wiki。将文件划分为簇，命名每个簇，并输出 `ARCHITECTURE.md` 及簇间边。 | | `qartez_workspace` | 运行时添加或移除工作区域。在 `.qartez/workspace.toml` 中注册外部目录，索引并移除。 | ### 层级管理 | 工具 | 作用 | |---|---| | `qartez_tools` | **始终可见。** 列出所有层级及其工具。使用 `enable: ["analysis"]`、`enable: ["all"]` 或 `disable: ["refactor"]` 控制暴露给代理的工具。核心工具无法禁用。 | ## 工作流提示 五个开箱即用的配方链式调用上述工具。按需作为 Slash 命令在 Claude Code 或任何支持 MCP 的客户端中调用。 | 提示 | 作用 | |---|---| | `/qartez_review ` | 代码评审：爆炸半径、目录、引用、共变——然后生成聚焦检查清单。 | | `/qartez_architecture [top_n]` | 基于 PageRank 数据的一分钟架构概览。 | | `/qartez_debug ` | 一次性输出定义、调用者、被调用者和引用。 | | `/qartez_onboard [area]` | 为新贡献者生成五文件阅读列表，按重要性排序。 | | `/qartez_pre_merge ` | 预合并安全检查，给出“放行/保留”建议。 | ## 修改保护 Qartez 附带**安全网**，防止 AI 盲目编辑高负载文件。 `qartez-guard` 二进制文件会挂钩到 Claude Code 的 `PreToolUse` 系统，在任何 `Edit` / `Write` / `MultiEdit` 操作前拦截。若文件的 PageRank 或爆炸半径超过阈值（默认 0.05 和 10），编辑会被**阻止**，并附带说明列出触发了哪些阈值。AI 必须先调用 `qartez_impact file_path=src/server/mod.rs` 查看爆炸半径，然后才能获得 10 分钟的编辑窗口。再次尝试编辑即被允许。 零配置。可通过 `QARTEZ_GUARD_PAGERANK_MIN`、`QARTEZ_GUARD_BLAST_MIN`、`QARTEZ_GUARD_ACK_TTL_SECS` 或 `QARTEZ_GUARD_DISABLE=1` 调整或禁用。 ## 基准测试 不是宣称，是测量。可复现。运行 `make bench` 并自行验证。 ### 头条 **相比 `Glob + Grep + Read + git log` 的聚合令牌节省：+91.8%** （在 Qartez 自测中，28 个场景的 MCP 总令牌 38,789 对非 MCP 总令牌 472,109。保守低估：其中 10 个场景非 MCP 模拟不完整——这些行仍计入双方总和。在 18 个公平对比的场景中，节省提升至 **+94.5%**。） **LLM 评判质量（claude-opus-4-6）：** MCP 8.3 / 10，非 MCP 4.3 / 10（五个维度：正确性、完整性、可用性、 groundedness、简洁性），n=28。 **会话成本背景。** 典型的 Claude Code 会话初始提示约 20,000 个令牌。一次 `make bench` 运行节省约 433,000 个令牌——相当于**省下约 21 个空会话**的预算，仅通过将问题路由到合适的工具。 ### 各工具明细（基于 Rust 自测） 18 个工具的完整非 MCP 对照（公平令牌对比）： | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_cochange` | 92 | 14,622 | **+99.4%** | 2x | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_context` | 107 | 4,489 | **+97.6%** | **533x** | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_find` | 52 | 1,490 | **+96.5%** | **210x** | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_impact` | 352 | 9,243 | **+96.2%** | **140x** | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_outline` | 3,009 | 77,843 | **+96.1%** | 5x | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_project` | 68 | 1,394 | **+95.1%** | 0x | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_unused` | 468 | 6,750 | **+93.1%** | 22x | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_deps` | 166 | 2,286 | **+92.7%** | **118x** | | 工具 | MCP 令牌 | 无 MCP 令牌 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_map` | 87 | 674 | **+87.1%** | 1x | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_rename_file` | 27 | 185 | **+85.4%** | **211x** | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_grep` | 127 | 763 | **+83.4%** | 72x | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_stats` | 155 | 848 | **+81.7%** | 1x | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_move` | 161 | 701 | **+77.0%** | **159x** | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_calls` | 564 | 2,409 | **+76.6%** | 3x | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_refs` | 201 | 692 | **+71.0%** | 26x | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_read` | 150 | 495 | **+69.7%** | **100x** | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_hierarchy` | 735 | 2,056 | **+64.3%** | **127x** | | 工具 | MCP 索引 | 无 MCP 索引 | 节省 | 加速比 | |---|---:|---:|---:|---:| | `qartez_rename` | 439 | 648 | **+32.3%** | 11x | 10 个额外分析工具没有可比较的 `grep/read` 等效项——它们解决了非 MCP 栈无法解决的问题： `qartez_hotspots`、`qartez_clones`、`qartez_smells`、`qartez_test_gaps`、`qartez_wiki`、`qartez_boundaries`、`qartez_trend`、`qartez_knowledge`、`qartez_diff_impact`、`qartez_security`。

多语言基准测试

`make bench-all` 对同一 28 个场景运行相同测试，涵盖五种锁定版本的 OSS 仓库——`colinhacks/zod`（TypeScript）、`spf13/cobra`（Go）、`encode/httpx`（Python）、`FasterXML/jackson-core`（Java），以及 Qartez 自检（Rust）——并输出跨语言摘要到 `reports/benchmark-.md` 及合并矩阵。每个工具、每种语言、每个场景——使用 `cl100k_base` 分词器与真实的 `Glob + Grep + Read + git log` 模拟进行公平对比。 ``` make bench # Rust self-bench only - fresh measurements make bench-all # All 5 languages (Rust, TypeScript, Python, Go, Java) + cross-language summary make bench-fixtures # Clone and index the pinned fixture repos ``` 报告输出到 `reports/benchmark.md` / `reports/benchmark.json`（单语言运行）或 `reports/benchmark-.md` 加上合并的跨语言矩阵（`bench-all`）。

## 底层工作原理 四层计算，仅初始化一次，每次工具调用都查询 SQLite： ### 1. Tree-sitter 解析 每个源文件由语言专属的 Tree-sitter 语法解析。无 LSP 服务器、无需为每种语言安装 SDK、无冷启动惩罚。解析器提取符号（函数、方法、类型、常量）及其签名、行列范围、导出可见性，以及——对 21 种命令式语言——每个函数的圈复杂度。 ### 2. 结构形状哈希 函数体被规范化为 AST 骨架（标识符、字面量和注释被抹除），再计算哈希。哈希相同的符号即为结构重复。`qartez_clones` 查询即基于此。 ### 3. 图分析 导入边构成有向图。运行三种算法： - **PageRank**——与 Google 用于网页的随机游走算法相同。在导入图上应用，识别构成项目架构基石的文件。 - **爆炸半径**——从变更文件出发的反向 BFS，统计受影响的文件数。`qartez_impact` 使用此机制预警破坏风险。 - **Leiden 社区检测**——社区划分，为自动生成的架构 Wiki 和 `qartez_boundaries` starter 配置提供依据。 ### 4. Git 历史挖掘 遍历最近 N 次提交（默认 300），统计文件对共同出现的频率。这揭示了导入图无法捕获的**逻辑耦合**——那些虽无导入关系但总是一起变更的文件。 `qartez_impact`、`qartez_context`、`qartez_hotspots` 融合这四种信号——PageRank + 爆炸半径 + 共变 + 复杂度——生成单一排名答案。没有任何其他 MCP 服务器能同时结合这四个维度。 ### 存储 所有数据存储在 `.qartez/index.db`——单个 SQLite 文件，辅以 FTS5 全文索引。启动时，Qartez 仅重新解析修改时间已变的文件。文件监视器默认启用，编辑或新文件会在后台重新索引，零停机。`--no-watch` 可禁用。 ### 传输 通过 **stdio**（标准输入/输出 JSON-RPC）与 IDE 通信。这是 MCP 的标准传输方式。无 HTTP 服务器、无端口分配、无网络暴露。IDE 将 `qartez` 二进制文件作为子进程启动并通过管道交换消息。 ## 支持的语言 单一二进制文件，无需为每种语言单独设置。所有 37 种语言均由 Tree-sitter 解析（对缺乏成熟 grammar 的格式使用正则回退）。21 种命令式语言还提供每个函数的圈复杂度评分，供 `qartez_hotspots` 使用。

完整语言列表（37 种）

| 语言 | 扩展名 / 文件名 | |---|---| | TypeScript / JavaScript | `.ts` `.tsx` `.js` `.jsx` `.mts` `.cts` `.mjs` `.cjs` | | Rust | `.rs` | | Go | `.go` | | Python | `.py` `.pyi` | | Java | `.java` | | Kotlin | `.kt` `.kts` | | Swift | `.swift` | | C# | `.cs` | | C | `.c` `.h` | | C++ | `.cpp` `.cc` `.cxx` `.hpp` `.hh` `.hxx` | | Ruby | `.rb` | | PHP | `.php` | | Bash | `.sh` `.bash` | | CSS | `.css` `.scss` | | Scala | `.scala` `.sc` - 类、特质、对象、case 类 | | Dart | `.dart` - 类、mixin、枚举、下划线隐私 | | Lua | `.lua` - 函数、方法 (`M.f`/`M:f`)、`require` 导入 | | Elixir | `.ex` `.exs` - `defmodule`、`def`/`defp`、`defstruct`、`alias`/`use`/`import` | | Zig | `.zig` - `pub fn`、结构体、枚举、联合、`@import` | | Nix | `.nix` - 属性绑定、函数、`import` 路径 | | Haskell | `.hs` `.lhs` - 顶层函数、`data`、`newtype`、`type`、类型类、`import` | | OCaml | `.ml` `.mli` - `let` 绑定、`type`、`module`、`class`、`exception`、`open`/`include` | | R | `.r` `.R` - 函数/变量赋值、S4/R6 类、`library`/`require`/`source` | | Protobuf | `.proto` - `message`、`service`、`rpc`、`enum`、`import` | | SQL | `.sql` - `CREATE TABLE`/`VIEW`/`FUNCTION`/`PROCEDURE`、`ALTER`、`BEGIN...END` 块 | | HCL / Terraform | `.tf` - 跨文件 `var`/`local`/`module`/`data`/`resource` 引用 | | YAML | `.yaml` `.yml` - K8s、GitHub Actions、GitLab CI、Docker Compose、Ansible | | Dockerfile | `Dockerfile`、`Dockerfile.*`、`.dockerfile` - 多阶段 `COPY --from` 引用 | | Makefile | `Makefile`、`GNUmakefile`、`.mk` - 目标、变量、`include` 导入 | | TOML | `.toml` - 表、键、数组的表 | | Nginx | `.conf`、`.nginx` - `server`、`location`、`upstream` 块 | | Helm / Go 模板 | `.tpl` - `define`/`include`/`template` 块 | | Jenkinsfile / Groovy | `Jenkinsfile`、`.groovy` - `pipeline`、`stage`、`node`、`def` | | Starlark / Bazel | `BUILD`、`BUILD.bazel`、`WORKSPACE`、`WORKSPACE.bazel`、`.bzl`、`.star`、`.bazel` - `load`、规则名、`def` | | Jsonnet | `.jsonnet` `.libsonnet` - `local` 函数/变量、字段、`import`/`importstr` | | Caddyfile | `Caddyfile`、`.caddyfile` - 站点块、`handle`、`reverse_proxy`、片段 | | Systemd units | `.service` `.timer` `.socket` `.mount` `.target` `.path` `.slice` `.scope` - 段、`ExecStart`、指令 | **亮点：** TypeScript、Go、Python、Java、Kotlin、Swift、C#、C/C++、Ruby、PHP、Dart、Scala、Elixir、Zig、Lua、Haskell、OCaml、R，以及另外 17 种语言。所有 21 种命令式语言均包含圈复杂度评分，供 `qartez_hotspots` 使用。

## 与替代方案的对比 MCP 代码库智能领域在 2026 年竞争激烈。本节列出直接开源竞争对手、企业平台及相关生态系统。所有星数均于 2026 年 4 月交叉核对 GitHub 仓库。 ### 直接开源 MCP 竞争对手（按 GitHub 星数排序） | 项目 | 星数 | 实现 | 索引方式 | 语言 | MCP 工具数 | |---|---:|---|---|---|---| | **Qartez**（本仓库） | new | **Rust** | tree-sitter + SQLite + PageRank + 爆炸半径 + 共变 + 复杂度 + 克隆 + 边界 | **37** | **30** | | [Serena](https://github.com/oraios/serena) | 23k | Python | LSP（每语言语言服务器） | **46+** | ~35 | | [code-review-graph](https://github.com/tirth8205/code-review-graph) | 10.4k | Python | tree-sitter + SQLite + Leiden 聚类 | 23+ | 28 | | [Claude-Context](https://github.com/zilliztech/claude-context) | 5.9k | TypeScript | 嵌入 + Milvus/Zilliz 向量库 | 14 | 4 | | [CodeGraphContext](https://github.com/CodeGraphContext/CodeGraphContext) | 3k | Python | tree-sitter + KuzuDB / FalkorDB / Neo4j | 14 | 21 | | [Codebase-Memory MCP](https://github.com/DeusData/codebase-memory-mcp) | 1.6k | C | tree-sitter + SQLite + 混合类型解析 | **66** | 14 | | [Repowise](https://github.com/repowise-dev/repowise) | 1.2k | Python | 依赖图 + Git 历史 + LLM 生成的文档 | 14 | 7 |

功能对比表

| 功能 | Qartez | Serena | code-review-graph | Claude-Context | CodeGraphContext | Codebase-Memory | Repowise | Code Index MCP | Codanna | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | Tree-sitter 解析 | **Yes** | No (LSP) | Yes | Chunking only | Yes | Yes | No | Yes (10 langs) | Yes | | **PageRank 重要性排序** | **Yes** | No | No | No | No | No | No | No | No | | **爆炸半径（传递依赖）** | **Yes** | No | Yes | No | No | Yes | No | No | Yes | | **Git 共变挖掘** | **Yes** | No | No | No | No | Yes | Yes | No | No | | **每函数圈复杂度** | **Yes (21 langs)** | No | No | No | No | No | No | No | No | | **热点评分（复杂度 × PR × 变更）** | **Yes** | No | No | No | No | No | No | No | No | | **结构重复代码检测** | **Yes** | No | No | No | No | No | No | No | No | | **架构边界强制** | **Yes** | No | No | No | No | No | No | No | No | | **四信号组合影响分析** | **Yes** | No | No | No | No | No | No | No | No | | **代码异味检测** | **Yes** | No | No | No | No | No | No | No | No | | **测试覆盖缺口分析** | **Yes** | No | No | No | No | No | No | No | No | | **类型层级查询** | **Yes** | Via LSP | No | No | No | No | No | No | No | | **调用图（调用者/被调用者）** | Yes | Partial | Yes | No | Yes | Yes | No | Yes | Yes | | **重构（重命名/移动/重命名文件）** | **Yes（预览 + 应用）** | Rename only (LSP); move via JetBrains plugin (paid) | Rename preview only | No | No | No | No | No | No | | **工具链命令运行** | **Yes** | Shell only | No | No | No | No | No | No | No | | **智能多信号上下文构造器** | **Yes** | No | Partial | No | No | No | No | No | No | | **批处理差异影响分析** | **Yes** | No | No | No | No | No | No | No | No | | **MCP 提示模板** | **Yes (5)** | No | Yes (5) | No | No | No | No | No | No | | **一键多 IDE 安装** | **Yes (19 IDEs, Rust wizard)** | No (manual) | Yes (9 IDEs) | No (manual) | Yes (10 IDEs) | Yes (10 agents) | No | No | No | | **修改保护（阻止高风险编辑）** | **Yes** | No | No | No | No | No | No | No | No | | **已发布基准（含 LLM 评测）** | **Yes (28 场景, 8.3/10)** | Third-party only | Yes (6 repos, 8.2x avg) | Limited (~40% claim) | No | Yes (arXiv paper, 10x tokens) | No | No | Partial (criterion) | | **嵌入模型 / 向量数据库需求** | No | No | Optional | **Yes** | No | No | No | No | **Yes** | | **社区检测 + 自动生成架构 Wiki** | **Yes (Leiden + wiki)** | No | Yes (Leiden + wiki) | No | No | Partial (Louvain, no wiki) | No | No | No | | **Watch 模式（增量重新索引）** | **Yes（自动开启）** | Partial | Yes | Partial | Yes | Yes | No | Yes | Yes |

### 企业级与 IDE 原生替代方案 商业平台为愿意用本地优先和开源换 polished 体验的用户提供同类解决方案： - **Sourcegraph Cody / Amp**——编译器级 SCIP 索引器，官方 MCP 服务器自 2026 年起提供。云优先、企业定价。 - **Augment Code**——2.27 亿美元 B 轮融资。实时语义索引 + 跨 40 万 + 文件的关系图，官方 MCP 服务器自 2025 年 10 月起提供。云依赖。 - **Deep Graph MCP (CodeGPT)**——云托管知识图谱后端；将 `github.com` 替换为 `deepgraph.co` 即可在任意仓库上使用预构建代码图。无需本地索引。 - **JetBrains AI Assistant（IntelliJ 2025.2+）**——内置 MCP 服务器，提供 IDE 级符号与诊断。限于 JetBrains 生态。 - **Cursor**——定制嵌入模型 + Turbopuffer 团队共享索引。封闭 IDE，无 MCP 暴露。 - **Windsurf Cascade**——基于 RAG 的 M-Query 检索。封闭 IDE，无 MCP 服务器。 Qartez 在提供相同结构智能的同时，实现了**完全本地、免费、开源**。

相关项目（较小规模）

| 项目 | 星数 | 实现 | 定位 | |---|---:|---|---| | [Drift](https://github.com/dadbodgeoff/drift) | 772 | TS / Rust | 学习代码库惯例与风格，跨会话引导 AI | | [Octocode](https://github.com/Muvon/octocode) | 319 | Rust | 图 RAG + 混合语义搜索（4 MCP 工具） | | [mcp-server-tree-sitter](https://github.com/wrale/mcp-server-tree-sitter) | 287 | Python | 暴露原始 Tree-sitter 查询，供代理自行组合分析（约 20 工具） | | [CodeGraph](https://github.com/Jakedismo/codegraph-rust) | 179 | Rust | SurrealDB + LSP + ReAct / LATS 代理架构，部分爆破半径 | | [RepoMapper](https://github.com/pdavis68/RepoMapper) | 150 | Python | Aider 的 `repo_map` 输出封装为 MCP | | [Narsil-MCP](https://github.com/postrv/narsil-mcp) | 134 | Rust | 90 个 MCP 工具，32 种语言，调用图 + 污点分析 + SBOM 安全扫描 | | [Code Pathfinder](https://github.com/shivasurya/code-pathfinder) | 118 | Go | 安全聚焦 SAST，交叉文件污点/数据流分析 | | [Code Graph RAG MCP](https://github.com/er77/code-graph-rag-mcp) | 86 | TypeScript | 图 + RAG 混合，26 个 MCP 方法，复制检测 | | [Tree-sitter Analyzer](https://github.com/aimasteracc/tree-sitter-analyzer) | 20 | Python | PageRank + `modification_guard`（阻止不安全编辑，17 种语言） | | [AiDex](https://github.com/CSCSoftware/AiDex) | 25 | TypeScript | 30 个 MCP 工具，任务管理、截图捕获、日志中心（11 种语言） |

### 相邻生态（不同类别，但解决类似问题） - **Aider repo-map**——Paul Gauthier 的 CLI 先行方案，Tree-sitter + PageRank 于 2023 年 10 月引入。生活在 Aider CLI 内部，非 MCP 服务器。RepoMapper 将 `repo_map` 输出封装为 MCP。 - **Continue.dev**——MCP 客户端，非服务器。其文档明确建议搭配专用代码图谱 MCP 服务器使用——而这正是 Qartez 扮演的角色。 - **Context7**、**Mem0**、**Pieces LTM**——记忆与文档工具，互补而非竞争。 - **Block Goose**、**Cline**、**Codebuff**——编码代理客户端，依赖 MCP 服务器。它们是*使用者*而非*提供者*。 ## Qartez 的独特之处 **1. 四信号组合影响分析。** `qartez_impact`、`qartez_diff_impact`、`qartez_context` 与 `qartez_hotspots` 融合 PageRank 重要性、静态爆破半径、Git 共变与圈复杂度。尚无其他项目同时结合这四个信号。 **2. 热点、克隆、边界、安全、异味、测试缺口、知识因子与趋势于一体的单一服务器。** `qartez_hotspots` 按复杂度 × PageRank × 变更频率排名文件和函数，指示代码库中最高风险区域。`qartez_clones` 通过 AST 形状哈希发现重复逻辑。`qartez_boundaries` 强制执行架构规则。`qartez_security` 基于 PageRank 加权的正则匹配扫描漏洞。`qartez_smells` 检测上帝函数、长参数列表与特征羡慕。`qartez_test_gaps` 通过导入图进行覆盖缺口分析。`qartez_knowledge` 暴露团队知识集中点（Git blame）。`qartez_trend` 逐提交跟踪复杂度演化。这些在其它商业产品中通常是八个独立工具，Qartez 中每个只需一次 MCP 调用。 **3. 通过 MCP 实现的原生重构与预览。** `qartez_rename`、`qartez_move` 与 `qartez_rename_file` 提供可预览的原子重构，单次 MCP 调用即可完成。Serena 仅通过 LSP 提供重命名（需为每种语言安装语言服务器）；其余服务器完全不提供重构工具。 **4. 内置修改保护。** `qartez-guard` 拦截高风险编辑，迫使用户在修改前查看爆破半径。尚无其它主流通用服务器具备此功能。 **5. 实测数据，而非宣称。** 28 个场景、8.3/10 的 LLM 评分（相较非 MCP 的 4.3/10），每工具令牌统计与加速比。`make bench` 可复现。 **6. Rust 原生、本地优先、零云依赖。** 三个二进制文件（`qartez`、`qartez-guard`、`qartez-setup`）。无 Python 运行时、无向量数据库、无网络暴露。代码不出本地。可选 `semantic` 特性启用本地嵌入搜索，但默认构建无需模型下载。 ## 命令行选项 Qartez 也可作为独立 CLI 使用。运行 `qartez `（例如 `qartez map`、`qartez find Config`、`qartez impact src/server/mod.rs`）即可直接调用任意核心或分析工具，无需 MCP 客户端。 | 选项 | 说明 | 默认值 | |---|---|---| | `--root ` | 要索引的项目根目录（支持多仓库） | 自动检测 | | `--reindex` | 强制完全重新索引 | 关闭 | | `--git-depth ` | 用于共变分析的提交数 | `300` | | `--db-path ` | 覆盖索引文件位置 | `.qartez/index.db` | | `--no-watch` | 禁用自动文件监视器（默认开启） | 监视器开启 | | `--wiki ` | 索引后生成架构 Wiki | 关闭 | | `--leiden-resolution ` | 聚类粒度（值越大聚类越细） | `1.0` | | `--format ` | CLI 子命令输出格式：`human`、`json`、`compact` | `human` | | `--log-level ` | 日志级别：`error`、`warn`、`info`、`debug`、`trace` | `info` |

项目结构

``` src/ main.rs Entry point: index, compute, start server lib.rs Library root (re-exports) cli.rs CLI argument parsing (19 subcommands) cli_runner.rs CLI subcommand dispatcher config.rs Project configuration and root detection error.rs Error types str_utils.rs String utilities (stable floor_char_boundary polyfill) toolchain.rs Toolchain detection (Cargo, npm, Go, etc.) watch.rs File watcher for incremental re-indexing guard.rs Modification guard evaluation engine embeddings.rs Local embedding model for qartez_semantic (opt-in) server/ mod.rs MCP server entrypoint - dispatches to per-tool handlers tools/ 30 per-tool handler modules (one file per MCP tool) prompts.rs 5 workflow prompt templates tiers.rs Progressive tool disclosure (core/analysis/refactor/meta) cache.rs Tree-sitter parse cache helpers.rs Shared handler utilities overview.rs Overview/map generation params.rs Tool parameter structs treesitter.rs Tree-sitter integration helpers mcp_instructions.md Embedded MCP server instructions index/ mod.rs Core indexing engine (full + incremental, import resolution) walker.rs File discovery (respects .gitignore + .qartezignore) parser.rs Tree-sitter parser pool symbols.rs Symbols / imports / references + AST shape hashing languages/ 37 language adapters (21 with cyclomatic complexity) graph/ mod.rs Graph module root pagerank.rs PageRank on import graph blast.rs Blast radius BFS leiden.rs Community detection (Leiden clustering) boundaries.rs Architecture-boundary rules engine security.rs Security rule engine (powers qartez_security) wiki.rs Architecture wiki renderer git/ mod.rs Git module root cochange.rs Co-change pair mining diff.rs Diff range analysis (for qartez_diff_impact) trend.rs Complexity trend over git history knowledge.rs Code authorship and bus-factor analysis storage/ mod.rs Storage module root schema.rs SQLite + FTS5 schema read.rs / write.rs Query and mutation helpers models.rs Row structs bin/ setup.rs Interactive IDE setup wizard (19 IDEs) guard.rs PreToolUse modification guard benchmark.rs Benchmark harness entry point benchmark/ Benchmark internals (cargo feature) profiles/ Per-language benchmark profiles (Rust, TS, Python, Go, Java) scenarios.rs 28 benchmark scenarios judge.rs LLM-judge harness report.rs Markdown / JSON report writers tokenize.rs cl100k_base token accounting scripts/ Hook + snippet assets embedded by qartez-setup benchmarks/fixtures.toml Pinned OSS repos for multi-language benchmarks reports/ Generated benchmark.md / benchmark.json artifacts ```

## 贡献 发现 Bug？打开 [issue](https://github.com/kuberstar/qartez-mcp/issues)。想添加语言支持、修复解析器或改进工具？欢迎提交 PR——请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md) 与 [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md)。非重大 PR 需签署 [`CLA.md`](CLA.md)。 ``` git clone https://github.com/kuberstar/qartez-mcp.git cd qartez-mcp cargo build cargo test ``` 版本说明位于 [`CHANGELOG.md`](CHANGELOG.md)。 ## 安全 发现漏洞？**不要公开创建 issue。** 请遵循 [披露政策](SECURITY.md)。 ## 许可证 根据 **Qartez Small Team License**（个人及小型团队免费）与 **Qartez Commercial License**（其他用途）双重授权。详见 [`LICENSE`](LICENSE) 并参阅 [`COMMERCIAL.md`](COMMERCIAL.md) 获取商业条款摘要。SPDX 标识符：`LicenseRef-Qartez-Dual`。

Grep 面向人类。Qartez 面向代理。

如果 Qartez 每月为您节省 10% 的 AI 费用，请 star 该仓库——这是告诉其他开发者此方法值得尝试的唯一信号。

标签：AI编程助手, Claude Code, Git共变分析, MCP Server, PageRank, Rust, Token优化, 二进制分发, 云安全监控, 代码复杂度, 代码导航, 代码检索, 代码知识图谱, 可视化界面, 影响分析, 模型上下文协议, 符号搜索, 索引加速, 网络安全研究, 网络流量审计, 语义代码智能, 调用图, 跨文件导入分析, 通知系统, 静态分析, 项目地图, 预计算知识库