Qartez MCP

Qartez MCP

Visão de raio-X para o seu código-fonte — criado para agentes de IA, não para humanos.

O primeiro servidor de inteligência de código projetado desde o primeiro dia para ser
consumido por modelos de linguagem, não lido por pessoas. Reduz o uso de tokens de IA em ~94%.

Início rápido · 43 Ferramentas · Proteção · Benchmarks · Comparação · 37 Linguagens · CLI · Contribuição · Segurança · Changelog

Por que isso existe

grep, find, cat, e ls foram inventados na década de 1970 para humanos que leem um arquivo por vez em um terminal. Meio século depois, seu assistente de IA ainda os utiliza — escaneando arquivos byte por byte, relendo os mesmos diretórios a cada pergunta, adivinhando o que importa e queimando seus tokens em um trabalho para o qual as ferramentas nunca foram projetadas.

Qartez é uma espécie diferente de ferramenta. Não é um wrapper em torno do grep. É um grafo de conhecimento pré-computado do seu repositório — símbolos, imports, arestas de chamada, raios de explosão, PageRank, co-alteração git, complexidade ciclomática — servido a qualquer LLM através do Model Context Protocol. O agente para de ler seu código-fonte e começa a consultá-lo.

Pense nisso como o primeiro órgão sensorial projetado especificamente para agentes de codificação. O Grep vê uma linha por vez. O Qartez vê a forma inteira do código-fonte em um único olhar.

Toda vez que seu assistente de IA toca no código, três coisas caras acontecem:

1. Ele lê os mesmos arquivos repetidamente. Sem memória do repositório. Cada pergunta começa do zero. Você paga por cada token — de novo e de novo.

2. Ele não consegue ver o que vai quebrar. Seu assistente edita utils.ts sem saber que outros 14 arquivos o importam. Você descobre no CI. Ou em produção.

3. Ele desperdiça tokens para encontrar coisas. "Onde handleRequest está definido?" vira um Grep em 200 arquivos, Read em 5 candidatos e 1.600 tokens queimados antes de encontrar a resposta. O Qartez responde isso em 50 tokens.

A solução não é um modelo mais inteligente. É um índice mais inteligente.

Início rápido

Suporte de plataforma: macOS 13+, Ubuntu 22.04+ (e outros Linux modernos, gnu ou musl), Windows (PowerShell nativo 5.1+/7+) e WSL 2. Arquiteturas: x86_64 e arm64. MSRV Rust é 1.88 — necessário apenas para plataformas não suportadas ou para a saída de emergência --from-source.

Instalação (recomendada)

Escolha o comando de uma linha para o seu sistema operacional. Ambos os comandos fazem a mesma coisa: baixam um binário pré-compilado, verificam seu SHA-256 contra o SHA256SUMS do release, instalam os três binários (qartez, qartez-guard, qartez-setup) e iniciam o qartez-setup em modo não interativo para configurar todos os IDEs compatíveis com MCP que detectar (incluindo os hooks de proteção contra modificação para Claude Code).

macOS / Linux / WSL 2 — instalador bash, os binários ficam em ~/.local/bin/:

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

Windows (PowerShell nativo 5.1+/7+) — instalador PowerShell, os binários ficam em %LOCALAPPDATA%\Programs\qartez\:

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

Plataformas não suportadas (ex.: linux-musl arm64 sem artefato publicado) recorrem automaticamente a um cargo build local; passe --from-source (bash) ou -FromSource (PowerShell) para forçar esse caminho. O MSRV Rust 1.88 é necessário apenas para esse fallback.

Abra qualquer projeto no seu IDE — o Qartez o indexa automaticamente no início da sessão. Nenhuma etapa manual é necessária. O observador de arquivos mantém o índice atualizado conforme você edita.

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

O que o Qartez faz

O Qartez constrói um grafo de conhecimento do seu código-fonte — uma vez — e o serve a qualquer assistente de IA através do MCP. Em vez de escanear arquivos do zero a cada pergunta, seu assistente consulta um índice pré-computado que sabe:

• Quais arquivos importam mais (PageRank no grafo de imports)
• O que quebra se você alterar um arquivo (análise de raio de explosão)
• Quais arquivos sempre mudam juntos (mineração de co-alteração git)
• Quais funções são as mais perigosas de tocar (complexidade ciclomática x acoplamento x churn)
• Onde cada símbolo está definido, quem o usa e quem o chama
• Quais blocos de código estão duplicados (hash estrutural de forma AST)
• Quais fronteiras de arquitetura os imports estão violando
• Quais tipos implementam um trait/interface, e vice-versa

