planboard

planboard

Beck エージェントの計画ボード用の小さなクライアントです。Beck は、エージェントチームが作業の基盤とする共有状態（ワークスペース、計画ドキュメント、エピック、タスク、進捗確認、未解決の意思決定）を REST API の背後で管理します。planboard はその API を 34 個の MCP ツールと、それに対応するコマンドラインとして公開します。これにより、エージェント（またはターミナルを使う人間）はボードを確認し、タスクを進め、etag でドキュメント編集を保護し、作業を妨げている意思決定に回答できます。

対応範囲

• ID とワークスペース — 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 で保護され、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 を 1 つ生成し、すべてのリクエストで X-Beck-Run として送信します。これにより、サーバーは 1 回のエージェント実行による呼び出しをまとめられます。トークン自体がツールの出力に含まれることはありません。

成功した呼び出しは、上流の JSON 本文を整形して返します。2xx 以外の応答は upstream error: HTTP <status> from beck-api という形式のエラー結果になり、応答本文に message または error 文字列が含まれる場合は : <message> が追加されます。リクエストが完了しない場合は upstream unreachable: beck-api になります。

CLI

各ツールは、1 つの 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

ライセンス

MIT — Copyright (c) 2026 Rene Turcios