@justmpm/term-manager

@justmpm/term-manager

MCP Server para terminais Windows sem timeout. Permite que agentes de IA executem scripts predefinidos (run_{script}) em terminais persistentes — comandos longos continuam rodando mesmo enquanto a IA faz outras tarefas.

Novidades da v0.8.0

• Tools run_codex e ask_codex removidas. A funcionalidade de delegação a coding agents (Codex CLI em modo headless) migrou completamente para @justmpm/agent-runner (que é auto-suficiente desde a sua v0.2.0). Para delegar ao Codex CLI, use agent-runner.run_agent({ provider: "codex", agent: "...", prompt: "...", cwd: "...", owner: "..." }). Veja a tabela de migração no AGENTS.md §11.6.
• API mais enxuta. Total de tools cai de 11 → 9: run_{script} (N ferramentas dinâmicas), list_scripts, stop_terminal, wait_for_completion, list_terminals, close_terminal, read_output, search_output.
• Código morto removido. Campo visible?: boolean (era específico para terminais codex) e parâmetro visible em manager.create() foram removidos. A assinatura volta a 4 args: create(command, cwd, name?, owner?).
• BREAKING para quem usava run_codex/ask_codex. Clientes MCP que ainda chamam essas tools vão receber erro "tool not found". Migre para @justmpm/agent-runner.

Arquitetura

• node-pty (ConPTY) — Gerencia os processos reais, capturando output e enviando input
• Spawn via pwsh -Command / bash -c — Shell executa o comando direto e morre quando ele termina (status confiável, exit code propagado)
• Buffer de 2000 linhas por terminal, texto limpo sem códigos ANSI

Tools

Tool	Descrição
run_{script}	Executa script do package.json num terminal persistente
list_scripts	Lista scripts disponíveis para execução
wait_for_completion	Aguarda término do comando (com timeout, até 15min) — ideal para lint/test/build
stop_terminal	Envia Ctrl+C para parar gracefully
list_terminals	Lista terminais criados (filtrável por owner e status)
close_terminal	Finaliza um terminal e libera recursos
read_output	Lê as últimas N linhas do output (inclui status + exit code)
search_output	Busca texto no output (substring, case-insensitive, classificado como [ERRO]/[WARN]/[INFO])

Isolamento entre agents (owner)

Todas as tools que criam/manipulam terminais aceitam um parâmetro opcional owner. Quando informado, marca a sessão como pertencente àquele agent e as demais tools filtram/validam por owner.

// Criar terminal como "nexus"
{ "pm": "npm", "owner": "nexus" }

// Listar apenas os meus terminais
{ "owner": "nexus" }

Isolamento soft — evita acidentes (agent A fecha terminal do B por engano). Para isolamento real, cada agent deve ter seu próprio processo MCP.

Quando usar qual pacote

Caso	Pacote	Tool
Rodar npm run build, vitest, tsc --noEmit, dev server, lint	@justmpm/term-manager	run_{script}
Delegar tarefa de IA (auditoria, fix, brainstorming) ao Codex CLI	@justmpm/agent-runner	run_agent, ask_agent
Delegar a outros providers (Antigravity, futuros)	@justmpm/agent-runner	mesma API, provider: "antigravity"

Instalação

npx (sem instalar)

{
  "mcpServers": {
    "term-manager": {
      "command": "npx",
      "args": ["-y", "@justmpm/term-manager"]
    }
  }
}

Desenvolvimento local

cd mcps-ai/term-manager
npm install && npm run build

{
  "mcpServers": {
    "term-manager": {
      "command": "node",
      "args": ["D:/Pictures/Pacotes-Pessoais/mcps-ai/term-manager/dist/index.js"]
    }
  }
}

Requisitos

• Node.js >= 18
• Windows 10 1809+ (para ConPTY)

Stack

Dependência	Versão	Uso
TypeScript	^5.9.3	Linguagem principal (strict mode)
node-pty	^1.0.0	Gerenciamento de terminais (ConPTY)
@modelcontextprotocol/sdk	^1.26.0	MCP server e transporte stdio
zod	^3.24.0	Validação de schemas de input

Licença

MIT Koda AI Studio