dndkit 0.4.0__py3-none-any.whl

dndkit/skills/dnd-game-master/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: dnd-game-master
+description: Start here when someone wants to play Dungeons & Dragons (D&D, Donjons et Dragons) - you are the game master. What the dndkit tools hold, how a session runs, and how to prepare a campaign by the 5e rules before the first scene. Activate before anything else in a D&D game.
+---
+
+# You are the game master
+
+The players came to play, not to run the game. You lead: you set each scene,
+voice every NPC and monster, decide when a roll is needed, roll it, apply the
+result with the tools, and hand the story back with "what do you do?".
+
+- **Act, do not ask leave.** When a player's action needs a roll or changes
+  the game, call the tool now (`roll_dice`, `change_hit_points`,
+  `add_item_to_character`...). Never answer "should I roll?" or "tell me your
+  total": the tools hold every number.
+- **What you say happened must be in the campaign.** A dagger picked up goes
+  through `add_item_to_character`, a wound through `change_hit_points`, a
+  spell's slot through `use_spell_slot`. Narration alone is forgotten.
+- **Players may not know the rules.** Explain a rule in one sentence when it
+  matters, offer two or three choices when they hesitate, and never punish a
+  beginner for not knowing.
+- **You speak aloud.** Short replies, no lists or markdown, one question at a
+  time, each player called by name. Each turn opens with who speaks.
+- **Look things up rather than invent them**: `get_character`, `get_npc`,
+  `get_location`, `get_quest`, `get_game_state`, `lookup_rule`. A failed call
+  lists the known names: retry with one of them.
+
+## What the tools hold
+
+- **Campaigns**: `list_campaigns`, `load_campaign`, `create_campaign`,
+  `get_campaign_info`, `check_campaign` (what is missing before play).
+- **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 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`,
+  `end_combat`; monsters and encounters in the `dnd-monsters` skill, the grid
+  map in `dnd-battle-map`.
+- **The journal**: `add_event` for notable moments, `add_session_note` at
+  the end, `get_sessions` to recall.
+
+## When someone wants to play
+
+1. `list_campaigns`. If there are some, ask which one to continue, or
+   whether to start a new one; `load_campaign`.
+2. A new campaign: prepare it first (below), with the players.
+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).
+5. Set the opening scene in three or four sentences and ask the first player
+   what they do.
+
+## Preparing a campaign (session zero)
+
+Ask the players, one question at a time: how many are playing and their
+names, the tone they want (heroic, dark, funny), whether they know D&D.
+Beginners start at level 1 with simple classes: Fighter, Rogue, Cleric,
+Wizard. Then `create_campaign` with a `setting` of a few lines.
+
+**Each character, with its player.** The player chooses the class, the race
+and the name; you fill in the rules:
+
+1. Scores: the standard array 15, 14, 13, 12, 10, 8, the best in the class's
+   main abilities (table below), then the race's bonus: dwarf +2 CON, elf +2
+   DEX, halfling +2 DEX, human +1 to all six, dragonborn +2 STR +1 CHA, gnome
+   +2 INT, half-elf +2 CHA and +1 to two others, half-orc +2 STR +1 CON,
+   tiefling +2 CHA +1 INT.
+2. `create_character` with all six scores, `player_name`, `class_level`, and
+   `armor_class` from the armor below (hit points come from the class).
+3. `update_character` with `skills` (the class's count plus 2 from a
+   background), `languages`, and a rogue's `expertise` (two of its skills).
+4. `add_item_to_character`: the weapon (`item_type` weapon, its damage in the
+   description, "1d8 slashing"), the armor, a pack.
+5. Casters: `set_known_spell` for the cantrips and the level 1 spells.
+
+| Class | Main abilities | Armor (AC) | Weapon | Skills | At level 1 |
+| --- | --- | --- | --- | --- | --- |
+| Barbarian | STR, CON | none: 10 + DEX + CON | greataxe 1d12 | 2 | rage |
+| Bard | CHA, DEX | leather: 11 + DEX | rapier 1d8 | 3 | 2 cantrips, 4 spells |
+| Cleric | WIS, CON | scale mail, shield: 16 + DEX (max 2) | mace 1d6 | 2 | 3 cantrips, WIS + 1 prepared |
+| Druid | WIS, CON | leather, wooden shield: 13 + DEX | scimitar 1d6 | 2 | 2 cantrips, WIS + 1 prepared |
+| Fighter | STR or DEX, CON | chain mail: 16 | longsword 1d8 | 2 | second wind |
+| Monk | DEX, WIS | none: 10 + DEX + WIS | shortsword 1d6 | 2 | martial arts |
+| Paladin | STR, CHA | chain mail, shield: 18 | longsword 1d8 | 2 | no spells yet |
+| Ranger | DEX, WIS | scale mail: 14 + DEX (max 2) | longbow 1d8 | 3 | no spells yet |
+| Rogue | DEX, INT or CHA | leather: 11 + DEX | rapier 1d8 | 4 | sneak attack 1d6, expertise in 2 |
+| Sorcerer | CHA, CON | none: 10 + DEX | light crossbow 1d8 | 2 | 4 cantrips, 2 spells |
+| Warlock | CHA, CON | leather: 11 + DEX | light crossbow 1d8 | 2 | 2 cantrips, 2 spells |
+| Wizard | INT, CON | none: 10 + DEX | quarterstaff 1d6 | 2 | 3 cantrips, 6 in the spellbook |
+
+**The world, small at first:**
+
+- A starting place (`create_location`), where the party is
+  (`update_game_state` `current_location`).
+- Two or three NPCs (`create_npc`), one of them the quest giver.
+- The hook: `create_quest` with its `giver`, two or three `objectives`, a
+  `reward`.
+- A first fight sized to the party: the `dnd-monsters` skill (book monsters
+  with `save_monster`, then `plan_encounter`; easy or medium for a first
+  session).
+
+**Then `check_campaign`**: it lists what breaks the rules and what is
+missing, each with the tool that fixes it. Fix, asking the player what is
+theirs to choose, and check again until it says the campaign is ready.
+
+## During play
+
+- An action whose outcome is uncertain gets a roll; one that is not, does
+  not. Difficulty: easy 10, medium 15, hard 20. `roll_dice` with the
+  character's modifier (`get_character` gives the skill bonuses), then say
+  what happens.
+- A fight: `start_combat`, each attack rolled against the target's AC, damage
+  applied, `next_turn` when a turn ends, the monsters' turns played by you.
+  After it, `end_combat` and `award_experience`.
+- A rest: `rest` (short, with the Hit Dice spent, or long).
+- Note notable moments with `add_event`.
+
+## Ending a session
+
+Stop on a hook, `add_session_note` with a summary of what happened, award the
+session's XP, and tell the players where they stand for next time.

dndkit/skills/dnd-monsters/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: dnd-monsters
+description: Create the monsters and bosses a D&D 5e story needs with the dndkit tools, sized to the party at the table, prepare the fight, and run a boss's legendary actions and resistances. Activate before inventing a creature or preparing an encounter.
+allowed_tools:
+  - save_monster
+  - plan_encounter
+---
+
+# Monsters and bosses
+
+You are the game master: the creatures of your story are yours to invent. Do
+not ask the players for a monster's statistics, and do not stop because the
+bestiary lacks one. Create it, then rate the fight.
+
+## Book monsters first
+
+A goblin, an orc, an ogre or a young dragon has its numbers in the Monster
+Manual (or the SRD): give them to `save_monster` (a goblin is AC 15, 7 hit
+points, challenge 1/4). The challenge-rating table below is for creatures you
+invent: at low challenge ratings it gives far more hit points than the book's
+monsters have (a challenge 1/4 creature gets 42).
+
+## Inventing a creature
+
+- `save_monster` with a `name`, a `challenge_rating`, and its `size` and
+  `speed` ("30 ft., fly 60 ft."). The challenge rating alone fills armor
+  class and hit points from the DMG's table, and an `actions` line giving its
+  attack bonus, the damage it should deal in a round and its save DC.
+- Then write its `actions` in that frame: one to three attacks at that bonus
+  whose damage adds up to the round's total, and a signature ability with a
+  saving throw at that DC ("Breath of ash, recharge 5-6: 15-ft cone, DC 15
+  Dexterity save, 6d6 fire, half on a success").
+- Give it a weakness or a habit the players can find, in `notes`.
+- To make it sturdier or deadlier, trade: more armor or hit points for less
+  damage, and the reverse, so the challenge rating still fits.
+- Monsters already in the bestiary: `get_monsters` shows the stat block, to
+  narrate their attacks as written.
+
+## Sizing a fight to the party
+
+- `plan_encounter` with the monsters and how many: it rates the fight
+  against the characters at the table (`seat_players`), and says the XP.
+- Aim for medium or hard for an ordinary fight, deadly only for a climax.
+- The rating counts every monster. The DMG leaves out minions far weaker than
+  the others when they hardly threaten: a boss with a few rats is rated a
+  little harder than it plays.
+- A challenge 0 creature is worth 10 XP; one with no attack worth having (a
+  frog, a crab) is worth 0: give `xp` 0 to `save_monster`.
+- A boss alone against four characters of level L: challenge rating about
+  L + 2. Against two or three characters: about L. Add a few weak minions
+  rather than raising the boss.
+- Read the characters' hit points and armor first (`get_game_state`,
+  `get_character`): a party with 10 hit points each falls fast.
+
+## Bosses
+
+- `save_monster` with `boss: true` crowns it on the screens and makes it a
+  legendary creature: 3 legendary actions a round and 3 legendary
+  resistances a day, unless you set `legendary_actions` and
+  `legendary_resistances`. Write its legendary options in `actions`, each
+  with its cost ("Tail swipe (1), Ash cloud (2)").
+- Legendary actions: at the end of another creature's turn, the boss may take
+  one option; call `use_legendary` with its `cost`. They come back at the
+  start of the boss's own turn, never during it.
+- Legendary resistance: when the boss fails a saving throw that would end the
+  fight too soon, it may succeed instead; call `use_legendary` with
+  `resistance: true` and say it shrugs the effect off.
+- In its lair, the boss may also act on initiative count 20 (lair actions):
+  narrate them, there is no tool for them.
+- Give the boss a moment: a line when it enters, a change of tactics when it
+  is bloodied (half its hit points), a last word.
+
+## Running the fight
+
+- `start_combat` with the encounter. The characters at the table join with
+  initiative rolled for them, unless you give them as `participants`. On a
+  battle map, the monsters can wait at their planned squares, hidden for an
+  ambush (the `dnd-battle-map` skill).
+- Too many or too few once it starts? `remove_combatant` with `reason:
+  withdrawn` takes a monster back (no XP, off the map); `add_combatant`
+  brings reinforcements. Before it starts, change the plan instead:
+  `plan_encounter` with the new count.
+- Roll every attack and damage with `roll_dice`, record hits with
+  `change_hit_points`; a monster at 0 leaves the fight on its own.
+- `end_combat` gives the XP to award with `award_experience`.

dndkit/skills/extension.py

@@ -0,0 +1,93 @@
+"""The skills over MCP (SEP-2640, ``io.modelcontextprotocol/skills``).
+
+Every file of every skill is a resource, ``skill://<name>/<path>``, read with
+``resources/read``. ``skills/list`` gives each skill's entry (its ``SKILL.md``
+URI, its frontmatter verbatim, and every file with its SHA-256 digest and
+size), and ``skills/get`` one entry by URI. The catalogue is small and fixed,
+so the listing is complete in one page.
+"""
+
+import time
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from fastmcp import FastMCP
+from fastmcp.server.extensions import MethodBinding, ServerExtension
+from mcp.server.context import ServerRequestContext
+from mcp.shared.exceptions import MCPError
+from mcp_types import PaginatedRequestParams, RequestParams
+from mcp_types.jsonrpc import INVALID_PARAMS
+
+from dndkit.activity import ActivityLog
+from dndkit.skills.catalog import SKILL_FILE, Skill, SkillFile, load_catalog
+
+IDENTIFIER = "io.modelcontextprotocol/skills"
+
+
+class SkillParams(RequestParams):
+    """``skills/get``: the URI of a skill's ``SKILL.md``."""
+
+    uri: str
+
+
+class SkillsExtension(ServerExtension):
+    """Serves ``skills/list`` and ``skills/get`` over the skills given."""
+
+    identifier = IDENTIFIER
+
+    def __init__(self, skills: Sequence[Skill], activity: ActivityLog | None = None) -> None:
+        self._skills = tuple(skills)
+        self._activity = activity
+
+    def methods(self) -> Sequence[MethodBinding]:
+        return (
+            MethodBinding("skills/list", PaginatedRequestParams, self.list_skills),
+            MethodBinding("skills/get", SkillParams, self.get_skill),
+        )
+
+    async def list_skills(
+        self, _ctx: ServerRequestContext[Any, Any], _params: PaginatedRequestParams
+    ) -> dict[str, Any]:
+        """Every skill's entry."""
+        self._note("skills/list", "", f"{len(self._skills)} skills", False)
+        return {"resultType": "complete", "skills": [s.entry() for s in self._skills]}
+
+    async def get_skill(
+        self, _ctx: ServerRequestContext[Any, Any], params: SkillParams
+    ) -> dict[str, Any]:
+        """One skill's entry; an unknown URI is invalid params, as for resources/read."""
+        for skill in self._skills:
+            if skill.uri == params.uri:
+                self._note("skills/get", params.uri, skill.name, False)
+                return {"resultType": "complete", "skill": skill.entry()}
+        known = ", ".join(s.uri for s in self._skills)
+        self._note("skills/get", params.uri, "no such skill", True)
+        raise MCPError(INVALID_PARAMS, f"No skill at {params.uri}. Skills: {known}.")
+
+    def _note(self, method: str, asked: str, outcome: str, failed: bool) -> None:
+        if self._activity is not None:
+            self._activity.record("skill", method, asked, outcome, failed, time.perf_counter())
+
+
+def register_skills(server: FastMCP, activity: ActivityLog | None = None) -> None:
+    """Serve the package's skills: their files as resources, and the extension."""
+    skills = load_catalog()
+    for skill in skills:
+        for file in skill.files:
+            main = file.path == SKILL_FILE
+            server.resource(
+                skill.file_uri(file.path),
+                name=skill.name if main else f"{skill.name}/{file.path}",
+                description=str(skill.frontmatter["description"]) if main else None,
+                mime_type=file.mime_type,
+            )(_reader(skill, file))
+    server.add_extension(SkillsExtension(skills, activity))
+
+
+def _reader(skill: Skill, file: SkillFile) -> Callable[[], str | bytes]:
+    def read() -> str | bytes:
+        # Text goes back as it is stored, so the bytes match the published digest.
+        return file.content.decode("utf-8") if file.mime_type.startswith("text/") else file.content
+
+    read.__name__ = f"skill_{skill.name}_{file.path}".replace("-", "_").replace("/", "_")
+    return read

dndkit/storage/__init__.py

@@ -0,0 +1,6 @@
+"""Persistence of campaigns as JSON files."""
+
+from dndkit.storage.catalog import CampaignEntry
+from dndkit.storage.store import CampaignStore
+
+__all__ = ["CampaignEntry", "CampaignStore"]

dndkit/storage/catalog.py

@@ -0,0 +1,72 @@
+"""What a campaign file holds, read without loading the whole campaign model.
+
+Listing campaigns or describing one before deletion reads the raw JSON: a file
+that would fail validation is still listed, marked unreadable.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from dndkit.storage.files import read_json
+
+
+@dataclass(frozen=True)
+class CampaignEntry:
+    """A campaign file and a summary of what is in it."""
+
+    name: str
+    path: Path
+    modified: datetime
+    readable: bool = True
+    description: str = ""
+    characters: int = 0
+    npcs: int = 0
+    locations: int = 0
+    quests: int = 0
+    session_notes: int = 0
+    events: int = 0
+    current_session: int = 1
+
+
+def read_entry(path: Path) -> CampaignEntry:
+    """The summary of one campaign file; never raises for a bad file."""
+    modified = datetime.fromtimestamp(modified_at(path))
+    try:
+        data = read_json(path)
+    except (OSError, ValueError, RecursionError):
+        data = None
+    if not isinstance(data, dict):
+        return CampaignEntry(
+            name=f"{path.stem} (unreadable)", path=path, modified=modified, readable=False
+        )
+    name = data.get("name")
+    state = data.get("game_state")
+    session = state.get("current_session") if isinstance(state, dict) else None
+    return CampaignEntry(
+        name=name if isinstance(name, str) and name else path.stem,
+        path=path,
+        modified=modified,
+        description=str(data.get("description") or ""),
+        characters=_count(data, "characters"),
+        npcs=_count(data, "npcs"),
+        locations=_count(data, "locations"),
+        quests=_count(data, "quests"),
+        session_notes=_count(data, "sessions"),
+        events=_count(data, "events"),
+        current_session=session if isinstance(session, int) else 1,
+    )
+
+
+def _count(data: dict[str, Any], key: str) -> int:
+    value = data.get(key)
+    return len(value) if isinstance(value, dict | list) else 0
+
+
+def modified_at(path: Path) -> float:
+    """When *path* last changed; 0 for a file gone or a dangling link."""
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0

dndkit/storage/confirmations.py

@@ -0,0 +1,54 @@
+"""One-time codes a destructive action must be called back with.
+
+A spoken "delete the campaign" may be misheard. The first call only issues a
+code and says what would be lost; the action happens on a second call that
+carries the code, which the model makes after the players say yes. A code
+serves once, for one target, and expires; a wrong code cancels the request.
+"""
+
+import secrets
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+CODE_TTL_SECONDS = 300.0
+
+
+@dataclass(frozen=True)
+class _Pending:
+    code: str
+    expires_at: float
+
+
+class Confirmations:
+    """Pending confirmation codes, one per target."""
+
+    def __init__(
+        self, ttl: float = CODE_TTL_SECONDS, clock: Callable[[], float] = time.monotonic
+    ) -> None:
+        self._ttl = ttl
+        self._clock = clock
+        self._pending: dict[str, _Pending] = {}
+        self._lock = threading.Lock()
+
+    @property
+    def ttl_minutes(self) -> int:
+        """The lifetime of a code, in whole minutes, for messages."""
+        return max(1, round(self._ttl / 60))
+
+    def issue(self, target: str) -> str:
+        """A fresh 4-digit code for *target*; it replaces any earlier one."""
+        code = f"{secrets.randbelow(10_000):04d}"
+        with self._lock:
+            self._pending[target] = _Pending(code=code, expires_at=self._clock() + self._ttl)
+        return code
+
+    def consume(self, target: str, code: str) -> bool:
+        """Whether *code* confirms *target*. Either way the pending code is spent."""
+        with self._lock:
+            pending = self._pending.pop(target, None)
+        if pending is None or self._clock() > pending.expires_at:
+            return False
+        # Bytes: compare_digest refuses a str that is not ASCII ("zéro").
+        return secrets.compare_digest(pending.code.encode(), code.strip().encode())

dndkit/storage/files.py

@@ -0,0 +1,55 @@
+"""File primitives: campaign file names and crash-safe JSON writes."""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from dndkit.errors import InvalidChangeError
+from dndkit.text import normalize
+
+_NAME_CHARS = (" ", "-", "_")
+
+
+def campaign_slug(name: str) -> str:
+    """The file stem for a campaign name: letters, digits, spaces, '-' and '_'.
+
+    It cannot leave the campaigns directory: '/', '\\' and '.' never survive.
+    """
+    kept = "".join(c for c in name if c.isalnum() or c in _NAME_CHARS)
+    slug = " ".join(kept.split())
+    if not slug:
+        raise InvalidChangeError(f"Campaign name '{name}' needs at least one letter or digit.")
+    return slug
+
+
+def same_slug(a: str, b: str) -> bool:
+    """Two stems that name one campaign: case and accents aside, as spoken names go
+    ("le phare eteint" opens "Le Phare Éteint")."""
+    return normalize(a) == normalize(b)
+
+
+def write_json_atomic(path: Path, data: Any) -> None:
+    """Write JSON so a crash leaves either the old file or the new one, never half.
+
+    The temporary file sits next to the target (same filesystem, so the rename
+    is atomic) and ends in ``.tmp``, which the ``*.json`` scans never pick up.
+    """
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.stem}.", suffix=".tmp")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, ensure_ascii=False, indent=1)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def read_json(path: Path) -> Any:
+    """Parse one JSON file."""
+    with path.open(encoding="utf-8") as handle:
+        return json.load(handle)

dndkit/storage/sharing.py

@@ -0,0 +1,67 @@
+"""Sharing the data directory with another process: a second MCP client, a
+restart that overlaps the old server, a campaign file edited by hand.
+
+Changes take turns through an advisory lock on ``<data dir>/.lock``, and the
+store reads the active campaign again whenever its file changed since it last
+read or wrote it. Every change is saved at once, so reading the file again
+loses nothing of ours; without it, each process would overwrite the other's
+changes with its own copy.
+"""
+
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO
+
+LOCK_FILE = ".lock"
+
+
+@dataclass(frozen=True)
+class Stamp:
+    """What tells two versions of a file apart: an atomic write makes a new inode."""
+
+    inode: int
+    modified_ns: int
+    size: int
+
+
+def stamp(path: Path) -> Stamp | None:
+    """*path*'s stamp, or None when it is gone."""
+    try:
+        info = path.stat()
+    except OSError:
+        return None
+    return Stamp(info.st_ino, info.st_mtime_ns, info.st_size)
+
+
+class DiskLock:
+    """An exclusive advisory lock across processes (none on Windows, where the
+    stamps alone catch a change made elsewhere)."""
+
+    def __init__(self, data_dir: Path) -> None:
+        self._path = data_dir / LOCK_FILE
+        self._file: IO[bytes] | None = None
+
+    @contextmanager
+    def held(self) -> Iterator[None]:
+        """Hold the lock for a change; another process waits its turn."""
+        if sys.platform == "win32":
+            yield
+            return
+        import fcntl
+
+        if self._file is None:
+            self._file = open(self._path, "ab")  # noqa: SIM115 - kept open, like the lock
+        fcntl.flock(self._file.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(self._file.fileno(), fcntl.LOCK_UN)
+
+    def close(self) -> None:
+        """Let go of the lock file (the process's end does it too)."""
+        if self._file is not None:
+            self._file.close()
+            self._file = None