Qartez Mcp

Qartez MCP

代码库的 X 光视野——专为 AI Agent 打造，而非人类。

首个从设计之初就旨在由
大模型使用、而非供人阅读的代码智能服务。可将 AI 的 token 用量降低约 94%。

快速开始 · 43 个工具 · 修改防护 · 基准测试 · 对比 · 37 种语言 · 命令行 · 参与贡献 · 安全 · 更新日志

为什么要开发它

grep、find、cat 和 ls 都诞生于 20 世纪 70 年代，当时是为人们在终端中一次读取一个文件而设计的。半个世纪过去了，你的 AI 助手仍在使用这些工具——逐字节扫描文件，每次提问都重新读取相同的目录，猜测哪些内容重要，还把 token 浪费在这些工具从未被设计来处理的工作上。

Qartez 是一种全新的工具。 它不是 grep 的封装，而是预先计算好的代码库知识图谱，涵盖符号、导入关系、调用边、影响范围、PageRank、Git 共同变更和圈复杂度，并通过 Model Context Protocol 提供给任意大模型。Agent 不再读取你的代码库，而是开始查询它。

可以把它看作首个专为编码 Agent 打造的感知器官。Grep 一次只能看到一行。Qartez 一眼就能看清整个代码库的结构。

每当 AI 助手处理代码时，都会发生三件代价高昂的事：

1. 它反复读取相同的文件。 它对代码库毫无记忆。每个问题都从头开始。你为每个 token 付费——一次又一次。

2. 它看不到哪些地方会出问题。 助手修改 utils.ts，却不知道另外 14 个文件都导入了它。你会在 CI 中发现问题，或者在生产环境中发现。

3. 它浪费 token 来查找内容。 “handleRequest 定义在哪里？”会变成在 200 个文件中执行 Grep、在 5 个候选文件中执行 Read，还没找到答案就已经烧掉 1,600 个 token。Qartez 用 50 个 token 就能回答。

解决办法不是更聪明的模型，而是更聪明的索引。

快速开始

平台支持： macOS 13+、Ubuntu 22.04+（以及其他现代 Linux，gnu 或 musl）、Windows（原生 PowerShell 5.1+/7+）和 WSL 2。架构：x86_64 和 arm64。Rust MSRV 为 1.88——仅在不受支持的平台上，或使用 --from-source 备用方案时需要。

安装（推荐）

根据你的操作系统选择一行命令。两条命令执行相同的操作：下载预构建二进制文件，根据发布版本的 SHA256SUMS 验证其 SHA-256，安装三个二进制文件（qartez、qartez-guard、qartez-setup），并以非交互模式启动 qartez-setup，配置检测到的所有支持 MCP 的 IDE（包括 Claude Code 的修改防护钩子）。

macOS / Linux / WSL 2 - bash 安装程序，二进制文件会放在 ~/.local/bin/：

curl -sSfL https://qartez.dev/install | sh

Windows（原生 PowerShell 5.1+/7+） - PowerShell 安装程序，二进制文件会放在 %LOCALAPPDATA%\Programs\qartez\：

powershell -ExecutionPolicy Bypass -c "iwr https://raw.githubusercontent.com/kuberstar/qartez-mcp/main/install.ps1 -useb | iex"

不受支持的平台（例如，没有已发布构建产物的 linux-musl arm64）会自动回退到本地 cargo build；传入 --from-source（bash）或 -FromSource（PowerShell）可强制使用该方式。只有在回退时才需要 Rust MSRV 1.88。

在 IDE 中打开任意项目 - Qartez 会在会话开始时自动为其建立索引。无需手动操作。文件监视器会在你编辑时保持索引最新。

git clone https://github.com/kuberstar/qartez-mcp.git
cd qartez-mcp
make deploy

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

qartez-setup --ide cursor,zed,claude

qartez --root /path/to/your/project --reindex

{
  "mcpServers": {
    "qartez": {
      "command": "/absolute/path/to/qartez",
      "args": []
    }
  }
}

make uninstall

Qartez 的作用

