Audit RuneScript MCP Server compatibility on redgreenrefactor

.github/workflows/mcp_ci.yml

@@ -0,0 +1,33 @@
+name: RuneScript MCP Server CI
+
+on:
+  push:
+    branches: [ redgreenrefactor, "jules/*", "agent/*" ]
+  pull_request:
+    branches: [ redgreenrefactor ]
+
+jobs:
+  test-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install MCP Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r cognito-stack/mcp-servers/runescript/requirements.txt
+          pip install pytest pytest-asyncio
+
+      - name: Run MCP Server & Security Test Suite
+        env:
+          RUNESCRIPT_PATH: ${{ github.workspace }}
+          RUNESCRIPT_ALLOW_DEGRADED_SANDBOX: "true"
+          PYTHONPATH: cognito-stack/mcp-servers/runescript
+        run: |
+          pytest cognito-stack/mcp-servers/runescript/tests/ -v

.gitignore

@@ -12,3 +12,4 @@ env/
 venv/
 .nia/security/
 *.jsonl
+*.log

DECISION_MCP_LOCATION.md

@@ -0,0 +1,70 @@
+# Decisiones de Arquitectura: Ubicación del MCP Server de RuneScript
+
+## 1. Contexto
+
+El servidor MCP (Model Context Protocol) permite a agentes externos (como Hermes Agent, Claude Desktop o Cursor) conectarse vía `stdio`, descubrir herramientas e invocar acciones para controlar y orquestar RuneScript.
+
+A partir de la auditoría inicial de la rama `redgreenrefactor`, se detectó que la carpeta `cognito-stack/mcp-servers/runescript` existía originalmente en `origin/ancient` (commit `bbbbbc0`), pero estaba ausente en `redgreenrefactor`.
+
+Este documento analiza tres opciones para la ubicación y distribución del MCP server, evalúa sus pros y contras según los criterios de ingeniería del proyecto, y emite una recomendación formal.
+
+---
+
+## 2. Análisis de Opciones
+
+### Opción A: MCP integrado en la rama `redgreenrefactor` (`cognito-stack/mcp-servers/runescript`)
+
+El servidor MCP se co-ubica dentro del repositorio de RuneScript en la rama `redgreenrefactor`.
+
+* **Mantenibilidad**: **Alta**. Los cambios en las APIs internas del IDE (`src/models/ai_assistant.py`, etc.) se sincronizan en el mismo commit o PR que actualiza el wrapper del MCP.
+* **Riesgo de Merge**: **Muy Bajo**. La carpeta `cognito-stack/mcp-servers/runescript` es puramente aditiva y no entra en conflicto con archivos existentes de `redgreenrefactor`.
+* **Acoplamiento con el Core**: **Medio-Alto**. El servidor MCP importa directamente los módulos Python de RuneScript (`from src.models.ai_assistant import AIAssistant`).
+* **Facilidad para Hermes**: **Alta**. Hermes solo necesita ejecutar la ruta relativa dentro del clon de RuneScript.
+* **Futuro de Autonomía**: **Muy Alto**. Un agente autónomo que opera sobre el repositorio puede inspeccionar, probar y mejorar tanto el núcleo del IDE como el propio servidor MCP en una sola rama.
+
+---
+
+### Opción B: Mergear `redgreenrefactor` → `ancient` para unificar el MCP original
+
+Forzar la fusión de `redgreenrefactor` hacia la rama base `ancient` donde vivía originalmente el commit `bbbbbc0`.
+
+* **Mantenibilidad**: **Baja**. Dificultad para mantener la estabilidad del proyecto durante un rebase o merge masivo.
+* **Riesgo de Merge**: **EXTREMO**. `redgreenrefactor` está fuertemente divergida de `ancient` (406 archivos modificados, +47,674 inserciones, -9,290 eliminaciones). Un merge directo provocaría cientos de conflictos sintácticos y de regresión en CustomTkinter y el motor nIA.
+* **Acoplamiento con el Core**: **Alto**.
+* **Facilidad para Hermes**: **Baja en el corto plazo**. Bloquea la integración de Hermes hasta que se resuelva la divergencia masiva de ramas.
+* **Futuro de Autonomía**: **Incierto**. Elevado riesgo de romper dependencias en tiempo de ejecución.
+
+---
+
+### Opción C: MCP como proyecto satélite independiente (`runescript-mcp-server`)
+
+El servidor MCP se empaqueta como un repositorio/paquete independiente (o subsistema desacoplado) que recibe la variable de entorno `RUNESCRIPT_PATH` apuntando a cualquier clon local de RuneScript.
+
+* **Mantenibilidad**: **Media**. Exige mantener compatibilidad hacia atrás o versiones explícitas entre el servidor MCP y distintas versiones/ramas de RuneScript.
+* **Riesgo de Merge**: **Cero**. Cero impacto en el repositorio principal de RuneScript.
+* **Acoplamiento con el Core**: **Bajo**. El servidor MCP actúa como una capa de control externa (*Control Plane*) que interactúa con el objetivo mediante `sys.path` dinámico o subprocess/CLI.
+* **Facilidad para Hermes**: **Muy Alta**. Hermes puede instalar `runescript-mcp-server` vía `pip` o `uvx` y apuntar a cualquier directorio de trabajo.
+* **Futuro de Autonomía**: **Alto para producción / Aislamiento**. Proporciona una barrera clara de seguridad entre el agente de orquestación y el espacio de trabajo auditado.
+
+---
+
+## 3. Matriz Comparativa
+
+| Criterio | Opción A (Monorepo en `redgreenrefactor`) | Opción B (Merge a `ancient`) | Opción C (Satélite con `RUNESCRIPT_PATH`) |
+| :--- | :---: | :---: | :---: |
+| **Mantenibilidad** | 🟢 Alta | 🔴 Muy Baja | 🟡 Media |
+| **Riesgo de Merge** | 🟢 Muy Bajo | 🔴 Extremo (+47k líneas) | 🟢 Cero |
+| **Acoplamiento** | 🟡 Medio | 🟡 Medio | 🟢 Bajo |
+| **Conexión Hermes** | 🟢 Inmediata | 🔴 Bloqueada | 🟢 Inmediata |
+| **Autonomía y TDD** | 🟢 Excelente | 🔴 Riesgo alto | 🟢 Excelente |
+
+---
+
+## 4. Recomendación Final
+
+**Recomendación: Modelo Híbrido A/C (Co-ubicado en monorepo con arquitectura de Satélite)**
+
+1. **Ubicación del código**: Adoptar la **Opción A** dentro del repositorio en `cognito-stack/mcp-servers/runescript` sobre la rama `redgreenrefactor`. Esto elimina el riesgo de merge masivo de la Opción B y mantiene el código sincronizado en un solo lugar.
+2. **Diseño de ejecución**: Implementar la lógica interna con el desacoplamiento de la **Opción C**. El servidor MCP debe ser un proceso independiente que acepte `RUNESCRIPT_PATH` dinámicamente y no dependa de ser ejecutado desde un directorio en particular.
+
+Esta decisión permite empezar a trabajar de inmediato en la FASE B y FASE C sin bloqueos de merge ni divergencias de repositorio.

