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 · 30 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), Windows via WSL 2. Architectures: x86_64 and arm64. Rust MSRV is 1.88 - the installer fetches it via rustup if missing.

Install (recommended)

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

The installer checks for Rust, builds the three release binaries (qartez, qartez-guard, qartez-setup), installs them to ~/.local/bin/, and launches qartez-setup in non-interactive mode. The setup wizard 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.

Install via 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

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

Transport

Qartez communicates over stdio (stdin/stdout JSON-RPC), the standard MCP transport. No HTTP server, no port allocation, no network exposure. The IDE launches the qartez binary as a child process and exchanges messages over pipes.

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, smells, test gaps, knowledge, 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_smells detects god functions, long parameter lists, and feature envy. qartez_test_gaps finds untested source files ranked by risk. qartez_knowledge surfaces bus-factor risks from git blame. qartez_trend tracks how a function's complexity evolved commit by commit. These are eight 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. 28 scenarios, 8.3/10 vs 4.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, 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

Qartez also works as a standalone CLI. Run qartez <tool_name> (e.g., qartez map, qartez find Config, qartez impact src/server/mod.rs) to use any core or analysis tool directly from the terminal without an MCP client.

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

Contributing

Found a bug? Open an issue. Want to add a language, fix a parser, or improve a tool? Pull requests are welcome - read CONTRIBUTING.md and CODE_OF_CONDUCT.md first. Non-trivial PRs require signing the CLA.md.

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

Release notes for every version live in CHANGELOG.md.

Security

Found a vulnerability? Do not open a public issue. Follow the disclosure policy in SECURITY.md.

License

Dual-licensed under the Qartez Small Team License (free for individuals and small teams) and the Qartez Commercial License (for everyone else). Read the full text in LICENSE, and see COMMERCIAL.md for the commercial terms summary. SPDX identifier: LicenseRef-Qartez-Dual.

Grep was for humans. Qartez is for agents.

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.