os-control-mcp

MCP local para sessões persistentes de terminal. O processo mantém Bash, CMD, PowerShell, pwsh ou WSL ativos e separa envio de entrada da leitura incremental da saída.

Também possui objetivos persistentes: o agente pode criar um objetivo com critérios de aceitação, executar várias etapas, verificar evidências e continuar até concluir, falhar, ficar bloqueado ou atingir os limites definidos.

O dispatcher atende chamadas MCP concorrentes. Assim, vários chats podem ler, acompanhar e operar sessões no mesmo processo sem que uma leitura longa de saída bloqueie as outras. Sessões e objetivos aceitam client_id opcional para separar o contexto de cada chat; sem esse campo, o servidor mantém o comportamento compatível e lista o estado compartilhado.

Atenção: este servidor controla processos com as permissões do usuário que o executa. Use-o localmente, não rode como administrador/root por padrão e nunca exponha o processo diretamente à internet.

Transporte

O servidor usa MCP JSONL por stdio. Não abre uma porta de rede por padrão. As respostas JSON-RPC podem chegar fora da ordem quando há chamadas simultâneas; clientes devem correlacioná-las pelo campo id.

Shells

• bash, sh, zsh em sistemas POSIX;
• cmd, powershell e pwsh no Windows;
• wsl-bash no Windows, usando a distribuição definida em OS_CONTROL_WSL_DISTRO ou kali-linux por padrão.

Fluxo interativo

1. os_create_session cria uma sessão persistente.
2. os_send_input escreve imediatamente no PTY/ConPTY.
3. os_read_output usa since_seq e since_offset para buscar apenas saída nova, inclusive quando a resposta precisa ser paginada.
4. os_session_status acompanha PID, shell, diretório e encerramento.

Para separar recursos por chat, envie o mesmo client_id em os_create_session e nas chamadas seguintes (os_read_output, os_send_input, os_goal_*, etc.). Também é possível fornecer esse identificador em _meta.os_control_client_id no request MCP; nesse caso ele é aplicado automaticamente às ferramentas.

Fora de um objetivo autonomous, comandos potencialmente destrutivos exigem confirmação explícita. Em um objetivo autônomo, a autorização é contínua dentro dos limites de passos e tempo definidos pelo objetivo. O servidor é destinado a uso local e deve continuar protegido por autenticação e escopo quando for colocado atrás de um túnel remoto.

Objetivos autônomos

Fluxo recomendado:

1. os_create_session cria o terminal persistente.
2. os_goal_start recebe o objetivo, critérios e session_id.
3. os_send_input usa o goal_id para executar sem confirmação repetitiva.
4. os_read_output lê a saída incremental.
5. os_goal_update registra ação, resultado, evidência e próxima etapa.
6. O agente repete até comprovar todos os critérios.

Saída grande

O terminal mantém um buffer interno amplo. os_read_output pode retornar até 1 MB por chamada; quando ainda houver dados, a resposta informa has_more e retorna next_seq/next_offset. A próxima leitura deve reutilizar esses dois cursores para continuar sem perder o meio da saída.

{
  "since_seq": 8591,
  "since_offset": 0,
  "wait_ms": 1000,
  "max_bytes": 150000
}

O servidor não inventa a próxima ação nem chama o modelo sozinho; ele mantém o estado e os limites do objetivo. O cliente/agente deve continuar fazendo as chamadas até o estado terminal.

Instalação

git clone https://github.com/Willian-2-0-0-1/os-control-mcp.git
cd os-control-mcp
python -m pip install -r requirements.txt

No Windows, pywinpty habilita ConPTY para CMD e PowerShell. No Kali/Linux, o backend usa o PTY nativo. O arquivo .mcp.json pode ser usado por clientes MCP que aceitem servidores locais por stdio.

Plugin para GPT/Codex

O repositório contém o manifesto .codex-plugin/plugin.json e o servidor MCP. Isso permite distribuir o pacote para clientes compatíveis com plugins MCP.

Para usar no ChatGPT com um servidor local, cada usuário deve executar sua própria instância e configurar uma conexão privada. Um repositório GitHub, por si só, não dá ao ChatGPT acesso ao computador do usuário.