Qartez 一次性为你的代码库构建一个知识图谱，并通过 MCP 将其提供给任何 AI 助手。你的助手无需每次提问都从头扫描文件，而是查询一个预先计算好的索引，其中包含：

• 哪些文件最重要（导入图上的 PageRank）
• 修改某个文件会导致什么问题（影响范围分析）
• 哪些文件总是一起变更（Git 共变挖掘）
• 哪些函数最不宜触碰（圈复杂度 × 耦合度 × 变更频率）
• 每个符号的定义位置、使用者以及调用者
• 哪些代码块存在重复（基于 AST 结构形状哈希）
• 导入违反了哪些架构边界
• 哪些类型实现了某个 trait/interface，反之亦然

最终，你的 AI 工作更快、使用更少的 token、安全地重构，并且不再盲目修改承载关键功能的文件。

前后对比

43 个工具

可以把这些工具视为用于 AI 理解代码的标准库。每个工具都能用一次高效利用 token 的调用，替代需要多个步骤的人工工作流，让 Agent 能够据此推理。

工具按层级组织，并采用渐进式披露。核心工具始终可用。可按需通过 qartez_tools enable: ["analysis"]（或 "all"）解锁其他层级。

核心（始终可用）

分析（通过 qartez_tools 解锁）

重构（通过 qartez_tools 解锁）

元数据（通过 qartez_tools 解锁）

层级管理

工作流提示词

六个可直接使用的配方，按正确顺序串联上述工具。可在 Claude Code 或任何支持提示词的 MCP 客户端中将它们作为斜杠命令调用。

修改防护

Qartez 提供安全网，防止 AI 盲目编辑承载关键功能的文件。

qartez-guard 二进制程序会接入 Claude Code 的 PreToolUse 系统，并阻止对任何 PageRank 或影响范围超过阈值的文件执行 Edit/Write/MultiEdit，直到 AI 先调用 qartez_impact 确认风险。

工作原理：

1. AI 尝试编辑 src/server/mod.rs
2. 防护程序检查：PageRank 为 0.23（> 0.05 阈值），影响范围为 10（>= 10 阈值）
3. 编辑被阻止，并附上触发阈值的说明
4. AI 调用 qartez_impact file_path=src/server/mod.rs，查看影响范围
5. 防护程序为该文件授予 10 分钟的编辑窗口
6. AI 重试编辑，允许

无需配置。可通过 QARTEZ_GUARD_PAGERANK_MIN、QARTEZ_GUARD_BLAST_MIN、QARTEZ_GUARD_ACK_TTL_SECS 调整，或通过 QARTEZ_GUARD_DISABLE=1 禁用。

基准测试

不是宣称，而是实测，且可复现。运行 make bench 并自行验证。

核心数据

相较于 Glob + Grep + Read + git log，汇总 Token 节省：+91.8% （在 Qartez 自测的全部 28 个场景中，MCP Token 总数为 38,789，非 MCP Token 总数为 472,109。此处采用保守的低估：28 个场景中有 10 个场景的非 MCP 模拟不完整——这些行仍会将 MCP Token 计入两项总数。在 18 个可公平逐 Token 比较的场景中，节省率升至 +94.5%。）

LLM 评审质量（claude-opus-4-6）： 在五个维度（正确性、完整性、易用性、依据充分性、简洁性）的评估中，MCP 为 8.3 / 10，非 MCP 为 4.3 / 10，n=28。

会话成本背景。 一次典型的 Claude Code 会话，提示词开销约为 20,000 个 Token。运行一次 make bench 可节省约 433,000 个 Token，相当于省下 ~21 次空会话的预算，仅仅是因为通过合适的工具来处理问题。

按工具细分（Rust 自测基准）

18 个工具均有完整的非 MCP 模拟（以相同 token 数进行公平比较）：

另外 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          # 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

底层工作原理

共分为 4 层，只需计算一次，每次工具调用时从 SQLite 查询。

1. Tree-sitter 解析

