Stellaris MCP: búsqueda semántica en tu codebase

Si desarrollas con la ayuda de Claude, Cursor u otro agente de IA, probablemente ya has vivido esta frustración: la IA comete errores que no tienen nada que ver con sus capacidades. Propone código que duplica una función que ya existe. Alucina imports. Corrige un bug creando tres más, porque no vio que la lógica ya estaba gestionada en otro lugar.

No es un problema de inteligencia — es un problema de contexto.

Un agente de IA, por muy potente que sea, no puede leer todo tu proyecto en cada intercambio. Sería demasiado lento y, sobre todo, demasiado costoso en tokens. Así que trabaja con lo que le das explícitamente, y adivina el resto. Lo que funciona bien en archivos pequeños y aislados se convierte rápidamente en un problema en un proyecto real con decenas de archivos, cientos de funciones y una arquitectura que ha evolucionado durante meses.

La solución es darle a la IA una forma de buscar en tu código bajo demanda — ofrecerle una especie de motor de búsqueda interno que entienda lo que buscas, aunque no conozcas el nombre exacto de la función o del archivo.

Eso es exactamente lo que hace Stellaris MCP: una herramienta open source que desarrollé y publiqué en GitHub, diseñada para integrarse directamente con Claude Desktop (y cualquier cliente compatible con MCP).

Permite a la IA localizar con precisión el fragmento de código correcto en el momento adecuado, sin necesidad de cargar todo tu proyecto en memoria.

Resultado: menos errores, menos tokens consumidos y un asistente que realmente entiende tu codebase.

No hace falta ser un desarrollador avanzado para aprovecharlo — si usas Claude para ayudarte a programar, aunque sea de vez en cuando, Stellaris MCP te ahorrará tiempo desde la primera sesión.

¿Qué es un servidor MCP?

Imagina que Claude pudiera pulsar botones en tu nombre: abrir un archivo, buscar en tu base de datos, llamar a una API externa. Eso es exactamente lo que permite el Model Context Protocol (MCP) — un estándar abierto desarrollado por Anthropic que da a los agentes de IA la capacidad de interactuar con herramientas de terceros de forma estructurada y segura.

En la práctica, un servidor MCP expone “tools” — funciones que la IA puede invocar durante una conversación, según sus necesidades. Claude no las usa constantemente: las llama solo cuando es relevante, como le pedirías a un compañero una información específica en lugar de enviarle todo el expediente de golpe.

Esta lógica “bajo demanda” es lo que hace que los servidores MCP sean tan eficaces para ahorrar tokens y reducir los costes de inferencia. En lugar de cargar 50 archivos en contexto por precaución, Claude puede pedir exactamente lo que necesita, cuando lo necesita.

Stellaris MCP expone seis herramientas de este tipo, repartidas en dos categorías complementarias: la búsqueda semántica (que comprende tus intenciones) y la exploración estructural (que analiza la sintaxis de tu código).

Cómo funciona: dos enfoques complementarios

Stellaris MCP tiene dos modos de funcionamiento, según lo que quieras hacer.

Buscar por intención, no por palabra clave

El primer modo es la búsqueda semántica. En concreto, Stellaris analiza tu proyecto y crea una especie de huella digital de cada función, componente o clase. Estas huellas se almacenan localmente en tu máquina en una pequeña carpeta oculta.

¿La ventaja? Cuando Claude necesita algo, puede buscar por intención — “la función que gestiona el inicio de sesión del usuario” — sin conocer el nombre exacto del archivo o del método. Es como Google para tu código: describes lo que buscas, y el motor encuentra la correspondencia más relevante.

Esta indexación utiliza la API de OpenAI (se necesita una clave), pero el coste es mínimo — unos céntimos para un proyecto entero — y el índice se actualiza de forma incremental: solo los archivos modificados se reanalízan en cada arranque.

Tres herramientas cubren este modo:

• Búsqueda en el código — en lenguaje natural, en todos tus archivos fuente
• Búsqueda en la documentación — en tus archivos Markdown
• Reindexación — para forzar una actualización del índice

Explorar la estructura, sin gastar un solo token

El segundo modo es completamente gratuito: sin clave de API, sin llamada de red. Simplemente analiza la sintaxis de tu código para extraer su estructura — exactamente como lo haría un IDE.

Tres herramientas en esta categoría:

• Vista en árbol — la lista completa de todos tus archivos, con estadísticas por lenguaje
• Esquema de un archivo — todas las funciones y clases de un archivo, con sus números de línea
• Código fuente de un símbolo — el código exacto de una función específica, con su contexto (ver más abajo)

Este modo es especialmente útil para que Claude “descubra” tu proyecto al inicio de una sesión, sin tener que cargar todo en memoria.

El verdadero plus: el contexto automático

Aquí hay un detalle que realmente cambia la calidad del resultado. Cuando una herramienta de búsqueda te devuelve una función, te da simplemente… la función. Lo cual parece lógico, pero plantea un problema práctico: Claude no sabe de dónde vienen las variables utilizadas, ni si ya existen funciones similares en el mismo archivo.

Stellaris hace algo más inteligente: cuando recupera una función para Claude, adjunta automáticamente lo que la rodea — la lista de imports del archivo, los nombres de las funciones vecinas, y los posibles comentarios de advertencia (TODO, FIXME, etc.) presentes en el archivo.

Es un pequeño extra de información (unos cien tokens), pero evita los errores más frecuentes: refactorización ciega, duplicación de código, correcciones que rompen otra cosa sin darse cuenta. Una buena relación calidad/coste.

Compatible con tus lenguajes habituales

Stellaris MCP soporta de forma nativa TypeScript, JavaScript, React (TSX/JSX), Python, Go, Rust, PHP, HTML y CSS — así como archivos Markdown para la documentación. Eso cubre la gran mayoría de los proyectos web y backend actuales.

¿Cómo se ve en la práctica?

Una vez instalado, el flujo de trabajo natural con Claude se convierte en este:

1. Al inicio de una sesión, Claude pide ver la estructura de tu proyecto — en una sola llamada, sabe qué existe y dónde
2. Cuando busca algo concreto, hace una búsqueda por intención en lugar de pedirte que pegues código
3. Cuando modifica una función, recupera el contexto completo antes de escribir cualquier cosa

La mayoría de estas operaciones son completamente gratuitas — solo la búsqueda semántica usa la API de OpenAI, y únicamente durante la indexación inicial o las actualizaciones. En el uso habitual, casi no gastas nada.

Instalación e integración con Claude Desktop

git clone https://github.com/GDM-Pixel/stellaris-code-search.git
cd stellaris-code-search
npm install
npm run build

Luego en tu claude_desktop_config.json:

{
  "mcpServers": {
    "stellaris-mcp": {
      "command": "node",
      "args": ["/ruta/hacia/stellaris-code-search/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Sin clave de OpenAI, el servidor arranca normalmente — las tres herramientas AST siguen disponibles.

Open source, de verdad

El proyecto está publicado bajo licencia MIT en GitHub: github.com/GDM-Pixel/stellaris-code-search

Contribuciones bienvenidas — issues, pull requests, sugerencias de lenguajes adicionales. Si lo usas en tus proyectos y encuentras casos límite, abre una issue.

Es una herramienta que construí para mis propios flujos de desarrollo en GDM-Pixel y en Nova-Mind. La comparto porque el problema del contexto de código para los agentes de IA es universal — y una solución abierta vale más que una propietaria encerrada en un SaaS.