mcp-opencode

MCP local de 25 herramientas para que Codex/ChatGPT coordine OpenCode y sus agentes configurados.

Capacidades

• opencode_setup: salud, agentes, proveedores, proyecto, Git y sesiones.
• opencode_context: contexto agregado para planear: proyectos, agentes, modelos, sesiones, comandos, MCP y archivos.
• opencode_agents: agentes disponibles.
• opencode_projects / opencode_sessions: descubrimiento y continuidad de trabajo.
• opencode_providers / opencode_commands / opencode_mcp_status: capacidades disponibles.
• opencode_permissions / opencode_respond_permission: control explícito de pausas headless de OpenCode.
• opencode_run: tarea síncrona con respuesta y diff.
• opencode_reply: continuidad de una sesión existente.
• opencode_fire: tarea asíncrona para paralelización.
• opencode_parallel: fan-out controlado de hasta 12 tareas, con rechazo de escrituras concurrentes en el mismo directorio.
• opencode_check / opencode_wait / opencode_wait_many: seguimiento de sesiones.
• opencode_children / opencode_messages: auditoría de subagentes y continuidad.
• opencode_fork / opencode_summarize: bifurcación y compactación de sesiones largas.
• opencode_review: diff y estado de archivos.
• opencode_file_status: estado de archivos antes/después.
• opencode_abort: detención explícita de una sesión.

El servidor mantiene una interfaz de coordinación de alto nivel para el modelo y deja que OpenCode aplique sus propios permisos, agentes, herramientas MCP, AGENTS.md, modelos y subagentes.

Los listados de agentes se entregan compactados: conservan nombre, rol, modo, modelo, vista previa del prompt y resumen de permisos sin inyectar cientos de kilobytes de configuración en el contexto del modelo. Los modelos se seleccionan con provider/model, por ejemplo opencode-go/deepseek-v4-pro.

Las tareas, sesiones y operaciones de escritura requieren una ruta directory explícita para no modificar accidentalmente el propio MCP. Puedes definir OPENCODE_DEFAULT_DIRECTORY si quieres un proyecto predeterminado controlado.

Desarrollo

npm install
npm run check
npm run smoke
npm run runtime-smoke
npm start
npm run setup-startup

Configuración

Por defecto intenta iniciar OpenCode mediante el SDK oficial. Para conectarlo a un servidor ya iniciado:

$env:OPENCODE_BASE_URL = "http://127.0.0.1:4096"
$env:OPENCODE_AUTO_SERVE = "false"

Variables disponibles:

• OPENCODE_BASE_URL
• OPENCODE_SERVER_USERNAME
• OPENCODE_SERVER_PASSWORD
• OPENCODE_AUTO_SERVE (por defecto true)
• OPENCODE_DEFAULT_AGENT (por defecto chatgpt-coordinator)
• OPENCODE_DEFAULT_MODEL
• OPENCODE_DEFAULT_DIRECTORY (opcional; debe ser una carpeta de proyecto existente)

Registro en Codex Desktop

Después de compilar, una entrada global típica en C:\Users\TU_USUARIO\.codex\config.toml es:

[mcp_servers.opencode]
command = "node"
args = ["C:\\Users\\TU_USUARIO\\Documents\\Programming-personal\\mcp-opencode\\dist\\index.js"]
cwd = "C:\\Users\\TU_USUARIO\\Documents\\Programming-personal\\mcp-opencode"
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 900
default_tools_approval_mode = "prompt"

Reinicia Codex Desktop y verifica /mcp. No se deben registrar secretos en este archivo.

Inicio automático de Windows

Este MCP usa STDIO, así que Codex debe ser su cliente y proceso supervisor. Para que quede disponible al iniciar sesión de Windows, ejecuta desde la raíz:

npm run setup-startup

El comando registra una tarea idempotente que resuelve la instalación actual y abre Codex Desktop al iniciar sesión; así sobrevive a actualizaciones de WindowsApps. Codex carga entonces la entrada mcp_servers.opencode y lanza el MCP cuando corresponda. No se deja un proceso STDIO huérfano sin cliente. Para quitarlo:

npm run remove-startup

Política de coordinación

El servidor entrega instrucciones MCP para que el modelo:

1. consulte el contexto antes de delegar;
2. use opencode_run para tareas bloqueantes;
3. use opencode_fire solo para trabajos independientes;
4. nunca permita escrituras concurrentes sobre los mismos archivos;
5. consulte diff y pruebas antes de informar éxito.

Paralelización

opencode_parallel exige un directorio por tarea. Por defecto rechaza varias tareas con intención de escritura en el mismo directorio, porque las sesiones OpenCode comparten el árbol de archivos. Para cambios paralelos usa worktrees o carpetas distintas; allowSharedDirectory solo debe activarse cuando el usuario confirme que no habrá solapamiento.