# PlayDrop MCP で AI アプリからゲームを公開する

AI エージェントが MCP で PlayDrop に公開する方法：シンプルな方法とパッケージの方法、非公開テスト、publish_game_version、更新、制限、復旧。

Source: https://www.playdrop.ai/ja/create/learn/mcp-publishing

PlayDrop の MCP サーバーを使うと、AI アプリはユーザーの PlayDrop アカウントにゲームを公開し、更新しても使い続けられるリンクを返せます。このガイドでは作業の順番を説明します。各ステップには、詳細を説明したガイドへのリンクがあります。

## ビルドを始める前に

1. コードを書く前に `get_documentation({topic:"index"})` を呼び出し、ゲームで使う機能のガイドを読みます。全画面レイアウト、セーブ、操作方法を最初から計画しておけば、あとでゲームを書き直さずに済みます。メソッドの正確なシグネチャは、トピック `sdk-types`、`server-sdk-types`、`shared-types` で確認してください。
2. `list_games` を呼び出します。ゲームがすでにある場合は、それを更新して `name` を維持します。そうすれば、リンクもプレイヤーもそのまま引き継がれます。
3. 方法を選びます。PlayDrop SDK を使わない自己完結した HTML ファイル1つなら、[シンプルな方法](https://www.playdrop.ai/ja/create/learn/html-games)を使います。SDK の機能、掲載メディア、サーバーを含むそれ以外のすべては、[パッケージ](https://www.playdrop.ai/ja/create/learn/packaging)を使います。

クリエイターのソースプロジェクトは、AI アプリ側で保管してください。PlayDrop が受け取るのはビルド結果だけです。ソースのバックアップではないので、ソースコードを返すことはできません。

## シンプルな方法：upload_game

`requestId`、完全な HTML（最大 10 MiB、10,485,760 UTF-8 バイト）、ミニカタログを送信します。既存のゲームを更新するには `gameId` を渡します。バージョン番号は自動で上がります。フィールドについては[シンプルな HTML ゲーム](https://www.playdrop.ai/ja/create/learn/html-games)をご覧ください。

## パッケージの方法：準備、アップロード、完了

`requestId`、`expectedCurrentVersion` と、次のいずれか1つの入力形式を指定して `prepare_catalogue_upload` を呼び出します。

- **フォルダー：** `catalogue`（catalogue.json の内容）と `files`。`files` には、ファイルごとに相対パス付きの記述子を1つ入れます。記述子には、インラインの `text`、署名付きアップロードの情報、添付ファイルの割り当て、保持されているバージョンのファイルの `reuse` のいずれかを含めます。
- **ローカルの ZIP または .play：** ローカルで展開してから、ルートのカタログとフォルダーの記述子を送信します。アーカイブのバイトを base64 にしてツール呼び出しに入れるのは絶対にやめてください。
- **ChatGPT の添付ファイル：** ホストが解決した ZIP または .play を、本物の `download_url` と `file_id` 付きで `archive` として渡します。圧縮後で最大 20 MiB まで使え、catalogue.json をルートに置く必要があります。

署名付きアップロードでは、各記述子に `path`、`contentType`、`sizeBytes`、`sha256`（64文字の小文字の16進数）、`md5Base64` を指定します。これらはローカルで、実際のバイトから正確に計算してください。返された各 URL に、返されたすべてのヘッダーを付けてそのバイトを PUT し、同じ `requestId` で `complete_catalogue_upload` を呼び出します。

ChatGPT では、フォルダーのファイルを、位置で割り当てた添付ファイルから取得できます。

```
attachments: [htmlFile, iconFile]
files: [{path:"index.html", attachmentIndex:0}, {path:"listing/icon.png", attachmentIndex:1, role:"LISTING", app:"my-game"}]
```

すべてのアプリには、宣言した `version`、公開範囲（リクエストかアプリに指定）、そして名前をキーとする `expectedCurrentVersion` のエントリーが必要です。新規作成なら `null`、更新なら `list_games` から取得した現在の公開バージョンです。古い値は拒否されるので、別のアップロードを誤って上書きすることはありません。

## 非公開でテストしてから公開する

ゲームが SDK やサーバーを使う場合や、ユーザーがまず試したい場合は、`visibility: "private"` でアップロードします。アップロード結果の `url` を開くと、本物の SDK ホストを備えた PlayDrop の中で、そのバージョンそのものを遊べます。ホスト型サーバーの機能はアップロード済みのバージョンでしか動かないので、この方法でテストしてください。

うまく動いたら、`publish_game_version` でそのバージョンをそのまま公開します。`gameId`、`version`、`expectedCurrentVersion` と、ユーザーが選んでいれば `visibility`（`public` または `unlisted`）を渡してください。テスト済みのファイル、掲載情報、審査がそのまま再利用されます。公開するためにゲームをもう一度アップロードしないでください。

アップロード前にローカルのビルドを PlayDrop のフレームで試すには、ローカルサーバーを動かしているマシンの通常のブラウザで `https://www.playdrop.ai/@<username>/<slug>/dev?url=<URL-encoded local address>` を開きます。

## 誰が遊べるかを選ぶ

`visibility` には `public`、`unlisted`、`private` を指定できます。新しいゲームで選択がない場合は、クリエイターの保存済みの設定を使います。`upload_game` では公開範囲を省略するとこの設定が適用され、`get_account` では `publishing.defaultVisibility` として確認できます。更新では、ユーザーが変更しない限り、`list_games` のゲームの `gameVisibility` を維持してください。`upload_game` では公開範囲を省略するとそうなり、パッケージではその値を明示します。限定公開とは、リンクを知っている人なら誰でも遊べるということで、フレンドリストではありません。ユーザーの意図より広く公開することは絶対に避けてください。詳しくは[誰が遊べるか](https://www.playdrop.ai/ja/create/learn/distribution)をご覧ください。

## 正しいリンクを返す

公開と限定公開のゲームのアップロード結果には、ゲームの恒久的なページである `shareUrl` が含まれます。ユーザーにはこちらを渡してください。非公開バージョンでは、オーナー向けのそのバージョン専用リンクである `url` が返されます。パッケージのアップロード結果には項目ごとの結果が並びます。あとの項目が失敗しても、完了した項目は公開されたまま残ります。

## ゲームを更新する

`list_games` と現在のバージョンを読み取り、`name` を維持して、完全なスナップショットを送信します。省略したフィールドは新しいバージョンに含まれないため、意図したすべてのファイルとメタデータを含めてください。省略したカタログ項目が削除されることはありません。変更するバージョンの正確なカタログは、調整値（Tweaks）の状態も含めて `get_game_version` で読み取れます。

## 制限

- シンプルな方法：最大 10 MiB の HTML ファイル1つ。
- パッケージ：フォルダーのファイル記述子512個またはアーカイブのエントリー512個（catalogue.json とディレクトリを含む）、1ファイルあたり 50 MiB、展開後の合計 200 MiB、カタログの JSON 1 MiB。
- アーカイブ：安全な相対パスのみ。パスの重複、シンボリックリンク、暗号化、分割、ZIP64 のアーカイブは拒否されます。
- 準備したアップロードは30分で期限切れになります。

## エラーと再試行

エラーには `error`、`message`、`retryable`、`nextAction`、`docsUrl`、`documentationTopic` が含まれます。`nextAction` に従ってください。レスポンスが失われた場合は、同じ `requestId` でまったく同じ内容を再試行します。内容を変えた場合は新しい ID が必要です。[エラーと復旧](https://www.playdrop.ai/ja/create/learn/errors)をご覧ください。

再現できる問題やわかりにくい手順は、`send_feedback` で報告してください。トークンや署名付き URL は含めないでください。

## 関連ガイド

- [シンプルな HTML ゲーム](https://www.playdrop.ai/ja/create/learn/html-games): upload_game で最大 10 MiB の自己完結した HTML ファイル1つを公開します。対象となるゲーム、ミニカタログ、公開範囲、更新、パッケージに切り替えるタイミングを説明します。
- [パッケージ化と .play](https://www.playdrop.ai/ja/create/learn/packaging): ルートに catalogue.json を置いたビルド済みのフォルダー、ZIP、.play を用意し、掲載メディアとサーバーを宣言して、prepare_catalogue_upload でアップロードします。
- [公開範囲と集客](https://www.playdrop.ai/ja/create/learn/distribution): PlayDrop のゲームを誰が開けるかの選び方、アカウントの既定設定とバージョン公開のしくみ、ブースト、プレイ交換、インスタント、検索で新しいプレイヤーを集める方法を説明します。
- [エラーと復旧](https://www.playdrop.ai/ja/create/learn/errors): PlayDrop の MCP ツールが返すエラーの形式、同じ requestId で再試行すべきとき、よくあるエラーコードごとの直し方を説明します。