# 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

```bash
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+.

```bash
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):

```bash
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).