Labsco
waylaidwanderer logo

Background Process MCP

★ 10

from waylaidwanderer

A server that provides background process management capabilities, enabling LLMs to start, stop, and monitor long-running command-line processes.

🔥🔥🔥✓ VerifiedFreeQuick setup
#git

Background Process MCP

A Model Context Protocol (MCP) server that provides background process management capabilities. This server enables LLMs to start, stop, and monitor long-running command-line processes.

Motivation

Some AI agents, like Claude Code, can manage background processes natively, but many others can't. This project provides that capability as a standard tool for other agents like Google's Gemini CLI. It works as a separate service, making long-running task management available to a wider range of agents. I also added a TUI because I wanted to be able to monitor the processes myself.

Screenshot

<img src="./public/tui-screenshot.png" alt="TUI Screenshot" width="1126">

Tools

The following tools are exposed by the MCP server.

<details> <summary><b>Process Management</b></summary>

  • start_process

    • Description: Starts a new process in the background.
    • Parameters:
      • command (string): The shell command to execute.
    • Returns: A confirmation message with the new process ID.

  • stop_process

    • Description: Stops a running process.
    • Parameters:
      • processId (string): The UUID of the process to stop.
    • Returns: A confirmation message.

  • clear_process

    • Description: Clears a stopped process from the list.
    • Parameters:
      • processId (string): The UUID of the process to clear.
    • Returns: A confirmation message.

  • get_process_output

    • Description: Gets the recent output for a process. Can specify head for the first N lines or tail for the last N lines.
    • Parameters:
      • processId (string): The UUID of the process to get output from.
      • head (number, optional): The number of lines to get from the beginning of the output.
      • tail (number, optional): The number of lines to get from the end of the output.
    • Returns: The requested process output as a single string.

  • list_processes

    • Description: Gets a list of all processes being managed by the Core Service.
    • Parameters: None
    • Returns: A JSON string representing an array of all process states.

  • get_server_status

    • Description: Gets the current status of the Core Service.
    • Parameters: None
    • Returns: A JSON string containing server status information (version, port, PID, uptime, process counts).
</details>

Architecture

The project has three components:

  1. Core Service (src/server.ts): A standalone WebSocket server that uses node-pty to manage child process lifecycles. It is the single source of truth for all process states. It is designed to be standalone so that other clients beyond the official TUI and MCP can be built for it.

  2. MCP Client (src/mcp.ts): Exposes the Core Service functionality as a set of tools for an LLM agent. It can connect to an existing service or spawn a new one.

  3. TUI Client (src/tui.ts): An ink-based terminal UI that connects to the Core Service to display process information and accept user commands.