Background Process MCP

Un servidor que proporciona capacidades de gestión de procesos en segundo plano, permitiendo a los LLMs iniciar, detener y monitorear procesos de línea de comandos de larga duración.

GitHub
11

Documentación

Background Process MCP

Un servidor de Model Context Protocol (MCP) que proporciona capacidades de gestión de procesos en segundo plano. Este servidor permite a los LLM iniciar, detener y monitorear procesos de línea de comandos de larga duración.

Motivación

Algunos agentes de IA, como Claude Code, pueden gestionar procesos en segundo plano de forma nativa, pero muchos otros no pueden. Este proyecto proporciona esa capacidad como una herramienta estándar para otros agentes como el CLI de Gemini de Google. Funciona como un servicio separado, haciendo que la gestión de tareas de larga duración esté disponible para una gama más amplia de agentes. También añadí una TUI porque quería poder monitorear los procesos yo mismo.

Captura de pantalla

TUI Screenshot

Primeros pasos

Para comenzar, instala el servidor Background Process MCP en tu cliente preferido.

Configuración estándar

Esta configuración funciona para la mayoría de los clientes MCP:

{
  "mcpServers": {
    "backgroundProcess": {
      "command": "npx",
      "args": [
        "@waylaidwanderer/background-process-mcp@latest"
      ]
    }
  }
}

Para conectarte a un servidor independiente, añade el argumento --port al array args (por ejemplo, ...mcp@latest", "--port", "31337"]).

Claude Code

Usa el CLI de Claude Code para añadir el servidor Background Process MCP:

claude mcp add backgroundProcess npx @waylaidwanderer/background-process-mcp@latest
Claude Desktop

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Codex

Crea o edita el archivo de configuración ~/.codex/config.toml y añade:

[mcp_servers.backgroundProcess]
command = "npx"
args = ["@waylaidwanderer/background-process-mcp@latest"]

Para más información, consulta la documentación de MCP de Codex.

Cursor

Haz clic en el botón para instalar:

Install in Cursor

O instala manualmente:

Ve a Cursor Settings -> MCP -> Add new MCP Server. Nómbralo backgroundProcess, usa el tipo command con el comando npx @waylaidwanderer/background-process-mcp@latest.

Gemini CLI

Sigue la guía de instalación de MCP, usa la configuración estándar anterior.

Goose

Haz clic en el botón para instalar:

Install in Goose

O instala manualmente:

Ve a Advanced settings -> Extensions -> Add custom extension. Nómbralo backgroundProcess, usa el tipo STDIO y establece command a npx @waylaidwanderer/background-process-mcp@latest. Haz clic en "Add Extension".

LM Studio

Haz clic en el botón para instalar:

Add MCP Server backgroundProcess to LM Studio

O instala manualmente:

Ve a Program en la barra lateral derecha -> Install -> Edit mcp.json. Usa la configuración estándar anterior.

opencode

Sigue la documentación de MCP Servers. Por ejemplo, en ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "backgroundProcess": {
      "type": "local",
      "command": [
        "npx",
        "@waylaidwanderer/background-process-mcp@latest"
      ],
      "enabled": true
    }
  }
}
Qodo Gen

Abre el panel de chat de Qodo Gen en VSCode o IntelliJ → Connect more tools → + Add new MCP → Pega la configuración estándar anterior.

Haz clic en Save.

VS Code (para GitHub Copilot)

Haz clic en el botón para instalar:

Install in VS Code Install in VS Code Insiders

O instala manualmente:

Sigue la guía de instalación de MCP, usa la configuración estándar anterior. También puedes instalar el servidor usando el CLI de VS Code:

# For VS Code
code --add-mcp '{"name":"backgroundProcess","command":"npx","args":["@waylaidwanderer/background-process-mcp@latest"]}'
Windsurf

Sigue la documentación de MCP de Windsurf. Usa la configuración estándar anterior.

Herramientas

Las siguientes herramientas son expuestas por el servidor MCP.

Gestión de procesos

  • start_process

    • Descripción: Inicia un nuevo proceso en segundo plano.
    • Parámetros:
      • command (string): El comando de shell a ejecutar.
    • Devuelve: Un mensaje de confirmación con el nuevo ID del proceso.

  • stop_process

    • Descripción: Detiene un proceso en ejecución.
    • Parámetros:
      • processId (string): El UUID del proceso a detener.
    • Devuelve: Un mensaje de confirmación.

  • clear_process

    • Descripción: Elimina un proceso detenido de la lista.
    • Parámetros:
      • processId (string): El UUID del proceso a eliminar.
    • Devuelve: Un mensaje de confirmación.

  • get_process_output

    • Descripción: Obtiene la salida reciente de un proceso. Puede especificar head para las primeras N líneas o tail para las últimas N líneas.
    • Parámetros:
      • processId (string): El UUID del proceso del que obtener la salida.
      • head (number, opcional): El número de líneas a obtener desde el principio de la salida.
      • tail (number, opcional): El número de líneas a obtener desde el final de la salida.
    • Devuelve: La salida solicitada del proceso como una sola cadena.

  • list_processes

    • Descripción: Obtiene una lista de todos los procesos gestionados por el Core Service.
    • Parámetros: Ninguno
    • Devuelve: Una cadena JSON que representa un array de todos los estados de los procesos.

  • get_server_status

    • Descripción: Obtiene el estado actual del Core Service.
    • Parámetros: Ninguno
    • Devuelve: Una cadena JSON que contiene información del estado del servidor (versión, puerto, PID, tiempo de actividad, recuentos de procesos).

Arquitectura

El proyecto tiene tres componentes:

  1. Core Service (src/server.ts): Un servidor WebSocket independiente que usa node-pty para gestionar los ciclos de vida de los procesos hijos. Es la única fuente de verdad para todos los estados de los procesos. Está diseñado para ser independiente, de modo que otros clientes más allá de la TUI oficial y MCP puedan construirse para él.

  2. MCP Client (src/mcp.ts): Expone la funcionalidad del Core Service como un conjunto de herramientas para un agente LLM. Puede conectarse a un servicio existente o generar uno nuevo.

  3. TUI Client (src/tui.ts): Una interfaz de terminal basada en ink que se conecta al Core Service para mostrar información de los procesos y aceptar comandos del usuario.

Uso manual

Si deseas ejecutar el servidor y la TUI manualmente fuera de un cliente MCP, puedes usar los siguientes comandos.

Para un comando más corto, puedes instalar el paquete globalmente:

pnpm add -g @waylaidwanderer/background-process-mcp

Esto te dará acceso al comando bgpm.

1. Ejecutar el Core Service

Inicia el servicio en segundo plano manualmente:

# With npx
npx @waylaidwanderer/background-process-mcp server

# Or, if installed globally
bgpm server

El servidor escuchará en un puerto disponible (por defecto 31337) y mostrará un handshake JSON con los detalles de conexión.

2. Usar la TUI

Conecta la TUI a un servidor en ejecución a través de su puerto:

# With npx
npx @waylaidwanderer/background-process-mcp ui --port <port_number>

# Or, if installed globally
bgpm ui --port <port_number>