# PlayDrop MCP로 내 AI 앱에서 게임 게시하기

AI 에이전트가 MCP로 PlayDrop에 게시하는 방법: 간단한 방식과 패키지 방식, 비공개 테스트, publish_game_version, 업데이트, 제한, 복구.

Source: https://www.playdrop.ai/ko/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 파일 하나는 [간단한 방식](https://www.playdrop.ai/ko/create/learn/html-games)을 사용합니다. SDK 기능, 등록 정보 미디어, 서버 중 하나라도 있는 경우를 포함해 그 밖의 모든 경우는 [패키지](https://www.playdrop.ai/ko/create/learn/packaging)를 사용합니다.

크리에이터의 소스 프로젝트는 직접 보관하세요. PlayDrop은 빌드 결과물만 받습니다. 소스 백업이 아니며 소스 코드를 돌려줄 수 없습니다.

## 간단한 방식: upload_game

`requestId`, 완전한 HTML(최대 10 MiB, UTF-8 기준 10,485,760바이트), 미니 카탈로그를 보내세요. 기존 게임을 업데이트하려면 `gameId`를 넘기세요. 버전은 자동으로 올라갑니다. 필드는 [간단한 HTML 게임](https://www.playdrop.ai/ko/create/learn/html-games)을 참고하세요.

## 패키지 방식: 준비, 업로드, 완료

`requestId`, `expectedCurrentVersion`, 그리고 입력 형식 하나를 넣어 `prepare_catalogue_upload`를 호출하세요.

- **폴더:** `catalogue`(catalogue.json의 내용)와 `files`. 파일마다 상대 경로가 담긴 설명자가 하나씩 있습니다. 설명자에는 인라인 `text`, 서명된 업로드 설명, 첨부 파일 연결, 또는 보관된 버전의 파일을 다시 쓰는 `reuse`가 들어갑니다.
- **로컬 ZIP 또는 .play:** 로컬에서 압축을 푼 다음 루트 카탈로그와 폴더 설명자를 보내세요. 도구 호출에 base64로 인코딩한 아카이브 바이트를 절대 넣지 마세요.
- **ChatGPT 첨부 파일:** 호스트가 확인한 ZIP 또는 .play를 실제 `download_url`, `file_id`와 함께 `archive`로 넘기세요. 압축 상태로 최대 20 MiB이며, 루트에 catalogue.json이 있어야 합니다.

서명된 업로드에서는 각 설명자가 `path`, `contentType`, `sizeBytes`, `sha256`(소문자 16진수 64자), `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 안에서 바로 그 버전을 플레이할 수 있습니다. 호스팅 서버 기능은 업로드된 버전에서만 실행되므로 이 방법으로 테스트하세요.

잘 작동하면 `gameId`, `version`, `expectedCurrentVersion`, 그리고 사용자가 골랐다면 `visibility`(`public` 또는 `unlisted`)를 넘겨 `publish_game_version`으로 바로 그 버전을 출시하세요. 테스트한 파일, 등록 정보, 검토 결과를 재사용합니다. 출시하려고 게임을 다시 업로드하지 마세요.

업로드하기 전에 로컬 빌드를 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/ko/create/learn/distribution).

## 올바른 링크 전달하기

공개 및 일부 공개 게임의 업로드 결과에는 게임의 영구 페이지인 `shareUrl`이 들어 있습니다. 이 링크를 사용자에게 전달하세요. 비공개 버전은 소유자용 해당 버전 링크인 `url`을 반환합니다. 패키지 업로드 결과는 항목별로 나열되며, 나중 항목이 실패해도 완료된 항목은 게시된 상태로 남습니다.

## 게임 업데이트하기

`list_games`와 현재 버전을 읽고, `name`을 유지하고, 전체 스냅샷을 보내세요. 빠뜨린 필드는 새 버전에서 사라지므로, 넣으려는 모든 파일과 모든 메타데이터를 포함해야 합니다. 빠뜨린 카탈로그 항목은 삭제되지 않습니다. 변경하려는 버전의 정확한 카탈로그는 조정값 상태까지 포함해 `get_game_version`으로 읽으세요.

## 제한

- 간단한 방식: 최대 10 MiB의 HTML 파일 하나.
- 패키지: 폴더 파일 설명자 512개 또는 아카이브 항목 512개(catalogue.json과 디렉터리 포함), 파일당 50 MiB, 압축 해제 기준 총 200 MiB, 카탈로그 JSON 1 MiB.
- 아카이브: 안전한 상대 경로만 허용됩니다. 중복 경로, 심볼릭 링크, 암호화된 아카이브, 분할 아카이브, ZIP64 아카이브는 거부됩니다.
- 준비된 업로드는 30분 뒤에 만료됩니다.

## 오류와 재시도

오류에는 `error`, `message`, `retryable`, `nextAction`, `docsUrl`, `documentationTopic`이 들어 있습니다. `nextAction`을 따르세요. 응답을 받지 못했다면 같은 `requestId`로 똑같은 내용을 다시 시도하세요. 내용이 바뀌면 새 ID가 필요합니다. [오류와 복구](https://www.playdrop.ai/ko/create/learn/errors)를 참고하세요.

재현할 수 있는 문제나 헷갈리는 단계는 토큰이나 서명된 URL을 빼고 `send_feedback`으로 알려 주세요.

## 관련 가이드

- [간단한 HTML 게임](https://www.playdrop.ai/ko/create/learn/html-games): upload_game으로 10 MiB 이하의 독립 실행형 HTML 파일 하나를 게시하세요. 적합한 게임, 미니 카탈로그, 공개 범위, 업데이트, 패키지로 바꿀 때를 다룹니다.
- [패키징과 .play](https://www.playdrop.ai/ko/create/learn/packaging): catalogue.json을 루트에 둔 빌드 폴더, ZIP 또는 .play를 구성하고, 등록 정보 미디어와 서버를 선언한 뒤 prepare_catalogue_upload로 업로드하세요.
- [공개 범위와 노출](https://www.playdrop.ai/ko/create/learn/distribution): PlayDrop 게임을 열 수 있는 대상을 고르고, 계정 기본값과 버전 게시가 어떻게 작동하는지, 부스트, 플레이 교환, 인스턴트, 검색이 새 플레이어를 어떻게 데려오는지 알아보세요.
- [오류와 복구](https://www.playdrop.ai/ko/create/learn/errors): PlayDrop MCP 도구가 반환하는 오류 형식, 같은 requestId로 다시 시도해야 할 때, 자주 나오는 오류 코드별 해결 방법을 알아보세요.