run-dmcp 0.1.0

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/json.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/json.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { safeJsonParse, safeJsonParseOrNull } from '../json.js';
+describe('safeJsonParse', () => {
+    it('should parse valid JSON', () => {
+        const result = safeJsonParse('{"name": "test"}', {});
+        expect(result).toEqual({ name: 'test' });
+    });
+    it('should return fallback for invalid JSON', () => {
+        const fallback = { default: true };
+        const result = safeJsonParse('not valid json', fallback);
+        expect(result).toEqual(fallback);
+    });
+    it('should return fallback for empty string', () => {
+        const fallback = [];
+        const result = safeJsonParse('', fallback);
+        expect(result).toEqual(fallback);
+    });
+    it('should parse arrays', () => {
+        const result = safeJsonParse('["a", "b", "c"]', []);
+        expect(result).toEqual(['a', 'b', 'c']);
+    });
+    it('should parse primitive values', () => {
+        expect(safeJsonParse('42', 0)).toBe(42);
+        expect(safeJsonParse('"hello"', '')).toBe('hello');
+        expect(safeJsonParse('true', false)).toBe(true);
+        expect(safeJsonParse('null', 'fallback')).toBe(null);
+    });
+    it('should return fallback for undefined JSON text', () => {
+        const result = safeJsonParse(undefined, { fallback: true });
+        expect(result).toEqual({ fallback: true });
+    });
+});
+describe('safeJsonParseOrNull', () => {
+    it('should parse valid JSON', () => {
+        const result = safeJsonParseOrNull('{"name": "test"}');
+        expect(result).toEqual({ name: 'test' });
+    });
+    it('should return null for invalid JSON', () => {
+        const result = safeJsonParseOrNull('not valid json');
+        expect(result).toBeNull();
+    });
+    it('should return null for empty string', () => {
+        const result = safeJsonParseOrNull('');
+        expect(result).toBeNull();
+    });
+    it('should parse arrays', () => {
+        const result = safeJsonParseOrNull('[1, 2, 3]');
+        expect(result).toEqual([1, 2, 3]);
+    });
+    it('should return null for malformed JSON', () => {
+        expect(safeJsonParseOrNull('{name: "test"}')).toBeNull();
+        expect(safeJsonParseOrNull('{"name": test}')).toBeNull();
+        expect(safeJsonParseOrNull('{incomplete')).toBeNull();
+    });
+});

package/dist/utils/__tests__/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/validation.test.js

@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest';
+import { LIMITS, validatedSchemas, boundedString, boundedArray } from '../validation.js';
+import { z } from 'zod';
+describe('LIMITS', () => {
+    it('should have correct values', () => {
+        expect(LIMITS.NAME_MAX).toBe(200);
+        expect(LIMITS.DESCRIPTION_MAX).toBe(5000);
+        expect(LIMITS.CONTENT_MAX).toBe(50000);
+        expect(LIMITS.NARRATIVE_MAX).toBe(200000);
+        expect(LIMITS.ARRAY_MAX).toBe(100);
+        expect(LIMITS.MAX_DEPTH).toBe(10);
+    });
+});
+describe('validatedSchemas', () => {
+    describe('name', () => {
+        it('should accept valid names', () => {
+            expect(validatedSchemas.name.parse('Test Name')).toBe('Test Name');
+        });
+        it('should reject empty names', () => {
+            expect(() => validatedSchemas.name.parse('')).toThrow();
+        });
+        it('should reject names exceeding max length', () => {
+            const longName = 'a'.repeat(LIMITS.NAME_MAX + 1);
+            expect(() => validatedSchemas.name.parse(longName)).toThrow();
+        });
+        it('should accept names at max length', () => {
+            const maxName = 'a'.repeat(LIMITS.NAME_MAX);
+            expect(validatedSchemas.name.parse(maxName)).toBe(maxName);
+        });
+    });
+    describe('description', () => {
+        it('should accept valid descriptions', () => {
+            expect(validatedSchemas.description.parse('A description')).toBe('A description');
+        });
+        it('should accept empty descriptions', () => {
+            expect(validatedSchemas.description.parse('')).toBe('');
+        });
+        it('should reject descriptions exceeding max length', () => {
+            const longDesc = 'a'.repeat(LIMITS.DESCRIPTION_MAX + 1);
+            expect(() => validatedSchemas.description.parse(longDesc)).toThrow();
+        });
+    });
+    describe('id', () => {
+        it('should accept valid UUIDs', () => {
+            const uuid = '550e8400-e29b-41d4-a716-446655440000';
+            expect(validatedSchemas.id.parse(uuid)).toBe(uuid);
+        });
+        it('should reject IDs exceeding 100 characters', () => {
+            const longId = 'a'.repeat(101);
+            expect(() => validatedSchemas.id.parse(longId)).toThrow();
+        });
+    });
+    describe('stringArray', () => {
+        it('should accept valid arrays', () => {
+            const arr = ['one', 'two', 'three'];
+            expect(validatedSchemas.stringArray.parse(arr)).toEqual(arr);
+        });
+        it('should accept empty arrays', () => {
+            expect(validatedSchemas.stringArray.parse([])).toEqual([]);
+        });
+        it('should reject arrays exceeding max items', () => {
+            const longArr = Array(LIMITS.ARRAY_MAX + 1).fill('item');
+            expect(() => validatedSchemas.stringArray.parse(longArr)).toThrow();
+        });
+    });
+});
+describe('boundedString', () => {
+    it('should create a schema with default max length', () => {
+        const schema = boundedString();
+        expect(schema.parse('test')).toBe('test');
+        expect(() => schema.parse('a'.repeat(LIMITS.NAME_MAX + 1))).toThrow();
+    });
+    it('should create a schema with custom max length', () => {
+        const schema = boundedString(10);
+        expect(schema.parse('test')).toBe('test');
+        expect(() => schema.parse('a'.repeat(11))).toThrow();
+    });
+});
+describe('boundedArray', () => {
+    it('should create an array schema with default max items', () => {
+        const schema = boundedArray(z.string());
+        expect(schema.parse(['a', 'b'])).toEqual(['a', 'b']);
+        expect(() => schema.parse(Array(LIMITS.ARRAY_MAX + 1).fill('x'))).toThrow();
+    });
+    it('should create an array schema with custom max items', () => {
+        const schema = boundedArray(z.number(), 3);
+        expect(schema.parse([1, 2, 3])).toEqual([1, 2, 3]);
+        expect(() => schema.parse([1, 2, 3, 4])).toThrow();
+    });
+});

