Background Process MCP

Um servidor que fornece capacidades de gerenciamento de processos em segundo plano, permitindo que LLMs iniciem, parem e monitorem processos de linha de comando de longa duração.

GitHub
11

Documentação

Background Process MCP

Um servidor Model Context Protocol (MCP) que fornece recursos de gerenciamento de processos em segundo plano. Este servidor permite que LLMs iniciem, parem e monitorem processos de linha de comando de longa duração.

Motivação

Alguns agentes de IA, como o Claude Code, podem gerenciar processos em segundo plano nativamente, mas muitos outros não conseguem. Este projeto fornece essa capacidade como uma ferramenta padrão para outros agentes, como o Gemini CLI do Google. Ele funciona como um serviço separado, tornando o gerenciamento de tarefas de longa duração disponível para uma gama mais ampla de agentes. Também adicionei uma TUI porque queria poder monitorar os processos eu mesmo.

Captura de tela

TUI Screenshot

Começando

Para começar, instale o servidor Background Process MCP no seu cliente preferido.

Configuração Padrão

Esta configuração funciona para a maioria dos clientes MCP:

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

Para conectar a um servidor autônomo, adicione o argumento --port ao array args (por exemplo, ...mcp@latest", "--port", "31337"]).

Claude Code

Use a CLI do Claude Code para adicionar o servidor Background Process MCP:

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

Siga o guia de instalação do MCP, use a configuração padrão acima.

Codex

Crie ou edite o arquivo de configuração ~/.codex/config.toml e adicione:

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

Para mais informações, consulte a documentação do MCP do Codex.

Cursor

Clique no botão para instalar:

Install in Cursor

Ou instale manualmente:

Vá para Cursor Settings -> MCP -> Add new MCP Server. Nomeie como backgroundProcess, use o tipo command com o comando npx @waylaidwanderer/background-process-mcp@latest.

Gemini CLI

Siga o guia de instalação do MCP, use a configuração padrão acima.

Goose

Clique no botão para instalar:

Install in Goose

Ou instale manualmente:

Vá para Advanced settings -> Extensions -> Add custom extension. Nomeie como backgroundProcess, use o tipo STDIO e defina o command para npx @waylaidwanderer/background-process-mcp@latest. Clique em "Adicionar Extensão".

LM Studio

Clique no botão para instalar:

Add MCP Server backgroundProcess to LM Studio

Ou instale manualmente:

Vá para Program na barra lateral direita -> Install -> Edit mcp.json. Use a configuração padrão acima.

opencode

Siga a documentação dos Servidores MCP. Por exemplo, em ~/.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

Abra o painel de chat do Qodo Gen no VSCode ou IntelliJ → Conectar mais ferramentas → + Adicionar novo MCP → Cole a configuração padrão acima.

Clique em Save.

VS Code (para GitHub Copilot)

Clique no botão para instalar:

Install in VS Code Install in VS Code Insiders

Ou instale manualmente:

Siga o guia de instalação do MCP, use a configuração padrão acima. Você também pode instalar o servidor usando a CLI do VS Code:

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

Siga a documentação do MCP do Windsurf. Use a configuração padrão acima.

Ferramentas

As seguintes ferramentas são expostas pelo servidor MCP.

Gerenciamento de Processos

  • start_process

    • Descrição: Inicia um novo processo em segundo plano.
    • Parâmetros:
      • command (string): O comando shell a ser executado.
    • Retorna: Uma mensagem de confirmação com o novo ID do processo.

  • stop_process

    • Descrição: Para um processo em execução.
    • Parâmetros:
      • processId (string): O UUID do processo a ser interrompido.
    • Retorna: Uma mensagem de confirmação.

  • clear_process

    • Descrição: Remove um processo interrompido da lista.
    • Parâmetros:
      • processId (string): O UUID do processo a ser removido.
    • Retorna: Uma mensagem de confirmação.

  • get_process_output

    • Descrição: Obtém a saída recente de um processo. Pode especificar head para as primeiras N linhas ou tail para as últimas N linhas.
    • Parâmetros:
      • processId (string): O UUID do processo do qual obter a saída.
      • head (número, opcional): O número de linhas a obter do início da saída.
      • tail (número, opcional): O número de linhas a obter do final da saída.
    • Retorna: A saída solicitada do processo como uma única string.

  • list_processes

    • Descrição: Obtém uma lista de todos os processos gerenciados pelo Core Service.
    • Parâmetros: Nenhum
    • Retorna: Uma string JSON representando um array de todos os estados dos processos.

  • get_server_status

    • Descrição: Obtém o status atual do Core Service.
    • Parâmetros: Nenhum
    • Retorna: Uma string JSON contendo informações de status do servidor (versão, porta, PID, tempo de atividade, contagens de processos).

Arquitetura

O projeto tem três componentes:

  1. Core Service (src/server.ts): Um servidor WebSocket autônomo que usa node-pty para gerenciar ciclos de vida de processos filhos. É a fonte única de verdade para todos os estados de processos. Foi projetado para ser autônomo para que outros clientes além da TUI oficial e do MCP possam ser construídos para ele.

  2. MCP Client (src/mcp.ts): Expõe a funcionalidade do Core Service como um conjunto de ferramentas para um agente LLM. Ele pode se conectar a um serviço existente ou iniciar um novo.

  3. TUI Client (src/tui.ts): Uma interface de terminal baseada em ink que se conecta ao Core Service para exibir informações de processos e aceitar comandos do usuário.

Uso Manual

Se você deseja executar o servidor e a TUI manualmente fora de um cliente MCP, pode usar os seguintes comandos.

Para um comando mais curto, você pode instalar o pacote globalmente:

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

Isso dará acesso ao comando bgpm.

1. Execute o Core Service

Inicie o serviço em segundo plano manualmente:

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

# Or, if installed globally
bgpm server

O servidor escutará em uma porta disponível (padrão 31337) e exibirá um handshake JSON com os detalhes da conexão.

2. Use a TUI

Conecte a TUI a um servidor em execução via sua porta:

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

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