# 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.

## Diagnóstico e controle do sistema

Além das sessões persistentes, o MCP oferece:

- os_system_info para plataforma, versão, diretório, shells disponíveis e limite de sessões;
- os_process_list para listar processos sem argumentos de linha de comando, reduzindo o risco de vazar segredos;
- os_process_signal para interromper ou encerrar um processo com confirmação explícita.

As ferramentas MCP agora declaram readOnlyHint, destructiveHint, idempotentHint
e openWorldHint, permitindo que clientes como ChatGPT/Codex exibam melhor o
risco de cada ação. O servidor limita a 32 sessões simultâneas e 64 KiB por
envio de entrada.

## 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.

```json
{
  "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

```bash
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.