run-dmcp 0.1.0 → 0.3.0

package/dist/register/timeline.js

@@ -0,0 +1,311 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+import { replay } from "../timeline/replay.js";
+import { declareTimeAxis, setStoryTime, currentStoryTime } from "../timeline/clock.js";
+import { declareIrreversible, listIrreversibleFacts } from "../timeline/irreversible.js";
+import { exportTimelineToFile, importTimelineFromFile } from "../timeline/export.js";
+import { changesWithin } from "../timeline/changes.js";
+import { narrationConstraintAt } from "../timeline/narration.js";
+const log = createLogger("timeline");
+/**
+ * The `t` every tool below takes or returns. This is the surface an
+ * implementer actually meets the invariance property at (design §14, root
+ * CLAUDE.md hard rule 6) -- the description is deliberately short, because
+ * the property itself lives in `t.ts`'s `TimeAxis` doc comment; this is
+ * where a caller is reminded of it at the moment it matters.
+ */
+const tSchema = z
+    .number()
+    .finite()
+    .describe("An opaque ordinal on this game's declared time axis -- never a datetime, and never an " +
+    "index into units you might later re-cut.");
+/**
+ * Exactly the three variants `TimeAxis` (t.ts) allows, and no index-into-
+ * units fourth one -- the schema shape itself is part of what this issue
+ * asks for. `sequence` needs no `unit`; `elapsed`/`counter` need a
+ * caller-named one so the tool description alone can't be mistaken for
+ * always meaning "seconds".
+ */
+const timeAxisSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("sequence").describe("The engine's own append ordinal, one tick per write. Default for a game that declares nothing."),
+    }),
+    z.object({
+        kind: z.literal("elapsed").describe("Time since a fixed origin."),
+        unit: z.string().min(1).max(100).describe("What the elapsed count is measured in (e.g. 'second', 'minute')."),
+    }),
+    z.object({
+        kind: z.literal("counter").describe("A count of things that happened -- turns, ticks -- not of things authored."),
+        unit: z.string().min(1).max(100).describe("What is being counted (e.g. 'turn', 'tick')."),
+    }),
+]);
+export function registerTimelineTools(server) {
+    server.registerTool("replay_world_at", {
+        description: "Replay a game's world as it stood at a given t: every entity alive then, with every fact valid then. Works at any point in the game's recorded history, not only 'now'.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t }) => {
+        try {
+            const snapshot = replay({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(snapshot, null, 2) }] };
+        }
+        catch (error) {
+            log.error("replay_world_at failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("changes_within", {
+        description: "List every event and fact-interval transition a game recorded in the half-open window [t0, t1) -- t0 is in, t1 is not. The range companion to replay_world_at's point query, for callers whose units have duration. A fact that both opens and closes inside the window returns two rows, one per endpoint. Returns rows and nothing else: no verdict, no severity, no judgement about whether the window is 'clean'. What a change inside a window means is the caller's policy, not the engine's.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t0: tSchema.describe("Start of the window, inclusive. Same axis as every other t for this game."),
+            t1: tSchema.describe("End of the window, exclusive. Must be >= t0. There is no open-ended form and no start-plus-length form -- a window is two points on the axis, never a point and a duration."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t0, t1 }) => {
+        try {
+            const changeSet = changesWithin({ gameId, t0, t1 });
+            return { content: [{ type: "text", text: JSON.stringify(changeSet, null, 2) }] };
+        }
+        catch (error) {
+            log.error("changes_within failed", { gameId, t0, t1, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("get_story_time", {
+        description: "Get a game's current position on its own timeline: t, and the axis it is measured on.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId }) => {
+        try {
+            const storyTime = currentStoryTime(gameId);
+            if (!storyTime) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: `timeline: game '${gameId}' has no timeline clock yet -- nothing has been declared or written for it`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("get_story_time failed", { gameId, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("declare_time_axis", {
+        description: "Declare the axis a game's t is measured on -- fixed for the life of that game's timeline once set for real. Call this before creating anything else so the game's world starts at its own origin, not partway up the engine's default append ordinal. A game that already has a recorded t (e.g. from its own creation) has a floor there: startAt below it is refused with the floor named, never silently shifted down to fit.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            axis: timeAxisSchema.describe("The time axis. There is no variant for an index into units you might later re-cut -- only sequence, elapsed, or counter."),
+            startAt: z
+                .number()
+                .finite()
+                .optional()
+                .describe("Where this axis's t should start (or continue); defaults to 0 for a brand-new game, or to the current t otherwise. Must never be behind the current t."),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, axis, startAt }) => {
+        try {
+            const storyTime = declareTimeAxis({ gameId, axis, startAt });
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("declare_time_axis failed", {
+                gameId,
+                axis,
+                startAt,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("set_story_time", {
+        description: "Move a game's t forward on its declared axis. Only works once a non-sequence axis has been declared -- the engine's own append ordinal cannot be positioned by a caller. Never moves t backwards, including below whatever floor the axis inherited at declaration time.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, t }) => {
+        try {
+            const storyTime = setStoryTime({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(storyTime, null, 2) }] };
+        }
+        catch (error) {
+            log.error("set_story_time failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("declare_fact_irreversible", {
+        description: "Mark the fact currently open for one entity and key as irreversible: from its valid_from_t onward, the engine refuses any later assertion of a different value under that key. The temporal member of the same constraint family as bounded, monotonic and conserved sets. Closing the fact, and deleting the entity, both remain legal -- ending a record is not asserting its opposite -- but reopening the key at a different value is still refused. Irreversibility cannot be withdrawn once declared. Because the flag is per-fact, a property you intend to declare irreversible must live under its own key: declaring it locks the whole value stored under that key.",
+        inputSchema: {
+            entityId: z
+                .string()
+                .max(100)
+                .describe("The entity ID -- the same id as the row it was projected from (e.g. a resource ID)"),
+            key: z
+                .string()
+                .max(200)
+                .describe("The fact key, i.e. the column name the fact was projected from (e.g. 'value')"),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ entityId, key }) => {
+        try {
+            const fact = declareIrreversible({ entityId, key });
+            return { content: [{ type: "text", text: JSON.stringify(fact, null, 2) }] };
+        }
+        catch (error) {
+            log.error("declare_fact_irreversible failed", {
+                entityId,
+                key,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_irreversible_facts", {
+        description: "List every fact declared irreversible in a game, optionally narrowed to one entity. Each row carries the fact, its valid_from_t, and the event that opened it -- one hop of provenance, so a reviewer meeting a refusal can tell whether the fact is wrong or the claim is. Returns rows, never a verdict.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            entityId: z.string().max(100).optional().describe("Narrow the listing to one entity"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, entityId }) => {
+        try {
+            const facts = listIrreversibleFacts({ gameId, entityId });
+            return { content: [{ type: "text", text: JSON.stringify(facts, null, 2) }] };
+        }
+        catch (error) {
+            log.error("list_irreversible_facts failed", {
+                gameId,
+                entityId,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * Both export tools deal in a PATH and return only counts, never the
+     * artifact itself. That is design §6's point -- the deliverable is a file
+     * the client owns, not a payload passed back through a conversation -- and
+     * it is also what keeps a whole world's timeline from being pasted into
+     * the caller's context window, which is how a tool result kills the
+     * conversation that asked for it.
+     */
+    server.registerTool("export_timeline", {
+        description: "Freeze a game's entire timeline -- every entity, every fact interval, every event, and the declared time axis -- into a JSON file the caller owns. Deterministic: the same world exports byte-identically every time. Carries no media references and no live table rows by design, so the file can be re-imported anywhere and answer replay(t) identically. Returns the path and row counts, never the artifact itself.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            filePath: z.string().min(1).max(4096).describe("Absolute path to write the export file to"),
+        },
+        annotations: ANNOTATIONS.IDEMPOTENT_UPDATE,
+    }, async ({ gameId, filePath }) => {
+        try {
+            const artifact = exportTimelineToFile({ gameId, filePath });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            filePath,
+                            gameId: artifact.gameId,
+                            formatVersion: artifact.formatVersion,
+                            entities: artifact.entities.length,
+                            facts: artifact.facts.length,
+                            events: artifact.events.length,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            log.error("export_timeline failed", { gameId, filePath, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("import_timeline", {
+        description: "Restore a frozen timeline export into this database, verbatim -- ids and every t are carried through unchanged. Refuses rather than merges if the game already has any recorded history, and refuses an artifact whose rows do not all belong to the game it names. Imports the timeline only; the live tables are not repopulated.",
+        inputSchema: {
+            filePath: z.string().min(1).max(4096).describe("Absolute path of the export file to read"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ filePath }) => {
+        try {
+            const result = importTimelineFromFile(filePath);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            log.error("import_timeline failed", { filePath, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("narration_constraint_at", {
+        description: "Return what IS true for a game at t, and nothing else: every fact valid then on an entity alive then, plus every irreversible fact from valid_from_t onward even if it has since closed or its entity has been destroyed. Each fact carries one hop of causality -- the event that opened it, if any is recorded -- so a reviewer can tell whether a disputed fact or a disputed claim is the one that's wrong. This tool does not check anything and returns no verdict: it hands back the serialized constraint so a caller can run its own check (a live one now, or an offline lint over the saved JSON hours later) -- see the library-exported `contradictions` function for that half, which takes no database and is not exposed as a tool because wrapping a pure function in a tool call would defeat the point of it being callable offline.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: tSchema,
+            entityIds: z
+                .array(z.string().max(100))
+                .optional()
+                .describe("Narrow the constraint to only these entities. Omit for the whole game; an empty array narrows to nothing."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t, entityIds }) => {
+        try {
+            const constraint = narrationConstraintAt({ gameId, t, entityIds });
+            return { content: [{ type: "text", text: JSON.stringify(constraint, null, 2) }] };
+        }
+        catch (error) {
+            log.error("narration_constraint_at failed", {
+                gameId,
+                t,
+                entityIds,
+                error: error.message,
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/rpg/index.d.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Mechanic } from "../timeline/resolve.js";
+import type { RenderVocabulary } from "../timeline/render.js";
+/**
+ * Register every RPG-layer tool, resource and prompt onto an existing
+ * server. Combat brings dice with it (registerCombatTools registers both,
+ * matching how the pre-split assembly registered them as one domain).
+ */
+export declare function registerRpgTools(server: McpServer): void;
+/**
+ * Build the FULL assembly: every core tool plus every RPG tool, resource and
+ * prompt this engine has always served. Same name, same `{ mechanics?,
+ * vocabulary? }` options as the pre-split `createMcpServer` in
+ * src/mcp-server.ts -- this is that function, now composed from two layers
+ * instead of one, so src/bin/run-dmcp.ts's zero-argument call site keeps
+ * working unchanged and the registered tool/resource/prompt set is
+ * unchanged too (src/__tests__/layerBoundary.test.ts asserts this exactly).
+ */
+export declare function createMcpServer(options?: {
+    mechanics?: readonly Mechanic[];
+    vocabulary?: RenderVocabulary;
+}): McpServer;
+export { createHttpServer, startHttpServer } from "../http/server.js";
+export * from "./tools/dice.js";
+export * from "./tools/combat.js";
+export * from "./tools/ability.js";
+export * from "./tools/status.js";
+export * from "./tools/tables.js";
+export * from "./tools/quest.js";

package/dist/rpg/index.js

@@ -0,0 +1,55 @@
+import { createCoreMcpServer } from "../mcp-server.js";
+import { registerCombatTools } from "./register/combat.js";
+import { registerAbilityTools } from "./register/abilities.js";
+import { registerStatusTools } from "./register/status.js";
+import { registerTableTools } from "./register/tables.js";
+import { registerQuestTools } from "./register/quests.js";
+import { registerRpgBatchTools } from "./register/batch.js";
+import { registerRpgMcpResources } from "./register/mcp-resources.js";
+import { registerMcpPrompts } from "./register/mcp-prompts.js";
+/**
+ * Register every RPG-layer tool, resource and prompt onto an existing
+ * server. Combat brings dice with it (registerCombatTools registers both,
+ * matching how the pre-split assembly registered them as one domain).
+ */
+export function registerRpgTools(server) {
+    registerCombatTools(server); // Combat, Dice, Checks
+    registerQuestTools(server); // Quests, Objectives
+    registerTableTools(server); // Random Tables
+    registerStatusTools(server); // Status Effects
+    registerAbilityTools(server); // Abilities/Powers
+    registerRpgBatchTools(server); // setup_combat_encounter
+    registerRpgMcpResources(server); // game-quests, quest
+    registerMcpPrompts(server); // Reusable prompt templates (game-master session library)
+}
+/**
+ * Build the FULL assembly: every core tool plus every RPG tool, resource and
+ * prompt this engine has always served. Same name, same `{ mechanics?,
+ * vocabulary? }` options as the pre-split `createMcpServer` in
+ * src/mcp-server.ts -- this is that function, now composed from two layers
+ * instead of one, so src/bin/run-dmcp.ts's zero-argument call site keeps
+ * working unchanged and the registered tool/resource/prompt set is
+ * unchanged too (src/__tests__/layerBoundary.test.ts asserts this exactly).
+ */
+export function createMcpServer(options) {
+    const server = createCoreMcpServer(options);
+    registerRpgTools(server);
+    return server;
+}
+// The web UI. An application opts into serving it; importing this never
+// does. It lives on disk at src/http/server.ts, not under src/rpg/ -- it
+// imports RPG tools (quest/ability/combat), which is why it cannot be
+// reachable from the core entry point, but its CLIENT_DIST path resolution
+// is depth-sensitive in both src/ and compiled dist/, so it stays put and
+// only its EXPORT moves up to this layer.
+export { createHttpServer, startHttpServer } from "../http/server.js";
+// The RPG tool modules, exported as library functions -- the same shape
+// core's index.ts uses for the timeline (replay, changesWithin, and so on):
+// a consumer that wants to call combat/quest/table/status/ability/dice logic
+// directly, without going through an MCP tool call, can.
+export * from "./tools/dice.js";
+export * from "./tools/combat.js";
+export * from "./tools/ability.js";
+export * from "./tools/status.js";
+export * from "./tools/tables.js";
+export * from "./tools/quest.js";

package/dist/rpg/register/abilities.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAbilityTools(server: McpServer): void;

package/dist/rpg/register/abilities.js

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import * as abilityTools from "../tools/ability.js";
+import { LIMITS } from "../../utils/validation.js";
+import { ANNOTATIONS } from "../../utils/tool-annotations.js";
+export function registerAbilityTools(server) {
+    server.registerTool("create_ability", {
+        description: "Create an ability template or character-owned ability",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            ownerType: z.enum(["template", "character"]).describe("'template' for reusable, 'character' for owned"),
+            ownerId: z.string().max(100).optional().describe("Character ID if ownerType is 'character'"),
+            name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Ability name"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("Ability description"),
+            category: z.string().max(100).optional().describe("Category (e.g., 'spell', 'skill', 'power')"),
+            cost: z.record(z.number()).optional().describe("Resource costs (e.g., {mana: 10, stamina: 5})"),
+            cooldown: z.number().optional().describe("Cooldown in rounds"),
+            effects: z.array(z.string().max(LIMITS.DESCRIPTION_MAX)).max(LIMITS.ARRAY_MAX).optional().describe("Effect descriptions"),
+            requirements: z.record(z.number()).optional().describe("Requirements (e.g., {level: 5, strength: 10})"),
+            tags: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX).optional().describe("Tags for categorization"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async (params) => {
+        const ability = abilityTools.createAbility(params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(ability, null, 2) }],
+        };
+    });
+    server.registerTool("get_ability", {
+        description: "Get an ability by ID",
+        inputSchema: {
+            abilityId: z.string().max(100).describe("The ability ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ abilityId }) => {
+        const ability = abilityTools.getAbility(abilityId);
+        if (!ability) {
+            return {
+                content: [{ type: "text", text: "Ability not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(ability, null, 2) }],
+        };
+    });
+    server.registerTool("update_ability", {
+        description: "Update an ability's details",
+        inputSchema: {
+            abilityId: z.string().max(100).describe("The ability ID"),
+            name: z.string().max(LIMITS.NAME_MAX).optional().describe("New name"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("New description"),
+            category: z.string().max(100).nullable().optional().describe("New category"),
+            cost: z.record(z.number()).optional().describe("New cost"),
+            cooldown: z.number().nullable().optional().describe("New cooldown"),
+            effects: z.array(z.string().max(LIMITS.DESCRIPTION_MAX)).max(LIMITS.ARRAY_MAX).optional().describe("New effects"),
+            requirements: z.record(z.number()).optional().describe("New requirements"),
+            tags: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX).optional().describe("New tags"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ abilityId, ...updates }) => {
+        const ability = abilityTools.updateAbility(abilityId, updates);
+        if (!ability) {
+            return {
+                content: [{ type: "text", text: "Ability not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(ability, null, 2) }],
+        };
+    });
+    server.registerTool("delete_ability", {
+        description: "Delete an ability",
+        inputSchema: {
+            abilityId: z.string().max(100).describe("The ability ID"),
+        },
+        annotations: ANNOTATIONS.DESTRUCTIVE,
+    }, async ({ abilityId }) => {
+        const success = abilityTools.deleteAbility(abilityId);
+        return {
+            content: [{ type: "text", text: success ? "Ability deleted" : "Ability not found" }],
+            isError: !success,
+        };
+    });
+    server.registerTool("list_abilities", {
+        description: "List abilities with optional filters",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            ownerType: z.enum(["template", "character"]).optional().describe("Filter by owner type"),
+            ownerId: z.string().max(100).optional().describe("Filter by owner ID"),
+            category: z.string().max(100).optional().describe("Filter by category"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, ...filter }) => {
+        const abilities = abilityTools.listAbilities(gameId, filter);
+        return {
+            content: [{ type: "text", text: JSON.stringify(abilities, null, 2) }],
+        };
+    });
+    server.registerTool("learn_ability", {
+        description: "Copy a template ability to a character",
+        inputSchema: {
+            templateId: z.string().max(100).describe("The template ability ID"),
+            characterId: z.string().max(100).describe("The character ID to learn the ability"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ templateId, characterId }) => {
+        const ability = abilityTools.learnAbility(templateId, characterId);
+        if (!ability) {
+            return {
+                content: [{ type: "text", text: "Template not found or is not a template" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(ability, null, 2) }],
+        };
+    });
+    server.registerTool("use_ability", {
+        description: "Use an ability (checks cooldown, sets new cooldown)",
+        inputSchema: {
+            abilityId: z.string().max(100).describe("The ability ID"),
+            characterId: z.string().max(100).describe("The character using the ability"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ abilityId, characterId }) => {
+        const result = abilityTools.useAbility(abilityId, characterId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool("tick_ability_cooldowns", {
+        description: "Reduce all ability cooldowns (call at end of round)",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            amount: z.number().optional().describe("Rounds to tick (default: 1)"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ gameId, amount }) => {
+        const updated = abilityTools.tickCooldowns(gameId, amount);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ updatedCount: updated.length, abilities: updated }, null, 2) }],
+        };
+    });
+    server.registerTool("check_ability_requirements", {
+        description: "Check if a character meets an ability's requirements",
+        inputSchema: {
+            abilityId: z.string().max(100).describe("The ability ID"),
+            characterId: z.string().max(100).describe("The character ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ abilityId, characterId }) => {
+        const result = abilityTools.checkRequirements(abilityId, characterId);
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "Ability or character not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/rpg/register/batch.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRpgBatchTools(server: McpServer): void;

package/dist/rpg/register/batch.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import * as characterTools from "../../tools/character.js";
+import * as narrativeTools from "../../tools/narrative.js";
+import * as combatTools from "../tools/combat.js";
+import { LIMITS } from "../../utils/validation.js";
+import { ANNOTATIONS } from "../../utils/tool-annotations.js";
+// The one multi-entity workflow tool that reaches into combat, split out of
+// src/register/batch.ts (design §8, issue #17): everything else there --
+// batch_create_npcs, scene_transition, get_character_context,
+// get_location_context -- touches only entity/property concepts and stays in
+// core. This one calls combatTools.startCombat, so it is genuinely
+// game-shaped and belongs in the RPG layer above it, not beside it.
+export function registerRpgBatchTools(server) {
+    // ============================================================================
+    // SETUP COMBAT ENCOUNTER - Create NPCs, start combat with all participants
+    // ============================================================================
+    server.registerTool("setup_combat_encounter", {
+        description: "Complete combat setup in one call: creates enemy NPCs and starts combat with all participants (enemies + players at location). Returns the ready-to-play combat state.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+            locationId: z.string().describe("Location where combat takes place"),
+            enemies: z
+                .array(z.object({
+                name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Enemy name"),
+                attributes: z.record(z.string(), z.number()).optional(),
+                status: z
+                    .object({
+                    health: z.number().optional(),
+                    maxHealth: z.number().optional(),
+                })
+                    .optional(),
+            }))
+                .min(1)
+                .max(10)
+                .describe("Enemies to create and add to combat"),
+            includePlayersAtLocation: z
+                .boolean()
+                .default(true)
+                .describe("Auto-add player characters at this location"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ gameId, locationId, enemies, includePlayersAtLocation = true }) => {
+        // 1. Create enemy NPCs
+        const createdEnemies = [];
+        for (const enemy of enemies) {
+            const character = characterTools.createCharacter({
+                gameId,
+                name: enemy.name,
+                isPlayer: false,
+                attributes: enemy.attributes,
+                status: enemy.status,
+                locationId,
+            });
+            createdEnemies.push(character);
+        }
+        // 2. Get players at location if needed
+        const participantIds = [...createdEnemies.map((e) => e.id)];
+        if (includePlayersAtLocation) {
+            const playersAtLocation = characterTools.listCharacters(gameId, {
+                isPlayer: true,
+                locationId,
+            });
+            participantIds.push(...playersAtLocation.map((p) => p.id));
+        }
+        // 3. Start combat with all participants
+        const combat = combatTools.startCombat({
+            gameId,
+            locationId,
+            participantIds,
+        });
+        // 4. Log the encounter start
+        narrativeTools.logEvent({
+            gameId,
+            eventType: "combat",
+            content: `Combat begins! ${createdEnemies.length} enemies attack.`,
+            metadata: {
+                enemyIds: createdEnemies.map((e) => e.id),
+                locationId,
+            },
+        });
+        const result = {
+            combat,
+            createdEnemies: createdEnemies.map((e) => ({ id: e.id, name: e.name })),
+            participantCount: participantIds.length,
+            summary: `Combat started with ${participantIds.length} participants. ${createdEnemies.length} enemies created.`,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+}

package/dist/rpg/register/combat.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCombatTools(server: McpServer): void;