# 用 PlayDrop MCP 從你的 AI App 發布遊戲

AI 代理如何透過 MCP 發布到 PlayDrop：簡易方式與套件方式、私人測試、publish_game_version、更新、限制與復原。

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

PlayDrop 的 MCP 伺服器讓 AI App 能將遊戲發布到其使用者的 PlayDrop 帳號，並傳回一個在更新後依然有效的連結。本指南說明操作順序。每個步驟都附有詳細指南的連結。

## 開始製作之前

1. 在撰寫程式碼之前，呼叫 `get_documentation({topic:"index"})`，閱讀遊戲會用到的功能指南。從一開始就規劃全螢幕版面、存檔和操控，可以避免之後重寫遊戲。若需要確切的方法簽章，請閱讀主題 `sdk-types`、`server-sdk-types` 和 `shared-types`。
2. 呼叫 `list_games`。如果遊戲已經存在，你要更新它並保留它的 `name`，讓它保有原本的連結和玩家。
3. 選擇方式。不使用 PlayDrop SDK 的單一獨立 HTML 檔案採用[簡易方式](https://www.playdrop.ai/zh-hant/create/learn/html-games)。其他所有情況，包括任何 SDK 功能、上架媒體或伺服器，都使用[套件](https://www.playdrop.ai/zh-hant/create/learn/packaging)。

請自行保管創作者的原始專案。PlayDrop 只接收建置後的輸出：它不是原始碼備份，也無法傳回原始碼。

## 簡易方式：upload_game

傳送 `requestId`、完整的 HTML（最多 10 MiB，即 10,485,760 個 UTF-8 位元組）和迷你目錄。傳入 `gameId` 可更新現有遊戲。版本會自動遞增。欄位說明請參閱[簡易 HTML 遊戲](https://www.playdrop.ai/zh-hant/create/learn/html-games)。

## 套件方式：準備、上傳、完成

呼叫 `prepare_catalogue_upload`，附上 `requestId`、`expectedCurrentVersion` 和一種輸入形式：

- **資料夾：** `catalogue`（catalogue.json 的內容）加上 `files`，每個檔案一個描述項，附上它的相對路徑。描述項可攜帶內嵌的 `text`、簽名上傳說明、附件綁定，或對保留版本中檔案的 `reuse`。
- **本機 ZIP 或 .play：** 在本機解壓縮，然後傳送根目錄中 catalogue.json 的目錄內容，以及資料夾的檔案描述項。絕不要把 base64 編碼的壓縮檔位元組放進工具呼叫。
- **ChatGPT 附件：** 將主機端解析的 ZIP 或 .play 作為 `archive` 傳入，附上它真正的 `download_url` 和 `file_id`。壓縮後最多 20 MiB，且根目錄需要有 catalogue.json。

簽名上傳時，每個描述項都要提供 `path`、`contentType`、`sizeBytes`、`sha256`（64 個小寫十六進位字元）和 `md5Base64`，這些值都要在本機根據確切的位元組計算。將這些位元組連同每個傳回的標頭 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`，就能在 PlayDrop 中搭配真正的 SDK 主機端遊玩該確切版本。託管伺服器功能只會在已上傳的版本上執行，所以請用這種方式測試。

運作正常後，用 `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/zh-hant/create/learn/distribution)。

## 交回正確的連結

公開與不公開遊戲的回執包含 `shareUrl`，也就是遊戲的長期頁面：請把這個連結交給你的使用者。私人版本則傳回 `url`，也就是給擁有者的確切版本連結。套件回執會列出每個項目；即使後面的項目失敗，已完成的項目仍會維持發布狀態。

## 更新遊戲

讀取 `list_games` 和目前版本，保留 `name`，並傳送完整快照：所有預計的檔案和所有預計的中繼資料，因為省略的欄位不會出現在新版本中。省略的目錄項目絕不會被刪除。使用 `get_game_version` 讀取你要變更的版本的確切目錄，包括它的可調數值（Tweaks）狀態。

## 限制

- 簡易方式：一個最多 10 MiB 的 HTML 檔案。
- 套件：512 個資料夾檔案描述項或 512 個壓縮檔項目（包括 catalogue.json 和資料夾）、每個檔案 50 MiB、解壓縮後總計 200 MiB，以及 1 MiB 的目錄 JSON。
- 壓縮檔：只接受安全的相對路徑；重複路徑、符號連結、加密、分割和 ZIP64 壓縮檔都會被拒絕。
- 準備好的上傳會在 30 分鐘後過期。

## 錯誤與重試

錯誤包含 `error`、`message`、`retryable`、`nextAction`、`docsUrl` 和 `documentationTopic`。請遵循 `nextAction`。回應遺失後，以相同的 `requestId` 重試完全相同的內容；內容變更則需要新的 ID。請參閱[錯誤與復原](https://www.playdrop.ai/zh-hant/create/learn/errors)。

使用 `send_feedback` 回報可重現的問題或令人困惑的步驟，內容不要包含權杖或簽名網址。

## 相關指南

- [簡易 HTML 遊戲](https://www.playdrop.ai/zh-hant/create/learn/html-games): 用 upload_game 發布一個最多 10 MiB 的獨立 HTML 檔案：適用範圍、迷你目錄、可見性、更新，以及何時改用套件。
- [打包與 .play](https://www.playdrop.ai/zh-hant/create/learn/packaging): 安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。
- [可見性與觸及](https://www.playdrop.ai/zh-hant/create/learn/distribution): 選擇誰能開啟 PlayDrop 遊戲，了解帳號預設值與版本發布如何運作，以及 Boost、互玩、即玩和搜尋如何帶來新玩家。
- [錯誤與復原](https://www.playdrop.ai/zh-hant/create/learn/errors): PlayDrop MCP 工具傳回的錯誤格式、何時以相同的 requestId 重試，以及各種常見錯誤代碼的修正方式。