Planboard

planboard

A small client for the Beck agent plan board. Beck keeps the shared state an agent team works from — workspaces, planning documents, epics, tasks, progress checks and open decisions — behind a REST API, and planboard exposes that API as 34 MCP tools plus a matching command line, so an agent (or a human at a terminal) can read the board, move tasks along, guard document edits with etags, and answer the decisions that block work.

What it covers

• Identity and workspaces — whoami, list_workspaces, create_workspace.
• API tokens — list_api_tokens, create_api_token, revoke_api_token.
• Documents — list_documents, read_document, create_document, write_document, delete_document, list_document_versions, restore_document. Writes and deletes are guarded by the document's etag, sent as an If-Match header, so a stale editor cannot silently overwrite someone else's revision.
• Epics — list_epics, get_epic, plan_it, get_epic_github, link_epic_github.
• Tasks — list_tasks (filterable by status, epic, assignee and icebox), get_task, get_task_context, recommend_task, start_task, finish_task (with a what-was-attempted report), accept_task, reject_task (a reason is required), update_task (only the fields you provide are sent), add_comment, list_comments.
• Progress — log_progress (passed/total checks with an optional note and label) and list_progress.
• Decisions — list_decisions (filterable by open / answered status and epic), ask_decision (every question carries a default answer), and answer_decision, which accepts exactly one of an explicit answer or keepDefault: true.

Workspace scoping is explicit everywhere: every workspace-scoped tool takes a required workspaceId, sent as a query parameter on reads and deletes and inside the JSON body on writes.

Configuration

export BECK_API_TOKEN="..."          # requiredexport BECK_API_URL="https://beck.bot"   # optional overrideexport BECK_REPO="owner/repo"        # optional, sent as X-Beck-Repoexport BECK_BRANCH="main"            # optional, sent as X-Beck-Branch

Without BECK_API_TOKEN, every tool returns the error text BECK_API_TOKEN is not set and no request is made. Each process also generates one random run id, sent as X-Beck-Run on every request, so the server can group the calls a single agent run makes. The token itself never appears in any tool output.

Successful calls return the upstream JSON body, pretty-printed. A non-2xx response becomes an error result of the form upstream error: HTTP <status> from beck-api, with : <message> appended when the response body carries a message or error string; a request that never completes becomes upstream unreachable: beck-api.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/planboard whoami '{}'npx @reneturcios/planboard list_tasks '{"workspaceId":"w1","status":"open"}'npx @reneturcios/planboard write_document '{"workspaceId":"w1","path":"plan.md","content":"...","etag":"etag-7"}'npx @reneturcios/planboard answer_decision '{"workspaceId":"w1","decisionId":"d1","keepDefault":true}'npx @reneturcios/planboard --version

Output is the same text the MCP tool returns. Exit codes: 0 on success, 1 when the tool result is an error, 2 on a usage error.

MCP server

npx -y @reneturcios/planboard mcp

MCP client config:

{  "mcpServers": {    "planboard": {      "command": "npx",      "args": ["-y", "@reneturcios/planboard", "mcp"],      "env": {        "BECK_API_TOKEN": "..."      }    }  }}

Docker

docker run -i -e BECK_API_TOKEN="..." ghcr.io/cloudcorprecords/planboarddocker run --rm -e BECK_API_TOKEN="..." ghcr.io/cloudcorprecords/planboard list_epics '{"workspaceId":"w1"}'

Development

npm installnpm run build   # tsc -> dist/npm test        # tsx --test test/*.test.ts (fake fetch only, no network)npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios