chokugaki

chokugaki 向けの stdio 型 MCP サーバーです。 Cursor、Codex、Cline、Zed などの MCP 対応クライアントから chokugaki フィードバック管理 API を直接操作できる薄い HTTP クライアントを提供します。

認証は アカウント単位の API キー1本（環境変数 CHOKUGAKI_API_KEY）です。 MCP 対応クライアントに一度だけ登録すれば、あなたが所属するすべてのプロジェクトで使えます（プロジェクトごとの MCP 設定は不要）。

クイックスタート（1回だけの登録）

1. ダッシュボードの「API キー」ページでキーを1本発行します（ckg_...。発行時に一度だけ全文が表示されます）。
2. お使いの MCP 対応クライアントのユーザースコープに登録します(例):

claude mcp add chokugaki --scope user \
  --env CHOKUGAKI_API_KEY=ckg_xxxxxxxx \
  -- npx -y chokugaki

または ~/.claude.json（ユーザースコープの MCP 設定）に直接:

{
  "mcpServers": {
    "chokugaki": {
      "command": "npx",
      "args": ["-y", "chokugaki"],
      "env": {
        "CHOKUGAKI_API_KEY": "ckg_xxxxxxxx"
      }
    }
  }
}

3. 案件ごとにリポジトリ直下で一度だけ実行し、対象プロジェクトを紐付けます:

npx chokugaki link

これで .chokugaki（プロジェクト ID を 1 行だけ書いたファイル）が作られます。リポジトリにコミットすれば、チームメンバーも clone した時点で紐付け済みになります。

できること

登録すると、MCP 対応クライアントとの会話でクライアントのフィードバック対応が一気通貫でこなせます。普段のお願いの例:

• 「未対応の指摘を見せて」 … 未対応タスクを種別・重要度つきで一覧し、着手順を提案します。
• 「fb_xxx の詳細を教えて」 … セレクタや HTML 断片つきで、直すべき箇所の手がかりを取得します。
• 「fb_xxx を直して完了報告して」 … 該当コードを特定して修正し、クライアントに完了通知を送ります。
• 「この指摘、意図が曖昧だからクライアントに確認して」 … 選択肢つきの質問をウィジェット側スレッドに送ります。

新着の確認と、クライアントへの転送

chokugaki はメールなどの通知を送りません。新着の指摘は MCP で定期的に確認してください。Claude Code なら /loop で定期実行できます(例: /loop 30m /chokugaki-task)。

AI がクライアントに聞き返している指摘(needs_clarification)には、list_feedback / get_task の結果に clarification_relay が付きます。中の message は、クライアントにそのまま貼れる短い文面と、その質問をページ上で開ける直リンクです。Slack や Chatwork などいつもの連絡手段で転送してください。リンクには投稿したレビュアーの招待が含まれるので、相手はログインなしでそのまま回答できます。

スラッシュコマンド

よく使うワークフローはスラッシュコマンドから一発で始められます。

~/.claude/commands を読み込むエージェントの場合 — 短いカスタムコマンドを配布できます:

npx chokugaki install-commands

これで ~/.claude/commands/ に chokugaki-task.md / chokugaki-fix.md が書き出され、エージェントを再起動すると 次の短いコマンドが使えます（チームで共有したいときはリポジトリ直下で --scope project を付けて実行すると .claude/commands/ に書き出されます）:

| コマンド | 引数 | 動作 | |---|---|---| | /chokugaki-task | [project] | 未対応フィードバックを一覧し、種別・重要度つきで着手順を提案します。needs_clarification はクライアント回答待ちとして明示します。引数を渡すとプロジェクト ID として扱います。 | | /chokugaki-fix | [id] | 指摘を1件、該当箇所の特定 → 修正 → 完了報告（または確認質問）まで対応します。引数を省略すると最優先の1件を自動選択します。 |

その他の MCP 対応クライアントの場合 — MCP プロンプト由来のコマンドをそのまま使います:

| コマンド | 引数 | 動作 | |---|---|---| | /mcp__chokugaki__tasks | project? | /chokugaki-task と同じ。未対応を一覧して着手順を提案します。 | | /mcp__chokugaki__fix | id? | /chokugaki-fix と同じ。1件を修正して完了報告まで対応します。 |

提供ツール（5つ）

