mcplens

Búsqueda semántica de bases de código para asistentes de codificación de IA: reducción de tokens del 70-85%, 100% local, sin dependencia de la nube.

Los asistentes de codificación de IA como Claude Code, Cursor y Codex son potentes, pero tienen un problema fundamental: cuando haces una pregunta, leen archivos adivinando cuáles son relevantes basándose en heurísticas de ruta y nombre de archivo. En un proyecto de tamaño mediano, una sola consulta puede consumir entre 10.000 y 20.000 tokens de contexto solo cargando archivos que quizás ni siquiera sean relevantes.

claude-context-optimizer resuelve esto dándole a tu asistente de IA búsqueda semántica sobre tu base de código. En lugar de leer archivos a ciegas, llama a search_code("¿cómo funciona el pago?") y obtiene solo los 5 fragmentos de código más relevantes, indexados localmente mediante embeddings, almacenados en SQLite, sin que ningún dato salga de tu máquina.

Cómo funciona

Cuando abres tu asistente de IA en un proyecto:

1. El servidor MCP se inicia automáticamente (generado a través de stdio por el asistente)

2. Compara los hashes de los archivos con el último índice y solo vuelve a indexar lo que cambió (indexación delta)

3. Un observador de archivos mantiene el índice sincronizado mientras programas

4. Tu asistente ahora tiene acceso a 3 herramientas de búsqueda semántica en lugar de leer archivos sin procesar

You ask: "how does the Asaas webhook work?"

Without cco:                          With cco:
  Read AsaasWebhookController.php       search_code("asaas webhook")
  Read AsaasWebhookService.php          → returns 5 relevant chunks
  Read PaymentService.php               → ~800 tokens total
  Read BillingModule.php
  Read ...8 more files
  → ~15,000 tokens total

Bajo el capó

• Embeddings: Ollama con nomic-embed-text (768-dim): 100% local, gratuito, sin clave API

• Almacén de vectores: SQLite con similitud de coseno calculada en el proceso: sin infraestructura adicional

• Fragmentación (Chunking): Basada en AST mediante tree-sitter (divide por función/clase) con respaldo de ventana deslizante

• Transporte: MCP stdio: el asistente genera el proceso y se comunica a través de una tubería (pipe)

• Persistencia: El índice reside en .claude-context/index.db y sobrevive entre sesiones

Related MCP server: LocalNest MCP

Compatibilidad

claude-context-optimizer funciona con cualquier asistente de codificación de IA compatible con MCP. MCP (Model Context Protocol) es un estándar abierto: el mismo servidor funciona en todos los clientes sin modificaciones.

El comando init detecta qué asistentes utilizas y registra el servidor automáticamente en el lugar correcto.

Ahorro de tokens

El índice reside localmente. El asistente obtiene solo lo que es relevante. Los números hablan por sí solos:

Estos son tokens de contexto, la parte que tú controlas. El ahorro aumenta con el tamaño del proyecto porque los proyectos más grandes activan más lecturas de archivos heurísticas de forma predeterminada.

Herramientas expuestas

Agrega esto al CLAUDE.md (o equivalente) de tu proyecto para guiar al asistente:

## Context Search

Always use MCP tools before reading files:

- search_code() — for conceptual or natural language queries
- get_symbol() — for exact class/function/method lookups
  Only read full files if both tools return insufficient context.

Opciones de instalación

Opción A: npm (requiere Ollama)

Sin sobrecarga. Ideal para desarrolladores que ya tienen Ollama instalado.

npm install -g @vmsfigueredo/mcplens
ollama pull nomic-embed-text:latest
cd your-project && mcplens init

Consulta INSTALL.md para obtener instrucciones completas de configuración.

Opción B: Docker

Aún no disponible. La distribución de Docker (que incluye Node + Ollama + modelo) está planificada pero no implementada. Sigue el progreso en la Hoja de ruta.

Configuración

.claude-context/config.json es creado automáticamente por init. Edítalo para personalizar el comportamiento:

{
  "embeddings": {
    "provider": "ollama",
    "ollamaUrl": "http://localhost:11434",
    "ollamaModel": "nomic-embed-text:latest"
  },
  "search": {
    "topK": 5,
    "minScore": 0.3
  },
  "ignore": [
    "**/tests/fixtures/**"
  ]
}

Para usar embeddings de OpenAI en su lugar:

{
  "embeddings": {
    "provider": "openai",
    "openaiApiKey": "sk-...",
    "openaiModel": "text-embedding-3-small"
  }
}

Qué se indexa

Incluido por defecto: .ts .tsx .js .jsx .mjs .php .svelte .vue .py .rb .go .rs .css .scss .json .yaml .yml .md .sql

Ignorado por defecto: node_modules, .git, vendor, dist, build, .next, .claude-context

El directorio .claude-context/ se agrega automáticamente a .gitignore.

Referencia del tamaño del índice

Panel de control (Dashboard)

Un panel web ligero está disponible en http://localhost:3000 mientras el servidor se está ejecutando:

• Resumen: archivos indexados, fragmentos, tamaño del índice, estado de Ollama

• Actividad: feed en vivo de eventos de reindexación

• Búsqueda: prueba consultas manualmente y observa las puntuaciones (útil para calibrar minScore)

• Archivos: lista completa de archivos indexados con recuentos de fragmentos

El panel se ejecuta en el puerto 3333 de forma predeterminada. Si ese puerto ya está ocupado (por ejemplo, dos proyectos abiertos simultáneamente), el puerto se calcula automáticamente a partir del nombre del proyecto. Para abrir:

mcplens dashboard

Para desactivar: agrega --no-dashboard a los argumentos del servidor en tu configuración de MCP.

Privacidad

Todo se ejecuta en tu máquina:

• Los embeddings se generan localmente a través de Ollama: tu código nunca sale de tu equipo

• El índice se almacena en .claude-context/index.db en tu proyecto

• Sin telemetría, sin análisis, sin cuentas

⚠️ Si utilizas la opción de embeddings de OpenAI, los fragmentos se envían a la API de OpenAI.

¿Por qué no usar herramientas existentes?

El objetivo es ser la opción más accesible para desarrolladores JS/TS, no la más completa en funciones. Si ya tienes Node.js, estás a un comando de distancia.

Hoja de ruta

• [x] Fragmentación basada en AST mediante tree-sitter

• [x] Indexación delta por hash de archivo

• [x] Observador de archivos en tiempo real

• [x] Panel de control

• [x] Inicio multi-cliente (Claude Code, Cursor, Windsurf, Trae)

• [x] Búsqueda híbrida (BM25 + semántica)

• [ ] Opción Docker con Ollama incluido

• [ ] Recuperación contextual (resúmenes de fragmentos generados por LLM)

• [ ] Análisis de uso de tokens a través de hooks de Claude Code

Contribución

Las PR son bienvenidas. Consulta INSTALL.md para la configuración de desarrollo local.

Construido con

Este proyecto fue construido usando Claude Code, que es exactamente la razón por la que existe.

Licencia

MIT