REPL MCP Server

Un administrador de sesiones REPL universal compatible con Python, Node.js, Ruby y más, con gestión de sesiones y recuperación asistida por LLM.

GitHub

Prueba este MCPPatrocinado

Documentación

repl-mcp

Un servidor MCP simple para gestionar sesiones REPL. Proporciona herramientas básicas para crear y ejecutar comandos en varios REPLs y shells, con una interfaz web integrada para la monitorización de sesiones desde el navegador.

Motivación

Trabajar con REPLs remotos (como la consola de Rails en servidores de producción) a menudo te obliga a comprimir operaciones complejas en comandos individuales, ya que perder la conexión significa perder el estado de tu sesión. Esta herramienta permite sesiones REPL persistentes que sobreviven a ejecuciones de comandos individuales, permitiéndote trabajar de forma natural con entornos interactivos a través de agentes de IA. La interfaz web integrada proporciona monitorización basada en navegador para la observación de sesiones.

Características

Características principales

Soporte de múltiples REPLs: Python, IPython, Node.js, Ruby (pry, irb), bash, zsh
Gestión de sesiones: Crear, ejecutar comandos y destruir sesiones REPL
Integración con interfaz web: Monitorización de terminal basada en navegador para la observación de sesiones
Configuración personalizable: Configura comandos de inicio y variables de entorno
Multiplataforma: Funciona en Windows, macOS y Linux

Características adicionales

Recuperación por tiempo de espera: Asistencia de LLM cuando los comandos agotan el tiempo
Aprendizaje de sesiones: Recuerda patrones de prompt dentro de las sesiones

Monitorización de sesiones basada en navegador

URLs de sesión: http://localhost:8023/session/SESSION_ID - Monitoriza sesiones en el navegador
Puertos dinámicos: Selecciona automáticamente puertos disponibles a partir del 8023
Multiplataforma: Funciona en cualquier dispositivo con navegador moderno
Tiempo real: Salida de terminal en vivo mediante conexión WebSocket

Instalación

VS Code

Haz clic en el botón de arriba o añádelo a tu .vscode/mcp.json:

{
  "servers": {
    "repl-mcp": {
      "command": "npx",
      "args": ["-y", "repl-mcp@latest"]
    }
  }
}

Claude Code

claude mcp add repl-mcp -- npx -y repl-mcp@latest

Configuración manual de MCP

Añade a tu archivo de configuración de MCP:

{
  "mcpServers": {
    "repl-mcp": {
      "command": "npx",
      "args": ["-y", "repl-mcp@latest"]
    }
  }
}

Desde el código fuente

Clona este repositorio
Instala las dependencias: npm install
Compila el proyecto: npm run build
Añade a tu configuración de MCP:

{
  "mcpServers": {
    "repl-mcp": {
      "command": "node",
      "args": ["path/to/repl-mcp/build/index.js"]
    }
  }
}

Herramientas disponibles

`create_session`

Crea una nueva sesión REPL con configuración predefinida o personalizada. Usa displayName para establecer un nombre personalizado que aparezca en el título de la pestaña del navegador. Devuelve un webUrl que se puede abrir en un navegador para monitorizar la sesión mediante la interfaz web.

Parámetros:

presetConfig (opcional): Nombre de la configuración predefinida
displayName (opcional): Nombre personalizado para la sesión (se muestra en la pestaña del navegador)
customConfig (opcional): Objeto de configuración personalizada

Ejemplo con configuración predefinida:

{
  "presetConfig": "pry",
  "displayName": "My Ruby Session"
}

Ejemplo con configuración personalizada:

{
  "displayName": "Custom Python Session",
  "customConfig": {
    "type": "python",
    "shell": "bash",
    "commands": ["python3"],
    "timeout": 10000
  }
}

Respuesta:

{
  "success": true,
  "sessionId": "abc123",
  "config": "Ruby Pry REPL",
  "webUrl": "http://localhost:8023/session/abc123"
}

