GZOO Cortex MCP Server

GZOO Cortex

Grafo de conocimiento local primero para desarrolladores. Observa los archivos de tus proyectos, extrae entidades y relaciones usando LLMs, y te permite consultar todos tus proyectos en lenguaje natural.

“¿Qué decisiones de arquitectura he tomado en todos mis proyectos?”

Cortex encuentra decisiones en tus READMEs, archivos TypeScript, archivos de configuración, y exportaciones de conversaciones — luego sintetiza una respuesta con citas de fuentes.

Por qué

Trabajas en múltiples proyectos. Las decisiones, patrones y contexto están dispersos en cientos de archivos. Olvidas lo que decidiste hace tres meses. Vuelves a resolver problemas que ya solucionaste en otro repositorio.

Cortex observa los directorios de tus proyectos, extrae conocimiento automáticamente, y te lo devuelve cuando lo necesitas.

Qué hace

• Observa tus archivos de proyecto (md, ts, js, py, json, yaml) en busca de cambios
• Extrae entidades: decisiones, patrones, componentes, dependencias, restricciones, elementos de acción
• Infere relaciones entre entidades a través de proyectos
• Detecta contradicciones cuando las decisiones entran en conflicto
• Consulta en lenguaje natural con citas de fuentes
• Busca semánticamente — combina similitud por palabra clave y vectorial (embedding) para que las consultas coincidan por significado, no solo por palabras clave (opcional; ver Búsqueda Semántica)
• Enruta inteligentemente entre LLMs en la nube y locales
• Respeta la privacidad — los proyectos restringidos nunca salen de tu máquina
• Panel web con visualización del grafo de conocimiento, feed en vivo y explorador de consultas
• Servidor MCP para integración directa con Claude Code

Inicio Rápido

1. Instalar

npm install -g @gzoo/cortex

Si la instalación global falla con EACCES, usa un prefijo de usuario en su lugar:

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

O instala desde el código fuente:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

Verificar: cortex --version (versión actual: 0.8.1)

2. Configuración

Ejecuta el asistente interactivo:

cortex init
cortex doctor                              # verify config, providers, and DB

Esto te guía a través de:

• Proveedor LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, u Ollama (local)
• Clave API — guardada de forma segura en ~/.cortex/.env
• Modo de enrutamiento — prioridad nube, híbrido, prioridad local, o solo local
• Directorios a observar — qué directorios debe monitorear Cortex
• Límite de presupuesto — tope de gasto mensual en LLM

cortex init escribe la configuración global en ~/.cortex/cortex.config.json. Las claves API van en ~/.cortex/.env.

3. Registrar Proyectos

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. Ingerir, Observar y Consultar

Primero rellena los archivos existentes — el observador solo capta nuevos cambios:

cortex ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

Comando	Qué hace
cortex serve	Panel web + API + observador de archivos (ignoreInitial — sin re-ingesta al iniciar)
cortex watch	Observador de archivos solo CLI (sin panel)
cortex ingest	Ingesta única; los eventos no aparecen en el Feed en Vivo

No ejecutes watch y serve juntos — compiten por los cambios de archivos. El Feed en Vivo muestra eventos en tiempo real solo de cortex serve (archivos guardados mientras el servidor está en ejecución).

cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Panel Web

cortex serve                               # open http://localhost:3710

Acceso remoto:

cortex serve --host 0.0.0.0