每个源文件都会由对应语言的 tree-sitter 语法进行解析。无需 LSP 服务，无需为每种语言安装 SDK，也没有冷启动开销。解析器会提取符号（函数、方法、类型、常量）、其签名、行范围、导出可见性、导入关系，以及 21 种命令式语言中每个函数的圈复杂度。

2. 结构形状哈希

函数体会被规范化为 AST 骨架（标识符、字面量和注释会被统一处理并忽略），然后进行哈希。具有相同哈希的两个符号即为结构克隆。这正是 qartez_clones 查询的内容。

3. 图分析

导入边构成有向图。其上会运行 3 种算法：

• PageRank——Google 曾用于网页排名的同一种随机游走算法。应用于导入图后，它会找出构成项目架构骨干的文件。
• 影响范围——通过反向 BFS 统计某项更改会传递影响多少个文件。qartez_impact 会利用这一点，在编辑前发出警告。
• Leiden 聚类——社区检测算法，可将代码库划分为逻辑模块，用于自动生成架构知识库和 qartez_boundaries 起始配置。

4. Git 历史挖掘

遍历最近 N 次提交（默认 300 次），统计在同一提交中出现的文件对。这能揭示导入图无法发现的逻辑耦合——文件之间没有导入关联，却总是一起修改。

qartez_impact、qartez_context 和 qartez_hotspots 将这些信号融合——PageRank + 影响范围 + 联合变更 + 复杂度——给出一个综合排名结果。没有其他 MCP 服务能结合这四项。

存储

所有内容都存储在 .qartez/index.db 中，这是一个包含 FTS5 全文索引的 SQLite 文件。启动时，Qartez 只会重新解析修改时间发生变化的文件。服务器运行期间会自动启用文件监视器——编辑和新增的文件都会在后台重新索引，全程无需停机。传入 --no-watch 可将其禁用。

传输方式

Qartez 使用 stdio（stdin/stdout JSON-RPC）通信，这是标准的 MCP 传输方式。无需 HTTP 服务器，无需分配端口，也不会暴露到网络。IDE 会将 qartez 二进制文件作为子进程启动，并通过管道交换消息。

支持的语言

单个二进制文件，无需按语言单独配置。所有 37 种语言均由 tree-sitter 解析（对于缺少兼容语法的格式，则使用正则表达式回退方案）。其中 21 种命令式语言还会计算每个函数的圈复杂度，为 qartez_hotspots 提供支持。

亮点： TypeScript、Rust、Go、Python、Java、Kotlin、Swift、C#、C/C++、Ruby、PHP、Dart、Scala、Elixir、Zig、Lua、Haskell、OCaml、R，以及另外 17 种语言。全部 21 种命令式语言均支持圈复杂度评分。

与其他方案的比较

2026 年，MCP 代码库智能领域竞争激烈。本节介绍直接的开源竞争项目、企业平台和相关生态系统。所有星标数均已于 2026 年 4 月对照各项目的 GitHub 仓库核实。

直接的开源 MCP 竞争项目

有九个项目与“用于代码库智能的 MCP 服务”这一细分领域相同，以下按 GitHub 星标数排序。

面向愿意牺牲本地优先和开源特性，以换取精致体验或跨代码库规模的用户，解决相同问题的商业平台：

• Sourcegraph Cody / Amp - 编译器级 SCIP 索引器，自 2026 年起提供官方 MCP 服务。以云端为先，企业级定价。
• Augment Code - B 轮融资 2.27 亿美元。实时语义索引 + 跨 400k+ 个文件的代码关系图，自 2025 年 10 月起提供官方 MCP 服务。依赖云端。
• Deep Graph MCP (CodeGPT) - 392 个星标。托管于云端的知识图谱后端；将任何仓库 URL 中的 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 为你提供这些平台出售的同等结构化智能——完全在你的笔记本电脑上运行，而且免费。

相邻生态（类别不同，解决的问题相同）

