Construir un sistema multi-agente para Claude Code con TEI + Qdrant

TL;DR

Vectoricé el codigo con TEI (Text Embeddings Inference), lo almacene en Qdrant, y construi un sistema donde 9 agentes de Claude Code buscan en lugar de leer el codigo.

1. Por que lo construi

Limitaciones de Claude Code

Claude Code es potente, pero cuando necesita comprender el codebase en su totalidad, abre y lee los archivos uno por uno.

Read src/auth.ts          → 200 lineas consumidas
Read src/middleware.ts     → 150 lineas consumidas
Read src/utils/token.ts    → 100 lineas consumidas
...

Hay casos en los que es inevitable leer todo el codigo, como revisiones de calidad o seguridad, y el consumo es considerable.

Pense que agentes como el revisor de codigo o el verificador de seguridad podrian comprender el codigo sin la herramienta Read, reduciendo asi el coste de tokens, asi que decidi probarlo.

2. Arquitectura

Componentes

3. Por que este stack

El objetivo no era encontrar el modelo de embeddings mas reciente ni la combinacion optima. El objetivo era probar si el pipeline RAG realmente funciona en un NAS sin GPU. Por eso elegi una combinacion ligera y facil de auto-alojar.

TEI + e5-base

• TEI — Servidor de embeddings oficial de Hugging Face. Se despliega con una sola linea de Docker
• e5-base — 768 dimensiones. ~50ms/query en CPU, suficientemente practico
• Soporta busqueda asimetrica con los prefijos query: / passage:, lo que es ventajoso para emparejar preguntas cortas → fragmentos de codigo largos

Por que construi el servidor MCP en Rust

• Un solo binario — Despliegue con un unico ejecutable. 0 dependencias de runtime
• Memoria — ~15MB de memoria residente. Un servidor Python consume 200MB+
• Claude Code MCP — JSON-RPC basado en stdio. serde + tokio de Rust son ideales
• Comunicacion externa — Procesamiento asincrono HTTP + gRPC

4. Flujos principales

4.1 Indexacion (Codigo → Vectores)

Directorio del proyecto
    │
    ▼
[walkdir] Recorrido de archivos (max depth: 10)
    │
    ▼
[filter] Exclusion de 52 directorios + 60 extensiones
         (node_modules, target, .git, imagenes, binarios...)
    │
    ▼
[verificacion incremental] Comparacion de tiempo de modificacion
         → Solo se procesan los archivos modificados
    │
    ▼
[chunk] Division en unidades de 1500 caracteres (300 de solapamiento)
    │
    ▼
[TEI] Cada fragmento → "passage: {content}" → Vector de 768 dimensiones
    │
    ▼
[Qdrant] Upsert basado en UUID v5 (lotes de 100)
         Collection: "code-rag-{project_name}"

Por que fragmentos de 1500 caracteres?

• Demasiado grande → Precision de busqueda reducida (ruido)
• Demasiado pequeno → Una funcion se divide en multiples fragmentos, perdiendo contexto
• 1500 caracteres + 300 de solapamiento → Evita cortes en los limites de funciones

4.2 Ejemplo de busqueda — Agente de revision de codigo

[Agente_de_revision] Inicio de auditoria de seguridad
    │
    ▼
search_codebase("logica de autenticacion", project_name="my-app")
    │
    ▼
Resultados recibidos (Top 10, solo similitud >= 0.5):
    │
    ▼
search_codebase("generacion de consultas SQL", project_name="my-app")
    │
    ▼
search_codebase("validacion de entrada de usuario", project_name="my-app")
    │
    ▼
Generacion de informe de seguridad con los fragmentos de codigo recopilados

Resultado: 0 lecturas (Read), 3 busquedas para completar el informe. Analiza vulnerabilidades de seguridad del codebase sin abrir un solo archivo.

4.3 Indexacion automatica

Agente: search_codebase("manejo de errores", project_name="blog")
    │
    ▼
[Verificacion de Collection] Existe "my-app"?
    │
    ├─ No → Dispara indexacion automatica → Busca tras completar la indexacion
    │
    └─ Si → Busqueda inmediata

El agente no necesita invocar la indexacion directamente. El indice se crea automaticamente en la primera busqueda.

5. Cifras reales

6. Herramientas MCP

mcp-code-rag proporciona 2 herramientas MCP a Claude Code.

Si se obliga a los agentes a llamar primero a search_codebase al explorar codigo, se evita el desperdicio de tokens al recorrer archivos con la herramienta Read.

Ventajas

• Una vez indexado, las busquedas son instantaneas — La indexacion es lenta solo la primera vez; despues es incremental y solo procesa archivos modificados. La busqueda en si tarda ~200ms
• Consumo de tokens 0 — Al no abrir archivos con Read, no se gasta la ventana de contexto en busquedas
• Exploracion de codigo en lenguaje natural — Encuentra codigo relevante al instante con preguntas como "manejo de autenticacion" o "consultas SQL"
• Fuerte en tareas que requieren escanear todo el codebase — Ideal para casos como auditorias de seguridad o revisiones de codigo donde se necesita identificar patrones amplios

Limitaciones

Para busquedas semanticas precisas como "el manejo de errores esta bien implementado?", la similitud vectorial por si sola no es suficiente. En estos casos, es necesario agregar un modelo de Rerank o combinar busqueda por palabras clave (BM25) con busqueda vectorial en un enfoque hibrido.

7. Como empezar

Requisitos

• Entorno Docker (para ejecutar Qdrant y TEI)
• Rust (para compilar mcp-code-rag)
• Claude Code (plan Pro)

Una vez instalado todo y registrado el servidor MCP en Claude Code, obtiene solo el codigo necesario basandose en significado semantico, sin desperdiciar tokens.