@justmpm/opencode-control

MCP Server para controlar o OpenCode pelo CLI. Permite que agentes descubram projetos, gerenciem sessões, executem tarefas em background e extraiam resultados — tudo via CLI nativo, sem depender de opencode serve ou SDK.

Requisitos

• Node.js >= 22
• CLI opencode instalado e no PATH do sistema
• Windows (testado), macOS/Linux (deve funcionar)

Instalação

Global (recomendado)

npm install -g @justmpm/opencode-control

{
  "mcpServers": {
    "opencode-control": {
      "command": "opencode-control"
    }
  }
}

Via npx (sem instalar)

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

Fallback para Windows (se opencode não for encontrado)

{
  "mcpServers": {
    "opencode-control": {
      "command": "cmd",
      "args": ["/c", "opencode-control"]
    }
  }
}

Tools

| Tool | O que faz | |------|-----------| | opencode_projects_list | Lista projetos conhecidos pelo OpenCode | | opencode_sessions_list | Lista sessões com filtro por projeto | | opencode_run_task | Executa tarefa em background (retorno imediato) | | opencode_continue_session | Continua uma sessão existente | | opencode_session_status | Status heurístico da sessão (working/input_required/completed/failed) | | opencode_wait_until_done | Polling até a sessão terminar | | opencode_session_result | Extrai o resultado via export | | opencode_run_command | ⚠️ Experimental |

Exemplos de Uso

Listar projetos que o OpenCode conhece

{
  "method": "opencode_projects_list",
  "params": {}
}

Listar sessões de um projeto específico

{
  "method": "opencode_sessions_list",
  "params": {
    "projectDir": "D:\\Projetos\\meu-app",
    "limit": 10
  }
}

Rodar uma tarefa

{
  "method": "opencode_run_task",
  "params": {
    "projectDir": "D:\\Projetos\\meu-app",
    "prompt": "Adicione validação de email no formulário de cadastro",
    "title": "feat-email-validation",
    "agent": "auto"
  }
}

Retorno imediato: { "sessionId": "ses_abc123", "started": true }

Aguardar conclusão e obter resultado

{
  "method": "opencode_wait_until_done",
  "params": {
    "sessionId": "ses_abc123",
    "includeResult": true,
    "timeoutSeconds": 300,
    "waitFor": "input_required"
  }
}

Continuar uma sessão

{
  "method": "opencode_continue_session",
  "params": {
    "sessionId": "ses_abc123",
    "prompt": "Agora adicione também testes unitários",
    "fork": false
  }
}

Workflows Típicos

Rodar e monitorar

1. opencode_run_task  →  sessionId
2. opencode_wait_until_done(sessionId, includeResult=true)  →  resultado

Descobrir e continuar

1. opencode_sessions_list(projectDir)  →  tabela de sessões
2. opencode_continue_session(sessionId, prompt)  →  continua

Apenas consultar status

1. opencode_session_status(sessionId, includeLastMessage=true)

Limitações Conhecidas

• opencode_run_task e opencode_continue_session não funcionam dentro do próprio OpenCode (conflito de servidor). Funcionam em clientes MCP externos: Claude Desktop, Cursor, Windsurf, etc.
• O status das sessões é inferido heuristicamente — o nível de confiança é informado junto com o resultado.

Arquitetura

src/
├── index.ts              # Servidor MCP (Server, StdioServerTransport)
├── types.ts              # Tipos compartilhados
├── error-utils.ts        # Formatação de erros para LLM
├── cli/                  # Spawn e execução de comandos
├── tasks/                # Gerenciamento de processos assíncronos
├── queries/              # Consultas de projetos e sessões
├── export/               # Parse e inferência de status
└── tools/                # Handlers MCP (8 tools)

Licença

MIT — Koda AI Studio