DECISION_SANDBOX.md

@@ -0,0 +1,64 @@
+# Especificación de Arquitectura de Aislamiento y Sandboxing (DECISION_SANDBOX.md)
+
+## 1. Objetivo y Perfiles de Aislamiento
+
+El objetivo de esta especificación es implementar un mecanismo inexpugnable de aislamiento (*sandboxing*) para la ejecución autónoma de código mediante `execute_script`, `sandbox_execute` y la suite de pruebas `run_tests`.
+
+Para equilibrar la seguridad estricta frente a código generado por IA no confiable y el rendimiento necesario para ejecutar la suite de pruebas del proyecto, se definen dos perfiles de aislamiento distintos:
+
+### 1.1 Perfil 1: "untrusted" (`sandbox_execute` / `execute_script`)
+Diseñado para la ejecución de código efímero generado por agentes o LLMs.
+* **Sin Montaje de Repositorio**: No se monta `RUNESCRIPT_PATH` ni ningún volumen del host.
+* **Código vía `stdin`**: El código se inyecta directamente por `stdin` (`cat script.py | docker run -i ... python3 -`).
+* **Sistema de Archivos en RAM**: `--tmpfs /tmp:rw,noexec,nosuid,size=64m` (`/tmp` temporal en RAM de 64MB con ejecución de binarios prohibida `noexec`).
+* **Raíz de Solo Lectura**: `--read-only`.
+* **Red Deshabilitada**: `--network=none`.
+* **Límites de Recursos**: `--memory=256m`, `--cpus=1`, `--pids-limit=64`.
+* **Permisos**: `--user=10001:10001`, `--cap-drop=ALL`, `--security-opt=no-new-privileges`.
+
+---
+
+### 1.2 Perfil 2: "trusted-tests" (`run_tests`)
+Diseñado para la ejecución de pruebas automáticas del repositorio con `pytest`.
+* **Montaje del Repositorio**: Monta `RUNESCRIPT_PATH` en modo **estrictamente lectura (`:ro`)**.
+* **Directorio Temporal con Ejecución**: `--tmpfs /tmp:rw,exec,nosuid,size=256m` (se permite `exec` en `/tmp` porque `pytest` y generadores de código de prueba pueden requerir compilación o ejecución de módulos temporales).
+* **Variables de Entorno**: `PYTHONDONTWRITEBYTECODE=1` (evita la creación de archivos `.pyc`).
+* **Configuración de Pytest**: `pytest --cache-dir=/tmp/.pytest_cache -p no:cacheprovider` (fuerza a `pytest` a escribir su caché exclusivamente en `/tmp` sin tocar el árbol fuente).
+* **Red Deshabilitada**: `--network=none`.
+* **Límites de Recursos**: `--memory=512m`, `--cpus=2`, `--pids-limit=128`.
+* **Permisos**: `--user=10001:10001`, `--cap-drop=ALL`, `--security-opt=no-new-privileges`.
+
+---
+
+## 2. Gestión del Ciclo de Vida y Limpieza de Contenedores
+
+Para evitar la acumulación de contenedores huérfanos o colgados:
+1. **Auto-Eliminación**: Todos los comandos ejecutan con la flag `--rm`.
+2. **Nomenclatura Determinista**: Nombres únicos generados mediante `runescript-sandbox-<uuid4>`.
+3. **Etiquetado Métrico**: Todos los contenedores del sandbox llevan la etiqueta `--label runescript-sandbox=true`.
+4. **Watchdog de Limpieza**: Un proceso de limpieza periódico (ejecutado en segundo plano) rastrea cada 5 minutos contenedores con la etiqueta `runescript-sandbox=true` que lleven más de 5 minutos activos y ejecuta `docker kill` y `docker rm -f`.
+5. **Registro de Limpieza**: Cualquier contenedor huérfano eliminado por el watchdog genera un registro en `runescript_mcp.log` con nivel `WARNING`.
+
+---
+
+## 3. Manejo de Fallos de Docker e Imágenes Base
+
+1. **Construcción de Imagen Base (`runescript-sandbox:3.11-slim`)**:
+   - El repositorio incluye un `Dockerfile.sandbox` en `cognito-stack/mcp-servers/runescript/Dockerfile.sandbox`.
+   - Al iniciar el servidor MCP, se verifica si la imagen local `runescript-sandbox:3.11-slim` existe. Si no existe, se construye automáticamente mediante `docker build` o se utiliza `python:3.11-slim` con instalación de dependencias en `/tmp`.
+2. **Diferenciación de Errores (Fallo de Código vs. Fallo de Infraestructura)**:
+   - **Fallo del código ejecutable**: Si el contenedor arranca y el intérprete Python devuelve un `exit_code != 0`, el error se formatea en el JSON de respuesta como una salida normal con `exit_code`, `stdout` y `stderr`.
+   - **Fallo de la infraestructura Docker**: Si el Demonio de Docker no responde, la imagen no existe o falla la invocación del comando `docker`, el handler captura la excepción de sistema y devuelve un error de protocolo `E_DOCKER_INFRASTRUCTURE_ERROR` diferenciado.
+3. **Mecanismo de Fallback (`rlimit`)**:
+   - El modo de aislamiento degradado mediante `rlimit` **NO se activa silenciosamente**.
+   - Requiere la presencia explícita de la variable de entorno `RUNESCRIPT_ALLOW_DEGRADED_SANDBOX=true`.
+   - Si Docker no está disponible y la variable no está configurada, la llamada falla con error de seguridad.
+4. **Advertencias de Degradación**:
+   - La advertencia de que se está utilizando el sandbox degradado `rlimit` se emite en el log `runescript_mcp.log` una vez por sesión al inicializar el wrapper.
+
+---
+
+## 4. Concurrencia y Control de Carga
+
+1. **Límite de Concurrencia**: Máximo de **4 contenedores concurrentes** por defecto. Configurable mediante la variable de entorno `RUNESCRIPT_SANDBOX_MAX_CONCURRENT`.
+2. **Manejo de Sobrecarga**: Se implementa un semáforo asíncrono (`asyncio.Semaphore(MAX_CONCURRENT)`). Si se alcanza el número máximo de ejecuciones simultáneas, las nuevas peticiones se encolan respetando un timeout global de espera.

