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 ~91%.

Why · Quickstart · 21 Tools · Benchmarks · Comparison · Star

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.

This is a new interface layer - the same way LSP was a new layer between editors and compilers. If you build AI tooling, you care about this. If you pay an AI bill, you really care about this.

The problem

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.

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 × coupling × 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

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

Before and after

Quickstart

One command. No prerequisites needed — the installer handles everything.

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

The installer checks for Rust (installs via rustup if missing), builds the release binaries, runs the test suite, installs them to ~/.local/bin/, and launches qartez-setup in non-interactive mode - it auto-detects every MCP-capable IDE on your machine and configures them all in one pass, including the modification-guard hooks for Claude Code.

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

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.

Works with 7 editors and agents

A single Rust binary (qartez-setup) detects and configures every supported editor. No per-editor shell scripts, no copy-paste 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

Supported out of the box: Claude Code, Cursor, Windsurf, Zed, Continue.dev, OpenCode, Codex CLI.

Benchmarks

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

Headline

Aggregate token savings vs Glob + Grep + Read + git log: +91.5%
(Σ MCP 8,604 / Σ non-MCP 101,740 tokens across 23 scenarios on the Qartez self-bench.)

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

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

Per-tool breakdown (Rust self-bench)

qartez_hotspots, qartez_clones, qartez_boundaries, and qartez_wiki are analytical tools with no meaningful grep/read equivalent - they solve problems the non-MCP stack cannot solve at all.

Multi-language bench

make bench-all runs the same 23-scenario harness against five pinned OSS fixtures - colinhacks/zod (TypeScript), spf13/cobra (Go), encode/httpx (Python), FasterXML/jackson-core (Java), plus the Qartez self-bench (Rust) - then emits a cross-language summary to reports/benchmark-<lang>.md plus a combined matrix. Every tool, every language, every scenario - measured with the cl100k_base tokenizer against a faithful Glob + Grep + Read + git log simulation.

The 21 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.

Navigate and understand

Analyze dependencies and risk

Find risk and duplication

Refactor safely

Build, test, document

Workflow prompts

Five 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.

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 16 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 that the import graph can't see - files that aren't linked by imports but are always edited together.

qartez_impact, qartez_context, and qartez_hotspots fuse these signals - PageRank + blast + co-change + complexity - into one ranked answer. No other MCP server combines all four.

Storage

Everything lives in .qartez/index.db - a single SQLite file with FTS5 full-text indices. On startup, Qartez re-parses only files whose modification time changed. The file watcher is enabled automatically while the server is running - edits and new files are re-indexed in the background with zero downtime. Pass --no-watch to disable it.

34 supported languages & formats

One binary. No per-language setup. All parsed by tree-sitter (with regex fallbacks for formats lacking a compatible grammar). 16 imperative languages also get cyclomatic complexity per function, powering qartez_hotspots.

Comparison with alternatives

The MCP codebase-intelligence space is crowded in 2026. This section covers direct OSS competitors, enterprise platforms, and adjacent ecosystems. All star counts were cross-checked against each project's GitHub repository in April 2026.

Direct OSS MCP competitors

Nine projects share the "MCP server for codebase intelligence" niche, sorted by GitHub stars.

Feature-by-feature comparison

Enterprise and IDE-native alternatives

Commercial platforms solving the same problem for users willing to trade local-first and open-source for polish or cross-repo scale:

• Sourcegraph Cody / Amp - compiler-grade SCIP indexers, official MCP server since 2026. Cloud-first, enterprise pricing.
• Augment Code - $227M Series B. Real-time semantic index + code-relationship graph across 400k+ files, official MCP server since Oct 2025. Cloud dependency.
• Deep Graph MCP (CodeGPT) - 392 stars. Cloud-hosted knowledge graph backend; swap github.com to deepgraph.co in any repo URL for a pre-built code graph. No local indexing needed.
• JetBrains AI Assistant (IntelliJ 2025.2+) - embedded MCP server exposing IDE-grade symbols and diagnostics. JetBrains-only.
• Cursor - custom embedding model, team-shared index in Turbopuffer. Closed IDE, no MCP exposure.
• Windsurf Cascade - RAG-based M-Query retrieval. Closed IDE, no MCP server.

Qartez gives you the same structural intelligence these platforms sell - running entirely on your laptop, for free.

Also notable

Smaller projects in the same space, sorted by stars:

Adjacent ecosystems (different category, same problem)

• Aider repo-map - Paul Gauthier's CLI pioneered tree-sitter + PageRank in October 2023. Lives inside the aider CLI, not as an MCP server. RepoMapper wraps the single repo_map output as MCP.
• Continue.dev - MCP client, not server. Its documentation explicitly recommends pairing Continue with a dedicated code-graph MCP server - the role Qartez fills.
• Context7, Mem0, Pieces LTM - memory and documentation tools, not codebase indexers. Complementary, not competing.
• Block Goose, Cline, Codebuff - coding agent clients that consume MCP servers. They are the users of tools like Qartez.

What makes Qartez different

