workbuddy-mcp

Permite que cualquier agente de IA de codificación maneje WorkBuddy como sub-agente — instala con un comando, funciona con cuatro clientes.

让任意 AI 编程助手（Claude Code / Codex / Cursor / OpenCode）把 WorkBuddy 当「子 Agent」调用——一条命令装好，四大客户端通吃。

Español · 简体中文

Qué hace / 它做什么

workbuddy-mcp es un servidor MCP (Model Context Protocol) muy pequeño que envuelve la CLI oficial de WorkBuddy (codebuddy). Expone una sola herramienta — run_workbuddy_task — para que cualquier agente compatible con MCP pueda delegar trabajo real a WorkBuddy sin que tengas que copiar y pegar entre aplicaciones.

workbuddy-mcp 是一个极小的 MCP（模型上下文协议）服务器，封装了官方的 WorkBuddy 命令行（codebuddy）。它只暴露一个工具 run_workbuddy_task，让任何支持 MCP 的 Agent 都能把真实任务委托给 WorkBuddy，不必在多个应用之间来回复制粘贴。

No necesitas entender MCP para usarlo: npx -y workbuddy-mcp --install detecta tus agentes instalados y registra el servidor por ti.

你不需要懂 MCP 就能用：一条 npx -y workbuddy-mcp --install 会自动检测你装了的 Agent 并注册好。

Related MCP server: all-agents-mcp

Tabla de contenidos / 目录

• Arquitectura / 架构

• Características / 特性

• Inicio rápido / 快速开始

• Instalación / 安装

• Uso / 用法

• Configuración / 配置

• Nota de seguridad / 安全提示

• Por qué / 为什么做这个

• FAQ

• Hoja de ruta / 路线图

• Contribuciones / 贡献

• Licencia / 许可证

Arquitectura / 架构

Your agent (Claude Code / Codex / Cursor / OpenCode)
      │  calls MCP tool: run_workbuddy_task(prompt)
      ▼
workbuddy-mcp   (this server, stdio MCP)
      │  shells out:
      ▼
codebuddy -p "<prompt>" --dangerously-skip-permissions
      │
      ▼
WorkBuddy   (does the actual work, returns text)

Características / 特性

Inicio rápido / 快速开始

Prerrequisito: instala e inicia sesión en la CLI de WorkBuddy una vez (interactivamente). 前置：先装好并登录一次 WorkBuddy 命令行（仅需一次，会打开登录流程）。

# 1. Install & log in the WorkBuddy CLI
npm install -g @tencent-ai/codebuddy-code
codebuddy -p "hello" --dangerously-skip-permissions   # first run opens a login flow

# 2. Install the MCP server into every agent you have
npx -y workbuddy-mcp --install

Luego, en cualquier agente, solo di por ejemplo "usa workbuddy para leer data.csv y redactar un informe semanal" — el agente llama a run_workbuddy_task por ti.

然后，在任意 Agent 里说「让 workbuddy 读取 data.csv 写一份周报」即可——Agent 会自动调用 run_workbuddy_task。

Instalación / 安装

Opción A — un comando (recomendado)

npx -y workbuddy-mcp --install

Detecta Claude Code / Codex / Cursor / OpenCode en tu máquina y registra el servidor. Vuelve a ejecutarlo después de instalar un nuevo agente.

Opción B — desde npm, luego instalar

npm install -g workbuddy-mcp
workbuddy-mcp --install

Opción C — manual (cualquier cliente MCP) Apunta tu cliente a node <path>/server.js. Ejemplos:

Claude Code

claude mcp add -s user workbuddy -- node /abs/path/to/workbuddy-mcp/server.js

Codex

codex mcp add workbuddy -- node /abs/path/to/workbuddy-mcp/server.js

Cursor — escribe en ~/.cursor/mcp.json:

{ "mcpServers": { "workbuddy": { "command": "node", "args": ["/abs/path/to/workbuddy-mcp/server.js"] } } }

OpenCode — escribe en opencode.json (raíz del proyecto o ~/.config/opencode/opencode.json):

{ "mcp": { "workbuddy": { "type": "local", "command": ["node", "/abs/path/to/workbuddy-mcp/server.js"], "enabled": true } } }

Consulta opencode.json.example para una plantilla lista para usar con cwd / WB_* env conectados.

Uso / 用法

El servidor expone una herramienta. Tu agente la llama por ti; también puedes invocarla directamente.

// Tool: run_workbuddy_task
{
  prompt: "读取 ./reports 下的 CSV，生成一份中文月度总结",  // required 必填
  cwd:    "/path/to/your/project",   // optional 可选: where WorkBuddy reads/writes files
  model:  "sonnet",                  // optional 可选: model alias
  json:   true                       // optional 可选: request --output-format json
}

Cosas que podrías darle a tu agente:

• "让 workbuddy 在我仓库根目录跑测试，把失败日志整理成 Markdown"

• "usa workbuddy para refactorizar src/utils.ts y explica los cambios"

¿A dónde van los archivos? Las respuestas de texto vuelven al chat. Los archivos que WorkBuddy escribe caen en su cwd (el cwd de la llamada → si no, WB_CWD → si no, la carpeta de trabajo del agente). No se añaden automáticamente al contexto de tu agente — léelos desde el disco.

