MCPサービス

AWRは、MCP（Model Context Protocol）を通じてワークレジャーを公開します。MCPは、コーディングアシスタントやデスクトップAIクライアントのようなエージェントホストがツールを発見して呼び出せるようにする標準プロトコルです。MCPサービスは、エージェントがCLIをシェル経由で呼ぶことなく、プロジェクトの状態を読み、コンテキストをコンパイルし、証跡を記録し、作業を前に進めるための仕組みです。実行方法は2つあります。

stdio —— クライアントが直接起動するローカルプロセス。一度に1つのプロジェクト。従来からのセットアップで、引き続き利用できます。
共有HTTP —— 複数のプロジェクトと複数の独立したクライアントに対応する単一のStreamable HTTP エンドポイント。npmとPyPIの両パッケージにこの機能が含まれています。

この記事は共有HTTPサービスに焦点を当てています。これは、複数の人やエージェントが同じプロジェクトを必要とするときに実行するものです。接続後にエージェントがこれらのツールで何をするかはエージェントを、同じ操作の人間向けの対応物はAWR CLIを参照してください。

共有サービスの仕組み

サーバー上で各プロジェクトをawr initで初期化し、次のコマンドが返すproject_idとともに、正規の絶対ルートを登録します:

awr --json status

AWRは起動時とすべてのリクエストでこの識別情報を検証します。ソースファイルと各プロジェクトの.awr データベースは分離されたままです —— サービスはリポジトリをクローンせず、クライアントのファイルシステムをマウントせず、プロジェクトレジャーをマージしません。クライアントが必要なのはサービスへのネットワークアクセスであり、ローカルのAWR実行ファイルではありません。プロジェクトファイルはサーバー上で読み取り可能でなければなりません。クライアントのラップトップ上のパスがリモートで読めるようになることはありません。共有の「現在のプロジェクト」は存在しません —— すべてのプロジェクトツールは明示的な project引数を取り、任意のサーバーパスを開くツールはありません。

サービスの設定

公開リポジトリの外に、運用者所有のTOMLファイルを作成します:

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

各クライアントエントリーは、ベアラー資格情報を保持する環境変数を指名します。少なくとも32文字の、個別にランダム生成された資格情報を用意してください。write許可は読み取りアクセスを含み、read許可はプロジェクトを変更できません。資格情報のローテーションを越えてクライアントIDを安定させてください —— 会話とリクエストのバインディングはクライアントIDにアタッチされ、変更すると別のスコープになります。設定変更はサービスの再起動後にのみ有効になります。

サービスの実行

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

すべてのHTTPリクエストは認証されます。組み込みの仕組みは静的ベアラー認証です —— OAuth認可サーバーやエンタープライズIDプロバイダーではありません。リモートアクセスの場合は、認証されたデプロイ境界でHTTPSを終端し、バックエンドへの直接アクセスを制限してください。追加のアクセス制御:

Originはallowed_originsに明示的に列挙されない限り拒否されます。ネイティブクライアントは通常 Originヘッダーを省略します。
SDKはallowed_hostsをチェックし、未設定の場合はループバックホストがデフォルトになります。
サービスはOriginを検証しますが、ブラウザのCORSプリフライトは実装していないため、ブラウザフロントエンドには適切なゲートウェイが必要です。

Unixでは、SIGTERMとCtrl-Cが新規リクエストの受付を適切に停止し、アクティブなHTTP処理をドレインします。クライアントの切断やサービスの再起動がAWRの作業セッションを終了することは決してありません —— プロトコル接続と永続セッションは別の識別情報です。AWRはシステムデーモンをインストールしません —— 起動と再起動にはデプロイ環境のプロセススーパーバイザーを使ってください。ローカルの単一クライアント用途では、stdioコマンドが引き続き使えます:

awr-mcp --project /absolute/project

クライアントの接続

各MCPクライアントを、同じサービスURL（/mcpパス）を使うStreamable HTTP向けに設定し、クライアント固有のベアラー資格情報を、そのクライアントの資格情報メカニズム経由でAuthorization: Bearer …ヘッダーとして渡します。接続後、awr_projects_listを呼び出して、あなたの資格情報が許可されているプロジェクトキーを発見します。すべてのプロジェクトツールはprojectを必須とします:

{"project": "billing", "work": "INVOICE-001"}

ツール一覧

共有HTTPサービスは合計21のツールを公開します（stdioではプロジェクト一覧ツールを除く20）。これらは 3つのグループに分かれます。

作業とコンテキストのツール

日常的なCLIアクションに対応します:

ツール	機能
`awr_project_status`	現在の継続、クレーム可能な作業、待機、ブロッカー、履歴サマリー
`awr_work_ready`	診断とクレームのヒント付きの準備完了アイテム
`awr_work_get`	作業アイテムのタスク、受け入れ、依存関係、決定、証跡
`awr_context_compile`	作業アイテムまたはブランチのコンテキストパケットをコンパイル
`awr_work_transition`	作業の進行、ブロック、ブロック解除、キャンセル、再開、完了
`awr_event_append`	レジャーにイベントを追加
`awr_evidence_record`	作業と受け入れ項目に紐付けられた証跡を記録
`awr_search`	プロジェクトレジャー全体を検索

セッションと継続のツール

セッションは会話を作業単位にバインドします。ホストから安定したconversation識別子を指定してください —— HTTP接続識別子ではありません。別のプロジェクトやクライアントの下での同じ会話文字列は、別のバインディングです。

ツール	機能
`awr_session_start`	作業に紐付いたセッションを開始。任意で作業にクレームを取得
`awr_session_get`	バインディング、セッション、クレーム、チェックポイント、中断された保存を検査
`awr_session_list`	このクライアントのセッション履歴をページング
`awr_session_checkpoint`	消費したコンテキストハッシュ、ダイジェスト、次のアクション、未解決ループを永続化
`awr_session_claim`	セッションのクレームを取得または解放
`awr_session_end`	セッションを明示的に終了または中断し、クレームを解放
`awr_session_resume`	チェックポイントとクレームを継承した後続セッションを作成
`awr_session_wait`	チェックポイントを保存し、ユーザーへの永続的な質問を記録
`awr_session_reply`	記録された待機にユーザーの回答を届ける
`awr_operation_get`	リクエストIDで書き込みの記録された結果を検査
`awr_operation_recover`	証拠がある場合に、中断された書き込みのコミット済み結果を記録
`awr_source_reindex`	権威あるソースからプロジェクトのプロジェクションを更新

保留中の待機は、ホストが回答を記録するまで作業トランジションと再開をブロックします。回答はそのブロックを解除しますが、作業ステータスを変更したりホストの次のターンをスケジュールしたりはしません —— ホストがセッションを検査し、新しいコンテキストをコンパイルし、継続するか後続セッションを作成するかを決めます。

書き込み、リビジョン、不確かな結果

共有HTTPのすべての書き込みは2つのものを必要とします:

クライアントが生成した安定したrequest_id（最大256バイト）、
最後に観察したexpected_revision。

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

まったく同じリクエストIDと引数を繰り返すと、アクションを再実行せずに記録済みの結果が返るため、タイムアウト後の再試行は安全です。引数を変える場合は新しいIDが必要です。返されたproject_revisionは次の書き込みのために保存し、1を足して次のリビジョンを計算してはいけません。リクエストジャーナルとドメイン操作の両方がリビジョンを消費します。

タイムアウトや切断の後は、同じプロジェクトとリクエストIDでawr_operation_getを呼び出してください。未完了のリクエストはwrite_outcome: unknownと報告します。中断された書き込みはすでにコミット済みかもしれないため、閉じたHTTPレスポンスストリームから失敗を推測してはいけません。awr_operation_recoverは、曖昧さのない終端イベントがリクエストに紐付いている場合にのみコミット済みの結果を記録できます —— 元のツールを再呼び出しすることは決してありません。読み取りは並行して実行できます。書き込みはプロジェクトごとに直列化され、異なるプロジェクトは独立したロックを持ちます。古い書き込みはコンフリクトを返します —— 再試行前に現在の状態を読んで再検討してください。

ワークストリームの読み取り（開発中）

開発ソースは、YAMLワークストリームレジャーを使うプロジェクトについて、明示的に列挙された不変のワークストリームへの読み取り専用アクセスをクライアントに許可するレジストリversion = 2を追加します。これらは運用者所有の許可です。プロジェクトレベルのread/write許可だけでは、どの分離ワークストリームも許可されません。

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

許可されたクライアントは共有専用のawr_workstreamツールを使い、action: "capabilities"と action: "list"から始めて何を読めるかを発見します。現在の制限に注意してください。この拡張は読み取りのみを許可します —— 変更、コンテンツファイルの読み取り、Team PostgreSQL操作はありません —— そしてこの拡張を有効にしたプロジェクトは、認可された実装が利用可能になるまで、すべての書き込みを含む従来の共有ツールを拒否します。有効化と再インデックスは、現段階ではローカルの運用者アクションです。

次に読むべきもの

エージェント —— エージェントがこれらのツール上でセッション、クレーム、チェックポイントをどう使うか。
AWR CLI —— 同じドメイン操作のコマンドライン版。運用者とデバッグ向け。
トラブルシューティング —— リビジョンコンフリクト、古いソース、リカバリー。