O resultado: sua IA trabalha mais rápido, usa menos tokens, refatora com segurança e para de fazer alterações às cegas em arquivos estruturais.

Antes e depois

As 43 ferramentas

Pense nelas como a biblioteca padrão para compreensão de código por IA. Cada uma substitui um fluxo de trabalho humano de várias etapas por uma única chamada eficiente em tokens que o agente pode raciocinar.

As ferramentas são organizadas em camadas com divulgação progressiva. As ferramentas principais estão sempre disponíveis. Camadas adicionais podem ser desbloqueadas sob demanda via qartez_tools enable: ["analysis"] (ou "all").

Principais (sempre disponíveis)

Análise (desbloqueie via qartez_tools)

Refatoração (desbloqueie via qartez_tools)

Meta (desbloqueie via qartez_tools)

Gerenciamento de níveis

Prompts de fluxo de trabalho

Seis receitas prontas para uso que encadeiam as ferramentas acima na ordem correta. Invoque-as como comandos de barra no Claude Code ou em qualquer cliente MCP que suporte prompts.

Guarda de modificação

O Qartez vem com uma rede de segurança que impede sua IA de editar cegamente arquivos críticos.

O binário qartez-guard se conecta ao sistema PreToolUse do Claude Code e bloqueia Edit/Write/MultiEdit em qualquer arquivo que exceda um limite de PageRank ou raio de explosão — até que a IA chame qartez_impact primeiro para reconhecer o risco.

Como funciona:

1. A IA tenta editar src/server/mod.rs
2. A guarda verifica: PageRank 0,23 (> limite de 0,05), raio de explosão 10 (>= limite de 10)
3. A edição é bloqueada com uma explicação listando quais limites foram acionados
4. A IA chama qartez_impact file_path=src/server/mod.rs — revisa o raio de explosão
5. A guarda concede uma janela de edição de 10 minutos para aquele arquivo
6. A IA tenta a edição novamente — permitida

Zero configuração. Ajustável via QARTEZ_GUARD_PAGERANK_MIN, QARTEZ_GUARD_BLAST_MIN, QARTEZ_GUARD_ACK_TTL_SECS ou desabilitada com QARTEZ_GUARD_DISABLE=1.

Benchmarks

Não são alegações. Medidos. Reproduzíveis. Execute make bench e verifique você mesmo.

Destaque

Economia agregada de tokens vs Glob + Grep + Read + git log: +91,8% (soma de MCP 38.789 / soma de não-MCP 472.109 tokens em todos os 28 cenários no auto-bench do Qartez. Subcontagem conservadora: 10 de 28 cenários têm uma simulação não-MCP incompleta — essas linhas ainda contribuem com seus tokens MCP para ambas as somas. Nos 18 cenários com comparação justa token a token, a economia sobe para +94,5%.)

Qualidade avaliada por LLM (claude-opus-4-6): MCP 8,3 / 10 vs não-MCP 4,3 / 10 em cinco eixos (correção, completude, usabilidade, fundamentação, concisão), n=28.

Contexto de custo de sessão. Uma sessão típica do Claude Code começa com ~20.000 tokens de overhead de prompt. Uma única execução de make bench economiza ~433.000 tokens — ~21 sessões vazias de orçamento recuperadas, apenas roteando perguntas pela ferramenta certa.

Detalhamento por ferramenta (auto-bench Rust)

18 ferramentas com simulações não-MCP completas (comparação justa token a token):

10 ferramentas analíticas adicionais não têm equivalente significativo de grep/read — elas resolvem problemas que a pilha não-MCP não consegue resolver de forma alguma:

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

Como funciona por baixo dos panos

Quatro camadas, calculadas uma vez, consultadas do SQLite em cada chamada de ferramenta.

1. Parsing com tree-sitter

Cada arquivo de código-fonte é analisado por uma gramática tree-sitter específica da linguagem. Sem servidor LSP, sem instalação de SDKs por linguagem, sem penalidade de cold-start. O parser extrai símbolos (funções, métodos, tipos, constantes), suas assinaturas, intervalos de linhas, visibilidade de exportação, relações de importação e — para 21 linguagens imperativas — complexidade ciclomática por função.

2. Hash de forma estrutural