• Aider repo-map - Paul Gauthier 的 CLI 于 2023 年 10 月率先将 tree-sitter 与 PageRank 结合。它集成在 aider CLI 中，而非作为 MCP 服务。RepoMapper 将单个 repo_map 输出封装为 MCP。
• Continue.dev - MCP 客户端，而非服务。其文档明确建议将 Continue 与专用代码图 MCP 服务配合使用——Qartez 正是承担这一角色。
• Context7、Mem0、Pieces LTM - 记忆和文档工具，而非代码库索引器。它们可以互补，而非竞争。
• Block Goose、Cline、Codebuff - 使用 MCP 服务的编码 Agent 客户端。它们是 Qartez 这类工具的使用者。

Qartez 的不同之处

1. 四信号影响分析。 qartez_impact、qartez_diff_impact、qartez_context 和 qartez_hotspots 将 PageRank 重要性、静态影响范围、Git 共同变更和圈复杂度融合为一个排序结果。其他项目都没有同时结合这四项指标。

2. 在一个服务中提供热点、克隆、边界、安全、代码异味、测试缺口、知识和趋势分析。 qartez_hotspots 按复杂度 × 耦合度 × 变更频率对仓库中最危险的函数进行排序。qartez_clones 通过 AST 形状哈希查找重复逻辑。qartez_boundaries 强制执行在 .qartez/boundaries.toml 中声明的架构规则。qartez_security 扫描漏洞模式，并根据 PageRank 评分。qartez_smells 检测上帝函数、过长的参数列表和特性依恋。qartez_test_gaps 查找未经测试的源文件，并按风险排序。qartez_knowledge 通过 Git blame 揭示单点知识风险。qartez_trend 逐次提交跟踪函数复杂度的变化。在其他地方，这些是八种独立的商业产品；在这里，每种只需一次 MCP 调用。

3. 通过 MCP 进行重构，支持预览和应用。 qartez_rename、qartez_move 和 qartez_rename_file 让助手通过一次 MCP 调用即可完成原子化、可审查的重构。Serena 通过 LSP 提供重命名功能（需要按语言安装服务器）；其余服务都没有提供重构工具。

4. 内置安全网。 修改保护机制会阻止 AI 在未先审查影响范围的情况下编辑高影响文件。主要竞品对比表中的其他服务都没有提供此功能。

5. 用数据衡量，而非空口声称。 28 个场景，LLM 评审质量评分为 8.3/10，对比结果为 4.3/10，并提供每种工具的令牌数量和延迟。所有结果都可通过 make bench（单语言）或 make bench-all（5 种语言，并提供跨语言摘要）复现。

6. 原生 Rust、本地优先、零云端依赖。 三个二进制文件（qartez、qartez-guard、qartez-setup）。无需 Python 运行时、向量数据库或云账户。所有操作都在你的机器上运行。代码不会离开本机。可选的 semantic cargo 功能可添加本地嵌入搜索，但默认构建无需下载模型。

命令行选项

Qartez 也可作为独立 CLI 使用。运行 qartez <tool_name>（例如，qartez map、qartez find Config、qartez impact src/server/mod.rs），即可直接在终端中使用任何核心或分析工具，无需 MCP 客户端。

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             6 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。想要添加一种语言、修复解析器或改进工具？欢迎提交拉取请求——请先阅读 CONTRIBUTING.md 和 CODE_OF_CONDUCT.md。非简单的 PR 需要签署 CLA.md。

git clone https://github.com/kuberstar/qartez-mcp.git
cd qartez-mcp
cargo build
cargo test

每个版本的发行说明都收录在 CHANGELOG.md 中。

安全

发现了漏洞？请勿公开提交 issue。 请按照 SECURITY.md 中的漏洞披露政策操作。

许可证

采用 Qartez Small Team License（个人和小型团队免费）和 Qartez Commercial License（适用于其他所有人）双重许可。请在 LICENSE 中阅读完整条款，并在 COMMERCIAL.md 中查看商业条款摘要。SPDX 标识符：LicenseRef-Qartez-Dual。

Grep 曾为人类而生。Qartez 专为 Agent 打造。

如果 Qartez 能为你节省哪怕 10% 的每月 AI 账单，请为项目点亮 Star——这是唯一能让其他开发者知道这种方法值得一试的信号。