Qartez MCP

Qartez MCP

Visión de rayos X para tu código base: construido para agentes de IA, no para humanos.

El primer servidor de inteligencia de código diseñado desde el primer día para ser
consumido por modelos de lenguaje, no leído por personas. Reduce el uso de tokens de IA en un ~94%.

Inicio rápido · 43 herramientas · Guard · Benchmarks · Comparación · 37 lenguajes · CLI · Contribuciones · Seguridad · Registro de cambios

Por qué existe esto

grep, find, cat y ls se inventaron en la década de 1970 para que los humanos leyeran un archivo a la vez en una terminal. Medio siglo después, tu asistente de IA todavía los usa: escaneando archivos byte a byte, releyendo los mismos directorios en cada pregunta, adivinando qué es importante y quemando tus tokens en trabajo para el que esas herramientas nunca fueron diseñadas.

Qartez es otra especie de herramienta. No es un envoltorio de grep. Es un grafo de conocimiento precomputado de tu repositorio: símbolos, imports, aristas de llamadas, radio de explosión, PageRank, co-cambio de git, complejidad ciclomática: servido a cualquier LLM a través del Protocolo de Contexto de Modelo. El agente deja de leer tu código base y empieza a consultarlo.

Piénsalo como el primer órgano sensorial diseñado específicamente para agentes de código. Grep ve una línea a la vez. Qartez ve la forma completa del código base de un vistazo.

Cada vez que tu asistente de IA toca código, ocurren tres cosas costosas:

1. Lee los mismos archivos una y otra vez. Sin memoria del repositorio. Cada pregunta empieza desde cero. Pagas por cada token, una y otra vez.

2. No puede ver qué se romperá. Tu asistente edita utils.ts sin saber que otros 14 archivos lo importan. Te enteras en CI. O en producción.

3. Desperdicia tokens buscando cosas. "¿Dónde está definido handleRequest?" se convierte en Grep en 200 archivos, Read en 5 candidatos y 1.600 tokens quemados antes de encontrar la respuesta. Qartez responde eso en 50 tokens.

La solución no es un modelo más inteligente. Es un índice más inteligente.

Inicio rápido

Soporte de plataformas: macOS 13+, Ubuntu 22.04+ (y otras distribuciones Linux modernas, gnu o musl), Windows (PowerShell nativo 5.1+/7+) y WSL 2. Arquitecturas: x86_64 y arm64. MSRV de Rust es 1.88: solo se necesita para plataformas no compatibles o la vía de escape de --from-source.

Instalación (recomendada)

Elige el comando de una línea para tu sistema operativo. Ambos comandos hacen lo mismo: descargan un binario precompilado, verifican su SHA-256 contra el SHA256SUMS de la versión, instalan los tres binarios (qartez, qartez-guard, qartez-setup) y lanzan qartez-setup en modo no interactivo para configurar cada IDE compatible con MCP que detecte (incluidos los hooks de protección de modificaciones para Claude Code).

macOS / Linux / WSL 2: instalador bash, los binarios se instalan en ~/.local/bin/:

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

Windows (PowerShell nativo 5.1+/7+): instalador PowerShell, los binarios se instalan en %LOCALAPPDATA%\Programs\qartez\:

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

Las plataformas no compatibles (p. ej., linux-musl arm64 sin un artefacto publicado) recurren automáticamente a un cargo build local; pasa --from-source (bash) o -FromSource (PowerShell) para forzar esa ruta. El MSRV de Rust 1.88 solo se requiere para esa alternativa.

Abre cualquier proyecto en tu IDE: Qartez lo indexa automáticamente al iniciar la sesión. No se necesita ningún paso manual. El observador de archivos mantiene el índice actualizado mientras editas.

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

Qué hace Qartez

Qartez construye un grafo de conocimiento de tu código base, una vez, y lo sirve a cualquier asistente de IA a través de MCP. En lugar de escanear archivos desde cero en cada pregunta, tu asistente consulta un índice precomputado que sabe:

• Qué archivos importan más (PageRank en el grafo de imports)
• Qué se rompe si cambias un archivo (análisis de radio de explosión)
• Qué archivos cambian siempre juntos (minería de co-cambio de git)
• Qué funciones son las más peligrosas de tocar (complejidad ciclomática x acoplamiento x cambios)
• Dónde está definido cada símbolo, quién lo usa y quién lo llama
• Qué bloques de código están duplicados (hash estructural de forma de AST)
• Qué límites de arquitectura están violando los imports
• Qué tipos implementan un trait/interfaz, y viceversa