Corpos de funções são canonicalizados em um esqueleto de AST (identificadores, literais e comentários normalizados) e transformados em hash. Dois símbolos com o mesmo hash são clones estruturais. É isso que as consultas qartez_clones usam.

3. Análise de grafo

Arestas de importação formam um grafo direcionado. Três algoritmos são executados sobre ele:

• PageRank — o mesmo algoritmo de caminhada aleatória que o Google usava para páginas web. Aplicado ao seu grafo de importações, ele revela os arquivos que formam a espinha dorsal arquitetural do seu projeto.
• Blast radius — BFS reverso que conta quantos arquivos são afetados transitivamente por uma alteração. qartez_impact usa isso para alertar antes de edições.
• Leiden clustering — detecção de comunidades que particiona seu codebase em módulos lógicos para a wiki de arquitetura gerada automaticamente e a configuração inicial do qartez_boundaries.

4. Mineração do histórico do git

Percorre os últimos N commits (padrão: 300) e conta pares de arquivos que aparecem no mesmo commit. Isso revela acoplamento lógico que o grafo de importações não consegue enxergar — arquivos que não estão ligados por imports, mas são sempre editados juntos.

qartez_impact, qartez_context e qartez_hotspots fundem esses sinais — PageRank + blast + co-change + complexidade — em uma única resposta ranqueada. Nenhum outro servidor MCP combina os quatro.

Armazenamento

Tudo fica em .qartez/index.db — um único arquivo SQLite com índices de texto completo FTS5. Na inicialização, o Qartez reanalisa apenas os arquivos cujo horário de modificação mudou. O file watcher é ativado automaticamente enquanto o servidor está em execução — edições e novos arquivos são reindexados em segundo plano sem downtime. Passe --no-watch para desativá-lo.

Transporte

O Qartez se comunica via stdio (JSON-RPC por stdin/stdout), o transporte MCP padrão. Sem servidor HTTP, sem alocação de porta, sem exposição de rede. A IDE inicia o binário qartez como processo filho e troca mensagens por pipes.

Linguagens suportadas

Um único binário. Sem configuração por linguagem. Todas as 37 linguagens são analisadas por tree-sitter (com fallbacks de regex para formatos sem gramática compatível). 21 linguagens imperativas também recebem complexidade ciclomática por função, alimentando qartez_hotspots.

Destaques: TypeScript, Rust, Go, Python, Java, Kotlin, Swift, C#, C/C++, Ruby, PHP, Dart, Scala, Elixir, Zig, Lua, Haskell, OCaml, R e mais 17. Todas as 21 linguagens imperativas incluem pontuação de complexidade ciclomática.

Comparação com alternativas

O espaço de inteligência de codebase via MCP está concorrido em 2026. Esta seção cobre concorrentes OSS diretos, plataformas empresariais e ecossistemas adjacentes. Todas as contagens de estrelas foram verificadas no repositório GitHub de cada projeto em abril de 2026.

Concorrentes OSS MCP diretos

Nove projetos compartilham o nicho de "servidor MCP para inteligência de codebase", ordenados por estrelas no GitHub.

Alternativas empresariais e nativas de IDE

Plataformas comerciais que resolvem o mesmo problema para usuários dispostos a trocar local-first e open-source por polimento ou escala entre repositórios:

• Sourcegraph Cody / Amp - indexadores SCIP de nível compilador, servidor MCP oficial desde 2026. Cloud-first, preços empresariais.
• Augment Code - Série B de US$ 227M. Índice semântico em tempo real + grafo de relacionamento de código em mais de 400 mil arquivos, servidor MCP oficial desde outubro de 2025. Dependência de nuvem.
• Deep Graph MCP (CodeGPT) - 392 estrelas. Backend de grafo de conhecimento hospedado em nuvem; troque github.com por deepgraph.co em qualquer URL de repositório para obter um grafo de código pré-construído. Nenhuma indexação local necessária.
• JetBrains AI Assistant (IntelliJ 2025.2+) - servidor MCP embutido que expõe símbolos e diagnósticos de nível IDE. Apenas JetBrains.
• Cursor - modelo de embedding personalizado, índice compartilhado em equipe no Turbopuffer. IDE fechado, sem exposição MCP.
• Windsurf Cascade - recuperação M-Query baseada em RAG. IDE fechado, sem servidor MCP.

Qartez oferece a mesma inteligência estrutural que essas plataformas vendem - rodando inteiramente no seu laptop, gratuitamente.

Ecossistemas adjacentes (categoria diferente, mesmo problema)

