WorkBuddy / CodeBuddy

Why this agent

WorkBuddy (also branded CodeBuddy — same product) is Tencent’s AI coding assistant, distributed as a desktop application + VS Code extension. It supports custom OpenAI-compatible models (per the awesome-deepseek-agent guide) and MCP servers via the codebuddy mcp CLI / config-file surface.

CodeBuddy is closed-source — Tencent does not publish a public repo for the product itself. The MCP schema documented here was reverse-engineered from third-party adapters (iOfficeAI/AionCore, Chat2AnyLLM/code-assistant-manager, git-men/agentstudio, iOfficeAI/AionUi) — all four implementations independently agree on the same file path and CLI grammar.

Prerequisites

• WorkBuddy / CodeBuddy installed and signed in.
• Project folder opened at least once so the app creates .codebuddy/ directories.
• codebuddy CLI on $PATH (ships with the desktop install).
• espctl installed at a stable path on disk.
• (Optional, for remote builds) the Aegis build server URL + MCP_AUTH_SECRET.

Install snippet (or alternative)

Option A — CLI (recommended; lets CodeBuddy pick the scope):

codebuddy mcp add -s user espctl /path/to/espctl -- mcp serve \
  -e CONTROL_BASE_URL=https://esphome.cloud \
  -e MCP_AUTH_SECRET=your-access-key

Scopes: user (global), local (current dir), project (project root). Picks up immediately; no restart.

Option B — direct file edit at ~/.codebuddy/mcp.json (Windows: C:\Users\<username>\.codebuddy\mcp.json):

{
  "mcpServers": {
    "espctl": {
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

Save as UTF-8 without BOM (same rule as models.json — some desktop versions fail to read BOM-prefixed JSON).

Replace:

• /path/to/espctl — full path to your espctl executable.
• CONTROL_BASE_URL — your Aegis build server URL.
• MCP_AUTH_SECRET — the access key your build server gave you.

Or grab the same envelope pre-filled:

Read the install://workbuddy resource.

First-run verification

In WorkBuddy / CodeBuddy chat:

What espctl tools do you have?

Expected: lists ~40 espctl tools. The MCP panel (CLI: codebuddy mcp list) should show espctl as Connected.

Troubleshooting

• codebuddy: command not found — CodeBuddy desktop install didn’t add CLI to $PATH. On macOS the CLI is bundled in the .app bundle; on Windows it lives in %LOCALAPPDATA%\CodeBuddy\bin\. Either add to $PATH or use Option B (file edit).
• mcp.json parse error — likely a BOM. Re-save as UTF-8 without BOM. (Same gotcha as models.json.)
• Tools listed but every call returns “auth required” — the MCP_AUTH_SECRET is missing or has been revoked. Get a fresh access key from the control plane and paste it into the config.
• Want HTTP transport? Use codebuddy mcp add-json -s user espctl '{"url":"https://esphome.cloud/mcp/esp-idf","transportType":"http", "headers":{"Authorization":"Bearer your-access-key"}}'.
• Want to remove? codebuddy mcp remove -s user espctl (try local / project scope if user reports “not found”).

Tested as-of 2026-05-19

WorkBuddy / CodeBuddy-specific notes

• WorkBuddy and CodeBuddy are the same product under two brand names — Tencent ships WorkBuddy in mainland China and CodeBuddy internationally. Config paths use .codebuddy regardless of brand.
• The ${DEEPSEEK_API_KEY} env-substitution syntax in models.json is documented; whether the same substitution works inside mcp.json’s env: block isn’t documented — paste the literal value if you hit any ${...} display weirdness.
• The three-scope model (user / local / project) means MCP servers can be tightly scoped to one repo. Useful if this MCP coverage should only be visible inside ESP-IDF projects.