run-dmcp 0.1.0

package/dist/utils/output-schemas.js

@@ -0,0 +1,331 @@
+import { z } from "zod";
+/**
+ * Shared output schemas for MCP tools.
+ * These enable clients to validate structured outputs from tools.
+ */
+// ============================================================================
+// COMMON RESPONSE PATTERNS
+// ============================================================================
+/** Simple success/failure response */
+export const successResponseSchema = {
+    success: z.boolean(),
+    message: z.string().optional(),
+};
+/** Simple text result */
+export const textResultSchema = {
+    result: z.string(),
+};
+/** Entity deleted response */
+export const deletedResponseSchema = {
+    deleted: z.boolean(),
+    id: z.string().optional(),
+};
+/** List response with count */
+export const listResponseSchema = (itemSchema) => ({
+    items: z.array(itemSchema),
+    count: z.number(),
+});
+// ============================================================================
+// GAME SCHEMAS
+// ============================================================================
+export const gameOutputSchema = {
+    id: z.string(),
+    name: z.string(),
+    setting: z.string(),
+    style: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    webUi: z.object({
+        url: z.string(),
+        message: z.string(),
+    }).optional(),
+};
+export const gameStateOutputSchema = {
+    game: z.object({
+        id: z.string(),
+        name: z.string(),
+        setting: z.string(),
+        style: z.string(),
+    }),
+    characterCount: z.number(),
+    locationCount: z.number(),
+    activeQuests: z.number(),
+    activeCombat: z.boolean(),
+};
+export const gameMenuOutputSchema = {
+    hasExistingGames: z.boolean(),
+    games: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        setting: z.string(),
+        style: z.string(),
+        createdAt: z.string(),
+        updatedAt: z.string(),
+        webUiUrl: z.string().optional(),
+    })),
+    instruction: z.string(),
+    webUi: z.object({
+        baseUrl: z.string(),
+        message: z.string(),
+    }).optional(),
+};
+// ============================================================================
+// CHARACTER SCHEMAS
+// ============================================================================
+export const characterStatusSchema = z.object({
+    health: z.number(),
+    maxHealth: z.number(),
+    conditions: z.array(z.string()),
+    experience: z.number(),
+    level: z.number(),
+});
+export const characterOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    name: z.string(),
+    isPlayer: z.boolean(),
+    attributes: z.record(z.string(), z.number()),
+    skills: z.record(z.string(), z.number()),
+    status: characterStatusSchema,
+    locationId: z.string().nullable(),
+    notes: z.string(),
+    createdAt: z.string(),
+};
+export const characterListOutputSchema = {
+    characters: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        isPlayer: z.boolean(),
+        status: characterStatusSchema,
+        locationId: z.string().nullable(),
+    })),
+    count: z.number(),
+};
+// ============================================================================
+// LOCATION SCHEMAS
+// ============================================================================
+export const exitSchema = z.object({
+    direction: z.string(),
+    destinationId: z.string(),
+    description: z.string().optional(),
+    locked: z.boolean().optional(),
+    hidden: z.boolean().optional(),
+});
+export const locationOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    name: z.string(),
+    description: z.string(),
+    properties: z.object({
+        exits: z.array(exitSchema),
+        features: z.array(z.string()),
+        atmosphere: z.string(),
+    }),
+};
+export const locationListOutputSchema = {
+    locations: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        description: z.string(),
+    })),
+    count: z.number(),
+};
+// ============================================================================
+// QUEST SCHEMAS
+// ============================================================================
+export const questObjectiveSchema = z.object({
+    id: z.string(),
+    description: z.string(),
+    completed: z.boolean(),
+    optional: z.boolean().optional(),
+});
+export const questOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    name: z.string(),
+    description: z.string(),
+    objectives: z.array(questObjectiveSchema),
+    status: z.enum(["active", "completed", "failed", "abandoned"]),
+    rewards: z.string().optional(),
+};
+// ============================================================================
+// COMBAT SCHEMAS
+// ============================================================================
+export const combatParticipantSchema = z.object({
+    characterId: z.string(),
+    initiative: z.number(),
+    isActive: z.boolean(),
+});
+export const combatOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    locationId: z.string(),
+    participants: z.array(combatParticipantSchema),
+    currentTurn: z.number(),
+    round: z.number(),
+    status: z.enum(["active", "resolved"]),
+    log: z.array(z.string()),
+};
+// ============================================================================
+// DICE SCHEMAS
+// ============================================================================
+export const diceRollOutputSchema = {
+    expression: z.string(),
+    rolls: z.array(z.number()),
+    modifier: z.number(),
+    total: z.number(),
+};
+export const checkResultOutputSchema = {
+    roll: z.object({
+        expression: z.string(),
+        rolls: z.array(z.number()),
+        modifier: z.number(),
+        total: z.number(),
+    }),
+    modifier: z.number(),
+    total: z.number(),
+    difficulty: z.number(),
+    success: z.boolean(),
+    criticalSuccess: z.boolean(),
+    criticalFailure: z.boolean(),
+    margin: z.number(),
+};
+// ============================================================================
+// ITEM SCHEMAS
+// ============================================================================
+export const itemOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    ownerId: z.string(),
+    ownerType: z.enum(["character", "location"]),
+    name: z.string(),
+    properties: z.object({
+        description: z.string(),
+        type: z.string(),
+        weight: z.number().optional(),
+        value: z.number().optional(),
+        effects: z.array(z.string()).optional(),
+    }),
+};
+export const inventoryOutputSchema = {
+    ownerId: z.string(),
+    ownerType: z.enum(["character", "location"]),
+    items: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        properties: z.object({
+            description: z.string(),
+            type: z.string(),
+        }),
+    })),
+    count: z.number(),
+};
+// ============================================================================
+// NARRATIVE SCHEMAS
+// ============================================================================
+export const narrativeEventOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    eventType: z.string(),
+    content: z.string(),
+    timestamp: z.string(),
+};
+export const narrativeSummaryOutputSchema = {
+    totalEvents: z.number(),
+    firstEvent: z.string().nullable(),
+    lastEvent: z.string().nullable(),
+    eventTypes: z.record(z.string(), z.number()),
+    recentEvents: z.array(z.object({
+        id: z.string(),
+        eventType: z.string(),
+        content: z.string(),
+        timestamp: z.string(),
+    })),
+};
+// ============================================================================
+// MAP SCHEMAS
+// ============================================================================
+export const mapOutputSchema = {
+    nodes: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        hasPlayer: z.boolean(),
+        exits: z.array(z.object({
+            direction: z.string(),
+            destinationId: z.string(),
+        })),
+    })),
+    connections: z.array(z.object({
+        from: z.string(),
+        to: z.string(),
+        direction: z.string(),
+    })),
+    bounds: z.object({
+        minX: z.number(),
+        maxX: z.number(),
+        minY: z.number(),
+        maxY: z.number(),
+    }),
+    playerLocation: z.string().optional(),
+};
+// ============================================================================
+// RESOURCE SCHEMAS
+// ============================================================================
+export const resourceOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    ownerId: z.string().nullable(),
+    ownerType: z.enum(["game", "character"]),
+    name: z.string(),
+    description: z.string(),
+    category: z.string().nullable(),
+    value: z.number(),
+    minValue: z.number().nullable(),
+    maxValue: z.number().nullable(),
+};
+// ============================================================================
+// CONDITION/STATUS EFFECT SCHEMAS
+// ============================================================================
+export const conditionModifyOutputSchema = {
+    characterId: z.string(),
+    characterName: z.string(),
+    conditions: z.array(z.string()),
+    action: z.enum(["added", "removed", "modified"]),
+    added: z.array(z.string()),
+    removed: z.array(z.string()),
+};
+export const statusEffectOutputSchema = {
+    id: z.string(),
+    targetId: z.string(),
+    name: z.string(),
+    description: z.string(),
+    effectType: z.enum(["buff", "debuff", "neutral"]).nullable(),
+    duration: z.number().nullable(),
+    stacks: z.number(),
+};
+// ============================================================================
+// TAG SCHEMAS
+// ============================================================================
+export const tagModifyOutputSchema = {
+    entityId: z.string(),
+    entityType: z.string(),
+    tags: z.array(z.string()),
+    action: z.enum(["added", "removed"]),
+    tag: z.string(),
+};
+// ============================================================================
+// IMAGE SCHEMAS
+// ============================================================================
+export const storedImageOutputSchema = {
+    id: z.string(),
+    gameId: z.string(),
+    entityId: z.string(),
+    entityType: z.string(), // Flexible: character, location, item, scene, faction, quest, ability, etc.
+    fileSize: z.number(),
+    mimeType: z.string(),
+    width: z.number().nullable(),
+    height: z.number().nullable(),
+    label: z.string().nullable(),
+    isPrimary: z.boolean(),
+    createdAt: z.string(),
+};

