Theus como servidor MCP
La inteligencia local de Theus no es exclusiva de su CLI: theus --project-context-mcp expone el grafo de símbolos, el recall híbrido y las memorias persistentes como un servidor MCP por stdio, para que cualquier cliente MCP-compatible — otros agentes, editores, IDEs — consuma el contexto del proyecto que Theus ya indexa.
El servidor de contexto de proyecto
El servidor se llama theus-project-context y arranca con:
theus --project-context-mcpEl root del proyecto se toma de la variable THEUS_PROJECT_ROOT o, en su ausencia, del directorio de trabajo. No requiere haber corrido Theus interactivo antes: si el proyecto nunca fue indexado, el servidor lo indexa él mismo en el primer arranque y persiste el grafo (mismos topes que el servicio interno: INDEX_MAX_FILES, por defecto 2500 archivos, e INDEX_MAX_FILE_BYTES, por defecto 1 MB), preservando las memorias que ya existieran. El índice se cachea en memoria — no se recarga en cada llamada — y todo log va a stderr: stdout pertenece al protocolo JSON-RPC. Ninguna herramienta puede tumbar el proceso; los errores se devuelven como resultado MCP.
Registro en otro agente
Ejemplo con un .mcp.json (el formato que usan varios clientes MCP):
{
"mcpServers": {
"theus-context": {
"command": "theus",
"args": ["--project-context-mcp"]
}
}
}"env": { "THEUS_PROJECT_ROOT": "/ruta/del/proyecto" } en la misma entrada.Las 5 herramientas
| Herramienta | Qué hace |
|---|---|
recall | Recuperación híbrida (keywords + embeddings + traversal del grafo) sobre el índice del proyecto. Devuelve los nodos más relevantes para la consulta — archivos, símbolos, entidades y memorias — con archivo:línea y score, más un resumen del subgrafo conectado. Parámetros: query (obligatorio) y limit (semillas a devolver, por defecto 8, máximo 50). |
symbols | Lista los símbolos indexados (funciones, clases, tipos, interfaces, enums, consts) con su archivo:línea, agrupados por archivo. Filtro opcional file (subcadena de la ruta relativa). |
project_map | Resumen estructural: archivos indexados, conteo de símbolos por tipo, entidades de dominio principales y esquema de base de datos si se detecta (Prisma/SQL). |
remember | Guarda una memoria persistente (title + text) en el grafo de conocimiento del proyecto. Sobrevive a la sesión y es recuperable luego vía recall o memories; devuelve el id del nodo creado. |
memories | Lista todas las memorias persistentes guardadas para el proyecto (título + texto). |
remember viven en el mismo grafo que usa el propio Theus (~/.theus/knowledge/): lo que un agente aprende, el otro lo recuerda.El ecosistema MCP interno del CLI
Además de actuar como servidor para otros, el CLI de Theus monta sus propios servidores MCP en cada sesión. Los tres viajan por stdio y siguen la misma regla: stdout es del protocolo, los logs van a stderr.
| Servidor | Activación | Qué aporta |
|---|---|---|
theus-naupa | Automática si el binario naupa está instalado; kill-switch THEUS_NO_NAUPA=1 | El motor de inteligencia de código: grafo AST del proyecto, cadenas de llamadas, consultas Cypher. Ver Ñaupa. |
theus-computer-use | Opt-in con THEUS_COMPUTER_USE=1 (solo macOS) | Control de escritorio: screenshot + mouse + teclado. Ver Computer-use. |
theus-project-context | theus --project-context-mcp (para clientes externos) | El servidor descrito en esta página. |
theus-naupa: auto-montado, permisos por capas
Theus resuelve el binario naupa de forma determinista (THEUS_NAUPA_BIN → ~/.local/bin → /opt/homebrew/bin → /usr/local/bin → PATH) y, si lo encuentra, lo monta sin preguntar — es 100% local, ningún servicio remoto está involucrado. Desde v0.1.13 el proyecto además se auto-indexa al abrir la sesión (con watcher de cambios), así que el grafo está listo desde el primer turno. Las herramientas de solo lectura van pre-permitidas (no disparan prompt de permiso): search_graph, trace_path, query_graph, get_graph_schema, get_architecture, get_code_snippet, search_code, detect_changes, index_status, list_projects. Las que escriben (index_repository, delete_project, manage_adr, ingest_traces) pasan por el flujo de permisos normal.
theus-computer-use: nunca se monta solo
A diferencia de Ñaupa, computer-use es opt-in explícito: sin THEUS_COMPUTER_USE=1 el servidor no existe en la sesión. Sus 12 herramientas y los permisos macOS necesarios están documentados en su página.