# Publikuj gry ze swojej aplikacji AI przez MCP PlayDrop

Jak agenci AI publikują w PlayDrop przez MCP: prosta ścieżka i pakiety, prywatne testy, publish_game_version, aktualizacje, limity i odzyskiwanie po błędach.

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

Serwer MCP PlayDrop pozwala aplikacji AI opublikować grę na koncie PlayDrop jej użytkownika i zwrócić link, który działa także po aktualizacjach. Ten poradnik opisuje kolejność kroków. Każdy krok odsyła do poradnika ze szczegółami.

## Zanim zaczniesz budować

1. Wywołaj `get_documentation({topic:"index"})` i przeczytaj poradniki o funkcjach, których gra będzie używać, zanim napiszesz kod. Zaplanowanie od początku układu pełnoekranowego, zapisów i sterowania pozwala uniknąć przepisywania gry później. Dokładne sygnatury metod znajdziesz w tematach `sdk-types`, `server-sdk-types` i `shared-types`.
2. Wywołaj `list_games`. Jeśli gra już istnieje, zaktualizujesz ją i zachowasz jej `name`, aby zachowała swój link i graczy.
3. Wybierz ścieżkę. Jeden samodzielny plik HTML bez PlayDrop SDK korzysta z [prostej ścieżki](https://www.playdrop.ai/pl/create/learn/html-games). Wszystko inne, w tym każda funkcja SDK, multimedia strony gry lub serwer, wymaga [pakietu](https://www.playdrop.ai/pl/create/learn/packaging).

Projekt źródłowy twórcy przechowuj u siebie. PlayDrop otrzymuje tylko zbudowaną grę: nie jest kopią zapasową źródeł i nie może zwrócić kodu źródłowego.

## Prosta ścieżka: upload_game

Wyślij `requestId`, kompletny HTML (najwyżej 10 MiB, czyli 10 485 760 bajtów UTF-8) i mini katalog. Przekaż `gameId`, aby zaktualizować istniejącą grę. Numery wersji rosną automatycznie. Pola opisuje poradnik [proste gry HTML](https://www.playdrop.ai/pl/create/learn/html-games).

## Ścieżka pakietu: przygotuj, prześlij, dokończ

Wywołaj `prepare_catalogue_upload` z `requestId`, `expectedCurrentVersion` i jedną formą danych wejściowych:

- **Folder:** `catalogue` (zawartość catalogue.json) oraz `files`, po jednym deskryptorze na plik z jego ścieżką względną. Deskryptor zawiera wbudowany `text`, opis podpisanego przesyłania, powiązanie z załącznikiem albo `reuse` pliku z zachowanej wersji.
- **Lokalny ZIP lub .play:** rozpakuj go lokalnie, a potem wyślij zawartość catalogue.json z katalogu głównego i deskryptory plików jak dla folderu. Nigdy nie umieszczaj bajtów archiwum w base64 w wywołaniu narzędzia.
- **Załącznik w ChatGPT:** przekaż jako `archive` plik ZIP lub .play rozwiązany przez hosta, z jego prawdziwymi `download_url` i `file_id`. Może mieć do 20 MiB po kompresji i wymaga catalogue.json w katalogu głównym.

Przy podpisanym przesyłaniu każdy deskryptor podaje `path`, `contentType`, `sizeBytes`, `sha256` (64 małe znaki szesnastkowe) i `md5Base64`, obliczone lokalnie z dokładnych bajtów. Wyślij te bajty metodą PUT na każdy zwrócony adres URL ze wszystkimi zwróconymi nagłówkami, a potem wywołaj `complete_catalogue_upload` z tym samym `requestId`.

W ChatGPT pliki folderu mogą pochodzić z załączników powiązanych według pozycji:

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

Każda aplikacja wymaga zadeklarowanej `version`, widoczności (w żądaniu lub w aplikacji) i wpisu w `expectedCurrentVersion` z kluczem równym jej nazwie: `null`, aby ją utworzyć, albo bieżącej opublikowanej wersji z `list_games`, aby ją zaktualizować. Nieaktualna wartość zostaje odrzucona, więc inne przesłanie nigdy nie zostanie przypadkiem nadpisane.

## Przetestuj prywatnie, a potem wydaj

Prześlij grę z `visibility: "private"`, gdy używa SDK lub serwera albo gdy twój użytkownik chce ją najpierw wypróbować. Otwórz `url` z potwierdzenia przesłania, aby zagrać w dokładnie tę wersję w PlayDrop z prawdziwym hostem SDK. Funkcje hostowanego serwera działają tylko w przesłanych wersjach, więc testuj je w ten sposób.

Gdy wszystko działa, wydaj dokładnie tę wersję przez `publish_game_version`, przekazując `gameId`, `version`, `expectedCurrentVersion` oraz, jeśli twój użytkownik ją wybrał, `visibility` (`public` lub `unlisted`). Wywołanie używa ponownie przetestowanych plików, strony gry i przeglądu. Nie przesyłaj gry ponownie, aby ją wydać.

Aby przed przesłaniem wypróbować lokalną kompilację w ramce PlayDrop, otwórz `https://www.playdrop.ai/@<username>/<slug>/dev?url=<URL-encoded local address>` w zwykłej przeglądarce na komputerze, na którym działa lokalny serwer.

## Wybierz, kto może grać

`visibility` przyjmuje `public`, `unlisted` i `private`. Dla nowej gry bez wybranej widoczności użyj zapisanego ustawienia twórcy: `upload_game` stosuje je, gdy pominiesz widoczność, a `get_account` pokazuje je jako `publishing.defaultVisibility`. Przy aktualizacji zachowaj `gameVisibility` gry z `list_games`, chyba że twój użytkownik ją zmieni; `upload_game` robi to, gdy pominiesz widoczność, a pakiet podaje ją wprost. Niepubliczna oznacza, że grać może każdy, kto ma link; to nie jest lista znajomych. Nigdy nie udostępniaj gry szerzej, niż zamierzał twój użytkownik. Szczegóły: [kto może grać](https://www.playdrop.ai/pl/create/learn/distribution).

## Przekaż właściwy link

Potwierdzenia przesłania gier publicznych i niepublicznych zawierają `shareUrl`, stałą stronę gry: to ten link przekaż swojemu użytkownikowi. Wersja prywatna zwraca `url`, link właściciela do dokładnie tej wersji. Potwierdzenia przesłania pakietu wymieniają każdy element; ukończone elementy pozostają opublikowane, nawet jeśli późniejszy element się nie powiedzie.

## Zaktualizuj grę

Odczytaj `list_games` i bieżącą wersję, zachowaj `name` i wyślij pełną migawkę: każdy zamierzony plik i wszystkie zamierzone metadane, ponieważ pominiętych pól nie ma w nowej wersji. Pominięte elementy katalogu nigdy nie są usuwane. Użyj `get_game_version`, aby odczytać dokładny katalog zmienianej wersji, w tym stan jej dostrojeń (Tweaks).

## Limity

- Prosta ścieżka: jeden plik HTML o rozmiarze najwyżej 10 MiB.
- Pakiet: 512 deskryptorów plików folderu lub 512 wpisów archiwum (wliczając catalogue.json i katalogi), 50 MiB na plik, łącznie 200 MiB po rozpakowaniu i 1 MiB JSON katalogu.
- Archiwa: tylko bezpieczne ścieżki względne; zduplikowane ścieżki, dowiązania symboliczne oraz archiwa szyfrowane, wieloczęściowe i ZIP64 są odrzucane.
- Przygotowane przesłania wygasają po 30 minutach.

## Błędy i ponowienia

Błędy zawierają `error`, `message`, `retryable`, `nextAction`, `docsUrl` i `documentationTopic`. Postępuj zgodnie z `nextAction`. Po utraconej odpowiedzi ponów identyczną treść z tym samym `requestId`; zmieniona treść wymaga nowego. Zobacz [błędy i odzyskiwanie](https://www.playdrop.ai/pl/create/learn/errors).

Użyj `send_feedback`, aby zgłosić powtarzalny problem lub niejasny krok, bez tokenów i podpisanych adresów URL.

## Powiązane poradniki

- [Proste gry HTML](https://www.playdrop.ai/pl/create/learn/html-games): Opublikuj jeden samodzielny plik HTML do 10 MiB przez upload_game: co się mieści, mini katalog, widoczność, aktualizacje i kiedy przejść na pakiet.
- [Pakowanie i .play](https://www.playdrop.ai/pl/create/learn/packaging): Zbudowana gra w folderze, ZIP lub .play z catalogue.json w katalogu głównym: media strony gry, serwery i przesyłanie przez prepare_catalogue_upload.
- [Widoczność i zasięg](https://www.playdrop.ai/pl/create/learn/distribution): Wybierz, kto może otworzyć grę, poznaj ustawienie konta i publikowanie wersji oraz to, jak Boost, Wymiana rozgrywek, Instant i wyszukiwarki przyciągają graczy.
- [Błędy i odzyskiwanie](https://www.playdrop.ai/pl/create/learn/errors): Struktura błędów zwracanych przez narzędzia MCP PlayDrop, kiedy ponawiać z tym samym requestId i jak naprawić każdy częsty kod błędu.