mcp-vitacore

MCP Context Project Vitacore: consolidación de memoria de sesiones con Gemini (resúmenes y evolución del Macro) y SQLite (persistencia).

Variables de entorno

Variable	Obligatoria	Default	Descripción
GEMINI_API_KEY	Sí	—	API Key de Google AI (Gemini).
VITACORE_DB_PATH	No	./data/vitacore.sqlite	Ruta del archivo SQLite.
GEMINI_MODEL	No	gemini-2.0-flash	Modelo Gemini (ej. gemini-2.0-flash).
GEMINI_TIMEOUT_MS	No	60000	Timeout en ms para llamadas a Gemini (AbortSignal).

Para Vertex AI u otra base URL, consultar la documentación de @google/genai (p. ej. GEMINI_BASE_URL si el SDK lo soporta).

Arranque

• Local: npm run build && npm start (o npm run dev). Requiere GEMINI_API_KEY en el entorno.
• Docker: docker compose up --build. Pasar GEMINI_API_KEY vía .env o env. El volumen vitacore_data persiste la DB.

Al iniciar se valida que GEMINI_API_KEY esté definida y se hace una llamada mínima a Gemini (generateSessionSummary([])). Si falla, se escribe en stderr y process.exit(1).

Flujo de datos

• Bottom-up: Tools MCP → Application (logStep, closeSession, hydrateAgentContext, evolveMacro) → Ports (StoragePort, GeminiPort) → Adapters (SQLite, Gemini).
• Top-down: El agente/orquestador llama a las tools; la aplicación orquesta storage + gemini y devuelve ToolResult; los adaptadores realizan I/O.

Tools MCP

Base (V1/V2)

• log_step — session_id, action, implications: registra un paso en la sesión.
• close_session — session_id: obtiene steps, genera resumen con Gemini y persiste la sesión. Idempotencia: si la sesión ya está cerrada, devuelve "Sesión ya cerrada." sin llamar a Gemini.
• hydrate_agent_context — role (opcional): devuelve macro + últimas 3 sesiones + debates abiertos (filtro por role).
• trigger_macro_evolution — sin args: evoluciona el Macro con las últimas 10 sesiones y Gemini y guarda.

V3 — Subconsciente Activo

El modelo de fondo (Gemini) actúa como curador y corrector: el agente en Cursor (Sistema 1) escribe código; el MCP con Gemini (Sistema 2) sintetiza, detecta contradicciones y propone refactors. SQLite es el tejido donde ambos se comunican.

• ask_the_oracle — technical_doubt: consulta una duda técnica. El MCP toma los últimos N steps (contexto reciente), los envía a Gemini y devuelve una directiva técnica curada (3 pasos). El agente nunca lee bitácora cruda para esa duda.
• check_architectural_health — sin args: compara el Macro con los resúmenes de sesiones recientes vía Gemini; detecta paradojas (contradicciones), las persiste en la tabla paradoxes y devuelve un resumen. Si hay paradojas, el agente puede usar resolve_architectural_paradox para ver el análisis.
• resolve_architectural_paradox — paradox_id: lee la paradoja por id, opcionalmente pide a Gemini una sugerencia de resolución, la marca como resuelta y devuelve descripción, análisis y sugerencia al agente.
• submit_for_background_review — session_id: toma los steps de esa sesión y el Macro, llama a Gemini para generar un plan de refactor desde la bitácora (deuda técnica, extracciones sugeridas) y lo persiste en refactor_plans. No requiere acceso al código; la revisión es sobre la bitácora.
• get_pending_refactors — module_name (opcional): lista los planes de refactor pendientes; si se pasa module_name, filtra por ese módulo.

Uso con Cursor

El MCP se consume por stdio. En el host, ejecutar el binario y configurar en .cursor/mcp.json el comando que arranca este servidor.

Cursor: uso standalone (repo por separado)

Si este repo se usa solo (sin orquestador):

npm install && npm run build

En .cursor/mcp.json del workspace:

"mcp-vitacore": {
  "command": "node",
  "args": ["mcp-vitacore/dist/index.js"],
  "env": {
    "GEMINI_API_KEY": "TU_API_KEY",
    "VITACORE_DB_PATH": "./data/vitacore.sqlite"
  }
}

Ajustá args si el MCP está en otra ruta. Reiniciar Cursor tras cambiar mcp.json.