1. Quad-signal impact analysis. qartez_impact, qartez_context, and qartez_hotspots fuse PageRank importance, static blast radius, git co-change, and cyclomatic complexity into one ranked answer. Codebase-Memory MCP ships blast radius and co-change separately but no PageRank and no fusion. code-review-graph ships blast radius alone. No other project combines all four.

2. Hotspots, clones, and boundaries - all in one server. qartez_hotspots ranks the most dangerous functions in the repo by complexity × coupling × churn. qartez_clones finds duplicated logic via AST shape hashing. qartez_boundaries enforces architecture rules declared in .qartez/boundaries.toml. These are three separate commercial products elsewhere - one MCP call each here.

3. Refactoring through MCP with preview and apply. qartez_rename, qartez_move, and qartez_rename_file give the assistant atomic, reviewable refactors in a single MCP call. Serena offers rename via LSP (requires per-language server install); move and rename-file need its paid JetBrains plugin. code-review-graph has rename preview only. The remaining six OSS servers ship no refactoring tools at all.

4. Built-in safety net. The modification guard blocks your AI from editing high-impact files without reviewing the blast radius first. Tree-sitter Analyzer (28 stars) has a similar concept; no one else in the main competitor table ships this.

5. Measured, not claimed. 23 scenarios, 7.9/10 vs 5.3/10 LLM-judge quality, per-tool token counts and latency - all reproducible with make bench (single-language) or make bench-all (5 languages with cross-language summary). code-review-graph publishes aggregate benchmarks (8.2×). Codebase-Memory MCP has an arXiv paper (10× tokens). No other OSS MCP publishes per-tool cross-language numbers with an LLM-judge quality axis.

6. Rust-native, local-first, embedding-free. Three binaries (qartez-mcp, qartez-guard, qartez-setup). No Python runtime, no embedding model, no vector database, no cloud account. Everything runs on your machine. No code leaves the box. Codanna is also Rust but requires a 150 MB embedding model. Codebase-Memory MCP is C and embedding-free, but has no PageRank, no refactoring, no hotspot scoring, no clone detection, no boundary enforcement, and no LLM-judge benchmarks.

Installation

One-shot deploy

git clone https://github.com/kuberstar/qartez-mcp.git
cd qartez-mcp
./install.sh

The installer handles everything: installs Rust via rustup if missing, builds the three release binaries (qartez-mcp, qartez-guard, qartez-setup), installs them to ~/.local/bin/, runs the test suite, and configures every detected IDE non-interactively via qartez-setup --yes - including hooks, MCP server registration, and the CLAUDE.md snippet for Claude Code.

make deploy does the same thing if you have make installed.

Restart your IDEs after install.

Windows: Use WSL 2 and run the commands above inside your WSL terminal. Native Windows is not supported.

Interactive install

make setup

Launches qartez-setup in interactive mode - it detects your installed IDEs and presents a checkbox list so you can pick which ones to configure.

Targeted install

qartez-setup --ide cursor,zed,claude

Configure a specific subset of IDEs only. Detected paths:

Every install path is idempotent and backs up the existing config.

Enable Qartez in a project

Qartez indexes automatically on session start — just open a project in your IDE. For manual re-indexing:

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

Claude Desktop (manual)

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

Uninstall

make uninstall

Removes Qartez from every configured IDE and deletes the binaries.

Command-line options

Project layout

src/
  main.rs                  Entry point: index, compute, start server
  cli.rs                   CLI argument parsing
  server/
    mod.rs                 MCP server - all 21 tool handlers
    prompts.rs             5 workflow prompt templates
  index/
    walker.rs              File discovery (respects .gitignore)
    parser.rs              Tree-sitter parser pool
    symbols.rs             Symbols / imports / references + AST shape hashing
    languages/             34 language adapters (16 with cyclomatic complexity)
  graph/
    pagerank.rs            PageRank on import graph
    blast.rs               Blast radius BFS
    leiden.rs              Community detection (Leiden clustering)
    boundaries.rs          Architecture-boundary rules engine
    wiki.rs                Architecture wiki renderer
  git/
    cochange.rs            Co-change pair mining
  storage/
    schema.rs              SQLite + FTS5 schema
    read.rs / write.rs     Query and mutation helpers
    models.rs              Row structs
  bin/
    setup.rs               Interactive IDE setup wizard
    guard.rs               PreToolUse modification guard
    benchmark.rs           Benchmark harness entry point
  benchmark/               Benchmark internals (cargo feature)
scripts/                   Hook + snippet assets embedded by qartez-setup
benchmarks/fixtures.toml   Pinned OSS repos for multi-language benchmarks

Running benchmarks

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 land in reports/benchmark.md / reports/benchmark.json for the single-language run, or reports/benchmark-<lang>.md plus a combined cross-language summary for bench-all.

License

Free for individuals, commercial license for businesses - see LICENSE.

Star history

If Qartez saves you even 10% of your monthly AI bill, star the repo - it's the only thing that tells other builders this approach is worth trying.

If you're working on AI agent infrastructure, a coding assistant, or your own MCP server: fork it, break it, and open an issue with what you broke. This is an open specification for what agent-native code tooling should look like, and every real-world bug report moves the standard forward.

Grep was for humans. Qartez is for agents.
make deploy - and give your assistant the senses it was missing.