package/dist/utils/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Structured error response with suggestions for agents
+ */
+export interface AgentError {
+    isError: true;
+    errorCode: string;
+    message: string;
+    entityType?: string;
+    entityId?: string;
+    suggestions: string[];
+}
+/**
+ * Create a structured error response with suggestions
+ */
+export declare function createError(errorCode: string, message: string, options?: {
+    entityType?: string;
+    entityId?: string;
+    additionalSuggestions?: string[];
+}): AgentError;
+/**
+ * Format an AgentError for MCP tool response
+ */
+export declare function formatErrorResponse(error: AgentError): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * Convenience helpers for common error types
+ */
+export declare const errors: {
+    gameNotFound: (gameId: string) => AgentError;
+    characterNotFound: (characterId: string) => AgentError;
+    locationNotFound: (locationId: string) => AgentError;
+    questNotFound: (questId: string) => AgentError;
+    itemNotFound: (itemId: string) => AgentError;
+    factionNotFound: (factionId: string) => AgentError;
+    abilityNotFound: (abilityId: string) => AgentError;
+    combatNotActive: (gameId: string) => AgentError;
+    invalidInput: (message: string, additionalSuggestions?: string[]) => AgentError;
+    constraintViolation: (resourceId: string, message: string) => AgentError;
+};

package/dist/utils/errors.js

