RPG Ledger MCP Server

Serwer legera do sesji RPG sterowanych przez AI. Udostępnia stan kampanii (postacie, ekwipunek, questy, logi) przez MCP i proste API HTTP, tak żeby np. ChatGPT mógł być Mistrzem Gry / NPC.

Architektura

app.py – FastAPI + FastMCP
- MCP tools (używane przez klienta AI):
  - list_campaigns() – lista kampanii
  - get_campaign(campaign_id) – pełne dane kampanii
  - get_character(campaign_id, char_id) – jedna postać
  - list_locations(campaign_id) – lista lokacji kampanii
  - list_factions(campaign_id) – lista frakcji kampanii
  - create_campaign(campaign_id, name, from_campaign_id, overwrite) – tworzenie kampanii
  - create_character(campaign_id, character) – dodanie nowej postaci
  - update_character(campaign_id, char_id, patch) – modyfikacja istniejącej postaci
  - upsert_location(campaign_id, location) – dodawanie/aktualizacja lokacji
  - delete_location(campaign_id, location_id_or_name) – usunięcie lokacji po id lub nazwie
  - faction_rep_add(campaign_id, faction_id, delta, name) – zmiana reputacji frakcji
  - upsert_faction(campaign_id, faction) – dodanie/aktualizacja frakcji (id, name, rep, description)
  - mutate(...) – modyfikacje legera (gold/hp/xp/notki/deń/questy/ekwipunek itd.)
  - spawn_npc_group(campaign_id, template_id, ...) – generowanie grupy NPC z szablonu
  - dev_todo(...) – narzędzie dla MG/AI do zapisywania TODO w logu
  - save_campaign_snapshot(campaign_id, slot) / restore_campaign_snapshot(campaign_id, slot) – snapshoty kampanii
data/ – pliki kampanii JSON (np. kampania-1.json)
logs/ – zdarzenia z gry (logs.jsonl)
static/index.html – prosta przeglądarka kampanii w przeglądarce

Serwer HTTP nasłuchuje na porcie 8000, MCP jest wystawione jako SSE pod /mcp (FastMCP over HTTPS/HTTP).

Uruchomienie przez Docker Compose (zalecane)

Wymagane:

Docker + Docker Compose

docker compose up --build

To uruchomi dwa kontenery:

rpg-ledger-mcp – serwer FastAPI + MCP na http://localhost:8000
rpg-ledger-ngrok – tunel HTTP do rpg-ledger-mcp:8000 (publiczny URL z ngrok)

W pliku docker-compose.yml można wstawić własny NGROK_AUTHTOKEN.

Przydatne adresy lokalnie:

UI kampanii: http://localhost:8000/
API kampanii: http://localhost:8000/api/campaigns itd.
Logi: http://localhost:8000/api/logs

Konfiguracja MCP (klient np. ChatGPT Desktop / inne)

Serwer MCP jest dostępny jako endpoint HTTP SSE:

URL: http://localhost:8000/mcp

W konfiguracji klienta MCP ustaw:

typ: „HTTP / SSE” (FastMCP)
endpoint: http://localhost:8000/mcp (lub publiczny URL z ngrok)

Po podłączeniu klient powinien widzieć narzędzia MCP (list_campaigns, get_campaign, get_character, mutate, dev_todo).

Lokalny development (bez Dockera)

Wymagany Python 3.11+.

pip install -r requirements.txt
uvicorn app:app --reload --host 0.0.0.0 --port 8000

Potem korzystasz z tych samych URL co wyżej (http://localhost:8000/...).

Dev TODO z poziomu MG / AI

Narzędzie dev_todo(...) pozwala MG/AI zapisywać pomysły na rozwój systemu:

wywołanie MCP dev_todo(summary=..., details=..., tags=[...])
wpis trafia do osobnego pliku logs/dev-todos.jsonl z type: "todo", odczytywanego przez endpoint /api/dev-todos i zakładkę TODO w UI

Dzięki temu możesz:

grać sesję,
pozwalać MG/AI zgłaszać brakujące funkcje jako TODO,
później przejrzeć /api/logs i zaimplementować kolejne kawałki logiki legera.

Kampania testowa / test pack

Żeby nie zaśmiecać logów głównej kampanii, w katalogu data/ jest osobna kampania testowa:

plik: data/kampania-test.json
id: kampania-test
zawiera prostą mapę (karczma ↔ las-testowy) i dwie postacie (test-warrior, test-mage).

Rekomendacja:

do ręcznych testów MCP/UI wybieraj w topbarze kampanię „Kampania Testowa”,
w narzędziach MCP (mutate, roll_dice, itp.) używaj campaign_id="kampania-test".

Dzięki temu wpisy testowe w logs/logs.jsonl będą odseparowane od właściwej kampanii po campaign_id.

E2E test pack (lokalnie)

Jest też prosty E2E test dla kampanii testowej (bezpośrednio po HTTP):

docker compose up -d
python scripts/e2e_test_pack.py

Test:

sprawdza dostępność serwera na http://localhost:8000,
upewnia się, że kampania-test istnieje w /api/campaigns,
przed testem przywraca plik data/kampania-test.json z szablonu data/kampania-test.template.json,
wykonuje kilka mutacji na kampanii testowej (hp_add, gold_add, location_set),
weryfikuje, że zmiany w stanie oraz wpisy w logs/logs.jsonl są zgodne z oczekiwaniami,
po udanym teście ponownie przywraca data/kampania-test.json z szablonu (logi pozostają append-only).