planboard

Name: planboard
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords生产力01 周前更新

代码仓库

关于 planboard

planboard 通过 MCP 工具和命令行提供 Beck Agent 计划看板的 REST API，供 Agent 和团队成员协作管理工作区、文档、史诗、任务、进度与决策。

主要功能

01读取和管理工作区
02创建文档并管理版本
03跟踪史诗与任务
04记录进度并处理决策
05通过 etag 保护文档编辑

适用场景

01按状态或史诗查看任务
02安全更新共享计划文档
03记录任务进度与完成情况
04回答阻塞工作的待决问题

MCP 相关

它将 Beck 计划看板 REST API 暴露为 34 个 MCP 工具，用于读取和更新指定工作区的数据；同时提供配套命令行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-planboard": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/planboard"
      ]
    }
  }
}

启动命令npx -y @reneturcios/planboard

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/planboard0.1.0stdio

ocighcr.io/cloudcorprecords/planboard:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

此工具无需参数。

详细介绍

planboard

一个用于 Beck Agent 计划板的小型客户端。Beck 通过 REST API 保存 Agent 团队协作所依赖的共享状态——工作区、规划文档、史诗、任务、进度检查和待处理决策；planboard 则将该 API 封装为 34 个 MCP 工具和配套的命令行，让 Agent（或在终端操作的人）能够查看计划板、推进任务、使用 etag 保护文档编辑，并回答阻碍工作的决策。

涵盖内容

身份和工作区 — whoami、list_workspaces、 create_workspace。
API 令牌 — list_api_tokens、create_api_token、 revoke_api_token。
文档 — list_documents、read_document、 create_document、write_document、delete_document、 list_document_versions、restore_document。写入和删除操作受文档 etag 保护，etag 会通过 If-Match 标头发送，因此过期的编辑器无法在不知情的情况下覆盖他人的修订版本。
史诗 — list_epics、get_epic、plan_it、 get_epic_github、link_epic_github。
任务 — list_tasks（可按状态、史诗、受派人和 icebox 筛选）、get_task、get_task_context、 recommend_task、start_task、finish_task（附带已尝试内容报告）、accept_task、reject_task （必须提供原因）、update_task（仅发送你提供的字段）、add_comment、list_comments。
进度 — log_progress（已通过／总检查项数，可选附注和标签）和 list_progress。
决策 — list_decisions（可按 open／ answered 状态和史诗筛选）、ask_decision（每个问题都附带默认答案）以及 answer_decision，它只接受明确答案或 keepDefault: true 中的一种。

所有地方都明确指定工作区范围：每个作用域为工作区的工具都需要 workspaceId；读取和删除时将其作为查询参数发送，写入时则放在 JSON 请求体中。

配置

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

未设置 BECK_API_TOKEN 时，每个工具都会返回错误文本 BECK_API_TOKEN is not set，且不会发起请求。每个进程还会生成一个随机运行 ID，并在每个请求中通过 X-Beck-Run 发送，以便服务器对单次 Agent 运行发出的调用进行分组。令牌本身不会出现在任何工具输出中。

成功调用会返回上游 JSON 请求体，并以美化格式打印。非 2xx 响应会转换为如下错误结果： upstream error: HTTP <status> from beck-api；如果响应体包含 message 或 error 字符串，则会在其后附加 : <message>；未能完成的请求则会变为 upstream unreachable: beck-api。

CLI

每个工具都是一个子命令，接受一个 JSON 字符串参数：

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

输出内容与 MCP 工具返回的文本相同。退出码：成功时为 0，工具结果为错误时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/planboard mcp

MCP 客户端配置：

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

Docker

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

开发

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