package/dist/utils/tool-annotations.d.ts

@@ -0,0 +1,147 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Pre-defined tool annotation sets for common patterns.
+ * These follow MCP best practices for describing tool behavior.
+ *
+ * Per the MCP spec:
+ * - readOnlyHint: If true, the tool does not modify its environment (default: false)
+ * - destructiveHint: If true, the tool may perform destructive updates (default: true when readOnlyHint is false)
+ * - idempotentHint: If true, calling the tool multiple times with same args has same effect as calling once
+ * - openWorldHint: If true, the tool may interact with an "open world" of external entities
+ */
+/**
+ * Read-only operations that don't modify state.
+ * Examples: get_character, list_locations, render_map
+ */
+export declare const READ_ONLY: ToolAnnotations;
+/**
+ * Operations that create new entities.
+ * Examples: create_game, create_character, create_location
+ */
+export declare const CREATE: ToolAnnotations;
+/**
+ * Operations that update existing entities.
+ * Examples: update_character, move_character, apply_damage
+ */
+export declare const UPDATE: ToolAnnotations;
+/**
+ * Idempotent update operations where repeated calls have the same effect.
+ * Examples: set_rules, set_time (setting to same value)
+ */
+export declare const IDEMPOTENT_UPDATE: ToolAnnotations;
+/**
+ * Operations that delete or remove entities permanently.
+ * These should trigger human-in-the-loop confirmation in MCP clients.
+ * Examples: delete_game, delete_character, remove_combatant
+ */
+export declare const DESTRUCTIVE: ToolAnnotations;
+/**
+ * Operations that connect to external systems.
+ * Examples: store_image with URL fetching
+ */
+export declare const EXTERNAL: ToolAnnotations;
+/**
+ * Read-only operations that connect to external systems.
+ * Examples: fetching external images for display
+ */
+export declare const EXTERNAL_READ: ToolAnnotations;
+/**
+ * Helper to merge annotation sets with custom overrides.
+ */
+export declare function withAnnotations(base: ToolAnnotations, overrides: Partial<ToolAnnotations>): ToolAnnotations;
+/**
+ * Annotation sets organized by tool category for easy reference.
+ */
+export declare const ANNOTATIONS: {
+    readonly READ_ONLY: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly CREATE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly UPDATE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly IDEMPOTENT_UPDATE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly DESTRUCTIVE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly EXTERNAL: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly EXTERNAL_READ: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly GET: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly LIST: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly RENDER: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly DELETE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly REMOVE: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+    readonly SET: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    };
+};