La respuesta incluye:

sessionId: Identificador único de sesión (formato de 6 caracteres)
webUrl: URL del navegador para la monitorización de la sesión
config: Nombre de la configuración utilizada

`send_input_to_session`

Envía entrada a una sesión REPL.

Parámetros:

sessionId: El ID de la sesión
input: Texto de entrada para enviar a la sesión
options (opcional): Objeto de opciones de entrada
- wait_for_prompt (por defecto: false): Esperar a que vuelva el prompt
- timeout (por defecto: 30000): Tiempo de espera en milisegundos
- add_newline (por defecto: true): Añadir nueva línea a la entrada

Ejemplo:

{
  "sessionId": "abc123",
  "input": "puts 'Hello, World!'",
  "options": {
    "wait_for_prompt": true
  }
}

`list_repl_sessions`

Lista todas las sesiones REPL activas. Cada sesión incluye un webUrl para acceso desde el navegador.

La respuesta incluye:

sessions: Array de objetos de sesión con webUrl para cada una
Cada sesión incluye: id, name, type, status, webUrl, etc.

`get_session_details`

Obtiene información detallada sobre una sesión específica. Incluye webUrl para acceso desde el navegador.

Parámetros:

sessionId: El ID de la sesión

La respuesta incluye:

session: Información detallada de la sesión
webUrl: URL del navegador para la monitorización de la sesión

`destroy_repl_session`

Destruye una sesión REPL existente.

Parámetros:

sessionId: El ID de la sesión

`list_repl_configurations`

Lista todas las configuraciones REPL predefinidas disponibles.

`send_signal_to_session`

Envía una señal (como Ctrl+C, Ctrl+Z) para interrumpir o controlar el proceso de una sesión REPL.

Parámetros:

sessionId: El ID de la sesión
signal: Señal a enviar (SIGINT, SIGTSTP, SIGQUIT)

Ejemplo:

{
  "sessionId": "abc123",
  "signal": "SIGINT"
}

Nota sobre Windows: En Windows, solo SIGINT es prácticamente efectivo. Se envía como un evento Ctrl+C y se puede usar para interrumpir comandos en ejecución o terminar procesos compatibles como los REPLs de Node.js. SIGTSTP y SIGQUIT no tienen efecto.

`set_session_ready`

Marca una sesión como lista con un patrón de prompt específico. Se utiliza durante la recuperación de sesiones.

Parámetros:

sessionId: El ID de la sesión
pattern: Patrón de prompt (regex o cadena literal)

Ejemplo:

{
  "sessionId": "abc123",
  "pattern": "❯ "
}

`wait_for_session`

Espera tiempo adicional para que una sesión esté lista.

Parámetros:

sessionId: El ID de la sesión
seconds: Número de segundos a esperar

Ejemplo:

{
  "sessionId": "abc123",
  "seconds": 5
}

`mark_session_failed`

Marca una sesión como fallida con un motivo.

Parámetros:

sessionId: El ID de la sesión
reason: Motivo del fallo

Ejemplo:

{
  "sessionId": "abc123",
  "reason": "Process crashed"
}

Configuraciones predefinidas

Nota: Cada herramienta REPL debe estar instalada y disponible en tu PATH.

Configuraciones REPL

pry: REPL de Ruby Pry con funciones avanzadas de depuración
irb: REPL de Ruby IRB con funcionalidad estándar
ipython: REPL de Python mejorado con funciones enriquecidas
node: REPL de JavaScript de Node.js
python: REPL estándar de Python

Configuraciones de shell

bash: Entorno de shell Bash
zsh: Entorno de shell Zsh (con soporte para Oh My Zsh)

Configuraciones avanzadas

rails_console: Consola de Rails con bundle exec
rails_console_production: Consola de Rails de producción

Recuperación de sesiones

Cuando las sesiones agotan el tiempo de espera o dejan de responder, puedes usar las herramientas de recuperación:

send_signal_to_session - Envía Ctrl+C, Ctrl+Z u otras señales para interrumpir procesos
set_session_ready - Marca la sesión como lista cuando detectes un prompt funcional
wait_for_session - Espera más tiempo para que los comandos lentos se completen
mark_session_failed - Marca la sesión como fallida cuando la recuperación no es posible

Los patrones de prompt aprendidos durante la recuperación se recuerdan durante la duración de la sesión.

Ejemplos de uso

Uso básico de REPL

Crear una sesión de Python

{
  "tool": "create_session",
  "arguments": {
    "presetConfig": "python",
    "displayName": "My Python Session"
  }
}

Respuesta:

{
  "success": true,
  "sessionId": "xyz789",
  "config": "Python REPL",
  "webUrl": "http://localhost:8023/session/xyz789"
}

Ejecutar código Python

{
  "tool": "send_input_to_session",
  "arguments": {
    "sessionId": "xyz789",
    "input": "print('Hello from REPL!')",
    "options": {
      "wait_for_prompt": true
    }
  }
}

Monitorización de sesiones con interfaz web

Para monitorizar una sesión, créala usando las herramientas MCP y abre el webUrl de la respuesta en un navegador. Esto te permite observar la actividad del terminal en tiempo real.

Flujo de trabajo de ejemplo:

Crea la sesión mediante MCP para obtener un webUrl.
Abre la URL en un navegador (por ejemplo, http://localhost:8023/session/xyz789), manualmente o usando herramientas de automatización como Playwright MCP.
Observa el terminal en vivo.

Ejemplo de recuperación de sesión

Cuando un comando agota el tiempo de espera o se bloquea, puedes recuperar la sesión:

Interrumpir con Ctrl+C:

{
  "tool": "send_signal_to_session",
  "arguments": {
    "sessionId": "xyz789",
    "signal": "SIGINT"
  }
}

Marcar la sesión como lista:

{
  "tool": "set_session_ready",
  "arguments": {
    "sessionId": "xyz789",
    "pattern": "❯ "
  }
}

Gestión de sesiones

Cada sesión mantiene:

ID de sesión único: Formato de 6 caracteres para fácil identificación y gestión
Detalles de configuración: Tipo de REPL, shell, comandos de inicio, etc.
Estado actual: initializing, ready, executing, error, terminated
Historial de comandos: Registro de comandos ejecutados
Última salida y errores: Resultados de ejecución más recientes
Marcas de tiempo de creación y actividad: Seguimiento del ciclo de vida de la sesión
Patrones de prompt aprendidos: Patrones personalizados descubiertos mediante asistencia de LLM
Acceso a la interfaz web: URL del navegador para la monitorización de la sesión

Ciclo de vida de la sesión

Inicialización: La sesión se crea con la configuración especificada
Lista: La sesión está preparada para la ejecución de comandos
Ejecutando: El comando se está procesando
Aprendiendo: Asistencia de LLM para la detección de prompts (cuando es necesario)
Optimizada: Los patrones aprendidos permiten una ejecución rápida

Manejo de errores

El servidor proporciona un manejo integral de errores con recuperación inteligente:

Manejo de errores tradicional

Fallos en la creación de sesiones: Mensajes de error claros con información de diagnóstico
Tiempos de espera en la ejecución de comandos: Manejo elegante del tiempo de espera con opciones de reintento
Bloqueos de REPL y recuperación: Detección automática y gestión del estado de la sesión
Detección de comandos no válidos: Validación de entrada e informes de error

Recuperación mejorada con LLM

Fallos en la detección de prompts: Consulta automática al LLM para prompts desconocidos
Manejo adaptativo del tiempo de espera: Espera inteligente basada en la complejidad del comando
Soporte de entornos personalizados: Aprendizaje dinámico para shells no estándar
Análisis de errores contextuales: Información de error enriquecida para la resolución de problemas

Formato de respuesta de error

Error estándar:

{
  "success": false,
  "error": "Session not found",
  "executionTime": 0
}

Error asistido por LLM:

{
  "success": false,
  "error": "Timeout - LLM guidance needed",
  "question": "Session timed out. What should I do?",
  "questionType": "timeout_analysis",
  "canContinue": true,
  "context": { "sessionId": "...", "rawOutput": "..." }
}

Desarrollo

Compilación

npm run build

Modo de desarrollo

npm run dev

Esto iniciará TypeScript en modo de observación para el desarrollo.

Notas específicas de plataforma

Windows

Usa cmd o powershell como shell predeterminado
Algunas funciones de REPL pueden comportarse de manera diferente
Manejo de señales: Solo SIGINT se admite de forma efectiva. Se traduce a un evento Ctrl+C, que puede detener la mayoría de las herramientas de línea de comandos y salir de REPLs como Node.js. SIGTSTP (Ctrl+Z) y SIGQUIT (Ctrl+\) no son compatibles con la consola de Windows y no tendrán efecto.

macOS/Linux

Usa bash o zsh como shell predeterminado
Soporte completo de funciones

Solución de problemas

Problemas comunes

Falla la creación de la sesión: Comprueba que el comando REPL requerido esté instalado y sea accesible
Los comandos agotan el tiempo de espera constantemente: Aumenta el valor del tiempo de espera o comprueba la capacidad de respuesta del REPL
REPL no encontrado: Asegúrate de que el ejecutable del REPL esté en tu PATH

Problemas con la interfaz web

Conflictos de puertos: El servidor encuentra automáticamente puertos disponibles a partir del 8023
El terminal del navegador no responde: Comprueba que JavaScript esté habilitado e intenta actualizar
La URL de la sesión no funciona: Verifica que la sesión siga activa y que el puerto sea correcto
Problemas de tamaño del terminal: El terminal usa un tamaño de 132x43 para una mejor compatibilidad de aplicaciones

Problemas de recuperación de sesiones

La sesión se bloquea: Usa send_signal_to_session con SIGINT para interrumpir procesos atascados
El patrón no funciona: Usa set_session_ready con el patrón de prompt correcto
Los comandos agotan el tiempo de espera: Prueba wait_for_session para comandos lentos o send_signal_to_session para interrumpir

Buenas prácticas

Para shells complejos

Prompts personalizados: Usa set_session_ready para especificar tu patrón de prompt
Entornos anidados: Usa wait_for_session para entornos que necesitan tiempo para estabilizarse
Procesos atascados: Usa send_signal_to_session para interrumpir comandos de larga duración

Consejos de rendimiento

Aprendizaje de sesiones: Los patrones aprendidos durante la asistencia del LLM mejoran los comandos posteriores
Múltiples sesiones: Cada sesión aprende de forma independiente

Información de depuración

Variables de entorno

REPL_MCP_DEBUG=1: Habilita el registro de depuración detallado para la resolución de problemas de rendimiento y el desarrollo

Habilita la depuración detallada comprobando el campo debugLogs en las respuestas:

{
  "success": true,
  "output": "...",
  "debugLogs": [
    "2025-06-22T15:31:15.504Z: [DEBUG session_xxx] Prompt detected: true",
    "2025-06-22T15:31:15.505Z: [DEBUG session_xxx] Learned new prompt pattern: '∙'"
  ]
}

Contribuciones

¡Las contribuciones son bienvenidas! Las funciones asistidas por LLM facilitan la adición de soporte para nuevos entornos de shell y tipos de REPL. Al contribuir:

Prueba con diferentes shells: Asegura la compatibilidad entre bash, zsh y otros entornos
Considera variaciones de prompts: Prueba con prompts y temas personalizados
Actualiza las configuraciones: Añade nuevas configuraciones predefinidas para configuraciones comunes
Documenta los patrones de LLM: Comparte patrones de prompt exitosos para otros

Licencia

Licencia MIT