El resultado: tu IA trabaja más rápido, usa menos tokens, refactoriza de forma segura y deja de hacer cambios a ciegas en archivos de carga crítica.

Antes y después

Las 43 herramientas

Piénsalas como la biblioteca estándar para la comprensión de código por IA. Cada una reemplaza un flujo de trabajo humano de varios pasos con una única llamada eficiente en tokens que el agente puede razonar.

Las herramientas están organizadas en niveles con divulgación progresiva. Las herramientas principales están siempre disponibles. Se pueden desbloquear niveles adicionales bajo demanda mediante qartez_tools enable: ["analysis"] (o "all").

Principales (siempre disponibles)

Análisis (desbloquear mediante qartez_tools)

Refactor (desbloquear mediante qartez_tools)

Meta (desbloquear mediante qartez_tools)

Gestión de niveles

Prompts de flujo de trabajo

Seis recetas listas para usar que encadenan las herramientas anteriores en el orden correcto. Invócalos como comandos de barra en Claude Code o en cualquier cliente MCP que admita prompts.

Protección de modificación

Qartez incluye una red de seguridad que impide que tu IA edite a ciegas archivos críticos para la carga.

El binario qartez-guard se engancha al sistema PreToolUse de Claude Code y bloquea Edit/Write/MultiEdit en cualquier archivo que supere un umbral de PageRank o de radio de explosión — hasta que la IA llame a qartez_impact primero para reconocer el riesgo.

Cómo funciona:

1. La IA intenta editar src/server/mod.rs
2. El guard comprueba: PageRank 0.23 (> umbral 0.05), radio de explosión 10 (>= umbral 10)
3. La edición es bloqueada con una explicación que lista qué umbrales se activaron
4. La IA llama a qartez_impact file_path=src/server/mod.rs — revisa el radio de explosión
5. El guard concede una ventana de edición de 10 minutos para ese archivo
6. La IA reintenta la edición — permitida

Cero configuración. Ajustable mediante QARTEZ_GUARD_PAGERANK_MIN, QARTEZ_GUARD_BLAST_MIN, QARTEZ_GUARD_ACK_TTL_SECS, o deshabilitada con QARTEZ_GUARD_DISABLE=1.

Benchmarks

No afirmaciones. Medidos. Reproducibles. Ejecuta make bench y verifícalo tú mismo.

Titular

Ahorro agregado de tokens vs Glob + Grep + Read + git log: +91.8% (suma de MCP 38,789 / suma de no-MCP 472,109 tokens en todos los 28 escenarios del auto-bench de Qartez. Sub-conteo conservador: 10 de 28 escenarios tienen una simulación no-MCP incompleta — esas filas siguen contribuyendo sus tokens MCP a ambas sumas. En los 18 escenarios con una comparación justa token a token el ahorro sube a +94.5%.)

Calidad evaluada por LLM-juez (claude-opus-4-6): MCP 8.3 / 10 vs no-MCP 4.3 / 10 en cinco ejes (corrección, completitud, usabilidad, basamiento, concisión), n=28.

Contexto de coste por sesión. Una sesión típica de Claude Code comienza con ~20,000 tokens de sobrecarga de prompt. Una sola ejecución de make bench ahorra ~433,000 tokens — ~21 sesiones vacías de presupuesto recuperadas, solo por enrutar preguntas a través de la herramienta correcta.

Desglose por herramienta (auto-bench de Rust)

18 herramientas con simulaciones no-MCP completas (comparación justa token a token):

10 herramientas analíticas adicionales no tienen equivalente grep/lectura significativo — resuelven problemas que la pila no-MCP no puede resolver en absoluto:

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

Cómo funciona por dentro

Cuatro capas, calculadas una vez, consultadas desde SQLite en cada llamada de herramienta.

1. Análisis con tree-sitter

Cada archivo fuente se analiza con una gramática tree-sitter específica del lenguaje. Sin servidor LSP, sin instalaciones de SDK por lenguaje, sin penalización de arranque en frío. El analizador extrae símbolos (funciones, métodos, tipos, constantes), sus firmas, rangos de líneas, visibilidad de exportación, relaciones de importación y —para 21 lenguajes imperativos— la complejidad ciclomática por función.

2. Hash de forma estructural

Los cuerpos de las funciones se canonizan en un esqueleto AST (identificadores, literales y comentarios normalizados) y se les aplica un hash. Dos símbolos con el mismo hash son clones estructurales. Eso es lo que consulta qartez_clones.

