Qartez MCP

X-ray vision for your codebase - built for AI agents, not humans.

The first code-intelligence server designed from day one to be
consumed by language models, not read by people. Cuts AI token usage by ~94%.

Quickstart · 43 Tools · Guard · Benchmarks · Comparison · 37 Languages · CLI · Contributing · Security · Changelog

Why this exists

grep, find, cat, and ls were invented in the 1970s for humans reading one file at a time in a terminal. Half a century later, your AI assistant is still using them - scanning files byte by byte, re-reading the same directories on every question, guessing at what matters, and burning your tokens on work the tools were never designed to do.

Qartez is a different species of tooling. It is not a wrapper around grep. It is a pre-computed knowledge graph of your repository - symbols, imports, call edges, blast radii, PageRank, git co-change, cyclomatic complexity - served to any LLM through the Model Context Protocol. The agent stops reading your codebase and starts querying it.

Think of it as the first purpose-built sensory organ for coding agents. Grep sees one line at a time. Qartez sees the entire shape of the codebase in one glance.

Every time your AI assistant touches code, three expensive things happen:

1. It reads the same files over and over. No memory of the repo. Every question starts from scratch. You pay for every token - again and again.

2. It can't see what will break. Your assistant edits utils.ts without knowing 14 other files import it. You find out in CI. Or in production.

3. It wastes tokens finding things. "Where is handleRequest defined?" turns into Grep across 200 files, Read on 5 candidates, and 1,600 tokens burned before it finds the answer. Qartez answers that in 50 tokens.

The fix isn't a smarter model. It's a smarter index.

Quickstart

Platform support: macOS 13+, Ubuntu 22.04+ (and other modern Linux, gnu or musl), Windows (native PowerShell 5.1+/7+) and WSL 2. Architectures: x86_64 and arm64. Rust MSRV is 1.88 - only needed for unsupported platforms or the --from-source escape hatch.

Install (recommended)

Pick the one-liner for your operating system. Both commands do the same thing: download a pre-built binary, verify its SHA-256 against the release's SHA256SUMS, install the three binaries (qartez, qartez-guard, qartez-setup), and launch qartez-setup in non-interactive mode to configure every MCP-capable IDE it detects (including the modification-guard hooks for Claude Code).

macOS / Linux / WSL 2 - bash installer, binaries land in ~/.local/bin/:

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

Windows (native PowerShell 5.1+/7+) - PowerShell installer, binaries land in %LOCALAPPDATA%\Programs\qartez\:

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

Unsupported platforms (e.g. linux-musl arm64 without a published artifact) fall back to a local cargo build automatically; pass --from-source (bash) or -FromSource (PowerShell) to force that path. Rust MSRV 1.88 is only required for that fallback.

Open any project in your IDE - Qartez indexes it automatically on session start. No manual step needed. The file watcher keeps the index fresh as you edit.

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

What Qartez does

Qartez builds a knowledge graph of your codebase - once - and serves it to any AI assistant through MCP. Instead of scanning files from scratch on every question, your assistant queries a pre-computed index that knows:

• Which files matter most (PageRank on the import graph)
• What breaks if you change a file (blast radius analysis)
• Which files always change together (git co-change mining)
• Which functions are the most dangerous to touch (cyclomatic complexity x coupling x churn)
• Where every symbol is defined, who uses it, and who calls it
• Which blocks of code are duplicated (structural AST shape hashing)
• Which architecture boundaries the imports are violating
• What types implement a trait/interface, and vice versa

The result: your AI works faster, uses fewer tokens, refactors safely, and stops making blind changes to load-bearing files.

Before and after

The 43 tools

Think of these as the standard library for AI code understanding. Each one replaces a multi-step human workflow with a single, token-efficient call the agent can reason about.

Tools are organized into tiers with progressive disclosure. Core tools are always available. Additional tiers can be unlocked on demand via qartez_tools enable: ["analysis"] (or "all").

Core (always available)

Analysis (unlock via qartez_tools)

Refactor (unlock via qartez_tools)

Meta (unlock via qartez_tools)

Tier management

Workflow prompts

Six ready-to-use recipes that chain the tools above in the right order. Invoke them as slash commands in Claude Code or any MCP client that supports prompts.

Modification guard

Qartez ships a safety net that prevents your AI from blindly editing load-bearing files.

The qartez-guard binary hooks into Claude Code's PreToolUse system and blocks Edit/Write/MultiEdit on any file that exceeds a PageRank or blast-radius threshold - until the AI calls qartez_impact first to acknowledge the risk.

How it works:

1. AI tries to edit src/server/mod.rs
2. Guard checks: PageRank 0.23 (> 0.05 threshold), blast radius 10 (>= 10 threshold)
3. Edit is blocked with an explanation listing which thresholds fired
4. AI calls qartez_impact file_path=src/server/mod.rs - reviews the blast radius
5. Guard grants a 10-minute edit window for that file
6. AI retries the edit - allowed

Zero configuration. Tuneable via QARTEZ_GUARD_PAGERANK_MIN, QARTEZ_GUARD_BLAST_MIN, QARTEZ_GUARD_ACK_TTL_SECS, or disabled with QARTEZ_GUARD_DISABLE=1.

Benchmarks

Not claims. Measured. Reproducible. Run make bench and verify yourself.

Headline

Aggregate token savings vs Glob + Grep + Read + git log: +91.8% (sum of MCP 38,789 / sum of non-MCP 472,109 tokens across all 28 scenarios on the Qartez self-bench. Conservative under-count: 10 of 28 scenarios have an incomplete non-MCP sim - those rows still contribute their MCP tokens to both sums. On the 18 scenarios with a fair token-to-token comparison the saving rises to +94.5%.)

LLM-judge quality (claude-opus-4-6): MCP 8.3 / 10 vs non-MCP 4.3 / 10 across five axes (correctness, completeness, usability, groundedness, conciseness), n=28.

Session cost context. A typical Claude Code session starts at ~20,000 tokens of prompt overhead. A single make bench run saves ~433,000 tokens - ~21 empty sessions worth of budget bought back, just from routing questions through the right tool.

Per-tool breakdown (Rust self-bench)

18 tools with complete non-MCP simulations (fair token-to-token comparison):

10 additional analytical tools have no meaningful grep/read equivalent - they solve problems the non-MCP stack cannot solve at all:

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

How it works under the hood

Four layers, computed once, queried from SQLite on every tool call.

1. Tree-sitter parsing

Every source file is parsed by a language-specific tree-sitter grammar. No LSP server, no per-language SDK installs, no cold-start penalty. The parser extracts symbols (functions, methods, types, constants), their signatures, line ranges, export visibility, import relationships, and - for 21 imperative languages - cyclomatic complexity per function.

2. Structural shape hashing

Function bodies are canonicalized into an AST skeleton (identifiers, literals, and comments normalized away) and hashed. Two symbols with the same hash are structural clones. That's what qartez_clones queries.

3. Graph analysis

Import edges form a directed graph. Three algorithms run on top:

• PageRank - the same random-walk algorithm Google used for web pages. Applied to your import graph, it surfaces the files that form the architectural backbone of your project.
• Blast radius - reverse BFS that counts how many files are transitively affected by a change. qartez_impact uses this to warn before edits.
• Leiden clustering - community detection that partitions your codebase into logical modules for the auto-generated architecture wiki and the qartez_boundaries starter config.

4. Git history mining

Walks the last N commits (default 300) and counts file pairs that appear in the same commit. This reveals logical coupling