run-dmcp 0.1.0

package/dist/register/time.js

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import * as timeTools from "../tools/time.js";
+import * as timerTools from "../tools/timers.js";
+import { LIMITS } from "../utils/validation.js";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+const gameDateTimeSchema = z.object({
+    year: z.number(),
+    month: z.number(),
+    day: z.number(),
+    hour: z.number(),
+    minute: z.number(),
+});
+// A declared, structured on-expiry consequence: when the event/timer
+// expires, the server applies this delta to the named resource itself, in
+// the same call, with no LLM action required. Opt-in -- omit entirely for
+// the old passive-only behavior.
+const expiryConsequenceSchema = z.object({
+    resourceId: z.string().max(100).describe("The resource to modify when this expires"),
+    delta: z.number().describe("Amount to add to the resource's value (negative to subtract)"),
+});
+export function registerTimeTools(server) {
+    // ============================================================================
+    // TIME/CALENDAR TOOLS
+    // ============================================================================
+    server.registerTool("set_calendar", {
+        description: "Configure the calendar system for a game (months, days per month, hours per day, etc.)",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            config: z.object({
+                monthNames: z.array(z.string().max(100)).max(24).optional().describe("Names of months"),
+                daysPerMonth: z.array(z.number()).max(24).optional().describe("Days in each month"),
+                hoursPerDay: z.number().optional().describe("Hours per day (default: 24)"),
+                minutesPerHour: z.number().optional().describe("Minutes per hour (default: 60)"),
+                startYear: z.number().optional().describe("Starting year number"),
+                eraName: z.string().max(LIMITS.NAME_MAX).optional().describe("Name of the era/age"),
+            }).optional().describe("Calendar configuration (defaults to fantasy calendar)"),
+            currentTime: gameDateTimeSchema.optional().describe("Starting time"),
+        },
+        annotations: ANNOTATIONS.SET,
+    }, async ({ gameId, config, currentTime }) => {
+        const gameTime = timeTools.setCalendar(gameId, config || {}, currentTime);
+        return {
+            content: [{ type: "text", text: JSON.stringify(gameTime, null, 2) }],
+        };
+    });
+    server.registerTool("get_time", {
+        description: "Get the current in-game time",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId }) => {
+        const gameTime = timeTools.getTime(gameId);
+        if (!gameTime) {
+            return {
+                content: [{ type: "text", text: "No calendar set for this game. Use set_calendar first." }],
+                isError: true,
+            };
+        }
+        const formatted = timeTools.formatDateTime(gameTime.currentTime, gameTime.calendarConfig);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ...gameTime, formatted }, null, 2) }],
+        };
+    });
+    server.registerTool("set_time", {
+        description: "Set the current in-game time to a specific value",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            time: gameDateTimeSchema.describe("The time to set"),
+        },
+        annotations: ANNOTATIONS.SET,
+    }, async ({ gameId, time }) => {
+        const gameTime = timeTools.setTime(gameId, time);
+        if (!gameTime) {
+            return {
+                content: [{ type: "text", text: "No calendar set for this game" }],
+                isError: true,
+            };
+        }
+        const formatted = timeTools.formatDateTime(gameTime.currentTime, gameTime.calendarConfig);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ...gameTime, formatted }, null, 2) }],
+        };
+    });
+    server.registerTool("advance_time", {
+        description: "Advance time by a duration. Any scheduled events whose trigger time is crossed fire, and their declared consequences (if any) are applied automatically -- no follow-up call needed. Check consequenceFailures for any that couldn't be applied (e.g. target resource missing); those events remain pending and are not silently marked handled.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            days: z.number().optional().describe("Days to advance"),
+            hours: z.number().optional().describe("Hours to advance"),
+            minutes: z.number().optional().describe("Minutes to advance"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ gameId, days, hours, minutes }) => {
+        const result = timeTools.advanceTime(gameId, { days, hours, minutes });
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "No calendar set for this game" }],
+                isError: true,
+            };
+        }
+        const gameTime = timeTools.getTime(gameId);
+        if (!gameTime) {
+            return {
+                content: [{ type: "text", text: "Failed to get time after advancing" }],
+                isError: true,
+            };
+        }
+        const formatted = timeTools.formatDateTime(result.newTime, gameTime.calendarConfig);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        ...result,
+                        formatted,
+                        triggeredCount: result.triggeredEvents.length,
+                    }, null, 2),
+                }],
+        };
+    });
+    server.registerTool("schedule_event", {
+        description: "Schedule an event to trigger at a specific in-game time. Optionally attach a consequence -- a resource delta the server applies itself the moment the event fires, atomically, with no further action required.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Event name"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("Event description"),
+            triggerTime: gameDateTimeSchema.describe("When the event should trigger"),
+            recurring: z.enum(["daily", "weekly", "monthly", "yearly"]).optional().describe("Recurrence pattern"),
+            metadata: z.record(z.string(), z.unknown()).optional().describe("Additional event data"),
+            consequence: expiryConsequenceSchema.optional().describe("Optional: a resource delta applied automatically when this event triggers"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async (params) => {
+        const event = timeTools.scheduleEvent(params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(event, null, 2) }],
+        };
+    });
+    server.registerTool("list_scheduled_events", {
+        description: "List upcoming scheduled events",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            includeTriggered: z.boolean().optional().describe("Include already-triggered events"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, includeTriggered }) => {
+        const events = timeTools.listScheduledEvents(gameId, includeTriggered);
+        return {
+            content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
+        };
+    });
+    server.registerTool("cancel_event", {
+        description: "Cancel a scheduled event",
+        inputSchema: {
+            eventId: z.string().max(100).describe("The event ID to cancel"),
+        },
+        annotations: ANNOTATIONS.DESTRUCTIVE,
+    }, async ({ eventId }) => {
+        const success = timeTools.cancelEvent(eventId);
+        return {
+            content: [{ type: "text", text: success ? "Event cancelled" : "Event not found" }],
+            isError: !success,
+        };
+    });
+    // ============================================================================
+    // TIMER TOOLS
+    // ============================================================================
+    server.registerTool("create_timer", {
+        description: "Create a countdown, stopwatch, or segmented clock. Optionally attach a consequence -- a resource delta the server applies itself the moment the timer crosses its trigger value, atomically, with no further action required.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Timer name (e.g., 'Doom Clock', 'Ritual Progress')"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("Timer description"),
+            timerType: z.enum(["countdown", "stopwatch", "clock"]).describe("Type: countdown (decreases), stopwatch (increases), clock (segmented like Blades in the Dark)"),
+            currentValue: z.number().optional().describe("Starting value"),
+            maxValue: z.number().optional().describe("Maximum value (for clocks: number of segments, default 6)"),
+            direction: z.enum(["up", "down"]).optional().describe("Direction of change"),
+            triggerAt: z.number().optional().describe("Value that triggers an event. If not provided, defaults to 0 for countdowns (direction 'down') or maxValue for stopwatches (direction 'up')"),
+            unit: z.string().max(100).optional().describe("Unit label (e.g., 'rounds', 'hours', 'segments')"),
+            visibleToPlayers: z.boolean().optional().describe("Whether players can see this timer"),
+            consequence: expiryConsequenceSchema.optional().describe("Optional: a resource delta applied automatically the moment this timer triggers"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async (params) => {
+        const timer = timerTools.createTimer(params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(timer, null, 2) }],
+        };
+    });
+    server.registerTool("get_timer", {
+        description: "Get timer details",
+        inputSchema: {
+            timerId: z.string().max(100).describe("The timer ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ timerId }) => {
+        const timer = timerTools.getTimer(timerId);
+        if (!timer) {
+            return {
+                content: [{ type: "text", text: "Timer not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(timer, null, 2) }],
+        };
+    });
+    server.registerTool("update_timer", {
+        description: "Update timer settings",
+        inputSchema: {
+            timerId: z.string().max(100).describe("The timer ID"),
+            name: z.string().max(LIMITS.NAME_MAX).optional().describe("New name"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).optional().describe("New description"),
+            maxValue: z.number().nullable().optional().describe("New max value"),
+            triggerAt: z.number().nullable().optional().describe("New trigger value"),
+            unit: z.string().max(100).optional().describe("New unit label"),
+            visibleToPlayers: z.boolean().optional().describe("Visibility to players"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ timerId, ...updates }) => {
+        const timer = timerTools.updateTimer(timerId, updates);
+        if (!timer) {
+            return {
+                content: [{ type: "text", text: "Timer not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(timer, null, 2) }],
+        };
+    });
+    server.registerTool("delete_timer", {
+        description: "Delete a timer",
+        inputSchema: {
+            timerId: z.string().max(100).describe("The timer ID"),
+        },
+        annotations: ANNOTATIONS.DESTRUCTIVE,
+    }, async ({ timerId }) => {
+        const success = timerTools.deleteTimer(timerId);
+        return {
+            content: [{ type: "text", text: success ? "Timer deleted" : "Timer not found" }],
+            isError: !success,
+        };
+    });
+    server.registerTool("list_timers", {
+        description: "List active timers in a game",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            includeTriggered: z.boolean().optional().describe("Include triggered timers"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, includeTriggered }) => {
+        const timers = timerTools.listTimers(gameId, includeTriggered);
+        return {
+            content: [{ type: "text", text: JSON.stringify(timers, null, 2) }],
+        };
+    });
+    // ============================================================================
+    // MODIFY TIMER - CONSOLIDATED (replaces tick_timer + reset_timer)
+    // ============================================================================
+    server.registerTool("modify_timer", {
+        description: "Modify a timer's state. Use mode 'tick' to advance by amount, or 'reset' to reset to initial state. If ticking crosses the timer's trigger value and it has a declared consequence, that consequence is applied automatically in this same call (see consequenceApplied on the result).",
+        inputSchema: {
+            timerId: z.string().max(100).describe("The timer ID"),
+            mode: z.enum(["tick", "reset"]).describe("'tick' to advance/reduce, 'reset' to reset to initial state"),
+            amount: z.number().optional().describe("Amount to tick (only for mode 'tick', default: 1)"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ timerId, mode, amount }) => {
+        const result = timerTools.modifyTimerState(timerId, { mode, amount });
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "Timer not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/dist/register/world.d.ts

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

package/dist/register/world.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import * as worldTools from "../tools/world.js";
+import { imageGenSchema } from "../schemas/index.js";
+import { LIMITS } from "../utils/validation.js";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+export function registerWorldTools(server) {
+    server.registerTool("create_location", {
+        description: "Create a new location in the game world. IMPORTANT: Call this IMMEDIATELY when describing any new place, BEFORE narrating what happens there. Every location the player visits or hears about should exist in the database.",
+        inputSchema: {
+            gameId: z.string().max(100).describe("The game ID"),
+            name: z.string().min(1).max(LIMITS.NAME_MAX).describe("Location name"),
+            description: z.string().max(LIMITS.DESCRIPTION_MAX).describe("Location description"),
+            properties: z.object({
+                features: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX).optional(),
+                atmosphere: z.string().max(LIMITS.DESCRIPTION_MAX).optional(),
+            }).optional().describe("Additional location properties"),
+            imageGen: imageGenSchema.optional().describe("Image generation metadata for location art"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ gameId, name, description, properties, imageGen }) => {
+        const location = worldTools.createLocation({ gameId, name, description, properties, imageGen });
+        return {
+            content: [{ type: "text", text: JSON.stringify(location, null, 2) }],
+        };
+    });
+    server.registerTool("get_location", {
+        description: "Get location details",
+        inputSchema: {
+            locationId: z.string().describe("The location ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ locationId }) => {
+        const location = worldTools.getLocation(locationId);
+        if (!location) {
+            return {
+                content: [{ type: "text", text: "Location not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(location, null, 2) }],
+        };
+    });
+    server.registerTool("update_location", {
+        description: "Update a location",
+        inputSchema: {
+            locationId: z.string().describe("The location ID"),
+            name: z.string().optional().describe("New name"),
+            description: z.string().optional().describe("New description"),
+            properties: z.record(z.string(), z.unknown()).optional().describe("Property updates"),
+            imageGen: imageGenSchema.nullable().optional().describe("Image generation metadata (null to remove)"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ locationId, name, description, properties, imageGen }) => {
+        const location = worldTools.updateLocation(locationId, { name, description, properties, imageGen });
+        if (!location) {
+            return {
+                content: [{ type: "text", text: "Location not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(location, null, 2) }],
+        };
+    });
+    server.registerTool("list_locations", {
+        description: "List all locations in a game",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId }) => {
+        const locations = worldTools.listLocations(gameId);
+        return {
+            content: [{ type: "text", text: JSON.stringify(locations, null, 2) }],
+        };
+    });
+    server.registerTool("connect_locations", {
+        description: "Create exits/paths between two locations. Call this whenever you describe how locations connect to each other - the player should be able to navigate based on database connections.",
+        inputSchema: {
+            fromLocationId: z.string().describe("First location ID"),
+            toLocationId: z.string().describe("Second location ID"),
+            fromDirection: z.string().describe("Direction from first location (e.g., 'north', 'up', 'through the door')"),
+            toDirection: z.string().describe("Direction from second location back (e.g., 'south', 'down')"),
+            description: z.string().optional().describe("Description of the path"),
+            bidirectional: z.boolean().optional().describe("Create exit in both directions (default: true)"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ fromLocationId, toLocationId, fromDirection, toDirection, description, bidirectional }) => {
+        const result = worldTools.connectLocations({
+            fromLocationId,
+            toLocationId,
+            fromDirection,
+            toDirection,
+            description,
+            bidirectional,
+        });
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "Failed to connect locations - one or both locations not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool("get_location_by_name", {
+        description: "Look up a location by name within a game. Supports exact, partial, and fuzzy matching. Returns the best match or an error if no reasonable match found.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID to search within"),
+            name: z.string().describe("Location name to search for (case-insensitive)"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, name }) => {
+        const location = worldTools.getLocationByName(gameId, name);
+        if (!location) {
+            return {
+                content: [{ type: "text", text: `No location found matching "${name}"` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(location, null, 2) }],
+        };
+    });
+}