dndkit 0.4.0__tar.gz → 0.5.0__tar.gz

{dndkit-0.4.0/src/dndkit.egg-info → dndkit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dndkit
-Version: 0.4.0
+Version: 0.5.0
 Summary: A D&D 5e campaign management MCP server, built for voice game masters
 Author: Sylvain Boily, Joel Casimir
 Maintainer: Sylvain Boily
@@ -95,7 +95,7 @@ says why and lists the known names, so the model can correct itself.
 Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
 
 ```bash
-# From PyPI (from the first release, 0.4.0)
+# From PyPI
 uvx dndkit
 
 # Straight from GitHub
@@ -109,7 +109,9 @@ uv run dndkit
 ```
 
 The server speaks MCP over stdio: an MCP client starts it, you don't keep it
-running yourself. `uvx` fetches it on first use and keeps it cached.
+running yourself. `uvx` fetches it on first use and keeps it cached. To run it
+as a server of its own, for several computers or on a home server, see
+[Docker](#docker).
 
 ### Configuration
 
@@ -117,9 +119,13 @@ running yourself. `uvx` fetches it on first use and keeps it cached.
 | --- | --- | --- |
 | `DNDKIT_STORAGE_DIR` | the per-user data directory (below) | Where campaigns are stored |
 | `DNDKIT_LOG_LEVEL` | `INFO` | Log level; logs go to stderr |
-| `DNDKIT_WEB_PORT` | unset: no web pages | Serve the [live web pages](#live-web-pages) on this port |
-| `DNDKIT_WEB_HOST` | `127.0.0.1` | `0.0.0.0` lets phones on the same network open them |
+| `DNDKIT_WEB_PORT` | unset: no web pages | Serve the [live web pages](#live-web-pages) on this port; the players' join codes (`show_join_codes`) need them |
+| `DNDKIT_WEB_HOST` | `127.0.0.1` | `0.0.0.0` lets phones on the same network open them, and scan their join codes |
 | `DNDKIT_WEB_URL` | guessed | The address phones should use, when the server cannot tell (a DNS name, Tailscale) |
+| `DNDKIT_TRANSPORT` | `stdio` | `http`: a server of its own, MCP at `/mcp` (Streamable HTTP) and `/health` |
+| `DNDKIT_HTTP_HOST` | `127.0.0.1` | Where HTTP listens; beyond this machine it takes a token |
+| `DNDKIT_HTTP_PORT` | `8000` | The HTTP port |
+| `DNDKIT_HTTP_TOKEN` | unset | The token every MCP request must carry (`Authorization: Bearer ...`); 16 characters at least, `openssl rand -hex 32` makes one |
 
 Default data directory:
 
@@ -146,7 +152,7 @@ In **Settings → Integrations → MCP**, add a server:
 | Transport | `stdio` |
 | Command | `uvx` |
 | Arguments | `dndkit` (from PyPI), or `--from git+https://github.com/sboily/dndkit dndkit` |
-| Environment variables | `DNDKIT_STORAGE_DIR=/Users/you/Games/dnd` (optional)<br>`DNDKIT_WEB_PORT=8765` and `DNDKIT_WEB_HOST=0.0.0.0` for the web pages (optional) |
+| Environment variables | `DNDKIT_STORAGE_DIR=/Users/you/Games/dnd` (optional)<br>`DNDKIT_WEB_PORT=8765` and `DNDKIT_WEB_HOST=0.0.0.0` for the web pages and the players' join codes on their phones (optional) |
 
 From a local checkout instead: Command `uv`, Arguments
 `run --directory /path/to/dndkit dndkit`.
@@ -156,9 +162,9 @@ roomkit-ui reads what the server publishes besides its tools: its skills
 tools are meant to be used (roomkit 0.99). Put the system prompt below in the
 assistant's personality.
 
-The 62 tool schemas weigh about 8,900 tokens by roomkit's own estimate, over
+The 63 tool schemas weigh about 8,950 tokens by roomkit's own estimate, over
 the 8,000 at which roomkit may hide tools behind `find_tools`: keep the skills
-on (the tools they bring then wait for them: about 7,300 tokens), or raise
+on (the tools they bring then wait for them: about 7,350 tokens), or raise
 roomkit's threshold (`tool_search_threshold_tokens`). roomkit-ui's automatic
 Tool Search leaves a local voice model every tool. Optional parameters are
 advertised without their `null` alternative to save room.
@@ -193,10 +199,68 @@ at each skill's URI, for hosts that only read resources. Load
 
 A skill's `allowed_tools` frontmatter is roomkit's: roomkit keeps those tools
 out of the catalogue, and out of its token count, until the model activates
-the skill. With the skills on, the catalogue weighs about 7,300 tokens.
+the skill. With the skills on, the catalogue weighs about 7,350 tokens.
 roomkit-ui lists them under the server's name; a client that does not speak
 the extension can load them from `src/dndkit/skills/` as a skill folder.
 
+### Docker
+
+The image runs dndkit as a server of its own: MCP over HTTP on port 8000 and
+the web pages on 8765, campaigns in a volume. It suits a table that plays from
+several computers, or a server that stays on (a NAS, a Raspberry Pi: the image
+is built for amd64 and arm64).
+
+```bash
+curl -O https://raw.githubusercontent.com/sboily/dndkit/main/compose.yaml
+echo "DNDKIT_HTTP_TOKEN=$(openssl rand -hex 32)" > .env
+echo "DNDKIT_WEB_URL=http://192.168.1.20:8765" >> .env   # this computer on your network
+docker compose up -d
+docker compose logs dndkit | grep Backstage   # the game master's link
+```
+
+The image sets `DNDKIT_TRANSPORT=http`, `DNDKIT_HTTP_HOST=0.0.0.0`,
+`DNDKIT_HTTP_PORT=8000`, `DNDKIT_WEB_HOST=0.0.0.0`, `DNDKIT_WEB_PORT=8765` and
+`DNDKIT_STORAGE_DIR=/data`; `compose.yaml` adds `DNDKIT_HTTP_TOKEN` and
+`DNDKIT_WEB_URL` from `.env`. Any other setting from the table above goes in
+the service's `environment`.
+
+In roomkit-ui, add the server with Transport `streamable_http`, URL
+`http://<the server's address>:8000/mcp`, and the header
+`Authorization: Bearer <the token from .env>`. The server refuses any request
+without that token, and does not start listening beyond its machine without
+one.
+
+`DNDKIT_WEB_URL` is the address the players' QR codes carry. Inside a
+container the server only knows its own addresses, which phones cannot reach
+(the log's "Phones on this network" names one): without the setting, the codes
+are right only when the table screen is opened at the server's network
+address, never at `localhost`.
+
+The backstage cannot tell the computer running Docker from any other (every
+visitor comes through Docker's gateway), so it opens with its link instead,
+`/gm/<code>/`, which the server writes in its log at each start: keep it to
+yourself, it shows everything. The code comes from the secret in the data
+volume, like the players' links.
+
+The image is `ghcr.io/sboily/dndkit`, published with each release from 0.5.0
+on, for amd64 and arm64: `0.5.0` is one release, `0.5` the latest of its
+fixes, `latest` the latest release. `compose.yaml` takes `latest`; name a
+version there to choose when to update (`docker compose pull` then
+`docker compose up -d`). Without compose:
+
+```bash
+docker run -d --name dndkit --restart unless-stopped \
+  -p 8000:8000 -p 8765:8765 -v dndkit-data:/data \
+  -e DNDKIT_HTTP_TOKEN="$(openssl rand -hex 32)" \
+  -e DNDKIT_WEB_URL=http://192.168.1.20:8765 \
+  ghcr.io/sboily/dndkit:0.5
+docker exec dndkit env | grep DNDKIT_HTTP_TOKEN   # the token, for roomkit-ui
+```
+
+The container runs as an unprivileged user (uid 1000), and `/health` tells
+Docker whether it is up. From a checkout, `docker compose up -d --build` builds
+the image instead of pulling it.
+
 ### With Claude Desktop
 
 ```json
@@ -290,7 +354,7 @@ Then call check_campaign and fix what it lists before the first scene.
 | NPCs | `create_npc`, `get_npc`, `update_npc`, `list_npcs` |
 | Locations | `create_location`, `get_location`, `update_location`, `list_locations` |
 | Quests | `create_quest`, `get_quest`, `update_quest`, `list_quests` |
-| Table | `seat_players` 🖥, `get_game_state` 🖥, `update_game_state`, `change_hit_points`, `set_condition`, `set_concentration` |
+| Table | `seat_players` 🖥, `show_join_codes` 🖥, `get_game_state` 🖥, `update_game_state`, `change_hit_points`, `set_condition`, `set_concentration` |
 | Combat | `start_combat` 🖥, `add_combatant`, `next_turn`, `remove_combatant`, `use_legendary`, `take_reaction`, `end_combat` |
 | Battle map | `set_battlefield` 🖥, `place_tokens`, `move_token`, `area_of_effect`, `check_target` |
 | Bestiary | `save_monster`, `get_monsters`, `plan_encounter`, `list_encounters` |
@@ -448,7 +512,7 @@ from where it can be put back by hand. A wrong code cancels the request.
 
 ## On-screen widgets (MCP Apps)
 
-Six tools carry an MCP App (`_meta.ui.resourceUri`): the client opens their
+Seven tools carry an MCP App (`_meta.ui.resourceUri`): the client opens their
 page next to the conversation.
 
 | Tool | Widget |
@@ -457,6 +521,7 @@ page next to the conversation.
 | `start_combat`, `set_battlefield` | Combat tracker, live: the battle map when there is one, initiative order, current turn, hit point bars that flash on damage or healing, AC, conditions, the defeated and their XP. |
 | `get_game_state` | Party board, live: location, date, funds, every character's hit points, spell slots, conditions and death saves, quest progress, combat banner. |
 | `seat_players` | The table, live: the players seated around it with their characters, newcomers without one yet, absent players and characters nobody plays. |
+| `show_join_codes` | Join codes: each character's QR code for the players' phones, the same as on the table screen, so roomkit-ui alone is enough to hand them out. Needs the web pages (`DNDKIT_WEB_PORT`, and `DNDKIT_WEB_HOST=0.0.0.0` for phones). |
 | `get_character` | Character sheet, live: hit points, AC, proficiency, XP to next level, abilities, conditions, spell slots, spells, inventory. |
 
 Each page is self-contained (no network access), French or English after the
@@ -494,10 +559,11 @@ the game goes on without the pages.
   skips the widgets' own `get_screen_data` polling. A call the client refuses
   before sending it (roomkit checks required arguments) never reaches the
   server, so it is not there: look at the client's log for those.
-- **The backstage** opens only from the computer running the server: a
-  loopback peer, asking for this server by name (`localhost`, its address or
-  `DNDKIT_WEB_URL`'s host), so a web page whose domain points at this
-  computer (DNS rebinding) is refused. Requests carrying proxy headers are
+- **The backstage** opens at `/gm/` only from the computer running the
+  server: a loopback peer, asking for this server by name (`localhost`, its
+  address or `DNDKIT_WEB_URL`'s host), so a web page whose domain points at
+  this computer (DNS rebinding) is refused. From anywhere else it opens with
+  its link, `/gm/<code>/`, written in the server's log at each start. Requests carrying proxy headers are
   refused too, but a reverse proxy or tunnel on that computer that adds none
   would make every visitor look local: do not put one in front of the pages.
 - **Read-only**: the pages never change the game; it changes through the
@@ -552,14 +618,18 @@ Unreleased section or an existing tag. The tag runs
 `.github/workflows/release.yml`: it checks that the tag matches the version,
 sits on `main` and has its changelog section, runs the tests and builds, then
 publishes to PyPI by trusted publishing (no token: PyPI trusts the workflow in
-its `pypi` environment) and makes the GitHub release, its notes the version's
-changelog section, the built files attached. A failed step stops what follows:
-nothing reaches GitHub's releases before PyPI has the version.
+its `pypi` environment), pushes the Docker image to `ghcr.io/sboily/dndkit`
+(the version, `<major>.<minor>` and `latest`, for amd64 and arm64), and makes
+the GitHub release, its notes the version's changelog section, the built files
+attached. A failed step stops what follows: nothing reaches GitHub's releases
+before PyPI and the registry have the version.
 
 Once, on pypi.org: add a pending trusted publisher for the project `dndkit`
 (owner `sboily`, repository `dndkit`, workflow `release.yml`, environment
 `pypi`). GitHub creates the `pypi` environment at the first release; required
 reviewers set on it (Settings → Environments) hold each release for approval.
+GitHub creates the image's package private at its first push: make it public
+once (the package's settings → Change visibility), or nobody can pull it.
 
 ## License
 

{dndkit-0.4.0 → dndkit-0.5.0}/README.md

@@ -63,7 +63,7 @@ says why and lists the known names, so the model can correct itself.
 Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
 
 ```bash
-# From PyPI (from the first release, 0.4.0)
+# From PyPI
 uvx dndkit
 
 # Straight from GitHub
@@ -77,7 +77,9 @@ uv run dndkit
 ```
 
 The server speaks MCP over stdio: an MCP client starts it, you don't keep it
-running yourself. `uvx` fetches it on first use and keeps it cached.
+running yourself. `uvx` fetches it on first use and keeps it cached. To run it
+as a server of its own, for several computers or on a home server, see
+[Docker](#docker).
 
 ### Configuration
 
@@ -85,9 +87,13 @@ running yourself. `uvx` fetches it on first use and keeps it cached.
 | --- | --- | --- |
 | `DNDKIT_STORAGE_DIR` | the per-user data directory (below) | Where campaigns are stored |
 | `DNDKIT_LOG_LEVEL` | `INFO` | Log level; logs go to stderr |
-| `DNDKIT_WEB_PORT` | unset: no web pages | Serve the [live web pages](#live-web-pages) on this port |
-| `DNDKIT_WEB_HOST` | `127.0.0.1` | `0.0.0.0` lets phones on the same network open them |
+| `DNDKIT_WEB_PORT` | unset: no web pages | Serve the [live web pages](#live-web-pages) on this port; the players' join codes (`show_join_codes`) need them |
+| `DNDKIT_WEB_HOST` | `127.0.0.1` | `0.0.0.0` lets phones on the same network open them, and scan their join codes |
 | `DNDKIT_WEB_URL` | guessed | The address phones should use, when the server cannot tell (a DNS name, Tailscale) |
+| `DNDKIT_TRANSPORT` | `stdio` | `http`: a server of its own, MCP at `/mcp` (Streamable HTTP) and `/health` |
+| `DNDKIT_HTTP_HOST` | `127.0.0.1` | Where HTTP listens; beyond this machine it takes a token |
+| `DNDKIT_HTTP_PORT` | `8000` | The HTTP port |
+| `DNDKIT_HTTP_TOKEN` | unset | The token every MCP request must carry (`Authorization: Bearer ...`); 16 characters at least, `openssl rand -hex 32` makes one |
 
 Default data directory:
 
@@ -114,7 +120,7 @@ In **Settings → Integrations → MCP**, add a server:
 | Transport | `stdio` |
 | Command | `uvx` |
 | Arguments | `dndkit` (from PyPI), or `--from git+https://github.com/sboily/dndkit dndkit` |
-| Environment variables | `DNDKIT_STORAGE_DIR=/Users/you/Games/dnd` (optional)<br>`DNDKIT_WEB_PORT=8765` and `DNDKIT_WEB_HOST=0.0.0.0` for the web pages (optional) |
+| Environment variables | `DNDKIT_STORAGE_DIR=/Users/you/Games/dnd` (optional)<br>`DNDKIT_WEB_PORT=8765` and `DNDKIT_WEB_HOST=0.0.0.0` for the web pages and the players' join codes on their phones (optional) |
 
 From a local checkout instead: Command `uv`, Arguments
 `run --directory /path/to/dndkit dndkit`.
@@ -124,9 +130,9 @@ roomkit-ui reads what the server publishes besides its tools: its skills
 tools are meant to be used (roomkit 0.99). Put the system prompt below in the
 assistant's personality.
 
-The 62 tool schemas weigh about 8,900 tokens by roomkit's own estimate, over
+The 63 tool schemas weigh about 8,950 tokens by roomkit's own estimate, over
 the 8,000 at which roomkit may hide tools behind `find_tools`: keep the skills
-on (the tools they bring then wait for them: about 7,300 tokens), or raise
+on (the tools they bring then wait for them: about 7,350 tokens), or raise
 roomkit's threshold (`tool_search_threshold_tokens`). roomkit-ui's automatic
 Tool Search leaves a local voice model every tool. Optional parameters are
 advertised without their `null` alternative to save room.
@@ -161,10 +167,68 @@ at each skill's URI, for hosts that only read resources. Load
 
 A skill's `allowed_tools` frontmatter is roomkit's: roomkit keeps those tools
 out of the catalogue, and out of its token count, until the model activates
-the skill. With the skills on, the catalogue weighs about 7,300 tokens.
+the skill. With the skills on, the catalogue weighs about 7,350 tokens.
 roomkit-ui lists them under the server's name; a client that does not speak
 the extension can load them from `src/dndkit/skills/` as a skill folder.
 
+### Docker
+
+The image runs dndkit as a server of its own: MCP over HTTP on port 8000 and
+the web pages on 8765, campaigns in a volume. It suits a table that plays from
+several computers, or a server that stays on (a NAS, a Raspberry Pi: the image
+is built for amd64 and arm64).
+
+```bash
+curl -O https://raw.githubusercontent.com/sboily/dndkit/main/compose.yaml
+echo "DNDKIT_HTTP_TOKEN=$(openssl rand -hex 32)" > .env
+echo "DNDKIT_WEB_URL=http://192.168.1.20:8765" >> .env   # this computer on your network
+docker compose up -d
+docker compose logs dndkit | grep Backstage   # the game master's link
+```
+
+The image sets `DNDKIT_TRANSPORT=http`, `DNDKIT_HTTP_HOST=0.0.0.0`,
+`DNDKIT_HTTP_PORT=8000`, `DNDKIT_WEB_HOST=0.0.0.0`, `DNDKIT_WEB_PORT=8765` and
+`DNDKIT_STORAGE_DIR=/data`; `compose.yaml` adds `DNDKIT_HTTP_TOKEN` and
+`DNDKIT_WEB_URL` from `.env`. Any other setting from the table above goes in
+the service's `environment`.
+
+In roomkit-ui, add the server with Transport `streamable_http`, URL
+`http://<the server's address>:8000/mcp`, and the header
+`Authorization: Bearer <the token from .env>`. The server refuses any request
+without that token, and does not start listening beyond its machine without
+one.
+
+`DNDKIT_WEB_URL` is the address the players' QR codes carry. Inside a
+container the server only knows its own addresses, which phones cannot reach
+(the log's "Phones on this network" names one): without the setting, the codes
+are right only when the table screen is opened at the server's network
+address, never at `localhost`.
+
+The backstage cannot tell the computer running Docker from any other (every
+visitor comes through Docker's gateway), so it opens with its link instead,
+`/gm/<code>/`, which the server writes in its log at each start: keep it to
+yourself, it shows everything. The code comes from the secret in the data
+volume, like the players' links.
+
+The image is `ghcr.io/sboily/dndkit`, published with each release from 0.5.0
+on, for amd64 and arm64: `0.5.0` is one release, `0.5` the latest of its
+fixes, `latest` the latest release. `compose.yaml` takes `latest`; name a
+version there to choose when to update (`docker compose pull` then
+`docker compose up -d`). Without compose:
+
+```bash
+docker run -d --name dndkit --restart unless-stopped \
+  -p 8000:8000 -p 8765:8765 -v dndkit-data:/data \
+  -e DNDKIT_HTTP_TOKEN="$(openssl rand -hex 32)" \
+  -e DNDKIT_WEB_URL=http://192.168.1.20:8765 \
+  ghcr.io/sboily/dndkit:0.5
+docker exec dndkit env | grep DNDKIT_HTTP_TOKEN   # the token, for roomkit-ui
+```
+
+The container runs as an unprivileged user (uid 1000), and `/health` tells
+Docker whether it is up. From a checkout, `docker compose up -d --build` builds
+the image instead of pulling it.
+
 ### With Claude Desktop
 
 ```json
@@ -258,7 +322,7 @@ Then call check_campaign and fix what it lists before the first scene.
 | NPCs | `create_npc`, `get_npc`, `update_npc`, `list_npcs` |
 | Locations | `create_location`, `get_location`, `update_location`, `list_locations` |
 | Quests | `create_quest`, `get_quest`, `update_quest`, `list_quests` |
-| Table | `seat_players` 🖥, `get_game_state` 🖥, `update_game_state`, `change_hit_points`, `set_condition`, `set_concentration` |
+| Table | `seat_players` 🖥, `show_join_codes` 🖥, `get_game_state` 🖥, `update_game_state`, `change_hit_points`, `set_condition`, `set_concentration` |
 | Combat | `start_combat` 🖥, `add_combatant`, `next_turn`, `remove_combatant`, `use_legendary`, `take_reaction`, `end_combat` |
 | Battle map | `set_battlefield` 🖥, `place_tokens`, `move_token`, `area_of_effect`, `check_target` |
 | Bestiary | `save_monster`, `get_monsters`, `plan_encounter`, `list_encounters` |
@@ -416,7 +480,7 @@ from where it can be put back by hand. A wrong code cancels the request.
 
 ## On-screen widgets (MCP Apps)
 
-Six tools carry an MCP App (`_meta.ui.resourceUri`): the client opens their
+Seven tools carry an MCP App (`_meta.ui.resourceUri`): the client opens their
 page next to the conversation.
 
 | Tool | Widget |
@@ -425,6 +489,7 @@ page next to the conversation.
 | `start_combat`, `set_battlefield` | Combat tracker, live: the battle map when there is one, initiative order, current turn, hit point bars that flash on damage or healing, AC, conditions, the defeated and their XP. |
 | `get_game_state` | Party board, live: location, date, funds, every character's hit points, spell slots, conditions and death saves, quest progress, combat banner. |
 | `seat_players` | The table, live: the players seated around it with their characters, newcomers without one yet, absent players and characters nobody plays. |
+| `show_join_codes` | Join codes: each character's QR code for the players' phones, the same as on the table screen, so roomkit-ui alone is enough to hand them out. Needs the web pages (`DNDKIT_WEB_PORT`, and `DNDKIT_WEB_HOST=0.0.0.0` for phones). |
 | `get_character` | Character sheet, live: hit points, AC, proficiency, XP to next level, abilities, conditions, spell slots, spells, inventory. |
 
 Each page is self-contained (no network access), French or English after the
@@ -462,10 +527,11 @@ the game goes on without the pages.
   skips the widgets' own `get_screen_data` polling. A call the client refuses
   before sending it (roomkit checks required arguments) never reaches the
   server, so it is not there: look at the client's log for those.
-- **The backstage** opens only from the computer running the server: a
-  loopback peer, asking for this server by name (`localhost`, its address or
-  `DNDKIT_WEB_URL`'s host), so a web page whose domain points at this
-  computer (DNS rebinding) is refused. Requests carrying proxy headers are
+- **The backstage** opens at `/gm/` only from the computer running the
+  server: a loopback peer, asking for this server by name (`localhost`, its
+  address or `DNDKIT_WEB_URL`'s host), so a web page whose domain points at
+  this computer (DNS rebinding) is refused. From anywhere else it opens with
+  its link, `/gm/<code>/`, written in the server's log at each start. Requests carrying proxy headers are
   refused too, but a reverse proxy or tunnel on that computer that adds none
   would make every visitor look local: do not put one in front of the pages.
 - **Read-only**: the pages never change the game; it changes through the
@@ -520,14 +586,18 @@ Unreleased section or an existing tag. The tag runs
 `.github/workflows/release.yml`: it checks that the tag matches the version,
 sits on `main` and has its changelog section, runs the tests and builds, then
 publishes to PyPI by trusted publishing (no token: PyPI trusts the workflow in
-its `pypi` environment) and makes the GitHub release, its notes the version's
-changelog section, the built files attached. A failed step stops what follows:
-nothing reaches GitHub's releases before PyPI has the version.
+its `pypi` environment), pushes the Docker image to `ghcr.io/sboily/dndkit`
+(the version, `<major>.<minor>` and `latest`, for amd64 and arm64), and makes
+the GitHub release, its notes the version's changelog section, the built files
+attached. A failed step stops what follows: nothing reaches GitHub's releases
+before PyPI and the registry have the version.
 
 Once, on pypi.org: add a pending trusted publisher for the project `dndkit`
 (owner `sboily`, repository `dndkit`, workflow `release.yml`, environment
 `pypi`). GitHub creates the `pypi` environment at the first release; required
 reviewers set on it (Settings → Environments) hold each release for approval.
+GitHub creates the image's package private at its first push: make it public
+once (the package's settings → Change visibility), or nobody can pull it.
 
 ## License
 

{dndkit-0.4.0 → dndkit-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dndkit"
-version = "0.4.0"
+version = "0.5.0"
 description = "A D&D 5e campaign management MCP server, built for voice game masters"
 # Joel Casimir wrote gamemaster-mcp, the project dndkit was forked from.
 authors = [{ name = "Sylvain Boily" }, { name = "Joel Casimir" }]

{dndkit-0.4.0 → dndkit-0.5.0}/src/dndkit/app.py

@@ -17,9 +17,11 @@ from fastmcp import FastMCP
 from dndkit import __version__
 from dndkit.activity import ActivityLog
 from dndkit.config import (
+    SettingsError,
     WebSettings,
     configure_logging,
     resolve_data_dir,
+    resolve_http_settings,
     resolve_web_settings,
 )
 from dndkit.game.dice import DiceLog
@@ -27,9 +29,10 @@ from dndkit.skills import register_skills
 from dndkit.storage import CampaignStore
 from dndkit.tools import ALL_TOOLS
 from dndkit.tools.apps import register_apps
-from dndkit.tools.deps import DICE_LOG_KEY, STORE_KEY
+from dndkit.tools.deps import DICE_LOG_KEY, JOIN_CODES_KEY, STORE_KEY
 from dndkit.tools.recorder import Recorder
 from dndkit.tools.schema import compact
+from dndkit.transport import BearerToken, add_health, serve
 from dndkit.web import Changes, web_pages
 
 logger = logging.getLogger(__name__)
@@ -59,10 +62,13 @@ skill://dnd-monsters/SKILL.md (save_monster, plan_encounter: monsters, bosses,
 sizing a fight) and skill://dnd-battle-map/SKILL.md (the map tools)."""
 
 
-def build_server(data_dir: Path | None = None, web: WebSettings | None = None) -> FastMCP:
+def build_server(
+    data_dir: Path | None = None, web: WebSettings | None = None, token: str | None = None
+) -> FastMCP:
     """The MCP server; campaigns live in *data_dir*, else the configured directory.
 
-    With *web*, the server also serves the live web pages (``web/``).
+    With *web*, the server also serves the live web pages (``web/``). With
+    *token*, served over HTTP, every MCP request must carry it.
     """
 
     activity = ActivityLog()  # in memory, filled by the Recorder middleware
@@ -76,8 +82,8 @@ def build_server(data_dir: Path | None = None, web: WebSettings | None = None) -
         dice_log = DiceLog(on_record=changes.notify)
         activity.on_record = changes.notify_activity
         try:
-            async with web_pages(web, store, dice_log, activity, changes):
-                yield {STORE_KEY: store, DICE_LOG_KEY: dice_log}
+            async with web_pages(web, store, dice_log, activity, changes) as codes:
+                yield {STORE_KEY: store, DICE_LOG_KEY: dice_log, JOIN_CODES_KEY: codes}
         finally:
             store.close()
 
@@ -90,16 +96,28 @@ def build_server(data_dir: Path | None = None, web: WebSettings | None = None) -
         # errors (``GameError``) keep their message, written for the model.
         mask_error_details=True,
         middleware=[Recorder(activity)],
+        auth=BearerToken(token) if token else None,
     )
     for fn in ALL_TOOLS:
         tool = server.add_tool(fn)
         tool.parameters = compact(tool.parameters)
     register_apps(server)
     register_skills(server, activity)
+    add_health(server)
     return server
 
 
 def main() -> None:
-    """Run the server over stdio, the transport MCP clients launch."""
+    """Run the server: over stdio, the transport MCP clients launch, or over HTTP
+    (``DNDKIT_TRANSPORT=http``) as a server of its own."""
     configure_logging()
-    build_server(web=resolve_web_settings()).run(show_banner=False)
+    try:
+        http = resolve_http_settings()
+    except SettingsError as error:
+        logger.error("%s", error)
+        raise SystemExit(2) from None
+    server = build_server(web=resolve_web_settings(), token=http.token if http else None)
+    if http is None:
+        server.run(show_banner=False)
+    else:
+        serve(server, http)

{dndkit-0.4.0 → dndkit-0.5.0}/src/dndkit/config.py

@@ -1,4 +1,5 @@
-"""Runtime configuration: where the data lives, how much is logged, the web pages.
+"""Runtime configuration: where the data lives, how much is logged, the web pages,
+and how clients reach the server (stdio, or HTTP for a server of its own).
 
 MCP clients such as roomkit-ui or Claude Desktop start the server with no
 working directory of their own (often ``/`` on macOS), so the data directory
@@ -9,6 +10,7 @@ The project was called gamemaster-mcp before its rename: its ``GAMEMASTER_*``
 variables and its data directory still work.
 """
 
+import ipaddress
 import logging
 import os
 import sys
@@ -26,7 +28,15 @@ ENV_LOG_LEVEL = "DNDKIT_LOG_LEVEL"
 ENV_WEB_PORT = "DNDKIT_WEB_PORT"
 ENV_WEB_HOST = "DNDKIT_WEB_HOST"
 ENV_WEB_URL = "DNDKIT_WEB_URL"
+ENV_TRANSPORT = "DNDKIT_TRANSPORT"
+ENV_HTTP_HOST = "DNDKIT_HTTP_HOST"
+ENV_HTTP_PORT = "DNDKIT_HTTP_PORT"
+# Names and advice, not secrets: bandit takes any "token" string for a password.
+ENV_HTTP_TOKEN = "DNDKIT_HTTP_TOKEN"  # nosec B105
 DEFAULT_WEB_HOST = "127.0.0.1"
+DEFAULT_HTTP_PORT = 8000
+MIN_TOKEN_LENGTH = 16
+MAKE_A_TOKEN = "openssl rand -hex 32"  # nosec B105
 
 logger = logging.getLogger(__name__)
 
@@ -40,6 +50,19 @@ class WebSettings:
     public_url: str | None = None  # how phones reach the pages when the server cannot tell
 
 
+@dataclass(frozen=True)
+class HttpSettings:
+    """Where the MCP server listens over HTTP, and the token each request must carry."""
+
+    host: str = DEFAULT_WEB_HOST
+    port: int = DEFAULT_HTTP_PORT
+    token: str | None = None
+
+
+class SettingsError(ValueError):
+    """A setting the server cannot start with."""
+
+
 def setting(env: Mapping[str, str], name: str) -> str:
     """``$name``, else the same variable under its name from before the rename."""
     value = env.get(name, "").strip()
@@ -89,7 +112,8 @@ def resolve_web_settings(env: Mapping[str, str] = os.environ) -> WebSettings | N
     raw_port = setting(env, ENV_WEB_PORT)
     if not raw_port:
         return None
-    if not (raw_port.isascii() and raw_port.isdigit()) or int(raw_port) > 65535:
+    port = _port(raw_port)
+    if port is None:
         # The game must still run: only the web pages are lost to a typo.
         logger.warning("Web pages are off: %s=%r is not a port number.", ENV_WEB_PORT, raw_port)
         return None
@@ -98,7 +122,51 @@ def resolve_web_settings(env: Mapping[str, str] = os.environ) -> WebSettings | N
         logger.warning("Ignoring %s=%r: not an http(s) address.", ENV_WEB_URL, public_url)
         public_url = None
     return WebSettings(
-        port=int(raw_port),
+        port=port,
         host=setting(env, ENV_WEB_HOST) or DEFAULT_WEB_HOST,
         public_url=public_url,
     )
+
+
+def resolve_http_settings(env: Mapping[str, str] = os.environ) -> HttpSettings | None:
+    """None for stdio, the default; how to listen for ``DNDKIT_TRANSPORT=http``.
+
+    Unlike the web pages', a bad value stops the start: without its endpoint
+    there is no game. Listening beyond this machine takes a token.
+    """
+    transport = (setting(env, ENV_TRANSPORT) or "stdio").lower()
+    if transport == "stdio":
+        return None
+    if transport != "http":
+        raise SettingsError(f"{ENV_TRANSPORT} is stdio or http, not {transport!r}.")
+    raw_port = setting(env, ENV_HTTP_PORT) or str(DEFAULT_HTTP_PORT)
+    port = _port(raw_port)
+    if port is None:
+        raise SettingsError(f"{ENV_HTTP_PORT}={raw_port!r} is not a port number.")
+    host = setting(env, ENV_HTTP_HOST) or DEFAULT_WEB_HOST
+    token = setting(env, ENV_HTTP_TOKEN) or None
+    if token is not None and len(token) < MIN_TOKEN_LENGTH:
+        raise SettingsError(
+            f"{ENV_HTTP_TOKEN} needs {MIN_TOKEN_LENGTH} characters at least ({MAKE_A_TOKEN})."
+        )
+    if token is None and not _is_loopback(host):
+        raise SettingsError(
+            f"Listening on {host} lets other computers in: set {ENV_HTTP_TOKEN} "
+            f"({MAKE_A_TOKEN}), or {ENV_HTTP_HOST}=127.0.0.1."
+        )
+    return HttpSettings(host, port, token)
+
+
+def _port(raw: str) -> int | None:
+    if not (raw.isascii() and raw.isdigit()) or int(raw) > 65535:
+        return None
+    return int(raw)
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False

{dndkit-0.4.0 → dndkit-0.5.0}/src/dndkit/skills/dnd-game-master/SKILL.md

@@ -32,8 +32,9 @@ result with the tools, and hand the story back with "what do you do?".
 - **Characters**: `create_character`, `update_character` (scores, AC, skills,
   languages, features), `get_character`, items, spells and slots, `rest`,
   `award_experience`, `level_up`.
-- **The table**: `seat_players` (who plays whom tonight), `get_game_state`.
-  The dice, the party, a sheet and the fight show on the players' screen.
+- **The table**: `seat_players` (who plays whom tonight), `get_game_state`,
+  `show_join_codes` (the players' phones). The dice, the party, a sheet and
+  the fight show on the players' screen.
 - **The world**: NPCs, locations and quests (`create_`, `get_`, `update_`,
   `list_`), `update_game_state` (where the party is, the date).
 - **Fights**: `start_combat`, `next_turn` after every turn, `take_reaction`,
@@ -50,7 +51,9 @@ result with the tools, and hand the story back with "what do you do?".
 3. A campaign under way: `get_sessions` and `get_game_state`, then recall in
    two sentences where the story stopped.
 4. The roll call: as each player says who they are, `seat_players` with them
-   and their character (`start_over` the first time tonight).
+   and their character (`start_over` the first time tonight). Players who
+   want their sheet on their phone: `show_join_codes` puts each character's
+   QR code on screen.
 5. Set the opening scene in three or four sentences and ask the first player
    what they do.
 

{dndkit-0.4.0 → dndkit-0.5.0}/src/dndkit/tools/apps.py

@@ -18,6 +18,7 @@ COMBAT_APP = "ui://dndkit/combat.html"
 PARTY_APP = "ui://dndkit/party.html"
 CHARACTER_APP = "ui://dndkit/character.html"
 SEATING_APP = "ui://dndkit/seating.html"
+JOIN_APP = "ui://dndkit/join.html"
 
 _PAGES = {
     DICE_APP: ("dice", "Dice tray: the latest roll, rolling."),
@@ -25,6 +26,7 @@ _PAGES = {
     PARTY_APP: ("party", "Party board: hit points, conditions, location and quests, live."),
     CHARACTER_APP: ("character", "Character sheet, live."),
     SEATING_APP: ("seating", "The table: who plays which character tonight, live."),
+    JOIN_APP: ("join", "Join codes: each character's QR code, for the players' phones."),
 }