Menager MCP Server

menager es un servidor de Model Context Protocol (MCP) basado en TypeScript, diseñado para la orquestación de terminales entre sesiones. Permite que una sesión de agente de IA (o un operador humano) actúe como un plano de control maestro capaz de crear, supervisar, manejar y engancharse a entornos de terminal hijo (herramientas CLI, agentes de IA secundarios, shells interactivos o runtimes políglotas) mediante pseudo-terminales POSIX estándar (pty).

Tabla de contenido

• Características

• Instalación

• Uso

  • Inicio del servidor

• Herramientas disponibles

  • session_spawn

  • session_write

  • session_read

  • session_hook

  • session_signal

  • session_list

• Configuración con asistentes de IA

Related MCP server: pty-mcp

Características

• Multiplexación de entornos políglotas: Maneja procesos interactivos escritos en cualquier idioma mediante pseudo-terminales POSIX estándar.

• Escritura humana simulada: Inyecta texto, secuencias de control (SIGINT, EOF, Ctrl+C) y pulsaciones de teclado en bruto directamente en el stdin hijo.

• Intercepción predecible de eventos: Proporciona hooks de regex no bloqueantes con garantías de tiempo de espera y respuestas automáticas inmediatas opcionales.

• Observabilidad con memoria limitada: Mantiene búferes circulares dedicados por sesión (5000 líneas por defecto) con eliminación de códigos ANSI en tiempo real para un consumo eficiente en tokens del contexto de LLM.

• Asincronía estricta y disciplina de recursos: El manejo de eventos sigue siendo puramente dirigido por eventos mediante emisores de eventos y promesas de Node.js; los límites del búfer se aplican estrictamente para evitar fugas de memoria.

Instalación

Instalación manual

# Clone the repository
git clone <your-repo-url>
cd menager

# Install dependencies (requires build-essential/g++ for node-pty native bindings)
npm install

# Build the project
npm run build

Uso

Inicio del servidor

El servidor se ejecuta mediante el transporte Stdio, diseñado para ser ejecutado directamente por clientes MCP.

# Start the server (standard mode)
npm start

# Or run the built file directly
node build/index.js

Herramientas disponibles

session_spawn

Crea una nueva sesión PTY hija.

• command (string): Binario o ejecutable de destino (p. ej., bash, python3). Obligatorio.

• args (string[]): Argumentos de línea de comandos.

• cwd (string): Ruta del directorio de trabajo.

• env (object): Variables de entorno adicionales.

• maxBufferLines (number): Límite móvil de líneas para los búferes de memoria (por defecto 5000).

• terminalType (string): Tipo de emulación de terminal ("dumb" o "xterm-256color", por defecto "xterm-256color").

• name (string): Nombre o etiqueta lógica opcional para la sesión.

• cols (number): Columnas de la terminal (por defecto 80).

• rows (number): Filas de la terminal (por defecto 24).

session_wait

Bloquea y espera a que una sesión termine correctamente, devolviendo su código de salida final.

• sessionId (string): ID de la sesión de destino. Obligatorio.

• timeoutMs (number): Tiempo de espera opcional en milisegundos.

session_write

Inyecta pulsaciones de teclado, comandos o secuencias de escape en la entrada estándar de la sesión.

• sessionId (string): ID de la sesión de destino. Obligatorio.

• payload (string): Cadena o secuencia de caracteres de control. Obligatorio.

• pressEnter (boolean): Añade \n a la carga útil (por defecto false - Cambio importante en v4).

• pressKey (string): Inyección de teclas especiales (Ctrl+C, Ctrl+D, Enter, Tab, Escape, ArrowUp, ArrowDown).

session_read

Lee la salida almacenada en el búfer de la sesión de destino.

• sessionId (string): ID de la sesión de destino. Obligatorio.

• tailLines (number): Número de líneas finales a recuperar (por defecto 100).

• stripAnsi (boolean): Devuelve texto saneado sin códigos ANSI (por defecto true).

• clearBuffer (boolean): Vacía los búferes internos después de la lectura (por defecto false).

• offsetLines (number): Lee las líneas a partir de este índice de desplazamiento absoluto (sustituye a tailLines).

• grepPattern (string): Prefiltra las líneas del búfer mediante coincidencias de cadenas Regex.

session_hook

Espera un patrón regex específico en el flujo de la sesión con respuesta automática opcional.

• sessionId (string): ID de la sesión de destino. Obligatorio.

• pattern (string): Cadena de expresión regular a observar. Obligatorio.

• timeoutMs (number): Milisegundos antes de agotar el tiempo (por defecto 30000).

• autoResponse (string): Cadena opcional para escribir inmediatamente al producirse una coincidencia.

• triggerPayload (string): Escribe la carga útil después de que el hook se registre (evita el bloqueo por concurrencia).

session_resize

Cambia el tamaño de las dimensiones de la terminal PTY de destino.

• sessionId (string): ID de la sesión de destino. Obligatorio.

• cols (number): Columnas de la terminal. Obligatorio.

• rows (number): Filas de la terminal. Obligatorio.

session_signal

Envía una señal POSIX a la sesión de destino (con terminación recursiva del árbol de procesos).

• sessionId (string): ID de la sesión de destino. Obligatorio.

• signal (string): Señal a entregar (SIGINT, SIGTERM, SIGKILL). Obligatorio.

session_close

Fuerza la terminación del árbol de procesos de la sesión y elimina inmediatamente los búferes de memoria.

• sessionId (string): ID de la sesión de destino. Obligatorio.

session_prune

Elimina sesiones de forma forzada para liberar memoria.

• status (string): Solo elimina sesiones con este estado ("running" o "exited"). Por defecto "exited".

session_info

Devuelve los metadatos y métricas en tiempo real de una sola sesión.

• sessionId (string): ID de la sesión de destino. Obligatorio.

session_list

Lista todas las sesiones activas y completadas gestionadas por el servidor. No requiere parámetros.

Configuración con asistentes de IA

Configuración con Roo Code o Cline

1. Abre el archivo de configuración de MCP (normalmente cline_mcp_settings.json o config.json).

2. Añade la siguiente configuración para el modo stdio estándar:

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

Configuración con Claude Desktop

1. Abre claude_desktop_config.json.

2. Añade la siguiente configuración:

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