Coordination MCP

Coordination MCP は、複数の AI 参加者が利用する軽量な共有作業状態サービスです。MCP を通じて永続化された Ticket、不変の Update、テキスト型 Artifact を提供し、ChatGPT、ローカル AI、コーディングエージェントが同じ Scope 内で作業コンテキストを共有、増分同期、復元できるようにします。

V0.1 でできること

• Ticket は、作業の現在の状態を保存します。title、status、artifact_ids、meta を更新できます。

• Update は、発生済みの事実、発見、決定、結果を保存し、Scope ごとに単調増加する seq を割り当てます。

• Artifact は、Markdown、ログ、長文ドキュメントなど、不変の共有テキスト内容を保存します。

• すべてのオブジェクトには、サーバー側でグローバルに一意な ID が割り当てられます。

• Ticket と Artifact の参照は、同じ Scope に属している必要があります。

V0.1 では、authentication、workflow engine、queue acknowledgement、relationship graph、wake-up notification、binary artifact のサポートは含まれません。

推奨される使用パターン

• Ticket は、進行中の作業項目の現在の可変状態を表します。イベントログではありません。

• Update は、作業タイムラインで発生した不変のイベント（request、finding、decision、result など）を表します。

• Artifact は、不変の長文テキスト内容を表します。長いレビュー、仕様、ログは Artifact に入れ、Update には詰め込まず、artifact_ids で関連付けてください。

• created_by には、実行やエージェントをまたいで安定する participant label（例：chatgpt、pi-local-agent）を使用してください。毎回ランダムな名前や変動する名前を使うのは避けてください。タイムラインの帰属を明確に保つためです。このフィールドは provenance のためのものであり、authentication ではありません。

典型的なレビューループは次のとおりです。ローカル AI が Update でレビューを依頼 → ChatGPT が完全なレビューを Artifact として保存し、Update で要約と artifact_ids を返す → ローカル AI がコードを修正し、結果の Update を追加 → ChatGPT が再度レビューする。

クイックスタート

要件：Node.js 24+。

cd /path/to/coordination-mcp
npm install
npm run build
node dist/main.js

サービスはデフォルトで以下をリッスンします：

http://127.0.0.1:3000/mcp

開発版を直接実行することもできます：

npm run dev

サービスは 127.0.0.1 のみにバインドします。リモートの ChatGPT にアクセスさせる必要がある場合は、安全なトンネル経由で MCP endpoint を公開してください。Node.js サービスを直接インターネットに公開しないでください。V0.1 には現在 authentication はありません。

設定

設定の優先順位は低いものから高いものの順です：

代码默认值 < config/default.yml < ~/.coordination-mcp/config.yml < --profile < 环境变量

ユーザー設定

ユーザー設定を作成します：

mkdir -p ~/.coordination-mcp
$EDITOR ~/.coordination-mcp/config.yml

例：

port: 43721
allowedHosts:
  - 127.0.0.1
  - localhost
# dataDirectory: /absolute/path/to/coordination-data

~/.coordination-mcp/config.yml はオプションであり、サービスにより自動生成されません。dataDirectory が設定されていない場合のデフォルトは次のとおりです：

~/.coordination-mcp/data

カスタムの dataDirectory は絶対パスで指定することをお勧めします。相対パスは、プロセス起動時の current working directory を基準に解決されます。

Profile

Profile のパスは current working directory からの相対パスとして解決されます。指定した場合、ファイルが存在する必要があります：

node dist/main.js --profile config/local.yml
node dist/main.js --profile=/absolute/path/to/local.yml

Profile は自身が宣言したフィールドのみを上書きします。宣言していないフィールドは、前段の設定を引き継ぎます。

環境変数

PORT=43721 \
COORDINATION_DATA_DIR=/absolute/path/to/data \
COORDINATION_ALLOWED_HOSTS=127.0.0.1,localhost \
node dist/main.js

対応している環境変数：

設定ファイルはサービスの起動時にのみ読み込まれます。変更後は main.js を再起動する必要があります。

MCP ツール

サービスは POST /mcp で次の 8 つのツールを提供します：

MCP 初期化の例

curl -N \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'mcp-protocol-version: 2025-03-26' \
  -X POST http://127.0.0.1:3000/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "manual-client",
        "version": "0.1.0"
      }
    }
  }'

Ticket 作成の例

tools/call のパラメータの例：

{
  "name": "create_ticket",
  "arguments": {
    "scope": "coordination-mcp",
    "title": "Review the MCP integration",
    "created_by": "local-ai",
    "status": "open",
    "meta": {
      "priority": "high"
    }
  }
}

データ保存

デフォルトのデータディレクトリはオンデマンドで作成されます。サービスの起動や読み取り操作だけでは、データディレクトリは作成されません。最初のTicket、Update、Artifact を書き込むと、次のような構造が作成されます：

~/.coordination-mcp/
├── config.yml                 # 可选用户配置
└── data/
    └── scopes/
        └── <base64url-scope>/
            ├── tickets/
            │   └── T-*.json
            ├── updates.jsonl
            └── artifacts/
                └── A-*.json

• Ticket と Artifact は、独立した pretty-printed な JSON ファイルとして保存されます。

• 1 つの Scope の Updates は、append-only の JSONL ファイルで保存されます。読み取り時は、最後に改行されておらず解析できない壊れた末尾レコードは無視されますが、完全に改行されているレコード内の JSON の破損は隠されません。

• 新しいディレクトリは 0700、新しいデータファイルは 0600 で作成されます。

• V0.1 では、単一プロセス内の Scope ミューテックスを使用します。プロセスをまたぐロックや、分散配置には対応していません。

開発と検証

npm test
npm run check
npm run build

プロジェクトドキュメント

• Domain context

• Accepted ADRs

• Archived V0.1 protocol

• Archived implementation architecture