La autenticación se aplica automáticamente en hosts no locales. Se genera automáticamente un token de portador y se guarda en ~/.cortex/.env (léelo con grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Abre el panel una vez con http://<host>:3710/?token=<token> — el token se incrusta solo para solicitudes que ya demuestren posesión del mismo y luego se mantiene para la pestaña del navegador (para que los visitantes anónimos nunca lo reciban). Las llamadas API/WebSocket detrás de un proxy inverso usan Authorization: Bearer <token>.

Excluir Archivos y Directorios

Cortex ignora node_modules, dist, .git y otros directorios comunes por defecto. Para añadir más:

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

Cómo Funciona

Cortex ejecuta una tubería en cada cambio de archivo:

1. Analizar — el contenido del archivo se divide en fragmentos mediante un analizador consciente del lenguaje (tree-sitter para código, remark para markdown)
2. Extraer — el LLM identifica entidades (decisiones, componentes, patrones, etc.)
3. Relacionar — el LLM infiere relaciones entre entidades nuevas y existentes
4. Detectar — las contradicciones y duplicados se marcan automáticamente
5. Almacenar — entidades, relaciones y vectores van a SQLite + LanceDB
6. Consultar — las consultas en lenguaje natural buscan en el grafo y sintetizan respuestas

Todos los datos permanecen locales en ~/.cortex/. Solo las llamadas a la API del LLM salen de tu máquina (y nunca para proyectos restringidos).

Proveedores de LLM

Cortex es agnóstico al proveedor. Soporta:

• Anthropic Claude (Sonnet, Haiku) — a través de la API nativa de Anthropic
• Google Gemini — a través de API compatible con OpenAI
• DeepSeek (Reasoner, Chat) — razonamiento fuerte, muy asequible
• Groq — inferencia rápida con nivel gratuito
• Cualquier API compatible con OpenAI — OpenRouter, proxies locales, etc.
• Ollama (Mistral, Llama, etc.) — completamente local, sin necesidad de nube

El seguimiento de costos utiliza tarifas específicas del proveedor para modelos de DeepSeek, Gemini, Groq y OpenRouter — no una alternativa genérica de Anthropic.

Los embeddings (para búsqueda semántica) se configuran como un proveedor separado — independiente de tu modelo de chat — para que puedas ejecutar chat en DeepSeek y embeddings en OpenAI. Ver Búsqueda Semántica.

Modos de Enrutamiento

Modo	Costo en Nube	Calidad	Requiere Ollama
cloud-first	Varía según proveedor	Más alta	No
hybrid	Reducido	Alta	Sí
local-first	Mínimo	Buena	Sí
local-only	$0	Buena	Sí

En modo prioridad nube, todas las tareas se enrutan a tu proveedor en la nube. No se requiere Ollama y solo se usa si está habilitada la alternativa de presupuesto. El modo híbrido enruta tareas de alto volumen (extracción de entidades, clasificación) a Ollama y tareas de razonamiento intensivo (inferencia de relaciones, consultas) a tu proveedor en la nube.

Requisitos

• Node.js 20+
• Clave API de LLM para modos en la nube — Anthropic, Google Gemini, DeepSeek, Groq, o cualquier proveedor compatible con OpenAI
• Ollama — solo para modos hybrid, local-first, o local-only (instalar)

Configuración

La configuración está en capas — las fuentes posteriores sobrescriben las anteriores:

Prioridad	Ubicación	Alcance
1	Valores predeterminados integrados	Global
2	~/.cortex/cortex.config.json	Global (creado por cortex init)
3	./cortex.config.json	Anulaciones de proyecto (opcional)
4	CORTEX_* vars de entorno	Sesión

Las claves API se almacenan por separado en ~/.cortex/.env (nunca en JSON de configuración).

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted
cortex doctor                            # validate setup

Referencia completa de configuración: docs/configuration.md

Búsqueda Semántica (Embeddings)

Cortex combina búsqueda por palabra clave (texto completo) con similitud vectorial, para que las consultas coincidan por significado en lugar de palabras exactas. Los embeddings son opcionales y están desactivados por defecto — actívalos con un proveedor de embeddings en la nube (no se requiere GPU local ni Ollama):

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

El proveedor de embeddings es independiente de tu proveedor de chat — ejecuta chat en DeepSeek (o Anthropic, Groq, …) y embeddings en OpenAI. Cualquier endpoint de embeddings compatible con OpenAI funciona.

Los nuevos archivos se incrustan automáticamente a medida que se ingieren. Para construir el índice de un grafo que ya ingeriste, ejecuta una reindexación única:

cortex reindex                 # all projects
cortex reindex my-app          # a single project

Comandos

Comando	Descripción
cortex init	Asistente de configuración interactivo
cortex doctor	Validar configuración, proveedores, proyectos, secretos y base de datos
cortex projects add/list/remove/show	Gestionar proyectos registrados
cortex serve	Panel web + API + observador de archivos (puerto 3710)
cortex watch [project]	Observador de archivos solo CLI
cortex ingest <file-or-glob>	Ingesta única de archivos (separada del Feed en Vivo)
cortex reindex [project]	Reconstruir el índice de búsqueda semántica (embedding) para entidades existentes
cortex query <question>	Consulta en lenguaje natural con citas
cortex find <term>	Buscar entidades por nombre
cortex status	Estadísticas del grafo, costos, estado del proveedor
cortex costs	Desglose detallado de costos
cortex contradictions	Listar contradicciones activas
cortex resolve <id>	Resolver una contradicción
cortex models list/pull/test/info	Gestionar modelos de Ollama
cortex mcp	Iniciar servidor MCP para Claude Code
cortex report	Resumen post-ingesta
cortex privacy set/list	Establecer privacidad de directorio
cortex config list/get/set/validate	Leer/escribir configuración
cortex config exclude add/remove/list	Gestionar exclusiones de archivos/directorios
cortex stop / cortex restart	Gestionar procesos de observación/servicio en ejecución
cortex db	Operaciones de base de datos

Referencia completa de CLI: docs/cli-reference.md

Panel Web

Ejecuta cortex serve para abrir un panel web completo en http://localhost:3710 con:

• Inicio del Panel — estadísticas del grafo, actividad reciente, desglose por tipo de entidad
• Grafo de Conocimiento — grafo interactivo de fuerza D3 con agrupación, clic para explorar
• Feed en Vivo — eventos de cambio de archivo y extracción de entidades en tiempo real vía WebSocket (solo desde cortex serve)
• Explorador de Consultas — consultas en lenguaje natural con respuestas en streaming
• Resolvedor de Contradicciones — revisar y resolver decisiones conflictivas

Despliegue Remoto

Para acceso más allá de localhost, vincula a todas las interfaces y coloca Cortex detrás de un proxy inverso:

cortex serve --host 0.0.0.0

Ejemplo de configuración nginx — protege /api/ y /ws con autenticación básica; sirve activos estáticos sin autenticación (el panel inyecta el token de portador en el HTML):

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

Establece CORTEX_SERVER_AUTH_TOKEN o server.auth.token en la configuración. Cuando la autenticación está habilitada, Cortex inyecta el token en el HTML del panel para que las llamadas API y WebSocket se autentiquen automáticamente.

Servidor MCP (Integración con Claude Code)

Cortex incluye un servidor MCP para que Claude Code pueda consultar tu grafo de conocimiento directamente:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

Esto le da a Claude Code 12 herramientas:

Herramienta	Descripción
cortex_ask	Preguntas en lenguaje natural sobre tus proyectos
get_status	Estado del sistema y estadísticas del grafo
list_projects	Listar proyectos registrados
find_entity	Buscar entidades por nombre
query_cortex	Consultas estructuradas al grafo de conocimiento
get_contradictions	Listar contradicciones detectadas
resolve_contradiction	Resolver una contradicción
search_entities	Buscar entidades con filtros
ingest_file	Activar ingesta de archivos
add_project	Registrar un nuevo proyecto
remove_project	Dar de baja un proyecto
session_brief	Resumen de contexto para la sesión actual

Arquitectura

Monorepositorio con ocho paquetes:

• @cortex/core — tipos, EventBus, cargador de configuración, clases de error
• @cortex/ingest — analizadores de archivos (tree-sitter + remark), fragmentador, observador, tubería
• @cortex/graph — almacén SQLite, vectores LanceDB, motor de consultas
• @cortex/llm — proveedores Anthropic/Gemini/compatible con OpenAI/Ollama, enrutador, prompts, caché
• @cortex/cli — CLI Commander.js
• @cortex/mcp — servidor de Protocolo de Contexto de Modelo (transporte stdio, 12 herramientas)
• @cortex/server — API REST Express + relay WebSocket
• @cortex/web — Panel web React + Vite + D3

Documentos de arquitectura: docs/

Privacidad y Seguridad

• Los archivos clasificados como restricted nunca se envían a LLMs en la nube
• Los archivos sensibles (.env, .pem, .key) se detectan y bloquean automáticamente
• Los secretos de claves API se escanean y redactan antes de cualquier transmisión a la nube
• Todos los datos se almacenan localmente en ~/.cortex/ — nada llama a casa

Arquitectura de seguridad completa: docs/security.md

Construido Con

• SQLite mediante better-sqlite3 — almacenamiento de entidades y relaciones
• LanceDB — embeddings vectoriales para búsqueda semántica
• Anthropic Claude — proveedor de LLM en la nube
• Google Gemini — proveedor de LLM en la nube (mediante API compatible con OpenAI)
• DeepSeek — proveedor de LLM en la nube (razonamiento + chat)
• Groq — inferencia rápida en la nube
• Ollama — inferencia local de LLM
• tree-sitter — análisis de archivos con reconocimiento de lenguaje
• Chokidar — observación de archivos multiplataforma
• Commander.js — framework de CLI
• React + Vite — panel web
• D3 — visualización de grafos de conocimiento

Contribuciones

Consulta CONTRIBUTING.md para conocer las pautas.

Licencia

MIT — consulta LICENSE

Acerca de

Creado por GZOO — una plataforma de automatización empresarial impulsada por IA.

Cortex comenzó como una herramienta interna para mantener el contexto en múltiples proyectos de clientes. Lo liberamos como código abierto porque todo desarrollador que trabaja en más de una cosa pierde contexto, y creemos que este enfoque — observación automática de archivos + grafo de conocimiento + consultas en lenguaje natural — es la forma correcta de resolverlo.