workbuddy-mcp

Lassen Sie jeden KI-Coding-Agenten WorkBuddy als Sub-Agenten steuern – Installation mit einem Befehl, funktioniert mit vier Clients.

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

English · 简体中文

Was es tut / 它做什么

workbuddy-mcp ist ein winziger MCP-Server (Model Context Protocol), der die offizielle WorkBuddy-CLI (codebuddy) kapselt. Er stellt ein einziges Tool bereit – run_workbuddy_task –, sodass jeder MCP-fähige Agent echte Arbeit an WorkBuddy delegieren kann, ohne dass Sie zwischen Apps kopieren und einfügen müssen.

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

Sie müssen nicht MCP verstehen, um es zu nutzen: npx -y workbuddy-mcp --install erkennt Ihre installierten Agenten und registriert den Server für Sie.

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

Related MCP server: all-agents-mcp

Inhaltsverzeichnis / 目录

• Architektur / 架构

• Funktionen / 特性

• Schnellstart / 快速开始

• Installation / 安装

• Verwendung / 用法

• Konfiguration / 配置

• Sicherheitshinweis / 安全提示

• Warum / 为什么做这个

• FAQ

• Roadmap / 路线图

• Mitwirken / 贡献

• Lizenz / 许可证

Architektur / 架构

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)

Funktionen / 特性

Schnellstart / 快速开始

Voraussetzung: Installieren und melden Sie sich einmalig (interaktiv) bei der WorkBuddy-CLI an. 前置：先装好并登录一次 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

Sagen Sie dann in einem beliebigen Agenten einfach z. B. „Lass workbuddy data.csv lesen und einen Wochenbericht entwerfen" – der Agent ruft run_workbuddy_task für Sie auf.

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

Installation / 安装

Option A – ein Befehl (empfohlen)

npx -y workbuddy-mcp --install

Erkennt Claude Code / Codex / Cursor / OpenCode auf Ihrem Rechner und registriert den Server. Nach der Installation eines neuen Agenten erneut ausführen.

Option B – von npm, dann installieren

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

Option C – manuell (beliebiger MCP-Client) Weisen Sie Ihren Client auf node <path>/server.js. Beispiele:

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 – schreiben Sie in ~/.cursor/mcp.json:

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

OpenCode – schreiben Sie in opencode.json (Projektwurzel oder ~/.config/opencode/opencode.json):

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

Siehe opencode.json.example für eine gebrauchsfertige Vorlage mit cwd / WB_*-Umgebungsvariablen.

Verwendung / 用法

Der Server stellt ein Tool bereit. Ihr Agent ruft es für Sie auf; Sie können es auch direkt aufrufen.

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

Dinge, die Sie Ihrem Agenten geben könnten:

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

• „Lass workbuddy src/utils.ts refaktorieren und die Änderungen erklären"

Wohin gehen die Dateien? Textantworten kommen in den Chat zurück. Dateien, die WorkBuddy schreibt, landen in seinem cwd (das cwd des Aufrufs → sonst WB_CWD → sonst der Arbeitsordner des Agenten). Sie werden nicht automatisch zum Kontext Ihres Agenten hinzugefügt – lesen Sie sie von der Festplatte.

Konfiguration / 配置

Alle Einstellungen erfolgen über Umgebungsvariablen – setzen Sie sie im environment-Block der MCP-Konfiguration Ihres Agenten.

Modelle wechseln / 切换模型

Die codebuddy-CLI bietet --model <id> und --fallback-model <id> (letzteres wirkt nur unter --print, was dieser Server immer verwendet). Dieser Server stellt beide bereit:

• Pro Aufruf – übergeben Sie model und/oder fallbackModel an run_workbuddy_task.

• Global – setzen Sie WB_MODEL und/oder WB_FALLBACK_MODEL im environment-Block des Agenten; sie gelten, wenn der Aufruf sie nicht übergibt.

Verfügbare Modelle (aus 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.

Wird das kostenlose Modell ratenbegrenzt? Wechseln Sie nicht hart – fügen Sie einen Fallback hinzu, sodass hy3 primär bleibt, aber bei Überlastung automatisch umschaltet:

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

Oder pro Aufruf: 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。

Sicherheitshinweis / 安全提示

Standardmäßig ist WB_SKIP_PERMISSIONS=true, wodurch codebuddy ohne interaktive Berechtigungsabfragen läuft. Das ermöglicht es einem Agenten, es unbeaufsichtigt zu steuern – bedeutet aber auch, dass alles, was der Agent anfordert, automatisch ausgeführt wird. Für persönliche, vertrauenswürdige Automatisierung ist das in Ordnung; wenn Sie einen Menschen im Loop behalten möchten, setzen Sie WB_SKIP_PERMISSIONS=false in Ihrer MCP-Konfiguration.

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

Warum / 为什么做这个

WorkBuddy ist ein leistungsfähiger Agent, aber jedes Produkt (Claude Code, Codex, Cursor, OpenCode…) lebt in seiner eigenen Box. Es gibt kein offizielles „Reverse MCP", um diesen Produkten den Zugriff auf WorkBuddy als Sub-Agenten zu ermöglichen. Dieses Projekt ist der dünne Kleber: Es verpackt WorkBuddy's eigene CLI hinter einem standardmäßigen MCP-Tool, sodass die vier beliebtesten Coding-Agenten ein WorkBuddy gemeinsam nutzen können.

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

FAQ

Muss die WorkBuddy-Desktop-App laufen? Nein. Es steuert die codebuddy-CLI, die eigenständig ist (gleiche Engine, Terminalform). Ein Desktop-Login genügt.

Funktioniert das offline? Der MCP-Server ist lokal; die codebuddy-Aufrufe erreichen den WorkBuddy-Dienst, daher ist für die eigentliche Aufgabe eine Internetverbindung erforderlich.

Wird mein WorkBuddy-Desktop-Chat anzeigen, was der Agent gefragt hat? codebuddy läuft als eigene Sitzung; Unterhaltungen erscheinen möglicherweise nicht im Verlauf der Desktop-App. Das ist zu erwarten.

Roadmap / 路线图

• Auto-Installation für Claude Code / Codex / Cursor / OpenCode

• Streaming-Ausgabe (Fortschritt anzeigen, statt auf das vollständige Ergebnis zu warten)

• Optionale strukturierte JSON-Ergebnisanalyse

• codebuddy nicht gefunden → geführter Installationshinweis

Mitwirken / 贡献

PRs und Ideen sind willkommen! Issues mit dem Label good first issue sind ein guter Einstieg. Siehe CONTRIBUTING.md.

Jeder Push / PR führt einen Smoke-Test aus (.github/workflows/smoke.yml), der die Syntax auf Node 18/20/22 prüft und verifiziert, dass der Server einen MCP-initialize → tools/list-Handshake abschließt. So führen Sie ihn lokal aus:

npm install
node test/smoke.mjs

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

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

Lizenz / 许可证

MIT © LinHaiJ. Siehe LICENSE für Details.