foundryvtt-mcp 0.11.0

package/dist/utils/cache-instance.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Global cache instance singleton
+ *
+ * This module provides a singleton cache instance that's configured
+ * from the application configuration.
+ */
+import { config } from '../config/index.js';
+import { CacheService } from './cache.js';
+/**
+ * Global cache instance
+ * Initialized with configuration from config system
+ */
+export const cache = new CacheService(config?.cache || {
+    enabled: false,
+    ttlSeconds: 300,
+    maxSize: 1000,
+});
+/**
+ * Cache key generators for consistent naming
+ */
+export const CacheKeys = {
+    worldInfo: () => 'world:info',
+    actor: (id) => `actor:${id}`,
+    actorSearch: (query, type, limit) => `actor:search:${query}:${type || 'all'}:${limit || 10}`,
+    item: (id) => `item:${id}`,
+    itemSearch: (query, type, rarity, limit) => `item:search:${query}:${type || 'all'}:${rarity || 'all'}:${limit || 10}`,
+    scene: (id) => (id ? `scene:${id}` : 'scene:current'),
+    rule: (query, system) => `rule:${query}:${system || 'default'}`,
+};
+//# sourceMappingURL=cache-instance.js.map

package/dist/utils/cache-instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-instance.js","sourceRoot":"","sources":["../../src/utils/cache-instance.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,YAAY,CACnC,MAAM,EAAE,KAAK,IAAI;IACf,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,GAAG;IACf,OAAO,EAAE,IAAI;CACd,CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,SAAS,EAAE,GAAG,EAAE,CAAC,YAAY;IAC7B,KAAK,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,SAAS,EAAE,EAAE;IACpC,WAAW,EAAE,CAAC,KAAa,EAAE,IAAa,EAAE,KAAc,EAAE,EAAE,CAC5D,gBAAgB,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,KAAK,IAAI,EAAE,EAAE;IACzD,IAAI,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,QAAQ,EAAE,EAAE;IAClC,UAAU,EAAE,CAAC,KAAa,EAAE,IAAa,EAAE,MAAe,EAAE,KAAc,EAAE,EAAE,CAC5E,eAAe,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,IAAI,EAAE,EAAE;IAC3E,KAAK,EAAE,CAAC,EAAW,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC;IAC9D,IAAI,EAAE,CAAC,KAAa,EAAE,MAAe,EAAE,EAAE,CAAC,QAAQ,KAAK,IAAI,MAAM,IAAI,SAAS,EAAE;CACxE,CAAC"}

