shift-mcp-server

---

概要

複数の AI エージェントが同じコードベースで同時に作業するための調整レイヤーです。タスクの概要と、作業対象として予定しているファイルを提示してチェックインし、稼働中の他のエージェント全員を確認して、作業が終わったらチェックアウトします。

ツール

ツール	説明
shift_check_in	ワーカーセッションを登録または更新します。ワーカー ID、調整プロトコル、稼働中の他のエージェントを返します。
shift_check_out	作業セッションを終了し、稼働中のワーカー一覧から削除します。

リソース

リソース	説明
shift://status	現在稼働中の全ワーカー、その作業概要、申告されたファイル、チェックイン時刻を確認できます。
shift://status{?workspace}	明示的に指定したワークスペースのワーカー一覧です。どちらかのツールが返す statusUri を使用します。

同じワーカー一覧は shift_check_in の応答にも含まれます。最新の subscriptions/listen ストリームでは、ワークスペースを含む URI に対して、チェックインの確定、セッションの更新、または実際の削除のたびに更新が 1 件送信されます。サーバーのデフォルトワークスペースでは、ベアエイリアスにも公開されます。どちらのプロトコル世代による変更も、同じサーバーイベントバスを通じて公開されます。このフレームワークの旧式の配信アダプターではポーリングが必要ですが、これは 2025 年プロトコル自体の制約ではありません。通知は同一プロセス内にとどまりますが、読み取りでは常に他のプロセスからの確定済み状態が反映されます。

機能リファレンス

shift_check_in _ツール

• セッションを更新するには、必須の gist と、任意の files、workspace、workerId（大文字と小文字を区別しない、ASCII の英字または数字 6 文字）が必要です。ID は大文字で保存され、返されます。
• セッション、activeWorkers、解決された workspace、修飾された statusUri を返します。更新時に省略されたファイルと元の checkedInAt は保持されます。files に空の配列を明示的に指定すると、宣言がクリアされます。
• 調整プロトコルと該当する単独ワーカー向けの通知は、構造化出力では notice として、テキストの末尾にも一度だけ配信されます。
• 未知の workerId は、理由 unknown_worker（NotFound）、復旧のヒント、現在の名簿とともに失敗します。

---

shift_check_out _ツール

• 必須の workerId（大文字と小文字を区別しない、ASCII の英字または数字 6 文字）と、任意の workspace および1文の summary を指定します。
• removed、解決された workspace、修飾された statusUri、ID／概要を返します。未知または削除済みの ID が指定された場合も成功し、removed: false を返します。ID が存在しない理由は推測せず、その名簿を示します。
• セッションが実際に存在し、削除された場合にのみ、リソース更新を公開します。

---

shift://status _リソース

• text/markdown を返します。アクティブワーカーのテーブル、または名簿が空の場合は「現在アクティブなエージェントはいません。」
• workerId は shift_check_in から取得されます。
• 修飾なしのリソースはプロセスのデフォルトのワークスペースを読み取ります。修飾されたテンプレートは、その URI にエンコードされた識別子を正確に読み取ります。
• テーブルのセルでは、バックスラッシュとパイプをエスケープし、CRLF／LF／CR をフラット化します。保存値と構造化出力は変更されません。

機能

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

調整機能：

• プロセス間で共有され、ワークスペースごとに分離されたユーザー単位の SQLite 名簿。明示的にチェックアウトされるまで、再起動後も保持されます
• 調整プロトコルはすべてのチェックイン応答に含まれるため、クライアント側の設定なしで、運用ルールをエージェントに伝えられます
• 状況把握に役立つアクティブワーカーのテーブルが、すべてのチェックインに付属します
• セッション更新ではパッチセマンティクスを採用し、指定されたフィールドのみを変更します

エージェントに適した出力：

• どちらのクライアントサーフェスでも同じデータを扱います。出力スキーマの structuredContent と format() の Markdown を提供します
• shift_check_in は型付きのエラーコントラクトを宣言するため、未知のワーカー ID は data.reason と復旧のヒントとともに返されます
• 失敗応答には現在の名簿が含まれるため、エージェントは状況を把握するために再度呼び出さなくても、同じターン内に復旧できます

はじめに

MCP クライアントの設定ファイルに以下を追加します。

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/shift-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SHIFT_WORKSPACE": "my-project"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/shift-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "SHIFT_WORKSPACE": "my-project"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "shift-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "SHIFT_WORKSPACE=my-project",
        "-v", "shift-state:/var/lib/shift-mcp-server",
        "ghcr.io/cyanheads/shift-mcp-server:latest"
      ]
    }
  }
}

共同作業するすべてのエージェントで、同じ SHIFT_WORKSPACE を設定し、同じ状態ディレクトリを使用してください。同じ OS ユーザーのネイティブプロセスは、デフォルトで ~/.local/state/shift-mcp-server を共有します。明示的に指定した識別子は不透明で、完全一致で扱われます。my-project と /path/my-project は別々の名前空間です。名前付きボリュームを使う代わりに、ネイティブの状態ディレクトリをコンテナにバインドマウントすれば、ネイティブクライアントと Docker クライアントでロスターを共有できます。

SHIFT_WORKSPACE が設定されていない場合、どちらのトランスポートでも、Git の外では起動時の作業ディレクトリ、Git の内では親となる Git ワークツリーのルートの実パスが使用されます。空のツールのワークスペースセレクターもこのデフォルトを使用します。空でない識別子は完全一致で扱われます。サブディレクトリまたはシンボリックリンクから起動しても、同じルートに集約されます。デスクトップクライアントやインストールバッジは、プロジェクト外から起動する場合があります。インストール後に SHIFT_WORKSPACE を設定するか、すべてのツール呼び出しで workspace を渡してください。Desktop バンドルでは、ワークスペースの入力を求められます。Codex プラグインは環境変数の SHIFT_WORKSPACE と SHIFT_STATE_DIR を引き継ぎます。Claude プラグインには、これに対応する設定オプションがあります。

共有 HTTP プロセスでは、起動時のディレクトリがデフォルトとして使用されます。多重化されたクライアントは、プロジェクトの明示的な workspace を渡す必要があります。

SHIFT_WORKSPACE=my-project MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.3 以降（または Node.js v24 以降）。
• API キー、アカウント、外部サービスは不要です。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/shift-mcp-server.git

2. ディレクトリに移動します。

cd shift-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env if you need to override a framework default

設定

ロスターは、フレームワークの STORAGE_PROVIDER_TYPE とは独立して SQLite を使用します。状態はチェックアウトまで保持されます。再起動しても、放棄されたセッションはクリアされません。TTL や自動削除の仕組みはありません。ワークスペース名とワーカー ID は調整用のセレクターであり、認証境界ではありません。

WAL と BEGIN IMMEDIATE により、変更、ID の割り当て、返されるロスターのスナップショットがシリアル化されます。起動時には、SQLite のロック競合に対して、最大 3 秒の期限内で再試行します。変更処理がビジーの場合も、最大 3 秒間待機します。ストレージがビジー、破損、または書き込み不可の場合は、インメモリへのフォールバックなしでエラーが明示されます。共有状態ディレクトリには、SQLite のロックをサポートするローカルファイルシステムを使用してください。

変数	説明	デフォルト
SHIFT_WORKSPACE	ツールで上書き可能な、不透明なデフォルトのワークスペース名前空間です。	実際の Git ルートまたは起動時の作業ディレクトリ
SHIFT_STATE_DIR	roster.sqlite を含む、共有可能なローカル書き込みディレクトリです。	~/.local/state/shift-mcp-server
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト名です。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションの処理方式です。auto、stateful、stateless を指定します。セッションを必要とするハンドラーがないため、サーバーは createApp() で stateless を宣言します。この変数を設定すると、その値で上書きされます。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（RFC 5424）。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false

任意の上書き設定の一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行します。

  bun run rebuild
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行します。

  bun run devcheck   # Lint, format, typecheck, security, packaging
  bun run test       # Vitest suites: unit, smoke, integration, fuzz
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t shift-mcp-server .
docker run --rm -p 127.0.0.1:3010:3010 -e SHIFT_WORKSPACE=my-project -v shift-state:/var/lib/shift-mcp-server shift-mcp-server

Dockerfile のデフォルト設定は、HTTP トランスポート、ステートレスセッションモード、/var/log/shift-mcp-server へのログ出力、/var/lib/shift-mcp-server への名簿状態の保存です。連携するすべてのコンテナで、同じ書き込み可能なボリュームとワークスペースを再利用してください。ホストのバインドマウントは、イメージの bun ユーザーが書き込み可能である必要があります。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイント — 定義、ストレージのセットアップ／終了処理、サーバー通知。
src/config	ストレージディレクトリとデフォルトのワークスペース設定。
src/mcp-server/tools	ツール定義（check-in.tool.ts、check-out.tool.ts）。
src/mcp-server/resources	静的なデフォルト名簿と、ワークスペースを指定するテンプレート。
src/services/worker-store	トランザクション対応の SQLite ワーカーストアとテーブルの書式設定。
tests/	src/ に対応する単体テスト、スモークテスト、統合テスト、ファズテストの各スイート。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md/AGENTS.md を参照してください。概要は次のとおりです。

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジックで try/catch を使わないでください。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用してください。
• 新しいツールとリソースは src/index.ts に登録してください。
• format() は出力スキーマのすべてのフィールドをレンダリングする必要があります。両方のクライアントインターフェースで同じデータが扱われます。

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。