# 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

```powershell
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:

```powershell
$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:

```toml
[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:

```powershell
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:

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