run-dmcp 0.1.0

package/dist/register/batch.js

@@ -0,0 +1,343 @@
+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";
+export function registerBatchTools(server) {
+    // ============================================================================
+    // BATCH CREATE NPCS - Create multiple NPCs at once
+    // ============================================================================
+    server.registerTool("batch_create_npcs", {
+        description: "Create multiple NPCs at once. Use this when populating a location with several characters. Returns all created characters.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+            npcs: z
+                .array(z.object({
+                name: z.string().min(1).max(LIMITS.NAME_MAX).describe("NPC name"),
+                attributes: z.record(z.string(), z.number()).optional(),
+                skills: z.record(z.string(), z.number()).optional(),
+                status: z
+                    .object({
+                    health: z.number().optional(),
+                    maxHealth: z.number().optional(),
+                    conditions: z.array(z.string()).optional(),
+                })
+                    .optional(),
+                locationId: z.string().optional().describe("Starting location"),
+                notes: z.string().max(LIMITS.CONTENT_MAX).optional(),
+                voice: voiceSchema.optional(),
+                imageGen: imageGenSchema.optional(),
+            }))
+                .min(1)
+                .max(20)
+                .describe("Array of NPCs to create (max 20)"),
+        },
+        annotations: ANNOTATIONS.CREATE,
+    }, async ({ gameId, npcs }) => {
+        const created = [];
+        const errors = [];
+        // Check for duplicate names within the batch
+        const nameCount = new Map();
+        for (const npc of npcs) {
+            const lowerName = npc.name.toLowerCase();
+            nameCount.set(lowerName, (nameCount.get(lowerName) || 0) + 1);
+        }
+        const duplicates = Array.from(nameCount.entries())
+            .filter(([, count]) => count > 1)
+            .map(([name]) => name);
+        if (duplicates.length > 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            isError: true,
+                            errorCode: "DUPLICATE_NAMES_IN_BATCH",
+                            message: `Duplicate NPC names in batch: ${duplicates.join(", ")}`,
+                            suggestions: ["Ensure all NPC names in the batch are unique"],
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        for (const npc of npcs) {
+            try {
+                const character = characterTools.createCharacter({
+                    gameId,
+                    name: npc.name,
+                    isPlayer: false,
+                    attributes: npc.attributes,
+                    skills: npc.skills,
+                    status: npc.status,
+                    locationId: npc.locationId,
+                    notes: npc.notes,
+                    voice: npc.voice,
+                    imageGen: npc.imageGen,
+                });
+                created.push(character);
+            }
+            catch (e) {
+                errors.push({ name: npc.name, error: e.message });
+            }
+        }
+        const result = {
+            created,
+            errors,
+            summary: `Created ${created.length}/${npcs.length} NPCs`,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    // ============================================================================
+    // 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", {
+        description: "Complete scene transition in one call: moves specified characters to a new location and logs a narrative event. Perfect for moving between scenes.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+            characterIds: z
+                .array(z.string())
+                .min(1)
+                .describe("Characters to move to the new scene"),
+            destinationId: z.string().describe("Destination location ID"),
+            narrativeDescription: z
+                .string()
+                .max(LIMITS.DESCRIPTION_MAX)
+                .describe("Description of the transition for the narrative log"),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ gameId, characterIds, destinationId, narrativeDescription }) => {
+        // 1. Move all characters
+        const moved = [];
+        const errors = [];
+        for (const characterId of characterIds) {
+            try {
+                const character = characterTools.getCharacter(characterId);
+                if (character) {
+                    characterTools.updateCharacter(characterId, { locationId: destinationId });
+                    moved.push({ id: characterId, name: character.name });
+                }
+                else {
+                    errors.push({ characterId, error: "Character not found" });
+                }
+            }
+            catch (e) {
+                errors.push({ characterId, error: e.message });
+            }
+        }
+        // 2. Log the narrative event
+        narrativeTools.logEvent({
+            gameId,
+            eventType: "scene",
+            content: narrativeDescription,
+            metadata: {
+                characterIds: moved.map((m) => m.id),
+                locationId: destinationId,
+            },
+        });
+        // 3. Get destination location details
+        const destination = worldTools.getLocation(destinationId);
+        const result = {
+            moved,
+            errors,
+            destination: destination ? { id: destination.id, name: destination.name } : null,
+            summary: `Moved ${moved.length} characters to ${destination?.name || destinationId}`,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    // ============================================================================
+    // GET CHARACTER CONTEXT - Character with all related data
+    // ============================================================================
+    server.registerTool("get_character_context", {
+        description: "Get comprehensive character context in one call: character details, inventory, and current location info. Reduces multiple tool calls to one.",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ characterId }) => {
+        const character = characterTools.getCharacter(characterId);
+        if (!character) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            isError: true,
+                            errorCode: "CHARACTER_NOT_FOUND",
+                            message: `Character '${characterId}' not found`,
+                            suggestions: [
+                                "Use list_characters to see available characters",
+                                "Create a character with create_character",
+                            ],
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Get inventory
+        const inventory = inventoryTools.getInventory(characterId, "character");
+        // Get location details if available
+        let location = null;
+        if (character.locationId) {
+            location = worldTools.getLocation(character.locationId);
+        }
+        const result = {
+            character,
+            inventory,
+            location: location
+                ? {
+                    id: location.id,
+                    name: location.name,
+                    description: location.description,
+                }
+                : null,
+            summary: `${character.name} at ${location?.name || "unknown location"} with ${inventory.length} items`,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+    // ============================================================================
+    // GET LOCATION CONTEXT - Location with all related data
+    // ============================================================================
+    server.registerTool("get_location_context", {
+        description: "Get comprehensive location context in one call: location details, present characters, and items here. Reduces multiple tool calls to one.",
+        inputSchema: {
+            locationId: z.string().describe("The location ID"),
+            gameId: z.string().describe("The game ID (needed for character lookup)"),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ locationId, gameId }) => {
+        const location = worldTools.getLocation(locationId);
+        if (!location) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            isError: true,
+                            errorCode: "LOCATION_NOT_FOUND",
+                            message: `Location '${locationId}' not found`,
+                            suggestions: [
+                                "Use list_locations to see available locations",
+                                "Create a location with create_location",
+                            ],
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Get characters at this location
+        const characters = characterTools.listCharacters(gameId, { locationId });
+        // Get items at this location
+        const items = inventoryTools.getInventory(locationId, "location");
+        const result = {
+            location,
+            characters: characters.map((c) => ({
+                id: c.id,
+                name: c.name,
+                isPlayer: c.isPlayer,
+            })),
+            items: items.map((i) => ({
+                id: i.id,
+                name: i.name,
+            })),
+            summary: `${location.name}: ${characters.length} characters, ${items.length} items`,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
+}

package/dist/register/character.d.ts

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

package/dist/register/character.js

@@ -0,0 +1,324 @@
+import { z } from "zod";
+import * as characterTools from "../tools/character.js";
+import { imageGenSchema, voiceSchema } from "../schemas/index.js";
+import { LIMITS } from "../utils/validation.js";
+import { ANNOTATIONS } from "../utils/tool-annotations.js";
+import { characterOutputSchema, characterStatusSchema, conditionModifyOutputSchema, } from "../utils/output-schemas.js";
+import { verbositySchema, applyVerbosity } from "../utils/verbosity.js";
+export function registerCharacterTools(server) {
+    // ============================================================================
+    // CREATE CHARACTER - with annotations and output schema
+    // ============================================================================
+    server.registerTool("create_character", {
+        description: "Create a new character (PC or NPC). IMPORTANT: Call this IMMEDIATELY when introducing any named NPC in narrative, BEFORE continuing the scene. Every named character mentioned in dialogue or description 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("Character name"),
+            isPlayer: z.boolean().describe("True for player character, false for NPC"),
+            attributes: z.record(z.string().max(50), z.number()).optional().describe("Character attributes"),
+            skills: z.record(z.string().max(50), z.number()).optional().describe("Character skills"),
+            status: z.object({
+                health: z.number().optional(),
+                maxHealth: z.number().optional(),
+                conditions: z.array(z.string().max(100)).max(LIMITS.ARRAY_MAX).optional(),
+                experience: z.number().optional(),
+                level: z.number().optional(),
+            }).optional().describe("Initial status"),
+            locationId: z.string().max(100).optional().describe("Starting location"),
+            notes: z.string().max(LIMITS.CONTENT_MAX).optional().describe("Character notes"),
+            voice: voiceSchema.optional().describe("Voice characteristics for TTS/voice mode"),
+            imageGen: imageGenSchema.optional().describe("Image generation metadata for character portraits"),
+        },
+        outputSchema: characterOutputSchema,
+        annotations: ANNOTATIONS.CREATE,
+    }, async (params) => {
+        const character = characterTools.createCharacter(params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(character, null, 2) }],
+            structuredContent: character,
+        };
+    });
+    // ============================================================================
+    // GET CHARACTER - read-only with output schema
+    // ============================================================================
+    server.registerTool("get_character", {
+        description: "Get character details",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+        },
+        outputSchema: characterOutputSchema,
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ characterId }) => {
+        const character = characterTools.getCharacter(characterId);
+        if (!character) {
+            return {
+                content: [{ type: "text", text: "Character not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(character, null, 2) }],
+            structuredContent: character,
+        };
+    });
+    // ============================================================================
+    // UPDATE CHARACTER
+    // ============================================================================
+    server.registerTool("update_character", {
+        description: "Update character attributes, skills, status, or voice",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+            name: z.string().optional().describe("New name"),
+            attributes: z.record(z.string(), z.number()).optional().describe("Attribute updates"),
+            skills: z.record(z.string(), z.number()).optional().describe("Skill updates"),
+            status: z.record(z.string(), z.unknown()).optional().describe("Status updates"),
+            locationId: z.string().optional().describe("New location"),
+            notes: z.string().optional().describe("Notes update"),
+            voice: voiceSchema.nullable().optional().describe("Voice characteristics (null to remove)"),
+            imageGen: imageGenSchema.nullable().optional().describe("Image generation metadata (null to remove)"),
+        },
+        outputSchema: characterOutputSchema,
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ characterId, ...updates }) => {
+        const character = characterTools.updateCharacter(characterId, updates);
+        if (!character) {
+            return {
+                content: [{ type: "text", text: "Character not found" }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(character, null, 2) }],
+            structuredContent: character,
+        };
+    });
+    // ============================================================================
+    // LIST CHARACTERS - read-only with verbosity control
+    // ============================================================================
+    server.registerTool("list_characters", {
+        description: "List characters in a game. Use verbosity to control response size: 'minimal' for quick lookups (id/name only), 'standard' for common fields, 'full' for all details.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+            isPlayer: z.boolean().optional().describe("Filter by player/NPC"),
+            locationId: z.string().optional().describe("Filter by location"),
+            verbosity: verbositySchema,
+        },
+        outputSchema: {
+            characters: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                isPlayer: z.boolean().optional(),
+                status: characterStatusSchema.optional(),
+                locationId: z.string().nullable().optional(),
+            })),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, isPlayer, locationId, verbosity = 'standard' }) => {
+        const characters = characterTools.listCharacters(gameId, { isPlayer, locationId });
+        const filtered = applyVerbosity(characters, 'character', verbosity);
+        const output = { characters: filtered };
+        return {
+            content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }],
+            structuredContent: output,
+        };
+    });
+    // ============================================================================
+    // MOVE CHARACTER
+    // ============================================================================
+    server.registerTool("move_character", {
+        description: "Move a character to a different location",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+            locationId: z.string().describe("The destination location ID"),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            characterId: z.string(),
+            newLocationId: z.string(),
+            tip: z.string().optional(),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ characterId, locationId }) => {
+        const success = characterTools.moveCharacter(characterId, locationId);
+        if (!success) {
+            return {
+                content: [{ type: "text", text: "Failed to move character" }],
+                isError: true,
+            };
+        }
+        const output = {
+            success: true,
+            characterId,
+            newLocationId: locationId,
+            tip: "Consider describing the new location to the player or showing relevant details about what they see.",
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            structuredContent: output,
+        };
+    });
+    // ============================================================================
+    // MODIFY HEALTH - CONSOLIDATED (replaces apply_damage + heal_character)
+    // ============================================================================
+    server.registerTool("modify_health", {
+        description: "Modify a character's health. Use mode 'damage' to reduce health, or 'heal' to restore health.",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+            mode: z.enum(["damage", "heal"]).describe("'damage' to reduce health, 'heal' to restore health"),
+            amount: z.number().describe("Amount of damage or healing"),
+        },
+        outputSchema: {
+            characterId: z.string(),
+            previousHealth: z.number(),
+            newHealth: z.number(),
+            maxHealth: z.number(),
+            mode: z.enum(["damage", "heal"]),
+        },
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ characterId, mode, amount }) => {
+        const result = characterTools.modifyHealth(characterId, { mode, amount });
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "Character not found" }],
+                isError: true,
+            };
+        }
+        const output = {
+            characterId,
+            previousHealth: result.previousHealth,
+            newHealth: result.newHealth,
+            maxHealth: result.character.status.maxHealth,
+            mode,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            structuredContent: output,
+        };
+    });
+    // ============================================================================
+    // MODIFY CONDITIONS - CONSOLIDATED (replaces add_condition + remove_condition)
+    // ============================================================================
+    server.registerTool("modify_conditions", {
+        description: "Add and/or remove conditions from a character in a single call. More efficient than separate add/remove calls.",
+        inputSchema: {
+            characterId: z.string().describe("The character ID"),
+            add: z.array(z.string().max(100)).max(LIMITS.ARRAY_MAX).optional().describe("Conditions to add"),
+            remove: z.array(z.string().max(100)).max(LIMITS.ARRAY_MAX).optional().describe("Conditions to remove"),
+        },
+        outputSchema: conditionModifyOutputSchema,
+        annotations: ANNOTATIONS.UPDATE,
+    }, async ({ characterId, add, remove }) => {
+        if (!add?.length && !remove?.length) {
+            return {
+                content: [{ type: "text", text: "No conditions to add or remove" }],
+                isError: true,
+            };
+        }
+        const result = characterTools.modifyConditions(characterId, { add, remove });
+        if (!result) {
+            return {
+                content: [{ type: "text", text: "Character not found" }],
+                isError: true,
+            };
+        }
+        const output = {
+            characterId: result.character.id,
+            characterName: result.character.name,
+            conditions: result.character.status.conditions,
+            action: result.added.length > 0 && result.removed.length > 0
+                ? "modified"
+                : result.added.length > 0
+                    ? "added"
+                    : "removed",
+            added: result.added,
+            removed: result.removed,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            structuredContent: output,
+        };
+    });
+    // ============================================================================
+    // GET CHARACTER BY NAME - lookup by name instead of UUID
+    // ============================================================================
+    server.registerTool("get_character_by_name", {
+        description: "Look up a character 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("Character name to search for (case-insensitive)"),
+        },
+        outputSchema: characterOutputSchema,
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId, name }) => {
+        const character = characterTools.getCharacterByName(gameId, name);
+        if (!character) {
+            return {
+                content: [{ type: "text", text: `No character found matching "${name}"` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(character, null, 2) }],
+            structuredContent: character,
+        };
+    });
+    // ============================================================================
+    // LIST CHARACTER SUMMARIES - quick identification info
+    // ============================================================================
+    server.registerTool("list_character_summaries", {
+        description: "List characters with quick-identification summaries. Use this to help identify characters by appearance before looking up their full details. More efficient than loading full character data when you just need to identify who's who.",
+        inputSchema: {
+            gameId: z.string().describe("The game ID"),
+        },
+        outputSchema: {
+            summaries: z.array(z.object({
+                id: z.string(),
+                name: z.string(),
+                isPlayer: z.boolean(),
+                summary: z.string().describe("One-line summary: gender, age, role"),
+                hasImageGen: z.boolean().describe("Whether character has imageGen data"),
+                hasImages: z.boolean().describe("Whether character has stored images"),
+            })),
+        },
+        annotations: ANNOTATIONS.READ_ONLY,
+    }, async ({ gameId }) => {
+        // Dynamic import to avoid circular dependency
+        const { listCharacterSummaries } = await import("../tools/image-prompt.js");
+        const summaries = listCharacterSummaries(gameId);
+        const output = { summaries };
+        return {
+            content: [{ type: "text", text: JSON.stringify(summaries, null, 2) }],
+            structuredContent: output,
+        };
+    });
+    // ============================================================================
+    // DELETE CHARACTER - destructive operation
+    // ============================================================================
+    server.registerTool("delete_character", {
+        description: "Delete a character permanently. This is IRREVERSIBLE and will remove the character and all associated data.",
+        inputSchema: {
+            characterId: z.string().describe("The character ID to delete"),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            deletedId: z.string(),
+        },
+        annotations: ANNOTATIONS.DELETE,
+    }, async ({ characterId }) => {
+        const success = characterTools.deleteCharacter(characterId);
+        if (!success) {
+            return {
+                content: [{ type: "text", text: "Character not found or already deleted" }],
+                isError: true,
+            };
+        }
+        const output = {
+            success: true,
+            deletedId: characterId,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+            structuredContent: output,
+        };
+    });
+}

package/dist/register/combat.d.ts

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