@@ -0,0 +1,121 @@
+/**
+ * Common error codes and their suggestions
+ */
+const ERROR_SUGGESTIONS = {
+    GAME_NOT_FOUND: [
+        'Use get_game_menu to see available games',
+        'Create a new game with create_game',
+    ],
+    CHARACTER_NOT_FOUND: [
+        'Use list_characters to see available characters',
+        'Create a character with create_character',
+    ],
+    LOCATION_NOT_FOUND: [
+        'Use list_locations to see available locations',
+        'Create a location with create_location',
+    ],
+    QUEST_NOT_FOUND: [
+        'Use list_quests to see available quests',
+        'Create a quest with create_quest',
+    ],
+    ITEM_NOT_FOUND: [
+        'Use list_items or get_inventory to see available items',
+        'Create an item with create_item',
+    ],
+    FACTION_NOT_FOUND: [
+        'Use list_factions to see available factions',
+        'Create a faction with create_faction',
+    ],
+    ABILITY_NOT_FOUND: [
+        'Use list_abilities to see available abilities',
+        'Create an ability with create_ability',
+    ],
+    COMBAT_NOT_ACTIVE: [
+        'Start combat with start_combat',
+        'Check if combat exists with get_active_combat',
+    ],
+    INVALID_INPUT: [
+        'Check the input schema for required fields',
+        'Verify all IDs reference existing entities',
+    ],
+    CONSTRAINT_VIOLATION: [
+        'Use get_resource to check the current value and its min/max bounds',
+        'Use list_resource_constraints to see what constraint is declared and why the write was rejected',
+        'Choose a value that satisfies the constraint, or remove it with remove_resource_constraint if it no longer applies',
+    ],
+    PERMISSION_DENIED: [
+        'Check if the entity belongs to the current game',
+        'Verify the character has permission for this action',
+    ],
+};
+/**
+ * Create a structured error response with suggestions
+ */
+export function createError(errorCode, message, options) {
+    const baseSuggestions = ERROR_SUGGESTIONS[errorCode] || [];
+    const suggestions = [...baseSuggestions, ...(options?.additionalSuggestions || [])];
+    return {
+        isError: true,
+        errorCode,
+        message,
+        entityType: options?.entityType,
+        entityId: options?.entityId,
+        suggestions,
+    };
+}
+/**
+ * Format an AgentError for MCP tool response
+ */
+export function formatErrorResponse(error) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(error, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Convenience helpers for common error types
+ */
+export const errors = {
+    gameNotFound: (gameId) => createError('GAME_NOT_FOUND', `Game '${gameId}' not found`, {
+        entityType: 'game',
+        entityId: gameId,
+    }),
+    characterNotFound: (characterId) => createError('CHARACTER_NOT_FOUND', `Character '${characterId}' not found`, {
+        entityType: 'character',
+        entityId: characterId,
+    }),
+    locationNotFound: (locationId) => createError('LOCATION_NOT_FOUND', `Location '${locationId}' not found`, {
+        entityType: 'location',
+        entityId: locationId,
+    }),
+    questNotFound: (questId) => createError('QUEST_NOT_FOUND', `Quest '${questId}' not found`, {
+        entityType: 'quest',
+        entityId: questId,
+    }),
+    itemNotFound: (itemId) => createError('ITEM_NOT_FOUND', `Item '${itemId}' not found`, {
+        entityType: 'item',
+        entityId: itemId,
+    }),
+    factionNotFound: (factionId) => createError('FACTION_NOT_FOUND', `Faction '${factionId}' not found`, {
+        entityType: 'faction',
+        entityId: factionId,
+    }),
+    abilityNotFound: (abilityId) => createError('ABILITY_NOT_FOUND', `Ability '${abilityId}' not found`, {
+        entityType: 'ability',
+        entityId: abilityId,
+    }),
+    combatNotActive: (gameId) => createError('COMBAT_NOT_ACTIVE', 'No active combat in this game', {
+        entityType: 'game',
+        entityId: gameId,
+    }),
+    invalidInput: (message, additionalSuggestions) => createError('INVALID_INPUT', message, { additionalSuggestions }),
+    constraintViolation: (resourceId, message) => createError('CONSTRAINT_VIOLATION', message, {
+        entityType: 'resource',
+        entityId: resourceId,
+    }),
+};

package/dist/utils/json.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted JSON data in the database.
+ */
+export declare function safeJsonParse<T>(json: string, fallback: T): T;
+/**
+ * Safely parse JSON, returning null on error.
+ */
+export declare function safeJsonParseOrNull<T>(json: string): T | null;

package/dist/utils/json.js

@@ -0,0 +1,23 @@
+/**
+ * Safely parse JSON with a fallback value.
+ * Prevents crashes from corrupted JSON data in the database.
+ */
+export function safeJsonParse(json, fallback) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Safely parse JSON, returning null on error.
+ */
+export function safeJsonParseOrNull(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,7 @@
+export interface Logger {
+    debug: (message: string, data?: Record<string, unknown>) => void;
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+}
+export declare function createLogger(module: string): Logger;

package/dist/utils/logger.js

@@ -0,0 +1,50 @@
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+function getMinLevel() {
+    const envLevel = process.env.DMCP_LOG_LEVEL?.toLowerCase();
+    if (envLevel && envLevel in LOG_LEVELS) {
+        return envLevel;
+    }
+    return "info";
+}
+function shouldLog(level) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[getMinLevel()];
+}
+function formatLog(entry) {
+    const base = `[${entry.timestamp}] ${entry.level.toUpperCase().padEnd(5)} [${entry.module}] ${entry.message}`;
+    if (entry.data && Object.keys(entry.data).length > 0) {
+        return `${base} ${JSON.stringify(entry.data)}`;
+    }
+    return base;
+}
+export function createLogger(module) {
+    const log = (level, message, data) => {
+        if (!shouldLog(level))
+            return;
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            module,
+            message,
+            data,
+        };
+        const formatted = formatLog(entry);
+        // Write to stderr so it doesn't interfere with MCP stdio transport
+        if (level === "error") {
+            console.error(formatted);
+        }
+        else {
+            console.error(formatted);
+        }
+    };
+    return {
+        debug: (message, data) => log("debug", message, data),
+        info: (message, data) => log("info", message, data),
+        warn: (message, data) => log("warn", message, data),
+        error: (message, data) => log("error", message, data),
+    };
+}