workbuddy-mcp

Позвольте любому AI-агенту использовать WorkBuddy как субагента — установка одной командой, работает с четырьмя клиентами.

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

Русский · 简体中文

Что это делает / 它做什么

workbuddy-mcp — это крошечный MCP-сервер (Model Context Protocol), который оборачивает официальный WorkBuddy CLI (codebuddy). Он предоставляет один инструмент — run_workbuddy_task — так что любой агент, поддерживающий MCP, может делегировать реальную работу WorkBuddy без копирования и вставки между приложениями.

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

Вам не нужно разбираться в MCP, чтобы использовать его: npx -y workbuddy-mcp --install автоматически обнаружит установленных агентов и зарегистрирует сервер за вас.

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

Related MCP server: all-agents-mcp

Оглавление / 目录

• Архитектура / 架构

• Возможности / 特性

• Быстрый старт / 快速开始

• Установка / 安装

• Использование / 用法

• Конфигурация / 配置

• Замечание о безопасности / 安全提示

• Зачем / 为什么做这个

• FAQ

• Дорожная карта / 路线图

• Вклад / 贡献

• Лицензия / 许可证

Архитектура / 架构

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)

Возможности / 特性

Быстрый старт / 快速开始

Предварительное требование: установите и войдите в WorkBuddy CLI один раз (в интерактивном режиме). 前置：先装好并登录一次 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

Затем в любом агенте просто скажите, например: "используй workbuddy, чтобы прочитать data.csv и составить еженедельный отчёт" — агент вызовет run_workbuddy_task за вас.

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

Установка / 安装

Вариант A — одна команда (рекомендуется)

npx -y workbuddy-mcp --install

Обнаруживает Claude Code / Codex / Cursor / OpenCode на вашем компьютере и регистрирует сервер. Повторно запустите после установки нового агента.

Вариант B — из npm, затем установка

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

Вариант C — вручную (любой MCP-клиент) Укажите вашему клиенту node <path>/server.js. Примеры:

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 — запишите в ~/.cursor/mcp.json:

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

OpenCode — запишите в opencode.json (в корне проекта или в ~/.config/opencode/opencode.json):

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

См. opencode.json.example — готовый шаблон с подключёнными cwd / WB_* переменными.

Использование / 用法

Сервер предоставляет один инструмент. Ваш агент вызывает его за вас; вы также можете вызывать его напрямую.

// 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
}

Что можно поручить вашему агенту:

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

• "используй workbuddy, чтобы отрефакторить src/utils.ts и объясни изменения"

Куда попадают файлы? Текстовые ответы возвращаются в чат. Файлы, которые WorkBuddy записывает, попадают в его cwd (из вызова cwd → иначе WB_CWD → иначе рабочая папка агента). Они не добавляются автоматически в контекст вашего агента — читайте их с диска.

Конфигурация / 配置

Вся настройка через переменные окружения — задайте их в блоке environment конфигурации MCP вашего агента.

Переключение моделей / 切换模型

CLI codebuddy предоставляет --model <id> и --fallback-model <id> (последний действует только при --print, который этот сервер всегда использует). Этот сервер предоставляет оба:

• Для каждого вызова — передайте model и/или fallbackModel в run_workbuddy_task.

• Глобально — задайте WB_MODEL и/или WB_FALLBACK_MODEL в блоке environment MCP агента; они применяются, когда вызов их не передаёт.

Доступные модели (из 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.

Ограничение по частоте на бесплатной модели? Не переключайтесь жёстко — добавьте запасной вариант, чтобы hy3 оставался основным, но автоматически восстанавливался при перегрузке:

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

Или для каждого вызова: 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。

Замечание о безопасности / 安全提示

По умолчанию WB_SKIP_PERMISSIONS=true, что заставляет codebuddy работать без интерактивных запросов разрешений. Именно это позволяет агенту управлять им без присмотра — но также означает, что всё, что запрашивает агент, выполняется автоматически. Для личной доверенной автоматизации это нормально; если вы предпочитаете сохранить участие человека, установите WB_SKIP_PERMISSIONS=false в конфигурации MCP.

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

Зачем / 为什么做这个

WorkBuddy — способный агент, но каждый продукт (Claude Code, Codex, Cursor, OpenCode…) живёт в своей песочнице. Нет официального «обратного MCP», который позволил бы этим продуктам использовать WorkBuddy как субагента. Этот проект — тонкий клей: он упаковывает собственный CLI WorkBuddy за стандартный MCP-инструмент, так что четыре самых популярных агента программирования могут использовать одного WorkBuddy.

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

FAQ

Нужно ли запущенное десктопное приложение WorkBuddy? Нет. Он управляет CLI codebuddy, который является автономным (тот же движок, терминальная форма). Достаточно одного входа в десктоп.

Работает ли это офлайн? MCP-сервер локальный; вызовы codebuddy обращаются к сервису WorkBuddy, поэтому для фактической задачи требуется интернет-соединение.

Будут ли мои чаты в десктопном WorkBuddy показывать, что запросил агент? codebuddy работает в собственной сессии; разговоры могут не появляться в истории десктопного приложения. Это ожидаемо.

Дорожная карта / 路线图

• Автоустановка для Claude Code / Codex / Cursor / OpenCode

• Потоковый вывод (показывать прогресс вместо ожидания полного результата)

• Опциональный разбор структурированного JSON-результата

• codebuddy не найден → подсказка по установке

Вклад / 贡献

PR и идеи приветствуются! Задачи с меткой good first issue — хорошее место для начала. См. CONTRIBUTING.md.

Каждый push / PR запускает смоук-тест (.github/workflows/smoke.yml), который проверяет синтаксис на Node 18/20/22 и проверяет, что сервер завершает рукопожатие MCP initialize → tools/list. Для локального запуска:

每提交 / 开 PR 都会跑一个冒烟测试（.github/workflows/smoke.yml），在 Node 18/20/22 上检查语法并验证 Server 能完成 MCP initialize → tools/list 握手。本地自测：

npm install
node test/smoke.mjs

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

Лицензия / 许可证

MIT © LinHaiJ. Подробности см. в LICENSE.