Ñaupa MCP: conecta tu agente al mapa de tu código

Antes de que tu IA cambie código, dale un mapa. Ñaupa construye un índice local del repositorio y ofrece herramientas MCP para encontrar dependencias, explorar la arquitectura y analizar el posible impacto de un cambio. Puedes usarlo sin una cuenta ni una suscripción a Theus.

Esta guía explica cómo instalar el motor, conectarlo a un cliente MCP local y hacer una primera consulta. El cliente o modelo que elijas puede tener sus propios requisitos, permisos y costos.

Qué es

Ñaupa construye un grafo de conocimiento con símbolos y relaciones detectadas en el código. Sobre ese grafo el agente puede preguntar «¿quién llama a esta función?», «¿qué rutas usan esta tabla?» o «¿cómo se organiza este módulo?». Los resultados ayudan a orientar la lectura; no sustituyen revisar el código ni ejecutar las pruebas adecuadas.

• Binario estático en C — sin runtime, sin dependencias; parsing por AST con tree-sitter para 158 lenguajes.
• Resolución semántica: el análisis adicional de tipos y relaciones está disponible para un subconjunto de lenguajes. Soporte de sintaxis no significa idéntica precisión en todos ellos.
• Grafo persistente — relaciones CALLS, rutas HTTP y data flows consultables con Cypher.
• Consultas sobre un índice persistente: el tiempo y el consumo dependen del equipo, el repositorio, el modo de indexación y la consulta. No se garantiza un tiempo fijo ni un porcentaje de ahorro de tokens.
• Embeddings incluidos — búsqueda semántica con embeddings nomic locales, sin llamadas a ninguna API.
• 19 herramientas MCP — cualquier agente compatible con MCP puede usarlas.
• UI 3D — visualización interactiva del grafo en http://localhost:9749.
• Índice local: el procesamiento del motor ocurre en tu equipo. Los fragmentos devueltos al agente pueden formar parte del contexto que ese agente envía a su proveedor.

Instala solo Ñaupa

macOS y Linux

Este comando descarga la variante con UI, comprueba su SHA-256 y deja el motor en tu equipo sin modificar la configuración de otros agentes:

curl -fsSL https://theus.pe/naupa.sh | bash -s -- --ui --skip-config

--ui elige el binario con visualización. --skip-config es una opción del instalador web, no de naupa install. Si el instalador avisa de que su carpeta no está en PATH, sigue la indicación mostrada o usa la ruta absoluta al ejecutable.

Windows, sin instalar Theus CLI

Descarga el ZIP de Ñaupa para tu arquitectura usando los enlaces de abajo. Compara su SHA-256 con checksums.txt antes de extraerlo y ejecutar el binario. No necesitas instalar Theus CLI para conectar Ñaupa a otro agente.

# Desde la carpeta donde descargaste el ZIP:
Get-FileHash .\naupa-ui-windows-amd64.zip -Algorithm SHA256

En un equipo ARM64, usa el nombre del ZIP ARM64. La huella debe coincidir con la línea de ese mismo archivo en checksums.txt. Si no coincide, no lo ejecutes.

Si prefieres instalar Theus CLI y Ñaupa juntos, consulta la página de descargas de Theus.

Para instalación manual en macOS/Linux, elige el .tar.gz de tu plataforma en descargas de Ñaupa. La variante con visualización empieza por naupa-ui-. Comprueba la huella del archivo antes de extraerlo; el instalador recomendado realiza esta comprobación automáticamente.

Instalación manual en Windows: descarga el .zip de tu arquitectura — naupa-ui-windows-amd64.zip o naupa-ui-windows-arm64.zip —, descomprímelo y deja naupa.exe en una carpeta de tu PATH. Los checksums de todos los artefactos están en https://theus.pe/dl/naupa/checksums.txt.

Registro automático opcional

La conexión manual de la siguiente sección permite elegir un solo agente. Si prefieres el registro automático en los agentes detectados, primero revisa los cambios previstos:

naupa install --dry-run

Solo si quieres aplicar esos cambios, ejecuta:

naupa install

Conecta el agente que elijas

Tu cliente debe admitir servidores MCP locales por stdio. En sus ajustes MCP, añade un servidor llamado naupa, indica la ruta absoluta al ejecutable y deja los argumentos vacíos. Si el cliente solo acepta una URL remota, esta configuración local no aplica.

Para localizar el binario en macOS/Linux:

command -v naupa
# Si la carpeta de instalacion no esta en PATH:
ls "$HOME/.local/bin/naupa"

En Windows, usa (Get-Command naupa.exe).Source si está en PATH, o (Resolve-Path .\naupa.exe).Path desde la carpeta donde lo extrajiste.

Clientes con una sección JSON mcpServers

{
  "mcpServers": {
    "naupa": {
      "command": "/RUTA/ABSOLUTA/naupa",
      "args": []
    }
  }
}