3. Análisis de grafo

Las aristas de importación forman un grafo dirigido. Sobre él se ejecutan tres algoritmos:

• PageRank: el mismo algoritmo de caminata aleatoria que Google usó para páginas web. Aplicado a tu grafo de importaciones, revela los archivos que forman la columna vertebral arquitectónica de tu proyecto.
• Blast radius: BFS inverso que cuenta cuántos archivos se ven afectados transitivamente por un cambio. qartez_impact lo utiliza para advertir antes de ediciones.
• Agrupamiento de Leiden: detección de comunidades que divide tu código base en módulos lógicos para la wiki de arquitectura generada automáticamente y la configuración inicial de qartez_boundaries.

4. Minería del historial de Git

Recorre los últimos N commits (300 por defecto) y cuenta los pares de archivos que aparecen en el mismo commit. Esto revela el acoplamiento lógico que el grafo de importaciones no puede ver: archivos que no están vinculados por importaciones pero que siempre se editan juntos.

qartez_impact, qartez_context y qartez_hotspots fusionan estas señales —PageRank + blast + co-cambio + complejidad— en una única respuesta clasificada. Ningún otro servidor MCP combina las cuatro.

Almacenamiento

Todo reside en .qartez/index.db: un único archivo SQLite con índices de texto completo FTS5. Al iniciar, Qartez reanaliza únicamente los archivos cuya hora de modificación haya cambiado. El vigilante de archivos se activa automáticamente mientras el servidor está en ejecución: las ediciones y los archivos nuevos se reindexan en segundo plano sin tiempo de inactividad. Pasa --no-watch para desactivarlo.

Transporte

Qartez se comunica a través de stdio (JSON-RPC sobre stdin/stdout), el transporte MCP estándar. Sin servidor HTTP, sin asignación de puertos, sin exposición a la red. El IDE lanza el binario qartez como proceso hijo e intercambia mensajes a través de tuberías.

Lenguajes compatibles

Un solo binario. Sin configuración por lenguaje. Los 37 lenguajes se analizan con tree-sitter (con respaldo de regex para formatos que carecen de gramática compatible). Los 21 lenguajes imperativos también obtienen complejidad ciclomática por función, lo que impulsa qartez_hotspots.

Aspectos destacados: TypeScript, Rust, Go, Python, Java, Kotlin, Swift, C#, C/C++, Ruby, PHP, Dart, Scala, Elixir, Zig, Lua, Haskell, OCaml, R y 17 más. Los 21 lenguajes imperativos incluyen puntuación de complejidad ciclomática.

Comparación con alternativas

El espacio de los servidores MCP de inteligencia de código está saturado en 2026. Esta sección cubre competidores OSS directos, plataformas empresariales y ecosistemas adyacentes. Todas las cifras de estrellas se contrastaron con el repositorio de GitHub de cada proyecto en abril de 2026.

Competidores MCP OSS directos

Nueve proyectos comparten el nicho de "servidor MCP para inteligencia de código", ordenados por estrellas de GitHub.

Alternativas empresariales y nativas de IDE

Plataformas comerciales que resuelven el mismo problema para usuarios dispuestos a intercambiar local-first y código abierto por pulido o escala entre repositorios:

• Sourcegraph Cody / Amp — indexadores SCIP de calidad de compilador, servidor MCP oficial desde 2026. Cloud-first, precios empresariales.
• Augment Code — Serie B de $227M. Índice semántico en tiempo real + grafo de relaciones de código en más de 400k archivos, servidor MCP oficial desde octubre de 2025. Dependencia de la nube.
• Deep Graph MCP (CodeGPT) — 392 estrellas. Backend de grafo de conocimiento alojado en la nube; intercambia github.com por deepgraph.co en cualquier URL de repositorio para obtener un grafo de código preconstruido. Sin necesidad de indexación local.
• JetBrains AI Assistant (IntelliJ 2025.2+) — servidor MCP integrado que expone símbolos y diagnósticos de nivel IDE. Solo JetBrains.
• Cursor — modelo de embeddings personalizado, índice compartido por equipo en Turbopuffer. IDE cerrado, sin exposición MCP.
• Windsurf Cascade — recuperación RAG M-Query. IDE cerrado, sin servidor MCP.

Qartez te da la misma inteligencia estructural que venden estas plataformas — funcionando por completo en tu laptop, de forma gratuita.

Ecosistemas adyacentes (categoría diferente, mismo problema)

