run-dmcp 0.1.0 → 0.3.0

package/dist/register/batch.js

@@ -2,11 +2,15 @@ import { z } from "zod";
 import * as characterTools from "../tools/character.js";
 import * as worldTools from "../tools/world.js";
 import * as inventoryTools from "../tools/inventory.js";
-import * as combatTools from "../tools/combat.js";
 import * as narrativeTools from "../tools/narrative.js";
 import { LIMITS } from "../utils/validation.js";
 import { ANNOTATIONS } from "../utils/tool-annotations.js";
 import { imageGenSchema, voiceSchema } from "../schemas/index.js";
+// Multi-entity workflow tools over entity/property concepts -- characters,
+// locations, inventory. `setup_combat_encounter` used to live here too, but
+// it is the one tool in this file that reaches into combat (design §8, issue
+// #17), so it moved to `src/rpg/register/batch.ts`'s `registerRpgBatchTools`
+// and this file no longer imports combat at all.
 export function registerBatchTools(server) {
     // ============================================================================
     // BATCH CREATE NPCS - Create multiple NPCs at once
@@ -96,84 +100,6 @@ export function registerBatchTools(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,
-        };
-    });
-    // ============================================================================
     // SCENE TRANSITION - Move characters, log event
     // ============================================================================
     server.registerTool("scene_transition", {

package/dist/register/mcp-resources.d.ts

@@ -1,2 +1,11 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const createGameListCallback: (suffix: string, nameFormatter: (g: {
+    id: string;
+    name: string;
+}) => string) => () => Promise<{
+    resources: {
+        uri: string;
+        name: string;
+    }[];
+}>;
 export declare function registerMcpResources(server: McpServer): void;

package/dist/register/mcp-resources.js

@@ -2,9 +2,24 @@ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as gameTools from "../tools/game.js";
 import * as characterTools from "../tools/character.js";
 import * as worldTools from "../tools/world.js";
-import * as questTools from "../tools/quest.js";
 import * as narrativeTools from "../tools/narrative.js";
 import * as rulesTools from "../tools/rules.js";
+// Helper to create list callback for game-scoped resources. Hoisted to
+// module scope and exported (design §8, issue #17) so that
+// src/rpg/register/mcp-resources.ts's game-quests and quest resources --
+// the two RPG-shaped entries pulled out of this file -- share this one
+// implementation rather than growing a second copy of it.
+export const createGameListCallback = (suffix, nameFormatter) => {
+    return async () => {
+        const games = gameTools.listGames();
+        return {
+            resources: games.map((g) => ({
+                uri: `dmcp://game/${g.id}${suffix}`,
+                name: nameFormatter(g),
+            })),
+        };
+    };
+};
 export function registerMcpResources(server) {
     // ============================================================================
     // STATIC RESOURCES
@@ -28,18 +43,6 @@ export function registerMcpResources(server) {
     // ============================================================================
     // GAME-SCOPED RESOURCES (templated)
     // ============================================================================
-    // Helper to create list callback for game-scoped resources
-    const createGameListCallback = (suffix, nameFormatter) => {
-        return async () => {
-            const games = gameTools.listGames();
-            return {
-                resources: games.map((g) => ({
-                    uri: `dmcp://game/${g.id}${suffix}`,
-                    name: nameFormatter(g),
-                })),
-            };
-        };
-    };
     // Game details
     server.registerResource("game", new ResourceTemplate("dmcp://game/{gameId}", {
         list: createGameListCallback("", (g) => g.name),
@@ -171,25 +174,6 @@ export function registerMcpResources(server) {
             ],
         };
     });
-    // Game quests
-    server.registerResource("game-quests", new ResourceTemplate("dmcp://game/{gameId}/quests", {
-        list: createGameListCallback("/quests", (g) => `${g.name} - Quests`),
-    }), {
-        description: "All quests in the game",
-        mimeType: "application/json",
-    }, async (uri, variables) => {
-        const gameId = variables.gameId;
-        const quests = questTools.listQuests(gameId);
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "application/json",
-                    text: JSON.stringify(quests, null, 2),
-                },
-            ],
-        };
-    });
     // Game history (recent narrative events)
     server.registerResource("game-history", new ResourceTemplate("dmcp://game/{gameId}/history", {
         list: createGameListCallback("/history", (g) => `${g.name} - History`),
@@ -302,34 +286,4 @@ export function registerMcpResources(server) {
             ],
         };
     });
-    // Quest by ID
-    server.registerResource("quest", new ResourceTemplate("dmcp://quest/{questId}", {
-        list: undefined, // No enumeration - access by ID only
-    }), {
-        description: "Quest details with objectives",
-        mimeType: "application/json",
-    }, async (uri, variables) => {
-        const questId = variables.questId;
-        const quest = questTools.getQuest(questId);
-        if (!quest) {
-            return {
-                contents: [
-                    {
-                        uri: uri.href,
-                        mimeType: "application/json",
-                        text: JSON.stringify({ error: "Quest not found" }),
-                    },
-                ],
-            };
-        }
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: "application/json",
-                    text: JSON.stringify(quest, null, 2),
-                },
-            ],
-        };
-    });
 }