Editores con una sección JSON servers

{
  "servers": {
    "naupa": {
      "type": "stdio",
      "command": "/RUTA/ABSOLUTA/naupa",
      "args": []
    }
  }
}

Clientes con una sección TOML mcp_servers

[mcp_servers.naupa]
command = "/RUTA/ABSOLUTA/naupa"
args = []

El archivo y la estructura dependen del cliente. Usa el formato que documenta tu agente, no los tres a la vez. Reinicia el agente después de guardar y comprueba su panel MCP: Ñaupa debe aparecer conectado y ofrecer herramientas como search_graph y get_architecture.

Ñaupa pagina el listado de herramientas. Si un cliente solo muestra la primera página, necesita procesar nextCursor para obtener la lista completa.

Tu primera consulta

Abre un repositorio de confianza y sustituye la ruta del siguiente mensaje por la carpeta real. Indexar construye datos locales; revisar el código y sus permisos sigue siendo tu responsabilidad.

Usa Ñaupa para indexar el repositorio en RUTA_ABSOLUTA_DEL_PROYECTO.
Después consulta get_architecture y explica sus módulos y puntos de entrada.
Cita archivos y líneas. No modifiques código.

El agente puede usar index_repository con repo_path y consultar list_projects para conocer el identificador del índice. Usa ese identificador en las consultas posteriores: no tiene por qué coincidir con el nombre corto de la carpeta.

Tres preguntas para trabajo real

Impacto de un cambio: «Usa blast_radius para analizar mi git diff. Muestra funciones afectadas, rutas y pruebas candidatas. Explica qué no puede resolver el análisis. No edites código ni ejecutes pruebas».

Arquitectura: «Usa get_architecture para explicar los módulos y puntos de entrada de este repositorio, con referencias al código».

Encontrar una funcionalidad: «Busca con search_graph dónde se valida la sesión y sigue las llamadas con trace_path. Cita archivos y líneas; distingue los enlaces encontrados de los no resueltos».

Uso con Theus CLI

Con Theus no hay nada que configurar: si el binario naupa está instalado, Theus lo monta automáticamente como servidor MCP con el nombre theus-naupa al arrancar la sesión. Sus 19 herramientas aparecen junto a las nativas y el agente las usa cuando necesita entender la estructura del proyecto.

# kill-switch: arranca Theus sin montar Ñaupa
THEUS_NO_NAUPA=1 theus

Las 19 herramientas MCP

Ejemplos reales

Las herramientas también están disponibles desde la línea de comandos con naupa cli <herramienta> '<json>':

# indexar el proyecto actual
naupa cli index_repository '{"repo_path":"."}'

# búsqueda híbrida sobre el grafo
naupa cli search_graph '{"project":"mi-proyecto","query":"dónde se valida el token de sesión"}'

# quién llama a una función (cadena de llamadas entrante)
naupa cli trace_path '{"project":"mi-proyecto","function_name":"handleLogin","direction":"inbound"}'

Consulta Cypher directa — por ejemplo, las 10 funciones más llamadas del proyecto:

naupa cli query_graph '{"project":"mi-proyecto","query":"MATCH (caller)-[:CALLS]->(f:Function) RETURN f.name, f.file, count(caller) AS llamadas ORDER BY llamadas DESC LIMIT 10"}'

Datos y privacidad

Ñaupa construye el índice en tu máquina. Eso no convierte automáticamente en local al agente conectado: los resultados MCP, incluidos fragmentos de código, pueden formar parte del contexto que ese agente envía a su proveedor. Revisa su política y configuración antes de usar repositorios sensibles.

La instalación y actualización descargan archivos de la distribución oficial. «Índice local» no significa que nunca haya tráfico de red ni que el servicio de modelos sea gratuito.

Si Ñaupa no aparece conectado

• No se encuentra el ejecutable: usa la ruta absoluta. La aplicación gráfica puede tener un PATH distinto al de tu terminal.
• El proceso espera sin mostrar una pantalla: ejecutar naupa sin argumentos inicia el servidor stdio. Es el agente quien debe comunicarse con él; no es una consola interactiva.
• No aparece el repositorio: consulta list_projects e indexa la ruta correcta. Comprueba también el almacén que utiliza esa conexión.
• No abre la UI: comprueba que tienes la variante con UI, que el servidor está activo y que el puerto no está ocupado. Si la habías desactivado, puedes pasar --ui=true como argumento del servidor MCP.
• No acepta la configuración: comprueba si tu cliente usa JSON, TOML o un formulario. Un servidor stdio local no se configura como una URL remota.

Licencia y atribución

Ñaupa se distribuye bajo licencia MIT y es un producto de Theus. La atribución de los componentes de terceros que vendoriza (tree-sitter y sus gramáticas, SQLite, mimalloc, nomic-embed, entre otros) se preserva en los avisos de licencia que acompañan a los binarios.