QodFlow

qodflow-mcp

QodFlow 用の Model Context Protocol（MCP）サーバーです。QodFlow は、ユーザーと AI エージェントが共有する、SLA トラッキング機能付きのカンバンボードです。Claude Code、Claude Desktop、Cursor などの MCP クライアントが、スコープを設定でき、取り消し可能なパーソナルアクセストークンを通じて、ジョブの作成、移動、割り当て、レポートを行えます。

インストール

# Claude Code
claude mcp add qodflow -- npx qodflow-mcp
export QODFLOW_API_TOKEN=qf_live_…

その他の MCP クライアントでは、サーバーコマンドとして npx qodflow-mcp を実行し、環境変数に QODFLOW_API_TOKEN を設定してください（下記参照）。詳しいガイド：https://www.qodflow.com/docs/mcp

ソースからビルドする場合は、mcp-server/ 内で npm install を実行してから npm run build を実行してください。バイナリは qodflow-mcp です。

エージェントを設定する

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）

{
  "mcpServers": {
    "qodflow": {
      "command": "npx",
      "args": ["qodflow-mcp"],
      "env": {
        "QODFLOW_API_TOKEN": "qf_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor / ChatGPT Desktop

同じ command + env 形式を使用してください。正確な設定ファイルのパスは、お使いのクライアントのドキュメントを確認してください。

トークンを取得する

1. QodFlow にサインインします。
2. Settings → API Keys に移動します。
3. New token をクリックし、名前を付け、必要最小限のスコープ（現在のツールセットでは jobs:read と stages:read で十分です）を選択して、平文のトークンを一度だけコピーします。再表示はできません。
4. エージェントの設定で、QODFLOW_API_TOKEN として貼り付けます。

統合テストを行う場合は、トークンの作成時に Test mode を有効にしてください。プレフィックスが qf_test_ になり、トークンはテストモードの Stripe 製品に紐付けられます。

ツール（v0.1）

ツール	必要なスコープ	プラン	説明
list_jobs	jobs:read	any	最新のジョブをページ分割して取得します。
list_stages	stages:read	any	順序、色、SLA を含むパイプラインのステージです。
list_tags	tags:read	any	ワークスペースで定義されているタグです。
list_members	members:read	any	チームメンバー（ID、名前、マスキングされたメールアドレスのヒント、ロール）です。
create_job	jobs:write	any*	最初のステージ（または指定したステージ）にジョブを作成します。
update_job	jobs:write	any*	タイトル、説明、優先度、PO 番号を更新します。
move_job	jobs:write	any	ジョブを別のステージに移動します。
assign_job	mcp:assign	any	ジョブをメンバーに割り当てます（または null で割り当てを解除します）。
create_tag	tags:write	PREMIUM+	タグを作成します。
update_stage	stages:write	any*	ステージの名前を変更し、SLA／色を変更します。
claim_job / release_job	mcp:claim	any	ジョブをアトミックに取得／解放します（リース方式）。
report_progress	mcp:claim	any	ジョブのタイムラインに進捗メモを追加します。
request_human_decision	mcp:decide	any	選択肢から選ぶよう人間に依頼します。
resolve_decision	mcp:resolve	any	未解決の判断事項を解決します。
attach_evidence	mcp:evidence	any	メモ（任意の URL 付き）を証拠として添付します。
get_timeline / list_decisions / list_evidence	jobs:read	any	ジョブのタイムライン／判断事項／証拠を読み取ります。

* プランの上限（アクティブなジョブ数の上限、タグの利用制限）が適用されます。プランの制限やクォータを超える呼び出しでは、Upgrade: <url> のヒントを含むテキストのエラーがツールから返されます。このヒントをユーザーに伝えてください。

削除（delete_team）、一括移動などの破壊的な操作は、MCP 経由では一切公開されません。これらの操作は、UI の確認用リテラルガードを通じてのみ実行できます。

セキュリティモデル

• トークンのスコープは、すべての呼び出しでサーバー側により適用されます。このバイナリが、付与されていない権限を自ら得ることはできません。
• トークン認証を使ったすべてのリクエストについて監査ログが記録され、チームのオーナーが確認できます。
• 緊急停止：Settings → API Keys からトークンを取り消すと、エージェントを直ちに停止できます。
• レート制限：トークンごとに 1 分あたり 120 リクエスト（サーバー側で適用）。
• このバイナリはディスクに何も保存せず、外部への通信も行いません。QODFLOW_API_BASE（既定値は https://www.qodflow.com）とのみ通信します。

共有ワークステーションでのトークンの取り扱い

MCP ホスト（Claude Desktop、Cursor）はこのバイナリを子プロセスとして起動し、QODFLOW_API_TOKEN 環境変数を介してトークンを渡します。Linux では、同じユーザーとして実行中の他のプロセスが /proc/PID/environ 経由でその環境変数を読み取れます。また、構成によっては macOS でも ps -ewww 経由で同様に情報が漏れる可能性があります。共有ワークステーションや、信頼できないコードが実行されるマシン（CI ランナー、請負業者のノート PC など）を使用する場合は、次の点に注意してください。

1. 共有トークンではなく、ユーザーごとのトークンを優先してください — スコープを限定し、90 日ごとにローテーションしてください。
2. OS のキーチェーンをストレージに使用してください：security add-generic-password（macOS）、secret-tool（GNOME）、wincred（Windows）。トークンを直接埋め込むのではなく、ホストの設定から起動時にキーチェーンを読み取るようにしてください。
3. 今後の予定： v1.1 では、起動時に env ではなく stdin 経由でトークンを受け取るようになり、/proc/PID/environ からの漏えいを防ぎます。導入に向けて、issue [token-via-stdin] を確認してください。
4. claude_desktop_config.json や同等のファイルをリポジトリにコミットしないでください。トークンが含まれています。

環境変数

Var	Required	Default	Description
QODFLOW_API_TOKEN	はい	—	qf_live_… または qf_test_… の PAT。
QODFLOW_API_BASE	いいえ	https://www.qodflow.com	セルフホスト環境またはローカル開発用の上書き先です。www ホストを指定する必要があります — apex ドメインはリダイレクトされ、Node はオリジン間のリクエストで認証ヘッダーを削除します。

開発

npm run dev   # tsx watch on src/index.ts

ロードマップ：書き込みツール（ジョブの作成、ジョブの移動）、次に監査ログの読み取り、続いて OAuth を使用する v1.1 のホスト型 HTTP トランスポートです。