Workstream

workstream-mcp

AI エージェントと人間が共同で行った作業の記録を保持する MCP サーバーです。計画、タスク、担当権、調査結果、修正の試み、判定を Postgres に保存し、GitHub Projects と Slack に反映します。

30 秒で試す

Postgres とサーバーをデモモードで実行する単一のコンテナーです。プロジェクト、進行中の計画、3 つのタスクがあらかじめ登録されています。

docker run --rm -p 127.0.0.1:8080:8080 ghcr.io/ahmad-codex/workstream-mcp:demo
claude mcp add --transport http workstream-demo http://localhost:8080/demo-insecure-token/mcp

次に、Claude に「workstream のプロジェクトを一覧表示して、デモ計画の次のタスクを担当してください」と依頼します。デモトークンは公開されており、管理者権限を持つため、ポートは 127.0.0.1 にバインドしてください。デモモードがオフの場合、サーバーはこのトークンを拒否します。コンテナーを停止すると、データは失われます。

http://localhost:8080/demo-insecure-token/ui/ を開くと、ダッシュボードで計画を確認できます。エージェントがタスクを取り合う様子を見るには、-e WORKSTREAM_ADMIN_TOKEN=local-admin を指定してコンテナーを起動し、WORKSTREAM_ADMIN_TOKEN=local-admin node scripts/simulate-agents.mjs を実行します。

Claude Code でセットアップする

リポジトリをクローンし、その中で Claude Code を開いて、次の内容を貼り付けます。

Set up workstream-mcp for me on this machine. Follow the README quick start using the
published Docker image, create an admin user for me, and connect this Claude Code session
to it. Then create a project and a development plan with three sample tasks, activate it,
and claim one task to show it works. When that is done, ask me whether I want GitHub
Projects or Slack sync, and walk me through docs/github-setup.md or docs/slack-setup.md
step by step, telling me exactly what to click and which values to paste back.

手動でセットアップしますか？クイックスタート（約 5 分）をご覧ください。

概要

エージェントの作業を調整する一般的な方法は、リポジトリに Markdown 形式の計画を置くことです。エージェントが読み、編集し、コミットするチェックリストです。1 つのセッションで 1 つのエージェントが作業する場合はうまく機能します。しかし、複数のエージェントや人が同じ計画に同時に取り組むと、問題が生じます。

• それを止める仕組みがないため、2 つのエージェントが同じ項目を選んでしまいます。
• エージェントがタスクの途中で停止すると、その項目はいつまでも「進行中」のままになります。
• ファイルの編集が競合し、誰が何をしたかの履歴は Git の差分に埋もれてしまいます。
• チームがいつも確認しているプロジェクトボードや Slack に、計画が表示されません。

workstream-mcp はファイルを小規模なサービスに置き換えます。エージェントは MCP ツールを呼び出して作業を担当し、結果を送信して判定を記録します。担当権はアトミックに付与され、有効期限が切れます。状態遷移は状態グラフに照らして確認され、すべての変更は追記専用のイベントログに記録されます。また、GitHub と Slack の更新はアウトボックス経由で行われるため、連携先に障害が発生してもエージェントの作業が妨げられることはありません。

機能

現在のコードでできること：

