Qartez MCP

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

Quickstart · 27 Tools · Benchmarks · Comparison · 37 Languages · Contributing

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

Prerequisites: macOS or Linux (Windows via WSL 2). Rust toolchain is installed automatically if missing.

One command to install:

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

The installer checks for Rust (installs via rustup if missing), builds the release binaries, 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.

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

Works with 19 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, Claude Desktop, Gemini, Cursor, Windsurf, Kiro, Zed, Continue.dev, Copilot CLI, Amazon Q, Amp, Cline, Roo Code, Goose, Warp, Augment, OpenCode, Codex CLI, Antigravity.

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

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 27 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

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.

Benchmarks

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

Headline

Aggregate token savings vs Glob + Grep + Read + git log: +91.5%(sum of MCP 8,604 / sum of non-MCP 101,740 tokens across 25 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=25.

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, qartez_wiki, qartez_diff_impact, qartez_hierarchy, qartez_trend, and qartez_tools are analytical tools with no meaningful grep/read equivalent. They solve problems the non-MCP stack cannot solve at all.

make bench-all runs the same 25-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.

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.

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

Supported languages

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

Highlights: TypeScript, Rust, Go, Python, Java, Kotlin, Swift, C#, C/C++, Ruby, PHP, Dart, Scala, Elixir, Zig, Lua, Haskell, OCaml, R, and 17 more. All 21 imperative languages include cyclomatic complexity scoring.

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.

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.

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_diff_impact, qartez_context, and qartez_hotspots fuse PageRank importance, static blast radius, git co-change, and cyclomatic complexity into one ranked answer. No other project combines all four.

2. Hotspots, clones, boundaries, security, and trends in one server. qartez_hotspots ranks the most dangerous functions in the repo by complexity x coupling x churn. qartez_clones finds duplicated logic via AST shape hashing. qartez_boundaries enforces architecture rules declared in .qartez/boundaries.toml. qartez_security scans for vulnerability patterns scored by PageRank. qartez_trend tracks how a function's complexity evolved commit by commit. These are five 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); the remaining 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. No other server in the main competitor table ships this.

5. Measured, not claimed. 25 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).

6. Rust-native, local-first, zero cloud dependency. Three binaries (qartez-mcp, qartez-guard, qartez-setup). No Python runtime, no vector database, no cloud account. Everything runs on your machine. No code leaves the box. An optional semantic cargo feature adds local embedding search, but the default build needs no model download.

Command-line options

src/
  main.rs                  Entry point: index, compute, start server
  lib.rs                   Library root (re-exports)
  cli.rs                   CLI argument parsing
  config.rs                Project configuration and root detection
  error.rs                 Error types
  toolchain.rs             Toolchain detection (Cargo, npm, Go, etc.)
  watch.rs                 File watcher for incremental re-indexing
  guard.rs                 Guard acknowledgment helpers
  embeddings.rs            Local embedding model for qartez_semantic (opt-in)
  server/
    mod.rs                 MCP server - all 27 tool handlers
    prompts.rs             5 workflow prompt templates
    tiers.rs               Progressive tool disclosure (core/analysis/refactor/meta)
    cache.rs               Response caching
    helpers.rs             Shared handler utilities
    overview.rs            Overview/map generation
    params.rs              Tool parameter structs
    treesitter.rs          Tree-sitter integration helpers
  index/
    mod.rs                 Index module root
    walker.rs              File discovery (respects .gitignore)
    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
  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)
scripts/                   Hook + snippet assets embedded by qartez-setup
benchmarks/fixtures.toml   Pinned OSS repos for multi-language benchmarks

Contributing

Found a bug? Open an issue. Want to add a language, fix a parser, or improve a tool? Pull requests are welcome.

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

License

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

Grep was for humans. Qartez is for agents. make deploy - and give your assistant the senses it was missing. If Qartez saves you even 10% of your monthly AI bill, star the repo - it's the only signal that tells other builders this approach is worth trying.