• Aider repo-map - O CLI de Paul Gauthier foi pioneiro em tree-sitter + PageRank em outubro de 2023. Vive dentro do CLI aider, não como servidor MCP. O RepoMapper encapsula a saída única de repo_map como MCP.
• Continue.dev - MCP cliente, não servidor. Sua documentação recomenda explicitamente combinar o Continue com um servidor MCP de grafo de código dedicado - o papel que o Qartez preenche.
• Context7, Mem0, Pieces LTM - ferramentas de memória e documentação, não indexadores de código. Complementares, não concorrentes.
• Block Goose, Cline, Codebuff - clientes de agentes de codificação que consomem servidores MCP. Eles são os usuários de ferramentas como o Qartez.

O que torna o Qartez diferente

1. Análise de impacto com quatro sinais. qartez_impact, qartez_diff_impact, qartez_context e qartez_hotspots fundem importância PageRank, raio de explosão estático, co-mudança git e complexidade ciclomática em uma única resposta classificada. Nenhum outro projeto combina os quatro.

2. Hotspots, clones, limites, segurança, cheiros, lacunas de teste, conhecimento e tendências em um único servidor. qartez_hotspots classifica as funções mais perigosas do repositório por complexidade x acoplamento x churn. qartez_clones encontra lógica duplicada via hash de forma AST. qartez_boundaries aplica regras de arquitetura declaradas em .qartez/boundaries.toml. qartez_security verifica padrões de vulnerabilidade pontuados por PageRank. qartez_smells detecta funções deus, listas longas de parâmetros e inveja de recurso. qartez_test_gaps encontra arquivos de origem não testados classificados por risco. qartez_knowledge revela riscos de fator de ônibus a partir do git blame. qartez_trend acompanha como a complexidade de uma função evoluiu commit a commit. São oito produtos comerciais separados em outros lugares, uma chamada MCP cada aqui.

3. Refatoração via MCP com pré-visualização e aplicação. qartez_rename, qartez_move e qartez_rename_file dão ao assistente refatorações atômicas e revisáveis em uma única chamada MCP. Serena oferece renomeação via LSP (exige instalação de servidor por linguagem); os demais servidores não trazem nenhuma ferramenta de refatoração.

4. Rede de segurança integrada. O guarda de modificação impede que sua IA edite arquivos de alto impacto sem revisar primeiro o raio de explosão. Nenhum outro servidor na tabela principal de concorrentes oferece isso.

5. Medido, não afirmado. 28 cenários, qualidade 8,3/10 vs 4,3/10 avaliada por LLM, contagens de tokens por ferramenta e latência. Tudo reproduzível com make bench (linguagem única) ou make bench-all (5 linguagens com resumo entre linguagens).

6. Rust nativo, local-first, zero dependência de nuvem. Três binários (qartez, qartez-guard, qartez-setup). Sem runtime Python, sem banco de dados vetorial, sem conta em nuvem. Tudo roda na sua máquina. Nenhum código sai do seu ambiente. Um recurso opcional de cargo semantic adiciona busca de embeddings local, mas a compilação padrão não precisa baixar modelo.

Opções de linha de comando

Qartez também funciona como CLI autônomo. Execute qartez <tool_name> (por exemplo, qartez map, qartez find Config, qartez impact src/server/mod.rs) para usar qualquer ferramenta principal ou de análise diretamente do terminal, sem um cliente 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

Contribuindo

Encontrou um bug? Abra uma issue. Quer adicionar uma linguagem, corrigir um parser ou melhorar uma ferramenta? Pull requests são bem-vindos - leia CONTRIBUTING.md e CODE_OF_CONDUCT.md primeiro. PRs não triviais exigem a assinatura do CLA.md.

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

As notas de versão de cada versão estão em CHANGELOG.md.

Segurança

Encontrou uma vulnerabilidade? Não abra uma issue pública. Siga a política de divulgação em SECURITY.md.

Licença

Licenciado duplamente sob a Qartez Small Team License (gratuita para indivíduos e pequenas equipes) e a Qartez Commercial License (para todos os demais). Leia o texto completo em LICENSE e veja COMMERCIAL.md para o resumo dos termos comerciais. Identificador SPDX: LicenseRef-Qartez-Dual.

Grep era para humanos. Qartez é para agentes.

Se o Qartez economizar até 10% da sua conta mensal de IA, dê uma estrela no repositório - é o único sinal que diz a outros desenvolvedores que essa abordagem vale a pena tentar.