• TTL 付きのアトミックなクレーム。 1 つのトランザクション内で SELECT ... FOR UPDATE SKIP LOCKED を実行するため、複数のクレーム実行者が同じタスクを取得したり、互いにブロックしたりすることはありません。更新されないクレームは期限切れとなり、作業はプールに戻ります。32 クレーム実行者による並行処理テストスイートで検証されています。
• データ駆動型のステートマシン。 ステータス、有効な遷移、許可されるロール、ロールの TTL、再試行の上限、ボード列のマッピングは、plan_types.state_graph（JSONB）に格納されています。2 種類のプランタイプが用意されています。audit（検出、検証、修正、再検証）と development（実装、レビュー）です。不正な遷移では illegal_transition と allowed_next が返されるため、呼び出し元のモデルは自身を修正できます。
• 追記専用のイベントログ。 状態が変更されるたびに events 行が書き込まれます。トリガーにより、events と verdicts に対する UPDATE と DELETE はブロックされます。
• GitHub Projects V2 同期。 タスクは Projects V2 ボード上でイシュー（リポジトリのないプロジェクトでは下書きアイテム）になり、列はタスクのステータスに従います。また、監査プランにはマイルストーンが設定されます。署名付き Webhook エンドポイントで受信したボードイベントを検証しますが、イベントの適用にはまだ対応していません（ロードマップを参照してください）。GitHub App を使用します。
• Slack 通知。 プロジェクトのチャンネルごとに Block Kit メッセージを送り、タスクごとにスレッド化します。エージェントの投稿にはロール別のペルソナを使用し、インタラクティブボタンは Slack 署名シークレットを使って検証します。
• アウトボックス。 GitHub と Slack の呼び出しは、リクエストのトランザクション内で board_sync_log と slack_notify_log にキューイングされ、バックグラウンドワーカーが再試行しながら処理します。
• Web ダッシュボード。 /<token>/ui/ に、プランごとの読み取り専用ボードを表示します。ステータス別のタスク、TTL カウントダウン付きのクレーム保持者、依存関係、停滞中の作業、各タスクのイベントタイムラインを確認できます。docs/dashboard.md を参照してください。
• URL を認証情報として使用する認証。 各ユーザーには https://host/<token>/mcp のような URL が割り当てられます。この URL を MCP クライアントに貼り付けるだけでセットアップは完了です。トークンはローテーション可能で、パスとログから削除されます。
• 監査ディスパッチャー（オプション）。 request_audit が監査実行をキューイングします。サイドカーコンテナーがリポジトリをクローンし、Claude Code を使ってプロジェクトの監査オーケストレーターを tmux セッション内で起動します。
• 管理 API と CLI。 静的ベアラートークンで保護された /admin/* エンドポイントから、ユーザーとボードを管理できます。また、ユーザー管理用の workstream-admin CLI もあります。プロジェクトとプランは、管理者権限が必要な MCP ツールからセットアップします。
• 停滞作業レポート。 1 時間ごとに実行されるジョブが、期限切れのクレーム、古い検出事項、アイドル状態のプランの件数を stuck_work_reports に書き込みます。

アーキテクチャ

flowchart LR
    subgraph Clients
        CC[Claude Code / Desktop / Cursor]
        ORCH[Orchestrator agents]
    end

    CC -- "POST /&lt;token&gt;/mcp<br/>JSON-RPC 2.0" --> API
    ORCH -- "POST /&lt;token&gt;/mcp" --> API

    subgraph Server
        API[Workstream.Api<br/>token middleware, MCP tools,<br/>state machine, claims]
        BSW[BoardSyncWorker]
        SNW[SlackNotifyWorker]
        DISP[AuditDispatchWorker<br/>dispatcher role]
    end

    API -- "one transaction:<br/>state + events + outbox rows" --> PGB[(PgBouncer)]
    PGB --> PG[(Postgres 16)]
    BSW -- drain board_sync_log --> PG
    SNW -- drain slack_notify_log --> PG
    DISP -- drain audit_dispatch_log --> PG

    BSW -- GraphQL / REST --> GH[GitHub Projects V2,<br/>issues, milestones]
    SNW -- chat.postMessage --> SL[Slack]
    GH -- signed webhook --> API
    SL -- signed interactivity --> API
    DISP -- tmux + claude --> REPO[checked-out repos]

プロジェクト	役割
src/Workstream.Api	ASP.NET Core ホスト、トークンミドルウェア、JSON-RPC エンドポイント、管理 API、Webhook、ディスパッチャー
src/Workstream.Core	ドメインモデル、ステートグラフパーサー、StateMachineService、クレームルール
src/Workstream.Data	Npgsql + Dapper リポジトリ、アウトボックス、SQL マイグレーションランナー
src/Workstream.Mcp	MCP ツールのクラスと登録
src/Workstream.GitHub	GitHub App 認証、Projects V2 クライアント、ボード同期ワーカー
src/Workstream.Slack	Slack クライアント、Block Kit ビルダー、通知ワーカー、署名チェック
src/Workstream.Telemetry	OpenTelemetry のセットアップとメトリクス定義
tools/workstream-admin	運用担当者向け CLI
deploy/	Dockerfile、Compose ファイル、マイグレーション、プランタイプのプロファイル、Caddy、PgBouncer、Grafana、Prometheus の設定

詳しくは、docs/architecture.md と docs/state-machine.md を参照してください。

クイックスタート（約5分）

Docker が必要です。Postgres と API のみを起動します。GitHub、Slack、ディスパッチャーは起動しません。

git clone https://github.com/ahmad-codex/workstream-mcp.git
cd workstream-mcp
docker compose -f deploy/docker-compose.quickstart.yml up -d --build
curl http://localhost:8080/healthz
# {"ok":true}

ローカルでのビルドを省略するには、公開済みのイメージを実行します。

WORKSTREAM_IMAGE=ghcr.io/ahmad-codex/workstream-mcp:latest \
  docker compose -f deploy/docker-compose.quickstart.yml up -d --no-build

API は起動時に SQL マイグレーションを適用します。これには audit と development のプランタイプも含まれます。

ユーザーを作成します。レスポンスにはユーザーの MCP URL が一度だけ含まれるので、コピーしてください。

curl -s -X POST http://localhost:8080/admin/users \
  -H "Authorization: Bearer local-admin-token" \
  -H "Content-Type: application/json" \
  -d '{"githubUsername":"alice","displayName":"Alice","actorType":"human","isAdmin":true}'
# { "user": {...}, "url": "http://localhost:8080/<token>",
#   "mcp_endpoint": "http://localhost:8080/<token>/mcp", "warning": "..." }

isAdmin によって、このユーザーはセットアップツール（create_project、create_plan、...）を呼び出せます。 URL を確認します。

curl http://localhost:8080/<token>
# {"ok":true,"actor":{"id":"...","github_username":"alice","is_admin":true},...}

次に MCP クライアントを接続し（次のセクションを参照）、プロジェクト、開発プラン、 いくつかのタスクの作成、プランの有効化、タスクの 1 つの取得を依頼します。

docker compose -f deploy/docker-compose.quickstart.yml down で停止します（データを削除するには -v を追加します）。

MCP クライアントの接続

サーバーは <base>/<token>/mcp で HTTP（JSON-RPC 2.0 POST）経由の MCP に対応しています。追加の ヘッダーは不要です。パス内のトークンでユーザーを識別します。

Claude Code

claude mcp add --transport http workstream http://localhost:8080/<token>/mcp

Claude Desktop（claude_desktop_config.json）。Claude Desktop はこのファイルから stdio サーバーを起動するため、 mcp-remote ブリッジを使用します（Node.js が必要です）。

{
  "mcpServers": {
    "workstream": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/<token>/mcp"]
    }
  }
}

サーバーに HTTPS でインターネット経由でアクセスできる場合は、代わりに Claude Desktop の設定で カスタムコネクターとして URL を追加できます。

stdio（任意のクライアント）。同じバイナリを --stdio で実行すると、stdin/stdout 経由で MCP に対応します。WORKSTREAM_USER_TOKEN にあるトークンのユーザーとして、 WORKSTREAM_DB_CONNECTION のデータベースに接続します（GitHub と Slack のアウトボックスを 処理するには、HTTP サーバーがどこかで稼働している必要があります）。

{
  "mcpServers": {
    "workstream": {
      "command": "dotnet",
      "args": ["/path/to/Workstream.Api.dll", "--stdio"],
      "env": {
        "WORKSTREAM_DB_CONNECTION": "Host=localhost;Database=workstream;Username=workstream;Password=...",
        "WORKSTREAM_USER_TOKEN": "<token>"
      }
    }
  }
}

WORKSTREAM_DB_CONNECTION がない場合、--stdio は検出モードで起動します。initialize と tools/list は動作しますが、すべてのツール呼び出しは not_configured エラーを返します。Glama などのディレクトリスキャナーは このモードを使用します。

Cursor（~/.cursor/mcp.json、またはプロジェクト内の .cursor/mcp.json）：

{
  "mcpServers": {
    "workstream": {
      "url": "http://localhost:8080/<token>/mcp"
    }
  }
}

URL は認証情報です。コミットせず、ユーザーレベルの設定に保管してください。 オンボーディングの全手順については、docs/onboarding.md を参照してください。

MCP ツール

36 個のツールです。すべての応答は { ok, data, error } 形式です。エラーには安定した code（ stale_claim、illegal_transition、retry_cap_exceeded、…）が含まれます。詳細は docs/mcp-tools.md をご覧ください。Slack への投稿に使用するロールのペルソナを設定するには、任意の呼び出しで as_agent を指定できます。

グループ	ツール	機能
検出	list_projects	アクティブなプランの件数と、呼び出し元が保持している未完了のクレームを含むプロジェクト一覧
	list_plans	プロジェクトのプラン一覧。ステータスで絞り込み可能で、ステータス別のタスク件数を表示
	get_plan_dashboard	ステータス別件数、次にクレーム可能な作業、自分のクレーム、停滞中の作業、最近のイベント
	get_my_active_work	呼び出し元が保持しているすべてのクレーム
クレーム	claim_next_task	ロールに対応する、優先度が最も高い未処理タスクをクレーム
	claim_specific_task	ID を指定してタスクをクレーム
	claim_next_finding_for_verification	監査：検証する指摘をクレーム
	claim_next_finding_for_fix	監査：修正対象として確定した指摘をクレーム
	claim_next_attempt_for_review	予約済み。v1 のスタブ
	refresh_claim	長時間の作業中にクレームの TTL を延長
	release_claim	提出せずに作業を返却
提出	start_work	claimed から in_progress に変更
	submit_findings	監査：タスクの指摘を提出
	submit_verification_verdict	監査：確認済み、却下、または判定不能を提出
	submit_attempt	コード変更を提出。再試行上限を適用
	submit_attempt_verdict	監査：fix_confirmed、fix_failed、または partial を提出
	submit_review_decision	開発：approved または changes_requested を提出
ライフサイクル	mark_task_status	deferred、blocked、skipped、out_of_scope、needs_human_review に設定
	record_commit	コミットハッシュを関連付け
	create_task / create_tasks	プランにタスクを追加。単一または一括
	override_verdict	状態を強制変更。can_override_verdict が必要
フォレンジック	get_event_log	1 つのエンティティのイベントタイムライン
	get_stuck_work	TTL を過ぎたタスクと試行、24 時間以上待機中の指摘、アイドル状態のプラン
	export_plan	プランのスナップショットを Markdown または JSON 形式で出力
	get_finding	1 件の指摘の全内容：重大度、根本原因、再現方法、ステータス、クレーム保持者
セットアップ（管理者）	create_project	新しいプロジェクト
	add_project_repo	GitHub リポジトリを関連付け
	add_project_board	Projects V2 ボードを登録
	set_project_slack	Slack チャンネルとボットトークンの参照先を設定
	create_plan	下書き状態の新しいプラン
	add_phase	プランにフェーズを追加
	activate_plan	下書きからアクティブに変更し、ボード項目をキューに追加
	archive_plan	プランを完了またはキャンセルとして終了
監査のディスパッチ（管理者）	request_audit	1 つ以上のプロジェクトの監査実行をキューに追加
	cancel_audit	実行中の監査に停止とクリーンアップを要求

設定

API が読み込む環境変数です。各 _FILE バリアントは、ファイル（Docker シークレット）から値を読み込みます。

変数	必須	用途
WORKSTREAM_DB_CONNECTION	はい	Npgsql 接続文字列です。Password=__from_secret__ は、WORKSTREAM_DB_PASSWORD_FILE の内容に置き換えられます
WORKSTREAM_DB_PASSWORD_FILE	いいえ	データベースのパスワードを格納するファイルです
WORKSTREAM_ADMIN_TOKEN / _FILE	管理 API 用	/admin/* のベアラートークンです。未設定の場合、管理リクエストは拒否されます
WORKSTREAM_PUBLIC_BASE_URL	いいえ	ユーザー URL を返す際に使用するベース URL です。デフォルトはリクエストのホストです
WORKSTREAM_GH_APP_ID	GitHub 用	GitHub App の ID です
WORKSTREAM_GH_INSTALLATION_ID	GitHub 用	App のインストール ID です
WORKSTREAM_GH_APP_KEY_PATH	GitHub 用	App の秘密鍵（PEM）へのパスです
WORKSTREAM_GH_WEBHOOK_SECRET / _FILE	GitHub 用	Webhook の HMAC シークレットです
WORKSTREAM_SLACK_SIGNING_SECRET / _FILE	Slack ボタン用	Slack の署名シークレットです
WORKSTREAM_ROLE	いいえ	api（デフォルト）または dispatcher です
WORKSTREAM_TRANSPORT	いいえ	標準入力／標準出力で MCP を提供するには stdio を指定します（--stdio と同じです）
WORKSTREAM_USER_TOKEN	stdio	stdio サーバーが操作するユーザーです
WORKSTREAM_DEMO	いいえ	true にするとデモデータが登録され、公開デモトークンが受け入れられます。ローカルでの試用に限ります
WORKSTREAM_AUDIT_DISPATCH_ENABLED	dispatcher	監査ディスパッチャーを実行するには true を指定します
WORKSTREAM_AUDIT_DISPATCH_SCRIPT	dispatcher	audit-dispatch.sh へのパスです
WORKSTREAM_AUDIT_DISPATCH_TIMEOUT	いいえ	ディスパッチスクリプトのタイムアウト（秒）です
WORKSTREAM_OTEL_ENDPOINT	いいえ	トレースとメトリクス用の OTLP エンドポイントです。未設定の場合、テレメトリーは無効です。URL トークンはスパンからマスキングされます
WS_SSH_MCP_HOST / WS_SSH_MCP_USER	dispatcher	監査実行に ssh-host MCP として渡す、任意のテストホストです

プロジェクトごとの Slack ボットトークンはシークレットディレクトリ内のファイルで、set_project_slack から参照されます。docs/slack-setup.md と docs/github-setup.md を参照してください。

ソースからのビルド

dotnet build
dotnet test tests/Workstream.UnitTests           # no Docker
dotnet test tests/Workstream.IntegrationTests    # Docker (Testcontainers, Postgres 16)
dotnet test tests/Workstream.ConcurrencyTests    # Docker

独自の Postgres に対して API を実行します。

export WORKSTREAM_DB_CONNECTION="Host=localhost;Database=workstream;Username=workstream;Password=devpass"
export WORKSTREAM_ADMIN_TOKEN="dev-admin-token"
dotnet run --project src/Workstream.Api

ドキュメント

• アーキテクチャ：モジュール、リクエストのライフサイクル、並行処理モデル
• 状態機械：状態グラフの形式と 2 種類のシードプラン
• MCP ツール：すべてのツール、エラーコード、as_agent
• オンボーディング：開発者にアクセス権を付与する方法
• GitHub のセットアップ：GitHub App、Projects V2 ボード、Webhook
• Slack のセットアップ：ボットトークン、チャンネル、インタラクティブ機能
• 監査ディスパッチ：ディスパッチャーのサイドカー
• デプロイ：本番用 compose、PgBouncer、Caddy、バックアップ
• 監査オーケストレーターの例：監査プランを最初から最後まで実行するプロンプト
• ダッシュボード：読み取り専用の Web ビューとその API
• ロードマップ：Now、Next、Later
• ビルド仕様：設計の全容

ステータス

初期段階のバージョン 0.2.1 です。既知の未対応項目：

• claim_next_attempt_for_review はスタブです。
• workstream-admin apply（宣言的なブートストラップ）はファイルを出力するだけです。
• 停滞中の作業レポートは保存されますが、Slack にはまだ投稿されません。
• 最新の master のみがサポートされています。リリースブランチはありません。

CHANGELOG.md とロードマップを参照してください。

コミュニティ

• 質問やアイデア：GitHub Discussions
• バグや機能リクエスト：イシュー
• サポート：SUPPORT.md。意思決定の方法：GOVERNANCE.md
• セキュリティに関する問題：SECURITY.md

貢献

CONTRIBUTING.mdと取り組みやすい課題をご覧ください。今後の予定はROADMAP.mdに記載されています。このリポジトリは、.NET 10 SDK と Postgres が用意された開発コンテナーまたは GitHub Codespaces で開きます。

コントリビューター

ライセンス

MIT。Copyright 2026 Ahmad Shawar.