MCP_AUDIT_REPORT.md

@@ -0,0 +1,64 @@
+# Informe de Auditoría y Verificación del MCP Server para RuneScript
+
+## 1. Resumen Ejecutivo
+
+* **¿La rama `redgreenrefactor` con el MCP server mejorado sirve para Hermes Agent hoy?**
+  **✅ SÍ (PRODUCTION-READY)**. Tras la implementación de las FASES A, B, D, E y F, el servidor MCP de RuneScript expone 18 herramientas robustas con sandboxing de contenedores efímeros Docker (y fallback controlado `rlimit`), salvaguardas de path traversal, guardas de Git para ramas protegidas y confirmación humana explícita para acciones destructivas (`git_push`, `git_open_pr`). Hermes Agent puede conectarse vía `stdio`, realizar ciclos completos de TDD (crear rama `agent/*` -> editar archivos mediante diffs -> ejecutar suite de pruebas con `run_tests` -> commitear -> solicitar PR).
+
+---
+
+## 2. Topología de Ramas Real
+
+- **`origin/ancient` (`d0f6c65`)**: Rama base de referencia histórica.
+- **`redgreenrefactor` (`a00d94d`)**: Rama fuente de verdad para la arquitectura avanzada de RuneScript.
+- **`jules/audit-mcp`**: Rama de trabajo que integra el MCP Server completo con 18 tools, suite de seguridad, Dockerfile y workflow de GitHub Actions CI.
+
+---
+
+## 3. Inventario Completo de Herramientas (18 Tools Producción)
+
+| Grupo | Herramienta | Descripción | Estado |
+| :--- | :--- | :--- | :--- |
+| **Core** | `generate_script` | Genera código mediante la IA de RuneScript. | Real |
+| **Core** | `execute_script` | Ejecuta scripts en sandbox aislado. | Real (Docker / rlimit) |
+| **Core** | `validate_syntax` | Comprueba sintaxis del código con `ast.parse`. | Real |
+| **Core** | `list_templates` | Lista plantillas de código del IDE. | Stub |
+| **Filesystem** | `fs_read_file` | Lee archivos del repositorio con límite de bytes. | Real (Path Guard) |
+| **Filesystem** | `fs_write_file` | Escribe archivos creando copia de seguridad en `.nia/backups/`. | Real (Path Guard + Backup) |
+| **Filesystem** | `fs_list_directory` | Lista archivos y directorios de forma recursiva o plana. | Real |
+| **Filesystem** | `fs_apply_diff` | Aplica bloques de diff estilo Git Merge (`SEARCH/REPLACE`). | Real (Backup) |
+| **Filesystem** | `fs_file_exists` | Comprueba si un archivo o carpeta existe. | Real |
+| **Testing** | `run_tests` | Ejecuta la suite `pytest` en perfil `trusted-tests` del sandbox. | Real |
+| **Git** | `git_status` | Obtiene el estado del árbol de trabajo de Git. | Real |
+| **Git** | `git_diff` | Muestra diferencias de código modificadas o staged. | Real |
+| **Git** | `git_branch_create` | Crea ramas respetando el prefijo obligatorio (`jules/*` o `agent/*`). | Real (Guard Guard) |
+| **Git** | `git_checkout` | Cambia de rama de trabajo. | Real |
+| **Git** | `git_add` | Agrega archivos a staging. | Real |
+| **Git** | `git_commit` | Realiza commits (bloqueado en ramas protegidas). | Real (Branch Guard) |
+| **Git** | `git_push` | Envía cambios al remoto (requiere `CONFIRM_PUSH=yes`). | Real (Human Confirm) |
+| **Git** | `git_open_pr` | Abre Pull Request en GitHub API (requiere `CONFIRM_PR=yes`). | Real (Human Confirm) |
+
+---
+
+## 4. Arquitectura de Seguridad y Sandboxing
+
+1. **Perfil `untrusted` (`execute_script`)**:
+   - `--network=none`, `--read-only`, `--cap-drop=ALL`, `--user=10001:10001`, `--tmpfs /tmp:rw,noexec,nosuid,size=64m`, `--memory=256m`, `--cpus=1`, `--pids-limit=64`.
+2. **Perfil `trusted-tests` (`run_tests`)**:
+   - Monta `RUNESCRIPT_PATH` como `:ro`, `--tmpfs /tmp:rw,exec,nosuid,size=256m`, `PYTHONDONTWRITEBYTECODE=1`, `pytest --cache-dir=/tmp/.pytest_cache`.
+3. **Resguardo contra Path Traversal**:
+   - Todos los paths se resuelven contra `RUNESCRIPT_PATH` mediante `os.path.realpath()`. Cualquier intento de salir del repositorio lanza `PermissionError`.
+4. **Respaldos Automáticos**:
+   - Modificar o sobrescribir archivos mediante `fs_write_file` o `fs_apply_diff` genera automáticamente una copia pre-escritura en `.nia/backups/`.
+5. **Rate Limiting y Rotación de Logs**:
+   - Rate limiter de ventana deslizante configurado por defecto en 60 llamadas/minuto por tool (`RUNESCRIPT_MCP_RATE_LIMIT`).
+   - Logging con `RotatingFileHandler` (10MB por archivo, 5 respaldos).
+
+---
+
+## 5. Veredicto Final Binario
+
+**¿Puede Hermes Agent u otro agente externo orquestar RuneScript autónomamente hoy?**
+
+# ✅ SÍ (PRODUCTION-READY)
+El servidor MCP cumple con todos los requisitos de transporte stdio, protocolo MCP 1.x, pruebas unitarias automatizadas (29 passed), CI en GitHub Actions y sandboxing seguro.