package/dist/utils/cache.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Caching utility with TTL (Time To Live) support
+ *
+ * This module provides a simple in-memory cache with automatic expiration
+ * and configurable size limits to improve performance for quasi-static data.
+ */
+/**
+ * Cache statistics for monitoring
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    hitRate: number;
+    size: number;
+    maxSize: number;
+    evictions: number;
+}
+/**
+ * Cache configuration options
+ */
+export interface CacheConfig {
+    enabled: boolean;
+    ttlSeconds: number;
+    maxSize: number;
+}
+/**
+ * Simple in-memory cache with TTL and LRU eviction
+ */
+export declare class CacheService {
+    private config;
+    private cache;
+    private stats;
+    private cleanupInterval;
+    constructor(config: CacheConfig);
+    /**
+     * Get a value from the cache
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a value in the cache with custom TTL
+     */
+    set<T>(key: string, value: T, customTtlSeconds?: number): void;
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get or set a value using a factory function
+     */
+    getOrSet<T>(key: string, factory: () => Promise<T>, customTtlSeconds?: number): Promise<T>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Destroy the cache service and release resources
+     */
+    destroy(): void;
+    /**
+     * Get cache keys (for debugging)
+     */
+    getKeys(): string[];
+    /**
+     * Cleanup expired entries
+     */
+    private cleanup;
+    /**
+     * Evict least recently used entry
+     */
+    private evictLeastRecentlyUsed;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,YAAY;IASX,OAAO,CAAC,MAAM;IAR1B,OAAO,CAAC,KAAK,CAAsC;IACnD,OAAO,CAAC,KAAK,CAIX;IACF,OAAO,CAAC,eAAe,CAA6C;gBAEhD,MAAM,EAAE,WAAW;IAqBvC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IA+BlC;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI;IAyB9D;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQ5B;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACG,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAehG;;OAEG;IACH,QAAQ,IAAI,UAAU;IActB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,OAAO,IAAI,MAAM,EAAE;IAInB;;OAEG;IACH,OAAO,CAAC,OAAO;IAmBf;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAqB/B"}

package/dist/utils/cache.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Caching utility with TTL (Time To Live) support
+ *
+ * This module provides a simple in-memory cache with automatic expiration
+ * and configurable size limits to improve performance for quasi-static data.
+ */
+import { logger } from './logger.js';
+/**
+ * Simple in-memory cache with TTL and LRU eviction
+ */
+export class CacheService {
+    config;
+    cache = new Map();
+    stats = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+    };
+    cleanupInterval;
+    constructor(config) {
+        this.config = config;
+        if (config.enabled) {
+            logger.info('Cache service initialized', {
+                ttlSeconds: config.ttlSeconds,
+                maxSize: config.maxSize,
+            });
+            // Clean up expired entries periodically
+            this.cleanupInterval = setInterval(() => {
+                try {
+                    this.cleanup();
+                }
+                catch (err) {
+                    logger.warn('Cache cleanup error', { error: err instanceof Error ? err.message : err });
+                }
+            }, Math.max((config.ttlSeconds * 1000) / 4, 30000));
+        }
+    }
+    /**
+     * Get a value from the cache
+     */
+    get(key) {
+        if (!this.config.enabled) {
+            return undefined;
+        }
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            logger.debug('Cache miss', { key });
+            return undefined;
+        }
+        // Check if entry has expired
+        const now = Date.now();
+        if (now - entry.timestamp > entry.ttl * 1000) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            logger.debug('Cache expired', { key, age: now - entry.timestamp });
+            return undefined;
+        }
+        // Update access metadata
+        entry.accessCount++;
+        entry.lastAccessed = now;
+        this.stats.hits++;
+        logger.debug('Cache hit', { key, accessCount: entry.accessCount });
+        return entry.value;
+    }
+    /**
+     * Set a value in the cache with custom TTL
+     */
+    set(key, value, customTtlSeconds) {
+        if (!this.config.enabled) {
+            return;
+        }
+        const ttl = customTtlSeconds ?? this.config.ttlSeconds;
+        const now = Date.now();
+        // Ensure cache doesn't exceed max size
+        if (this.cache.size >= this.config.maxSize && !this.cache.has(key)) {
+            this.evictLeastRecentlyUsed();
+        }
+        const entry = {
+            value,
+            timestamp: now,
+            ttl,
+            accessCount: 0,
+            lastAccessed: now,
+        };
+        this.cache.set(key, entry);
+        logger.debug('Cache set', { key, ttl, size: this.cache.size });
+    }
+    /**
+     * Delete a specific key from the cache
+     */
+    delete(key) {
+        const deleted = this.cache.delete(key);
+        if (deleted) {
+            logger.debug('Cache deleted', { key });
+        }
+        return deleted;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        const size = this.cache.size;
+        this.cache.clear();
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+        this.stats.evictions = 0;
+        logger.info('Cache cleared', { previousSize: size });
+    }
+    /**
+     * Get or set a value using a factory function
+     */
+    async getOrSet(key, factory, customTtlSeconds) {
+        if (!this.config.enabled) {
+            return await factory();
+        }
+        const cached = this.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const value = await factory();
+        this.set(key, value, customTtlSeconds);
+        return value;
+    }
+    /**
+     * Get cache statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? this.stats.hits / total : 0;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            hitRate: Math.round(hitRate * 100) / 100,
+            size: this.cache.size,
+            maxSize: this.config.maxSize,
+            evictions: this.stats.evictions,
+        };
+    }
+    /**
+     * Check if cache is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Destroy the cache service and release resources
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = undefined;
+        }
+        this.cache.clear();
+        logger.info('Cache service destroyed');
+    }
+    /**
+     * Get cache keys (for debugging)
+     */
+    getKeys() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Cleanup expired entries
+     */
+    cleanup() {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (now - entry.timestamp > entry.ttl * 1000) {
+                this.cache.delete(key);
+                cleaned++;
+            }
+        }
+        if (cleaned > 0) {
+            logger.debug('Cache cleanup completed', {
+                cleaned,
+                remaining: this.cache.size,
+            });
+        }
+    }
+    /**
+     * Evict least recently used entry
+     */
+    evictLeastRecentlyUsed() {
+        let lruKey;
+        let lruTime = Date.now(); // Start with current time
+        // Find the entry with the oldest lastAccessed time
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.lastAccessed <= lruTime) {
+                lruTime = entry.lastAccessed;
+                lruKey = key;
+            }
+        }
+        if (lruKey) {
+            this.cache.delete(lruKey);
+            this.stats.evictions++;
+            logger.debug('Cache evicted LRU entry', {
+                key: lruKey,
+                age: Date.now() - lruTime,
+            });
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"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"}