| ツール | 引数 | 動作 | |---|---|---| | list_projects | — | アクセス可能なプロジェクト一覧（id / name） | | list_feedback | project?, status? | 未対応タスク一覧（summary / type / severity / URL。聞き返し中は転送文と直リンク） | | get_task | id | タスク詳細（CSS セレクタ / HTML 断片 / env を含む、コード箇所を特定する材料一式。聞き返し中は転送文と直リンク） | | mark_resolved | id, summary | resolved に遷移させ、ウィジェットのスレッドに確認依頼を出す | | ask_client | id, question | 作業中の疑問をウィジェット側スレッドに送信 |

get_task / mark_resolved / ask_client は id からプロジェクトを引くため、プロジェクト指定は不要です。

プロジェクトの自動解決（list_feedback）

list_feedback の対象プロジェクトは次の 3 段フォールバックで解決されます:

1. ツール引数 project の明示指定
2. 環境変数 CHOKUGAKI_PROJECT
3. カレント作業ディレクトリ直下の .chokugaki ファイル（npx chokugaki link で生成）

いずれも無い場合は、list_projects で確認して project 引数を指定するよう促すエラーが返ります。

.chokugaki について

• リポジトリ直下に置く、プロジェクト ID を 1 行だけ書いたテキストファイルです。

• npx chokugaki link で対話生成します。非対話にしたい場合は --project <id> を渡します:

  npx chokugaki link --project prj_xxxxxxxx

• コミットしておくと、そのリポジトリで作業するメンバー全員が同じプロジェクトに紐付きます。

環境変数

| 変数 | 必須 | 説明 | |---|---|---| | CHOKUGAKI_API_KEY | ✅ | ダッシュボードの「API キー」ページで発行したアカウントキー | | CHOKUGAKI_PROJECT | 任意 | プロジェクト解決の既定値（.chokugaki を使うなら不要） | | CHOKUGAKI_API_URL | 任意 | API のベース URL（デフォルト: https://chokugaki.com） |

ローカル開発 / ステージング環境

CHOKUGAKI_API_URL で接続先を上書きできます。モノレポでビルド済みのローカルパッケージを直接指定する例:

{
  "mcpServers": {
    "chokugaki": {
      "command": "node",
      "args": ["/path/to/chokugaki/packages/mcp/dist/index.js"],
      "env": {
        "CHOKUGAKI_API_KEY": "ckg_localkey",
        "CHOKUGAKI_PROJECT": "prj_demo",
        "CHOKUGAKI_API_URL": "http://localhost:8787"
      }
    }
  }
}

使い方の流れ(MCP ツール直接呼び出し)

# 0. どのプロジェクトがあるか確認（.chokugaki が未設定のとき）
list_projects

# 1. 未対応タスクの一覧確認（.chokugaki があれば project 省略可）
list_feedback

# 2. 対象タスクの詳細取得（セレクタ / HTML 断片でコードを特定）
get_task id="fb_001"

# 3a. 修正完了を報告（クライアントに確認依頼が届く）
mark_resolved id="fb_001" summary="ヘッダーのフォントサイズを 32px に変更しました"

# 3b. 意図が不明な場合はクライアントに質問を送る
ask_client id="fb_001" question="フォントサイズは大きくしたいですか、それとも余白を広げたいですか？"

ステータスの流れ

open → structured → needs_clarification → in_progress → resolved → verified
                                                         ↑                ↑
                                                    mark_resolved    クライアント確認

• resolved: 開発者が mark_resolved を呼んだ時点。ウィジェットのスレッドに確認依頼が出る（クライアントへの通知は送らないので、必要ならいつもの連絡手段で伝える）。
• needs_clarification: AI がクライアントに聞き返している状態。get_task を呼んでも回答待ちのまま残る。
• verified: クライアントがウィジェット上で「確認済み」を押した時点。

エラー処理

API エラーはツール結果の isError: true で返ります（プロセスは落ちません）。

| HTTP ステータス | メッセージ | |---|---| | 401 | CHOKUGAKI_API_KEY が正しくないか失効している | | 403 | アクセス権なし | | 404 | 指定 ID のフィードバック / プロジェクトが存在しない、または未所属 | | 429 | レート制限超過。しばらく待ってから再試行 |

開発・テスト

# ビルド
pnpm --filter chokugaki build

# テスト（vitest, fetch モック）
pnpm --filter chokugaki test

# 型チェック
pnpm --filter chokugaki typecheck

ライセンス

MIT © 2026 buildia-lab