Configuración / 配置

Todo el ajuste se hace mediante variables de entorno — configúralas en el bloque environment de la configuración MCP de tu agente.

Cambiar modelos / 切换模型

La CLI codebuddy expone --model <id> y --fallback-model <id> (este último solo tiene efecto bajo --print, que este servidor siempre usa). Este servidor expone ambos:

• Por llamada — pasa model y/o fallbackModel a run_workbuddy_task.

• Globalmente — establece WB_MODEL y/o WB_FALLBACK_MODEL en el bloque environment MCP del agente; se aplican cuando la llamada no los pasa.

Modelos disponibles (de codebuddy --help): auto, hy3, hy3-x, glm-5.3, glm-5.2, glm-5.1, glm-5v-turbo, minimax-m3, kimi-k3-1, kimi-k2.7, kimi-k2.6, deepseek-v4-flash, deepseek-v4-pro.

¿Limitado por tasa en el modelo gratuito? No cambies bruscamente — añade un fallback para que hy3 siga siendo el principal pero se recupere automáticamente cuando esté sobrecargado:

// opencode.json / claude mcp config environment
{
  "WB_MODEL": "hy3",
  "WB_FALLBACK_MODEL": "deepseek-v4-flash"
}

O por llamada: run_workbuddy_task({ prompt: "...", fallbackModel: "deepseek-v4-flash" }).

切换模型 / 模型切换

codebuddy 自带 --model <id> 与 --fallback-model <id>（--fallback-model 仅在 --print 下生效，而本服务始终用 -p，所以可用）。本服务把两者都暴露出来：

• 单次调用：给 run_workbuddy_task 传 model 和/或 fallbackModel。

• 全局默认：在 Agent 的 MCP environment 里设 WB_MODEL / WB_FALLBACK_MODEL，调用未传时使用。

免费模型被限流时，建议不要硬性切走，而是加一个回退：hy3 仍是首选，过载时自动切到 deepseek-v4-flash 等，等限流恢复又自动用回 hy3。

Nota de seguridad / 安全提示

Por defecto WB_SKIP_PERMISSIONS=true, lo que hace que codebuddy se ejecute sin avisos interactivos de permisos. Eso es lo que permite que un agente lo maneje sin supervisión — pero también significa que cualquier cosa que el agente solicite se ejecuta automáticamente. Para automatización personal y confiable está bien; si prefieres mantener a un humano en el circuito, establece WB_SKIP_PERMISSIONS=false en tu configuración MCP.

默认 WB_SKIP_PERMISSIONS=true，即 codebuddy 会跳过交互式授权自动执行。这正是「让 Agent 无人值守地驱动它」所必需的；但也意味着 Agent 请求的任何操作都会自动执行。个人可信自动化场景下没问题；若你想保留人工确认，把 WB_SKIP_PERMISSIONS 设为 false。

Por qué / 为什么做这个

WorkBuddy es un agente capaz, pero cada producto (Claude Code, Codex, Cursor, OpenCode…) vive en su propia caja. No hay un "MCP inverso" oficial que permita a esos productos aprovechar WorkBuddy como sub-agente. Este proyecto es la capa fina: empaqueta la propia CLI de WorkBuddy detrás de una herramienta MCP estándar, para que los cuatro agentes de codificación más populares puedan compartir un solo WorkBuddy.

WorkBuddy 本身能力很强，但 Claude Code、Codex、Cursor、OpenCode 各成孤岛，官方并没有提供「反向 MCP」让这些产品把 WorkBuddy 当子 Agent 调用。本项目就是那层薄胶水：把 WorkBuddy 自己的命令行封装成一个标准 MCP 工具，让最主流的几个编程 Agent 共用同一个 WorkBuddy。

FAQ

¿Necesita esto que la aplicación de escritorio de WorkBuddy esté ejecutándose? No. Maneja la CLI codebuddy, que es independiente (mismo motor, forma de terminal). Un inicio de sesión de escritorio es suficiente.

¿Funciona esto sin conexión? El servidor MCP es local; las llamadas codebuddy llegan al servicio de WorkBuddy, por lo que se requiere conexión a internet para la tarea real.

¿Mostrará mi chat de escritorio de WorkBuddy lo que pidió el agente? codebuddy se ejecuta como su propia sesión; las conversaciones pueden no aparecer en el historial de la aplicación de escritorio. Eso es esperado.

Hoja de ruta / 路线图

• Auto-instalación para Claude Code / Codex / Cursor / OpenCode

• Salida en streaming (mostrar progreso en lugar de esperar el resultado completo)

• Análisis opcional de resultados JSON estructurados

• codebuddy no encontrado → sugerencia de instalación guiada

Contribuciones / 贡献

¡PRs e ideas son bienvenidos! Los issues etiquetados como good first issue son un buen punto de partida. Consulta CONTRIBUTING.md.

Cada push / PR ejecuta una prueba de humo (.github/workflows/smoke.yml) que verifica la sintaxis en Node 18/20/22 y comprueba que el servidor completa un handshake MCP initialize → tools/list. Para ejecutarlo localmente:

npm install
node test/smoke.mjs

欢迎 PR 和想法！可以从 good first issue 标签的议题入手。

Licencia / 许可证

MIT © LinHaiJ. Consulta LICENSE para más detalles.