MCP経由でAIにアプリの生成・プレビュー・公開を任せるとき、各ツールが成功を返すだけでは、意図した版が公開されたとは限りません。
下書きAを検証している間にAIが下書きBを保存し、その後「最新の下書き」を公開したら、公開されたBは未検証です。この記事では、この取り違えを避けるAPIの設計案を整理します。以下のツール名・データ形式は説明用で、Koi Launchの現行API仕様ではありません。
1. draftIdだけでなくrevisionを持つ
下書きの識別子と、内容の版は別に扱います。
| 値 | 表すもの | 変わるタイミング |
|---|---|---|
| appId | アプリそのもの | アプリを作成したとき |
| revision | 検証対象となる内容の版 | 内容を変更したとき |
| checkId | ある版に対する検証実行 | 検証を開始したとき |
| releaseId | 公開された版 | 公開が成立したとき |
revisionは単なる表示用の数字ではなく、サーバーが管理する不変のスナップショットに結び付けます。同じrevisionなのに取得するHTMLが変わるなら、検証結果と公開物を対応させられません。
たとえば検証の結果には、合否だけでなく対象の版を返します。
{
"checkId": "check-123",
"appId": "app-42",
"revision": "rev-7",
"status": "completed",
"passed": true
}
2. 「まだ実行中」を成功・失敗と分ける
非同期の検証では、処理を受け付けたことと検証が完了したことは別です。
- queued:実行待ち
- running:実行中
- completed:完了。ここでpassedと検出事項を読む
- failed:検証基盤の処理に失敗。アプリの不合格とは分ける
検証基盤がタイムアウトしたとき、「アプリに問題がない」とも「アプリが壊れている」とも判断できません。再実行できるか、何を確認すべきかを結果に含めます。
また、statusがrunningのままなら公開条件は満たしていません。AIが待ち続けないよう、状態取得の間隔、上限時間、打ち切り時の説明もクライアント側で決めます。
3. 公開時にサーバー側で整合性を確認する
公開要求では、公開したい版と検証実行を指定します。
{
"appId": "app-42",
"revision": "rev-7",
"checkId": "check-123",
"idempotencyKey": "publish-request-abc"
}
サーバーは少なくとも次を検証します。
- 呼び出し元に、そのアプリを公開する権限がある。
- checkIdが指すappIdとrevisionが公開要求に一致する。
- 検証が完了し、公開に必要な条件を満たしている。
- 実際に配信する内容が、そのrevisionのスナップショットである。
「現在の最新版だけ公開可」という運用なら、最新版との一致確認も同じトランザクションや条件付き更新で行います。事前確認の直後に別の更新が入り得るためです。逆に、過去の検証済み版を明示して公開できる設計もあります。どちらを許すかはAPIの契約として決めます。
AIへの指示文に「必ずチェックしてから公開」と書くことは補助になりますが、この整合性検証の代わりにはなりません。
4. 応答が届かなかった場合を設計する
公開がサーバーで成立した直後に通信が切れると、クライアントには結果が分かりません。同じ要求を再送して、別のリリースが増える可能性があります。
設計案として、同じ呼び出し元・同じ操作のidempotencyKeyを保存し、同じ内容の再要求には同じreleaseIdを返します。キーだけ同じで要求内容が違う場合は拒否します。キーの適用範囲、有効期間、処理中の重複要求をどう扱うかも決める必要があります。
MCPのツール名を分けただけで、この性質が自動で付くわけではありません。公開先のサーバーに実装する責務です。
5. 最低限、試したい失敗シナリオ
| シナリオ | 期待する結果 |
|---|---|
| rev-7を検証後、rev-8を同じcheckIdで公開 | 対象不一致として拒否 |
| runningのcheckIdで公開 | 未完了として拒否 |
| 他ユーザーのappId・checkIdを指定 | サーバー側で拒否 |
| 同じ公開要求を再送 | 契約で決めた期間内は同じreleaseId |
| 検証基盤だけがタイムアウト | アプリの合否と区別して説明 |
これらは設計上のテストケースであり、本記事で特定製品に対して実測した結果ではありません。UIのスクリーンショットだけでなく、公開されたrevisionと検証対象が一致するかを、APIの結果でも確認します。
MCP仕様との関係
MCPのTools仕様には、入力スキーマ、構造化した結果、出力スキーマ、ツール実行エラーなどの仕組みがあります。それを使って状態を明示しつつ、認可や公開処理の整合性はサービス側で実装します。プロトコルがあることと、業務上の条件が保証されることは別の責務です。
参照した仕様の版を固定しておきます。
開発しているもの
私はChatGPTやClaudeで小さなアプリを作り、公開・共有できるKoi Launchを開発しています。会話の中で生成と検証を繰り返せる仕組みに取り組む立場から、公開系ツールの設計を整理しました。