🌀 MCP HUB V12 — Unified Context Vortex & Memory Gateway

El servidor MCP centralizado definitivo. Un solo punto de entrada (mcp_stdio.py) que proporciona más de 40 herramientas para Inteligencia Contextual, Code Guardian, Vision, y Memory Gateway respaldado por MemPalace.

---

🏗️ Arquitectura Unificada (Agnóstica)

El HUB V12 consolida todas las características en un único servidor MCP agnóstico compatible con cualquier cliente (OpenCode, Claude Code, Gemini CLI, Cursor, etc.). Utiliza transporte estándar stdio garantizando una comunicación JSON-RPC estable sin interferencias visuales.

📊 Diagrama de Arquitectura

---

🔄 Flujo de Datos y Ciclo de Vida de la Información

El ciclo de vida de los datos está diseñado para maximizar el rendimiento del LLM minimizando el consumo de tokens mediante compresión y recuperación contextual:

1. Ingesta (Input):
   • El agente ejecuta herramientas como gateway_add_task o gateway_add_adr.
   • Code Guardian indexa código automáticamente (index_code).
2. Persistencia (Storage):
   • Los datos se almacenan en las "Rooms" de MemPalace.
   • Las relaciones complejas y fragmentos de texto son administrados directamente por el motor unificado de MemPalace, eliminando la necesidad de bases de datos externas fragmentadas o dependencias pesadas como torch.
3. Compresión (Lifecycle Management):
   • El historial temporal (/context) y las sesiones se comprimen incrementalmente mediante gateway_compress_session hacia la room /summaries.
4. Recuperación (Output):
   • En cada iteración de desarrollo, el agente llama a gateway_build_context.
   • Esta herramienta recupera tareas activas, el stack del proyecto (/knowledge), las decisiones de arquitectura (/decisions) y los resúmenes recientes.
   • Resultado: En lugar de inyectar 20,000 tokens de historial de chat, el LLM recibe un super-prompt compilado de apenas ~200 tokens con el contexto exacto.

---

🛠️ Herramientas Disponibles (43 Tools Unificadas)

El HUB expone un arsenal completo de herramientas agrupadas por capacidad para brindar autonomía total a los agentes:

🌐 V12 Memory Gateway (MemPalace)

Gestiona la persistencia a largo plazo y el conocimiento del proyecto:

• gateway_status: Obtiene el estado actual de la memoria y la feature activa.
• gateway_set_active_feature: Cambia el foco del agente hacia una rama/feature específica.
• gateway_add_adr: Añade un Architectural Decision Record (ADR) para documentar decisiones clave.
• gateway_add_knowledge: Añade reglas, convenciones o conocimiento estable del stack del proyecto.
• gateway_add_task: Registra una nueva tarea en el backlog (estados: todo, in_progress, done).
• gateway_compress_session: Analiza y comprime el historial reciente para reducir consumo de tokens.
• gateway_build_context: Herramienta Estrella. Compila un super-prompt ultracompacto (ADRs, conocimiento, y tareas activas) para inyectar al LLM al iniciar un agente.

🛡️ Code Guardian

Prevención de errores y análisis de calidad antes de escribir código:

• check_code_creation: Realiza validaciones estáticas y previene malas prácticas antes de la modificación.
• analyze_project_redundancy: Escanea el repositorio para evitar reescribir utilidades que ya existen.
• get_code_suggestions: Revisa fragmentos y sugiere mejoras de optimización.
• learn_from_context: Analiza el estilo del proyecto para adaptar futuras generaciones de código.

🌀 Context Vortex & Indexing (Code Intel)

Herramientas de recuperación y entendimiento semántico del código:

• index_code: Fuerza la indexación AST de un directorio o archivo específico al motor unificado.
• search_entity: Busca clases, funciones o variables exactas dentro de la base de código.
• extended_index / extended_search: Búsqueda profunda en documentaciones, constantes y patrones.
• get_knowledge_summary: Extrae un mapa mental de la estructura actual del proyecto.

🧠 Smart Sessions & Orchestration

Herramientas para mantener el enfoque de agentes múltiples:

• create_session / delete_session / list_sessions: Gestión del ciclo de vida de conversaciones.
• get_session_summary: Recupera un resumen narrativo de qué se hizo en sesiones anteriores.
• smart_session_init / smart_query: Motor iterativo de preguntas/respuestas respaldado por MemPalace.
• get_smart_status / get_system_status: Verificación de salud del HUB y sus subsistemas.

🌍 World Model & Quality (JEPA)

Validación factual anti-alucinaciones:

• sync_world_model: Sincroniza el estado actual de los archivos clave con la memoria interna.
• audit_jepa: Evalúa una propuesta de código del LLM cruzándola contra el modelo del mundo del proyecto para detectar alucinaciones.
• check_quality / get_quality_principles: Verificación de QA y reglas estables.

⚙️ Herramientas Base (V5 Core)

• ping: Verificación de latencia y conectividad del MCP.
• get_context: Búsqueda de vectores en crudo sobre MemPalace.
• validate_response: Herramienta interna de auto-evaluación.
• index_status: Comprueba cuántos archivos/tokens están indexados actualmente.

🌐 Herramientas Específicas de Framework (Django/FE)

• escanear_urls_django: Encuentra e indexa rutas de un proyecto Django automáticamente.
• analizar_tokens_css: Extrae variables y clases utilitarias de CSS/Tailwind.

👁️ Vision Specialist

• Toma asíncrona de screenshots a través de Playwright y análisis de interfaz usando FastVLM (Lazy-loaded para velocidad extrema de inicio del MCP).

---

🚀 Inicio Rápido y Configuración

No es necesario arrancar el servidor manualmente. El cliente MCP (ej. OpenCode) lo inicializa automáticamente cuando es requerido a través de stdio.

Requisitos

pip install -r requirements.txt
playwright install chromium

Configuración en Clientes

El HUB debe registrarse en tu cliente apuntando a mcp_stdio.py.

Ejemplo para opencode.json:

"memory-gateway": {
    "command": [
        "python",
        "\\HUB\\core\\mcp_stdio.py"
    ],
    "type": "local",
    "enabled": true
}

---

🧹 Estructura del Proyecto

Se ha eliminado el código redundante y mantenido una arquitectura ultra-limpia:

HUB/
├── core/
│   ├── mcp_stdio.py                 # 🌟 PUNTO DE ENTRADA ÚNICO (Transporte Stdio)
│   ├── mcp_http_server.py           # Engine Principal (FastMCP) y lógica de herramientas
│   ├── mempalace_backend.py         # Conector unificado de MemPalace
│   ├── visual_monitor.py            # Monitor Visual (Apagado preventivamente en stdio)
│   ├── pretty_logger.py             # Logging seguro para consolas (evita corrupción JSON-RPC)
│   ├── advanced_features/           # Componentes de Code Guardian y Vortex
│   ├── vision/                      # Módulo de procesamiento visual
│   ├── memory/                      # Gestión de estados y contexto
│   └── storage/                     # Wrappers de persistencia
├── data/                            # Almacenamiento local de la memoria (ignorado en git)
├── logs/                            # Registros de ejecución
└── tests/                           # Suite de 17 tests unitarios y de integración (100% passing)

---

Versión: V12.0.0 (Unified Architecture)
Estado: Estable, Unit Tests 100% Passed.