package/dist/utils/diagnostics.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Diagnostic utilities for enhanced user experience
+ *
+ * Provides smart error analysis, problem detection, and actionable suggestions
+ * to help users troubleshoot and resolve common issues.
+ */
+import type { FoundryClient } from '../foundry/client.js';
+/**
+ * Diagnostic result containing problem analysis and suggestions
+ */
+export interface DiagnosticResult {
+    /** Brief explanation of the issue */
+    explanation: string;
+    /** Actionable suggestions for resolution */
+    suggestions: string;
+    /** Severity level of the issue */
+    severity: 'info' | 'warning' | 'error' | 'critical';
+    /** Whether the feature can function with limitations */
+    canContinue: boolean;
+    /** Link to relevant documentation */
+    documentationUrl?: string;
+}
+/**
+ * Health check report for system status
+ */
+export interface HealthReport {
+    connectivity: {
+        status: 'connected' | 'limited' | 'offline';
+        emoji: string;
+        details: string;
+    };
+    authentication: {
+        method: 'api-key' | 'credentials' | 'none';
+        status: 'valid' | 'invalid' | 'untested';
+        emoji: string;
+    };
+    features: {
+        diceRolling: boolean;
+        actorSearch: boolean;
+        itemSearch: boolean;
+        sceneData: boolean;
+        diagnostics: boolean;
+    };
+    restApiAvailable: boolean;
+    websocketAvailable: boolean;
+}
+/**
+ * Enhanced diagnostic system for FoundryVTT MCP integration
+ */
+export declare class DiagnosticSystem {
+    private foundryClient;
+    constructor(foundryClient: FoundryClient);
+    /**
+     * Diagnose why a specific feature isn't working
+     */
+    diagnoseFeatureProblem(feature: 'actors' | 'items' | 'scenes' | 'diagnostics'): Promise<DiagnosticResult>;
+    /**
+     * Perform comprehensive health check
+     */
+    performHealthCheck(): Promise<HealthReport>;
+    /**
+     * Format health report for user display
+     */
+    formatHealthReport(report: HealthReport): string;
+    /**
+     * Create diagnostic for connectivity issues
+     */
+    private createConnectivityDiagnostic;
+    /**
+     * Create diagnostic for REST API issues
+     */
+    private createRestApiDiagnostic;
+    /**
+     * Create diagnostic for authentication issues
+     */
+    private createAuthenticationDiagnostic;
+    /**
+     * Create feature-specific diagnostic
+     */
+    private createFeatureSpecificDiagnostic;
+    /**
+     * Create generic error diagnostic
+     */
+    private createGenericErrorDiagnostic;
+    /**
+     * Test if feature requires REST API
+     */
+    private requiresRestApi;
+    /**
+     * Test REST API availability
+     */
+    private testRestApiAvailability;
+    /**
+     * Test authentication
+     */
+    private testAuthentication;
+    /**
+     * Test dice rolling functionality
+     */
+    private testDiceRolling;
+    /**
+     * Test actor search functionality
+     */
+    private testActorSearch;
+    /**
+     * Test item search functionality
+     */
+    private testItemSearch;
+    /**
+     * Test scene data functionality
+     */
+    private testSceneData;
+}
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/utils/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/utils/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;IACpD,wDAAwD;IACxD,WAAW,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE;QACZ,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;QAC5C,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,cAAc,EAAE;QACd,MAAM,EAAE,SAAS,GAAG,aAAa,GAAG,MAAM,CAAC;QAC3C,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;QACzC,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,QAAQ,EAAE;QACR,WAAW,EAAE,OAAO,CAAC;QACrB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;QACpB,SAAS,EAAE,OAAO,CAAC;QACnB,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IACF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,aAAa;gBAAb,aAAa,EAAE,aAAa;IAEhD;;OAEG;IACG,sBAAsB,CAC1B,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,aAAa,GACrD,OAAO,CAAC,gBAAgB,CAAC;IAiC5B;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC;IAyEjD;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;IAqChD;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAepC;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgB/B;;OAEG;IACH,OAAO,CAAC,8BAA8B;IAwBtC;;OAEG;YACW,+BAA+B;IAe7C;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAcpC;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;YACW,uBAAuB;IAcrC;;OAEG;YACW,kBAAkB;IAmBhC;;OAEG;YACW,eAAe;IAU7B;;OAEG;YACW,eAAe;IAU7B;;OAEG;YACW,cAAc;IAU5B;;OAEG;YACW,aAAa;CAS5B"}