package/dist/register/render.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { StateRenderer } from "../timeline/render.js";
+/**
+ * The MCP surface for the engine's state-to-text projection (design §7,
+ * §8, GitHub issue #16) -- one tool, `render_state_at`. Registered ONLY
+ * when a caller supplies a `StateRenderer` to `createCoreMcpServer`
+ * (src/mcp-server.ts), itself built by `createStateRenderer({ vocabulary
+ * })` (timeline/render.ts) over a caller-injected, caller-owned vocabulary.
+ * An engine with no injected vocabulary has nothing to name and registers
+ * no render tool at all -- the same "injection at construction" shape
+ * `registerResolveTools` (resolve.ts) already uses for its `Resolver`, and
+ * for the identical reason: there is no global renderer anywhere in this
+ * codebase, and this file carries no vocabulary of its own, not even an
+ * example (root CLAUDE.md hard rule 3, design §7's "mechanism is core, the
+ * vocabulary is injected").
+ */
+export declare function registerRenderTools(server: McpServer, renderer: StateRenderer): void;

package/dist/register/render.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+const log = createLogger("render");
+/**
+ * The MCP surface for the engine's state-to-text projection (design §7,
+ * §8, GitHub issue #16) -- one tool, `render_state_at`. Registered ONLY
+ * when a caller supplies a `StateRenderer` to `createCoreMcpServer`
+ * (src/mcp-server.ts), itself built by `createStateRenderer({ vocabulary
+ * })` (timeline/render.ts) over a caller-injected, caller-owned vocabulary.
+ * An engine with no injected vocabulary has nothing to name and registers
+ * no render tool at all -- the same "injection at construction" shape
+ * `registerResolveTools` (resolve.ts) already uses for its `Resolver`, and
+ * for the identical reason: there is no global renderer anywhere in this
+ * codebase, and this file carries no vocabulary of its own, not even an
+ * example (root CLAUDE.md hard rule 3, design §7's "mechanism is core, the
+ * vocabulary is injected").
+ */
+export function registerRenderTools(server, renderer) {
+    server.registerTool("render_state_at", {
+        description: "Render a game's world at t as positive concrete nouns, drawn only from the caller's own injected " +
+            "vocabulary -- 'the grain stores are full and the treasury coffers overflow', never 'the grain stores " +
+            "are no longer empty'. The renderer's sole source of state is replay(t): a fact that does not hold at " +
+            "t produces nothing, not a phrase about its absence. A fact that DOES hold but has no vocabulary entry " +
+            "is reported as an unnamed row rather than described or invented -- that is how a caller learns its " +
+            "vocabulary is too thin, without the engine passing judgement on it. No diff, no comparison against " +
+            "another t, and no transition/change form: state at one t, full stop.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            t: 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."),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, t }) => {
+        try {
+            const rendered = renderer.render({ gameId, t });
+            return { content: [{ type: "text", text: JSON.stringify(rendered, null, 2) }] };
+        }
+        catch (error) {
+            log.error("render_state_at failed", { gameId, t, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/register/resolve.d.ts

@@ -0,0 +1,14 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Resolver } from "../timeline/resolve.js";
+/**
+ * The MCP surface for the resolve protocol (design §5.2a, issue #10) --
+ * `resolve` and `list_mechanics`. Registered ONLY when a caller supplies a
+ * non-empty `mechanics` array to `createCoreMcpServer` (src/mcp-server.ts): an
+ * engine with no mechanics has no resolve surface, and that is the correct
+ * shape rather than a resolve tool that could only ever answer
+ * "unknown-mechanic" and a list_mechanics that could only ever answer `[]`.
+ * This keeps injection at construction -- there is still no global resolver
+ * anywhere in this codebase, only the one `Resolver` instance a caller built
+ * and handed in, closed over by the two tool handlers below.
+ */
+export declare function registerResolveTools(server: McpServer, resolver: Resolver): void;

package/dist/register/resolve.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { createLogger } from "../utils/logger.js";
+import { errors, formatErrorResponse } from "../utils/errors.js";
+import { ConstraintViolationError } from "../timeline/registry.js";
+import { ResolveProtocolError } from "../timeline/resolve.js";
+const log = createLogger("resolve");
+/**
+ * The MCP surface for the resolve protocol (design §5.2a, issue #10) --
+ * `resolve` and `list_mechanics`. Registered ONLY when a caller supplies a
+ * non-empty `mechanics` array to `createCoreMcpServer` (src/mcp-server.ts): an
+ * engine with no mechanics has no resolve surface, and that is the correct
+ * shape rather than a resolve tool that could only ever answer
+ * "unknown-mechanic" and a list_mechanics that could only ever answer `[]`.
+ * This keeps injection at construction -- there is still no global resolver
+ * anywhere in this codebase, only the one `Resolver` instance a caller built
+ * and handed in, closed over by the two tool handlers below.
+ */
+export function registerResolveTools(server, resolver) {
+    server.registerTool("resolve", {
+        description: "Propose a resolution to a registered mechanic and get back its outcome. The engine enforces the " +
+            "PROTOCOL -- resolution happens before narration, writes go through the audited path, declared " +
+            "expectations are checked before dispatch -- without knowing what the mechanic itself means. " +
+            "Refuses (no window opens, nothing is written) for an unknown mechanic, a game with no timeline " +
+            "clock, or a declared expectation that does not hold at the game's current t -- the last of these " +
+            "carries one hop of causality per contradicted expectation, so a caller can tell whether the fact " +
+            "is wrong or the claim is. A constraint violated mid-adjudication (bounded, monotonic, conserved, " +
+            "resolve_only, irreversible) rolls back every change in the resolution and records no event.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            mechanic: z.string().min(1).max(200).describe("The name of a mechanic registered with this resolver"),
+            parameters: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Opaque to the engine -- handed to the mechanic verbatim, never inspected here"),
+            expects: z
+                .array(z.object({
+                entityId: z.string().max(100).describe("The entity this expectation is about"),
+                key: z.string().max(200).describe("The fact key this expectation is about"),
+                value: z.union([z.string(), z.number()]).describe("The value this proposal declares it depends on"),
+            }))
+                .optional()
+                .describe("Facts this proposal declares it depends on, verified BEFORE the mechanic is dispatched. A caller's " +
+                "own declared precondition -- the engine only reports whether it holds, never why it should."),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ gameId, mechanic, parameters, expects }) => {
+        try {
+            const outcome = resolver.resolve({ gameId, mechanic, parameters, expects });
+            return { content: [{ type: "text", text: JSON.stringify(outcome, null, 2) }] };
+        }
+        catch (error) {
+            if (error instanceof ResolveProtocolError) {
+                log.error("resolve refused", { gameId, mechanic, reason: error.reason, error: error.message });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: error.message,
+                                reason: error.reason,
+                                contradictions: error.contradictions ?? undefined,
+                            }, null, 2),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (error instanceof ConstraintViolationError) {
+                log.error("resolve rolled back", {
+                    gameId,
+                    mechanic,
+                    constraintKind: error.constraintKind,
+                    error: error.message,
+                });
+                return formatErrorResponse(errors.constraintViolation(error.resourceId, error.message));
+            }
+            log.error("resolve failed", { gameId, mechanic, error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("list_mechanics", {
+        description: "List every mechanic name registered with this resolver. The engine holds these names; it never " +
+            "reads meaning into them -- they are exactly what a caller handed to createCoreMcpServer's mechanics option.",
+        inputSchema: {},
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async () => {
+        try {
+            return { content: [{ type: "text", text: JSON.stringify(resolver.mechanics(), null, 2) }] };
+        }
+        catch (error) {
+            log.error("list_mechanics failed", { error: error.message });
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/register/resources.js

@@ -9,7 +9,7 @@ export function registerResourceTools(server) {
         description: "Create a new resource (currency, reputation, counter, etc.)",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            ownerType: z.enum(["game", "character"]).describe("Owner type: 'game' for party/global resources, 'character' for personal resources"),
+            ownerType: z.enum(["game", "character", "faction", "location"]).describe("Owner type: 'game' for party/global resources, 'character' for personal resources, 'faction' or 'location' for resources owned by one of those entities"),
             ownerId: z.string().max(100).optional().describe("Character ID if ownerType is 'character' (omit for game-level resources)"),
             name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Resource name (e.g., 'Gold', 'Sanity', 'Thieves Guild Reputation')"),
             description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("Resource description"),
@@ -105,7 +105,7 @@ export function registerResourceTools(server) {
         description: "List resources in a game",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            ownerType: z.enum(["game", "character"]).optional().describe("Filter by owner type"),
+            ownerType: z.enum(["game", "character", "faction", "location"]).optional().describe("Filter by owner type"),
             ownerId: z.string().max(100).optional().describe("Filter by owner ID (for character resources)"),
             category: z.string().max(100).optional().describe("Filter by category"),
         },
@@ -207,17 +207,19 @@ export function registerResourceTools(server) {
         description: "Declare a server-enforced invariant on one or more resources, so update_resource_value cannot write a value that violates it. " +
             "'bounded': the resource must already have minValue and/or maxValue set (via create_resource/update_resource) -- once declared, writes outside those bounds are REJECTED instead of the default silent clamp. " +
             "'monotonic': the resource's value may only move in one direction ('increasing' = never decreases, 'decreasing' = never increases); holding steady is always allowed. " +
-            "'conserved': declares a set of 2+ resources that must always sum to a fixed total -- the members' current values must already sum to `total` (this does not rewrite them to match). Once declared, update_resource_value REJECTS direct writes to any member (ambiguous -- it can't know where the offsetting change comes from); use transfer_resource_value to move value between two members of the set atomically instead. A resource can belong to at most one 'conserved' set at a time.",
+            "'conserved': declares a set of 2+ resources that must always sum to a fixed total -- the members' current values must already sum to `total` (this does not rewrite them to match). Once declared, update_resource_value REJECTS direct writes to any member (ambiguous -- it can't know where the offsetting change comes from); use transfer_resource_value to move value between two members of the set atomically instead. A resource can belong to at most one 'conserved' set at a time. " +
+            "'resolve_only': every DIRECT write to the given fact key is refused -- both update_resource_value and transfer_resource_value -- so it can move only through an adjudicating call. Scoped to one fact key (factKey, default 'value'); a resource can hold a separate 'resolve_only' declaration per fact key.",
         inputSchema: {
             gameId: z.string().max(100).describe("The game ID"),
-            kind: z.enum(["bounded", "monotonic", "conserved"]).describe("Constraint kind"),
-            resourceId: z.string().max(100).optional().describe("Required for 'bounded' or 'monotonic': the resource to constrain"),
+            kind: z.enum(["bounded", "monotonic", "conserved", "resolve_only"]).describe("Constraint kind"),
+            resourceId: z.string().max(100).optional().describe("Required for 'bounded', 'monotonic' or 'resolve_only': the resource to constrain"),
             resourceIds: z.array(z.string().max(100)).optional().describe("Required for 'conserved': 2 or more resource IDs that must sum to `total`"),
             direction: z.enum(["increasing", "decreasing"]).optional().describe("Required for 'monotonic': the only direction the value may move"),
             total: z.number().optional().describe("Required for 'conserved': the fixed sum the resource set must maintain"),
+            factKey: z.string().max(100).optional().describe("For 'resolve_only' only: the fact key the constraint governs, defaulting to 'value'"),
         },
         annotations: ANNOTATIONS.CREATE,
-    }, async ({ gameId, kind, resourceId, resourceIds, direction, total }) => {
+    }, async ({ gameId, kind, resourceId, resourceIds, direction, total, factKey }) => {
         try {
             let constraint;
             if (kind === "bounded") {
@@ -231,6 +233,11 @@ export function registerResourceTools(server) {
                 }
                 constraint = constraintTools.declareMonotonicConstraint({ gameId, resourceId, direction });
             }
+            else if (kind === "resolve_only") {
+                if (!resourceId)
+                    throw new Error("resourceId is required for a 'resolve_only' constraint");
+                constraint = constraintTools.declareResolveOnlyConstraint({ gameId, resourceId, factKey });
+            }
             else {
                 if (!resourceIds || total === undefined) {
                     throw new Error("resourceIds and total are required for a 'conserved' constraint");

package/dist/register/timeline.d.ts

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