v0.3.0

v0.3.0 — first publishable release

MCP server that lets any MCP client (VS Code + Copilot Chat, and others) drive
the Freebuff coding agent, built on the official @codebuff/sdk runtime.

Highlights

• Five tools: freebuff_run, freebuff_status, freebuff_stop,
  freebuff_delete, freebuff_sessions
• Safe-by-default agent: built-in read-only freebuff-ask (search, read,
  answer — no writes, no terminal). Full edit/terminal capability is opt-in via
  agent: 'codebuff/base@0.0.16'
• Persisted sessions: every run is saved to disk and resumable by
  session_id across server restarts, with automatic pruning (50 sessions /
  30 days, configurable)
• Transcript resources: freebuff://sessions (JSON index) and
  freebuff://sessions/{id}/transcript (markdown transcript of every
  user/assistant/tool turn)
• Token-based resume guard: sessions carry an upper-bound token estimate;
  resumes above the ceiling are refused unless force_resume is set
  (thresholds via FREEBUFF_MCP_RESUME_WARN_TOKENS /
  FREEBUFF_MCP_RESUME_MAX_TOKENS)
• npx-ready: npx -y freebuff-mcp-server — no clone required
• CI + publishing: GitHub Actions runs typecheck/build/protocol-only tests
  on push and PRs (Node 20 + 22); npm publishing is automated from GitHub
  releases with tag/version verification and provenance

Installation

npx -y freebuff-mcp-server

Or in VS Code, use the included .vscode/mcp.json (launches via npx and
prompts for your API key on first use).

Authentication

Supply a Codebuff API key (https://www.codebuff.com/api-keys — same account as
Freebuff) via CODEBUFF_API_KEY / FREEBUFF_API_KEY, --api-key, or your
existing Freebuff CLI login, which is picked up automatically as a fallback.

Known limitation (verified Sept 2026): the stored CLI session token
authenticates but SDK runs are billed through the Codebuff API-key path, so
it currently yields Payment Required in normal mode (or Forbidden with
cost_mode: "free"). Generate an API key at the link above and the server
works out of the box.

Requirements

• Node.js >= 18 (CI covers 20 and 22)
• A Codebuff API key with SDK access for real agent runs