package/dist/utils/tool-annotations.js

@@ -0,0 +1,98 @@
+/**
+ * Pre-defined tool annotation sets for common patterns.
+ * These follow MCP best practices for describing tool behavior.
+ *
+ * Per the MCP spec:
+ * - readOnlyHint: If true, the tool does not modify its environment (default: false)
+ * - destructiveHint: If true, the tool may perform destructive updates (default: true when readOnlyHint is false)
+ * - idempotentHint: If true, calling the tool multiple times with same args has same effect as calling once
+ * - openWorldHint: If true, the tool may interact with an "open world" of external entities
+ */
+/**
+ * Read-only operations that don't modify state.
+ * Examples: get_character, list_locations, render_map
+ */
+export const READ_ONLY = {
+    readOnlyHint: true,
+};
+/**
+ * Operations that create new entities.
+ * Examples: create_game, create_character, create_location
+ */
+export const CREATE = {
+    readOnlyHint: false,
+    destructiveHint: false, // Additive, not destructive
+    idempotentHint: false, // Creates new entity each time
+};
+/**
+ * Operations that update existing entities.
+ * Examples: update_character, move_character, apply_damage
+ */
+export const UPDATE = {
+    readOnlyHint: false,
+    destructiveHint: false, // Updates, not deletes
+    idempotentHint: false, // State changes with each call
+};
+/**
+ * Idempotent update operations where repeated calls have the same effect.
+ * Examples: set_rules, set_time (setting to same value)
+ */
+export const IDEMPOTENT_UPDATE = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+};
+/**
+ * Operations that delete or remove entities permanently.
+ * These should trigger human-in-the-loop confirmation in MCP clients.
+ * Examples: delete_game, delete_character, remove_combatant
+ */
+export const DESTRUCTIVE = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true, // Deleting twice has same effect as deleting once
+};
+/**
+ * Operations that connect to external systems.
+ * Examples: store_image with URL fetching
+ */
+export const EXTERNAL = {
+    readOnlyHint: false,
+    openWorldHint: true,
+};
+/**
+ * Read-only operations that connect to external systems.
+ * Examples: fetching external images for display
+ */
+export const EXTERNAL_READ = {
+    readOnlyHint: true,
+    openWorldHint: true,
+};
+/**
+ * Helper to merge annotation sets with custom overrides.
+ */
+export function withAnnotations(base, overrides) {
+    return { ...base, ...overrides };
+}
+/**
+ * Annotation sets organized by tool category for easy reference.
+ */
+export const ANNOTATIONS = {
+    // Read operations
+    READ_ONLY,
+    // Write operations
+    CREATE,
+    UPDATE,
+    IDEMPOTENT_UPDATE,
+    DESTRUCTIVE,
+    // External operations
+    EXTERNAL,
+    EXTERNAL_READ,
+    // Convenience aliases
+    GET: READ_ONLY,
+    LIST: READ_ONLY,
+    RENDER: READ_ONLY,
+    DELETE: DESTRUCTIVE,
+    REMOVE: DESTRUCTIVE,
+    SET: IDEMPOTENT_UPDATE,
+};