• Aider repo-map — el CLI de Paul Gauthier fue pionero en tree-sitter + PageRank en octubre de 2023. Vive dentro del CLI de aider, no como servidor MCP. RepoMapper envuelve la salida única de repo_map como MCP.
• Continue.dev — cliente MCP, no servidor. Su documentación recomienda explícitamente combinar Continue con un servidor MCP dedicado de grafo de código — el rol que Qartez cubre.
• Context7, Mem0, Pieces LTM — herramientas de memoria y documentación, no indexadores de bases de código. Complementarios, no competidores.
• Block Goose, Cline, Codebuff — clientes de agentes de codificación que consumen servidores MCP. Son los usuarios de herramientas como Qartez.

Qué hace diferente a Qartez

1. Análisis de impacto de cuatro señales. qartez_impact, qartez_diff_impact, qartez_context y qartez_hotspots fusionan la importancia PageRank, el radio de explosión estático, la co-modificación de git y la complejidad ciclomática en una única respuesta clasificada. Ningún otro proyecto combina las cuatro.

2. Hotspots, clones, límites, seguridad, olores, brechas de prueba, conocimiento y tendencias en un solo servidor. qartez_hotspots clasifica las funciones más peligrosas del repositorio por complejidad x acoplamiento x cambios. qartez_clones encuentra lógica duplicada mediante hash de forma AST. qartez_boundaries aplica reglas de arquitectura declaradas en .qartez/boundaries.toml. qartez_security escanea patrones de vulnerabilidad puntuados por PageRank. qartez_smells detecta funciones dios, listas de parámetros largas y envidia de características. qartez_test_gaps encuentra archivos fuente sin probar clasificados por riesgo. qartez_knowledge revela riesgos de bus-factor a partir de git blame. qartez_trend rastrea cómo evolucionó la complejidad de una función commit a commit. Estas son ocho productos comerciales por separado en otros lugares, una sola llamada MCP aquí.

3. Refactorización a través de MCP con vista previa y aplicación. qartez_rename, qartez_move y qartez_rename_file le dan al asistente refactorizaciones atómicas y revisables en una sola llamada MCP. Serena ofrece renombrado vía LSP (requiere instalación de servidor por lenguaje); los servidores restantes no incluyen herramientas de refactorización en absoluto.

4. Red de seguridad integrada. El guardián de modificaciones bloquea que tu IA edite archivos de alto impacto sin revisar primero el radio de explosión. Ningún otro servidor en la tabla principal de competidores incluye esto.

5. Medido, no afirmado. 28 escenarios, 8.3/10 frente a 4.3/10 en calidad según juez LLM, conteos de tokens por herramienta y latencia. Todo reproducible con make bench (un solo lenguaje) o make bench-all (5 lenguajes con resumen entre lenguajes).

6. Rust nativo, local-first, cero dependencia de nube. Tres binarios (qartez, qartez-guard, qartez-setup). Sin runtime de Python, sin base de datos vectorial, sin cuenta en la nube. Todo se ejecuta en tu máquina. Ningún código sale del equipo. Una característica opcional de cargo semantic añade búsqueda de embeddings local, pero la compilación predeterminada no necesita descargar ningún modelo.

Opciones de línea de comandos

Qartez también funciona como CLI independiente. Ejecuta qartez <tool_name> (por ejemplo, qartez map, qartez find Config, qartez impact src/server/mod.rs) para usar cualquier herramienta principal o de análisis directamente desde la terminal sin un 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

Contribuciones

¿Encontraste un bug? Abre un issue. ¿Quieres añadir un lenguaje, corregir un parser o mejorar una herramienta? Las pull requests son bienvenidas — lee CONTRIBUTING.md y CODE_OF_CONDUCT.md primero. Los PR no triviales requieren firmar el CLA.md.

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

Las notas de versión de cada versión están en CHANGELOG.md.

Seguridad

¿Encontraste una vulnerabilidad? No abras un issue público. Sigue la política de divulgación en SECURITY.md.

Licencia

Doble licencia bajo la Qartez Small Team License (gratuita para individuos y equipos pequeños) y la Qartez Commercial License (para todos los demás). Lee el texto completo en LICENSE, y consulta COMMERCIAL.md para el resumen de los términos comerciales. Identificador SPDX: LicenseRef-Qartez-Dual.

Grep era para humanos. Qartez es para agentes.

Si Qartez te ahorra aunque sea el 10% de tu factura mensual de IA, dale una estrella al repositorio — es la única señal que les dice a otros desarrolladores que este enfoque vale la pena probar.