package/dist/utils/validation.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/**
+ * Common input length limits for security and performance.
+ * These prevent DoS attacks via extremely large inputs.
+ */
+export declare const LIMITS: {
+    readonly NAME_MAX: 200;
+    readonly DESCRIPTION_MAX: 5000;
+    readonly CONTENT_MAX: 50000;
+    readonly NARRATIVE_MAX: 200000;
+    readonly ARRAY_MAX: 100;
+    readonly MAX_DEPTH: 10;
+};
+/**
+ * Pre-built Zod schemas with length limits
+ */
+export declare const validatedSchemas: {
+    readonly name: z.ZodString;
+    readonly description: z.ZodString;
+    readonly content: z.ZodString;
+    readonly narrative: z.ZodString;
+    readonly id: z.ZodString;
+    readonly tag: z.ZodString;
+    readonly stringArray: z.ZodArray<z.ZodString, "many">;
+    readonly tagArray: z.ZodArray<z.ZodString, "many">;
+};
+/**
+ * Helper to create a bounded string schema
+ */
+export declare function boundedString(maxLength?: number): z.ZodString;
+/**
+ * Helper to create a bounded array schema
+ */
+export declare function boundedArray<T extends z.ZodType>(schema: T, maxItems?: number): z.ZodArray<T, "many">;

package/dist/utils/validation.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * Common input length limits for security and performance.
+ * These prevent DoS attacks via extremely large inputs.
+ */
+export const LIMITS = {
+    // Short text fields (names, titles)
+    NAME_MAX: 200,
+    // Medium text fields (descriptions)
+    DESCRIPTION_MAX: 5000,
+    // Long text fields (notes, content)
+    CONTENT_MAX: 50000,
+    // Very long text fields (story exports, narrative)
+    NARRATIVE_MAX: 200000,
+    // Array limits
+    ARRAY_MAX: 100,
+    // JSON object depth limit (for nested structures)
+    MAX_DEPTH: 10,
+};
+/**
+ * Pre-built Zod schemas with length limits
+ */
+export const validatedSchemas = {
+    // Name fields (character names, location names, etc.)
+    name: z.string().min(1).max(LIMITS.NAME_MAX),
+    // Description fields
+    description: z.string().max(LIMITS.DESCRIPTION_MAX),
+    // Content fields (notes, large text)
+    content: z.string().max(LIMITS.CONTENT_MAX),
+    // Narrative content (very large text allowed)
+    narrative: z.string().max(LIMITS.NARRATIVE_MAX),
+    // ID fields (UUIDs are 36 characters)
+    id: z.string().max(100),
+    // Tag/category strings
+    tag: z.string().min(1).max(100),
+    // Array of strings with limits
+    stringArray: z.array(z.string().max(LIMITS.NAME_MAX)).max(LIMITS.ARRAY_MAX),
+    // Array of tags
+    tagArray: z.array(z.string().min(1).max(100)).max(LIMITS.ARRAY_MAX),
+};
+/**
+ * Helper to create a bounded string schema
+ */
+export function boundedString(maxLength = LIMITS.NAME_MAX) {
+    return z.string().max(maxLength);
+}
+/**
+ * Helper to create a bounded array schema
+ */
+export function boundedArray(schema, maxItems = LIMITS.ARRAY_MAX) {
+    return z.array(schema).max(maxItems);
+}