foundryvtt-mcp 0.11.0

package/dist/utils/diagnostics.js

@@ -0,0 +1,330 @@
+/**
+ * @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 { config } from '../config/index.js';
+import { ApiStatusResponseSchema } from '../diagnostics/types.js';
+import { logger } from './logger.js';
+/**
+ * Enhanced diagnostic system for FoundryVTT MCP integration
+ */
+export class DiagnosticSystem {
+    foundryClient;
+    constructor(foundryClient) {
+        this.foundryClient = foundryClient;
+    }
+    /**
+     * Diagnose why a specific feature isn't working
+     */
+    async diagnoseFeatureProblem(feature) {
+        logger.debug(`Diagnosing problem with feature: ${feature}`);
+        try {
+            // Test basic connectivity
+            const isConnected = await this.foundryClient.testConnection();
+            if (!isConnected) {
+                return this.createConnectivityDiagnostic();
+            }
+            // Test REST API availability
+            const hasRestApi = await this.testRestApiAvailability();
+            if (!hasRestApi && this.requiresRestApi(feature)) {
+                return this.createRestApiDiagnostic(feature);
+            }
+            // Test authentication
+            const authResult = await this.testAuthentication();
+            if (!authResult.valid) {
+                return this.createAuthenticationDiagnostic(authResult);
+            }
+            // Feature-specific diagnostics
+            return await this.createFeatureSpecificDiagnostic(feature);
+        }
+        catch (error) {
+            logger.error('Error during diagnosis:', error);
+            return this.createGenericErrorDiagnostic(error);
+        }
+    }
+    /**
+     * Perform comprehensive health check
+     */
+    async performHealthCheck() {
+        logger.info('Performing system health check');
+        const report = {
+            connectivity: { status: 'offline', emoji: '❌', details: 'Not tested' },
+            authentication: { method: 'none', status: 'untested', emoji: '❓' },
+            features: {
+                diceRolling: false,
+                actorSearch: false,
+                itemSearch: false,
+                sceneData: false,
+                diagnostics: false,
+            },
+            restApiAvailable: false,
+            websocketAvailable: false,
+        };
+        try {
+            // Test connectivity
+            const isConnected = await this.foundryClient.testConnection();
+            if (isConnected) {
+                report.connectivity = {
+                    status: 'connected',
+                    emoji: '✅',
+                    details: `Connected to ${config.foundry.url}`,
+                };
+            }
+            else {
+                report.connectivity = {
+                    status: 'offline',
+                    emoji: '❌',
+                    details: `Cannot reach ${config.foundry.url}`,
+                };
+                return report; // Early return if not connected
+            }
+            // Test REST API
+            report.restApiAvailable = await this.testRestApiAvailability();
+            // Test authentication
+            const authResult = await this.testAuthentication();
+            report.authentication = {
+                method: config.foundry.apiKey ? 'api-key' : 'credentials',
+                status: authResult.valid ? 'valid' : 'invalid',
+                emoji: authResult.valid ? '✅' : '❌',
+            };
+            // Test individual features
+            report.features.diceRolling = await this.testDiceRolling();
+            report.features.actorSearch = await this.testActorSearch();
+            report.features.itemSearch = await this.testItemSearch();
+            report.features.sceneData = await this.testSceneData();
+            report.features.diagnostics = report.restApiAvailable;
+            // Update connectivity status based on feature availability
+            if (report.restApiAvailable) {
+                report.connectivity.status = 'connected';
+            }
+            else if (report.features.diceRolling) {
+                report.connectivity.status = 'limited';
+                report.connectivity.emoji = '⚠️';
+                report.connectivity.details += ' (Limited functionality - REST API not available)';
+            }
+        }
+        catch (error) {
+            logger.error('Health check failed:', error);
+            report.connectivity = {
+                status: 'offline',
+                emoji: '❌',
+                details: `Health check failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+            };
+        }
+        return report;
+    }
+    /**
+     * Format health report for user display
+     */
+    formatHealthReport(report) {
+        let output = '🏥 **FoundryVTT MCP Health Check**\n\n';
+        output += `**Connection**: ${report.connectivity.status.toUpperCase()} ${report.connectivity.emoji}\n`;
+        output += `  ${report.connectivity.details}\n\n`;
+        output += `**Authentication**: ${report.authentication.method.toUpperCase()} ${report.authentication.emoji}\n`;
+        if (report.authentication.status === 'invalid') {
+            output += `  ⚠️ Authentication failed - check your credentials\n`;
+        }
+        output += '\n';
+        output += `**Available Features**:\n`;
+        output += `  • Dice Rolling: ${report.features.diceRolling ? '✅ Working' : '❌ Failed'}\n`;
+        output += `  • Actor Search: ${report.features.actorSearch ? '✅ Full access' : '⚠️ Limited/None'}\n`;
+        output += `  • Item Search: ${report.features.itemSearch ? '✅ Full access' : '⚠️ Limited/None'}\n`;
+        output += `  • Scene Data: ${report.features.sceneData ? '✅ Real data' : '⚠️ Mock data only'}\n`;
+        output += `  • System Diagnostics: ${report.features.diagnostics ? '✅ Available' : '❌ Unavailable'}\n\n`;
+        if (!report.restApiAvailable) {
+            output += '💡 **Unlock Full Features**:\n';
+            output += '  → Install the "Foundry Local REST API" module in FoundryVTT\n';
+            output += '  → Enable the module and configure API key\n';
+            output += '  → See setup guide: https://github.com/laurigates/foundryvtt-mcp#setup\n\n';
+        }
+        if (report.connectivity.status === 'offline') {
+            output += '🔧 **Troubleshooting Steps**:\n';
+            output += '  1. Ensure FoundryVTT is running and accessible\n';
+            output += '  2. Check FOUNDRY_URL in your .env file\n';
+            output += '  3. Verify network connectivity\n';
+            output += '  4. Test with: `npm run test-connection`\n';
+        }
+        return output;
+    }
+    /**
+     * Create diagnostic for connectivity issues
+     */
+    createConnectivityDiagnostic() {
+        return {
+            explanation: 'Unable to connect to FoundryVTT server.',
+            suggestions: "• **Check if FoundryVTT is running** - Start FoundryVTT and ensure it's accessible\n" +
+                `• **Verify server URL** - Check that \`${config.foundry.url}\` is correct\n` +
+                '• **Test connectivity** - Run `npm run test-connection` for detailed diagnostics\n' +
+                '• **Check firewall** - Ensure no firewall is blocking the connection',
+            severity: 'critical',
+            canContinue: false,
+            documentationUrl: 'https://github.com/laurigates/foundryvtt-mcp/blob/main/TROUBLESHOOTING.md#connectivity-issues',
+        };
+    }
+    /**
+     * Create diagnostic for REST API issues
+     */
+    createRestApiDiagnostic(feature) {
+        return {
+            explanation: `${feature.charAt(0).toUpperCase() + feature.slice(1)} search requires the REST API module for full functionality.`,
+            suggestions: '• **Install REST API module** - Get it from the FoundryVTT module browser\n' +
+                "• **Enable the module** - Activate it in your world's module settings\n" +
+                '• **Configure API key** - Generate and copy the API key from module settings\n' +
+                '• **Update .env file** - Set FOUNDRY_API_KEY with your generated key\n' +
+                '• **Restart MCP server** - Restart to pick up the new configuration',
+            severity: 'warning',
+            canContinue: true,
+            documentationUrl: 'https://github.com/laurigates/foundryvtt-mcp/blob/main/SETUP_GUIDE.md#rest-api-setup',
+        };
+    }
+    /**
+     * Create diagnostic for authentication issues
+     */
+    createAuthenticationDiagnostic(_authResult) {
+        const isApiKey = !!config.foundry.apiKey;
+        return {
+            explanation: `Authentication failed using ${isApiKey ? 'API key' : 'username/password'}.`,
+            suggestions: isApiKey
+                ? "• **Check API key** - Verify the key is correct and hasn't expired\n" +
+                    '• **Regenerate key** - Generate a new API key in FoundryVTT module settings\n' +
+                    '• **Module status** - Ensure the REST API module is enabled and running\n' +
+                    '• **Restart FoundryVTT** - Sometimes a restart resolves authentication issues'
+                : '• **Check credentials** - Verify username and password are correct\n' +
+                    '• **User permissions** - Ensure the user has required permissions\n' +
+                    '• **Case sensitivity** - Check for typos in username (case-sensitive)\n' +
+                    '• **User status** - Make sure the user account is active',
+            severity: 'error',
+            canContinue: false,
+            documentationUrl: 'https://github.com/laurigates/foundryvtt-mcp/blob/main/TROUBLESHOOTING.md#authentication-issues',
+        };
+    }
+    /**
+     * Create feature-specific diagnostic
+     */
+    async createFeatureSpecificDiagnostic(feature) {
+        return {
+            explanation: `Connected with full access, but no ${feature} data found.`,
+            suggestions: `• **Check data exists** - Verify that ${feature} exist in your FoundryVTT world\n` +
+                '• **User permissions** - Ensure you have permission to view this data\n' +
+                '• **Module conflicts** - Check if other modules might be interfering\n' +
+                `• **Direct test** - Try accessing ${feature} directly in FoundryVTT`,
+            severity: 'info',
+            canContinue: true,
+            documentationUrl: 'https://github.com/laurigates/foundryvtt-mcp/blob/main/TROUBLESHOOTING.md#empty-results',
+        };
+    }
+    /**
+     * Create generic error diagnostic
+     */
+    createGenericErrorDiagnostic(_error) {
+        return {
+            explanation: 'An unexpected error occurred during diagnosis.',
+            suggestions: '• **Check logs** - Review server logs for detailed error information\n' +
+                '• **Restart services** - Try restarting both FoundryVTT and the MCP server\n' +
+                '• **Update software** - Ensure all components are up to date\n' +
+                '• **Report issue** - If problem persists, report it on GitHub',
+            severity: 'error',
+            canContinue: false,
+            documentationUrl: 'https://github.com/laurigates/foundryvtt-mcp/issues',
+        };
+    }
+    /**
+     * Test if feature requires REST API
+     */
+    requiresRestApi(feature) {
+        return ['actors', 'items', 'diagnostics'].includes(feature);
+    }
+    /**
+     * Test REST API availability
+     */
+    async testRestApiAvailability() {
+        try {
+            const response = await this.foundryClient.get('/api/status');
+            return (response?.data !== null &&
+                response?.data !== undefined &&
+                ApiStatusResponseSchema.parse(response.data).status === 'ok');
+        }
+        catch (error) {
+            logger.debug('REST API not available:', error);
+            return false;
+        }
+    }
+    /**
+     * Test authentication
+     */
+    async testAuthentication() {
+        try {
+            if (config.foundry.apiKey) {
+                // Test API key authentication
+                const response = await this.foundryClient.get('/api/world');
+                return { valid: !!response };
+            }
+            else {
+                // Test credential authentication (via WebSocket)
+                await this.foundryClient.connect();
+                return { valid: this.foundryClient.isConnected() };
+            }
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : 'Unknown authentication error',
+            };
+        }
+    }
+    /**
+     * Test dice rolling functionality
+     */
+    async testDiceRolling() {
+        try {
+            const result = await this.foundryClient.rollDice('1d20', 'Health check test');
+            return typeof result.total === 'number';
+        }
+        catch (error) {
+            logger.debug('Dice rolling test failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Test actor search functionality
+     */
+    async testActorSearch() {
+        try {
+            const result = await this.foundryClient.searchActors({ limit: 1 });
+            return Array.isArray(result.actors);
+        }
+        catch (error) {
+            logger.debug('Actor search test failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Test item search functionality
+     */
+    async testItemSearch() {
+        try {
+            const result = await this.foundryClient.searchItems({ limit: 1 });
+            return Array.isArray(result.items);
+        }
+        catch (error) {
+            logger.debug('Item search test failed:', error);
+            return false;
+        }
+    }
+    /**
+     * Test scene data functionality
+     */
+    async testSceneData() {
+        try {
+            const result = await this.foundryClient.getCurrentScene();
+            return !!result && typeof result.name === 'string';
+        }
+        catch (error) {
+            logger.debug('Scene data test failed:', error);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/utils/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/utils/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AA2CrC;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACP;IAApB,YAAoB,aAA4B;QAA5B,kBAAa,GAAb,aAAa,CAAe;IAAG,CAAC;IAEpD;;OAEG;IACH,KAAK,CAAC,sBAAsB,CAC1B,OAAsD;QAEtD,MAAM,CAAC,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QAE5D,IAAI,CAAC;YACH,0BAA0B;YAC1B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;YAE9D,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,OAAO,IAAI,CAAC,4BAA4B,EAAE,CAAC;YAC7C,CAAC;YAED,6BAA6B;YAC7B,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAExD,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjD,OAAO,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC;YAC/C,CAAC;YAED,sBAAsB;YACtB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAEnD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBACtB,OAAO,IAAI,CAAC,8BAA8B,CAAC,UAAU,CAAC,CAAC;YACzD,CAAC;YAED,+BAA+B;YAC/B,OAAO,MAAM,IAAI,CAAC,+BAA+B,CAAC,OAAO,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAC/C,OAAO,IAAI,CAAC,4BAA4B,CAAC,KAAK,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;QAE9C,MAAM,MAAM,GAAiB;YAC3B,YAAY,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE;YACtE,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE;YAClE,QAAQ,EAAE;gBACR,WAAW,EAAE,KAAK;gBAClB,WAAW,EAAE,KAAK;gBAClB,UAAU,EAAE,KAAK;gBACjB,SAAS,EAAE,KAAK;gBAChB,WAAW,EAAE,KAAK;aACnB;YACD,gBAAgB,EAAE,KAAK;YACvB,kBAAkB,EAAE,KAAK;SAC1B,CAAC;QAEF,IAAI,CAAC;YACH,oBAAoB;YACpB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;YAC9D,IAAI,WAAW,EAAE,CAAC;gBAChB,MAAM,CAAC,YAAY,GAAG;oBACpB,MAAM,EAAE,WAAW;oBACnB,KAAK,EAAE,GAAG;oBACV,OAAO,EAAE,gBAAgB,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;iBAC9C,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,YAAY,GAAG;oBACpB,MAAM,EAAE,SAAS;oBACjB,KAAK,EAAE,GAAG;oBACV,OAAO,EAAE,gBAAgB,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;iBAC9C,CAAC;gBACF,OAAO,MAAM,CAAC,CAAC,gCAAgC;YACjD,CAAC;YAED,gBAAgB;YAChB,MAAM,CAAC,gBAAgB,GAAG,MAAM,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAE/D,sBAAsB;YACtB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACnD,MAAM,CAAC,cAAc,GAAG;gBACtB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;gBACzD,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;gBAC9C,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;aACpC,CAAC;YAEF,2BAA2B;YAC3B,MAAM,CAAC,QAAQ,CAAC,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3D,MAAM,CAAC,QAAQ,CAAC,WAAW,GAAG,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;YAC3D,MAAM,CAAC,QAAQ,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;YACzD,MAAM,CAAC,QAAQ,CAAC,SAAS,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;YACvD,MAAM,CAAC,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC,gBAAgB,CAAC;YAEtD,2DAA2D;YAC3D,IAAI,MAAM,CAAC,gBAAgB,EAAE,CAAC;gBAC5B,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,WAAW,CAAC;YAC3C,CAAC;iBAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACvC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,SAAS,CAAC;gBACvC,MAAM,CAAC,YAAY,CAAC,KAAK,GAAG,IAAI,CAAC;gBACjC,MAAM,CAAC,YAAY,CAAC,OAAO,IAAI,mDAAmD,CAAC;YACrF,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAAC;YAC5C,MAAM,CAAC,YAAY,GAAG;gBACpB,MAAM,EAAE,SAAS;gBACjB,KAAK,EAAE,GAAG;gBACV,OAAO,EAAE,wBAAwB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE;aAC5F,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,kBAAkB,CAAC,MAAoB;QACrC,IAAI,MAAM,GAAG,wCAAwC,CAAC;QAEtD,MAAM,IAAI,mBAAmB,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,IAAI,CAAC;QACvG,MAAM,IAAI,KAAK,MAAM,CAAC,YAAY,CAAC,OAAO,MAAM,CAAC;QAEjD,MAAM,IAAI,uBAAuB,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,MAAM,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;QAC/G,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/C,MAAM,IAAI,uDAAuD,CAAC;QACpE,CAAC;QACD,MAAM,IAAI,IAAI,CAAC;QAEf,MAAM,IAAI,2BAA2B,CAAC;QACtC,MAAM,IAAI,qBAAqB,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC;QAC1F,MAAM,IAAI,qBAAqB,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC;QACrG,MAAM,IAAI,oBAAoB,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC;QACnG,MAAM,IAAI,mBAAmB,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,mBAAmB,IAAI,CAAC;QACjG,MAAM,IAAI,2BAA2B,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,MAAM,CAAC;QAEzG,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAAE,CAAC;YAC7B,MAAM,IAAI,gCAAgC,CAAC;YAC3C,MAAM,IAAI,iEAAiE,CAAC;YAC5E,MAAM,IAAI,+CAA+C,CAAC;YAC1D,MAAM,IAAI,6EAA6E,CAAC;QAC1F,CAAC;QAED,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC7C,MAAM,IAAI,iCAAiC,CAAC;YAC5C,MAAM,IAAI,oDAAoD,CAAC;YAC/D,MAAM,IAAI,4CAA4C,CAAC;YACvD,MAAM,IAAI,oCAAoC,CAAC;YAC/C,MAAM,IAAI,6CAA6C,CAAC;QAC1D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACK,4BAA4B;QAClC,OAAO;YACL,WAAW,EAAE,yCAAyC;YACtD,WAAW,EACT,sFAAsF;gBACtF,0CAA0C,MAAM,CAAC,OAAO,CAAC,GAAG,iBAAiB;gBAC7E,oFAAoF;gBACpF,sEAAsE;YACxE,QAAQ,EAAE,UAAU;YACpB,WAAW,EAAE,KAAK;YAClB,gBAAgB,EACd,+FAA+F;SAClG,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,uBAAuB,CAAC,OAAe;QAC7C,OAAO;YACL,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,8DAA8D;YAChI,WAAW,EACT,6EAA6E;gBAC7E,yEAAyE;gBACzE,gFAAgF;gBAChF,wEAAwE;gBACxE,qEAAqE;YACvE,QAAQ,EAAE,SAAS;YACnB,WAAW,EAAE,IAAI;YACjB,gBAAgB,EACd,sFAAsF;SACzF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,8BAA8B,CAAC,WAGtC;QACC,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAEzC,OAAO;YACL,WAAW,EAAE,+BAA+B,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,GAAG;YACzF,WAAW,EAAE,QAAQ;gBACnB,CAAC,CAAC,sEAAsE;oBACtE,+EAA+E;oBAC/E,2EAA2E;oBAC3E,+EAA+E;gBACjF,CAAC,CAAC,sEAAsE;oBACtE,qEAAqE;oBACrE,yEAAyE;oBACzE,0DAA0D;YAC9D,QAAQ,EAAE,OAAO;YACjB,WAAW,EAAE,KAAK;YAClB,gBAAgB,EACd,iGAAiG;SACpG,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,+BAA+B,CAAC,OAAe;QAC3D,OAAO;YACL,WAAW,EAAE,sCAAsC,OAAO,cAAc;YACxE,WAAW,EACT,yCAAyC,OAAO,mCAAmC;gBACnF,yEAAyE;gBACzE,wEAAwE;gBACxE,qCAAqC,OAAO,yBAAyB;YACvE,QAAQ,EAAE,MAAM;YAChB,WAAW,EAAE,IAAI;YACjB,gBAAgB,EACd,yFAAyF;SAC5F,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,4BAA4B,CAAC,MAAe;QAClD,OAAO;YACL,WAAW,EAAE,gDAAgD;YAC7D,WAAW,EACT,wEAAwE;gBACxE,8EAA8E;gBAC9E,gEAAgE;gBAChE,+DAA+D;YACjE,QAAQ,EAAE,OAAO;YACjB,WAAW,EAAE,KAAK;YAClB,gBAAgB,EAAE,qDAAqD;SACxE,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,eAAe,CAAC,OAAe;QACrC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,uBAAuB;QACnC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC7D,OAAO,CACL,QAAQ,EAAE,IAAI,KAAK,IAAI;gBACvB,QAAQ,EAAE,IAAI,KAAK,SAAS;gBAC5B,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAC7D,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAC/C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,kBAAkB;QAC9B,IAAI,CAAC;YACH,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC1B,8BAA8B;gBAC9B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;gBAC5D,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACN,iDAAiD;gBACjD,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;gBACnC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,EAAE,CAAC;YACrD,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,8BAA8B;aAC/E,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;YAC9E,OAAO,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YACnE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,cAAc;QAC1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;YAClE,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;YAChD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,aAAa;QACzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,eAAe,EAAE,CAAC;YAC1D,OAAO,CAAC,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;YAC/C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Centralized logging utility for FoundryVTT MCP Server
+ *
+ * This module provides a structured logging system with configurable log levels
+ * and consistent formatting across the application. It respects the LOG_LEVEL
+ * environment variable for controlling verbosity.
+ *
+ * @version 0.1.0
+ * @author FoundryVTT MCP Team
+ */
+/**
+ * Available log levels in order of severity
+ *
+ * - debug: Detailed information for debugging
+ * - info: General information about application flow
+ * - warn: Warning messages for potential issues
+ * - error: Error messages for failures and exceptions
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Centralized logger class for structured application logging
+ *
+ * Provides methods for different log levels and automatically filters
+ * messages based on the configured minimum log level.
+ *
+ * @class Logger
+ * @example
+ * ```typescript
+ * import { logger } from './utils/logger.js';
+ *
+ * logger.info('Server starting...');
+ * logger.error('Connection failed:', error);
+ * logger.debug('Detailed debug info', { data: someObject });
+ * ```
+ */
+declare class Logger {
+    private logLevel;
+    private levels;
+    /**
+     * Creates a new Logger instance
+     *
+     * @param logLevel - Minimum log level to display (default: 'info')
+     */
+    constructor(logLevel?: LogLevel);
+    /**
+     * Determines if a message should be logged based on current log level
+     *
+     * @private
+     * @param level - The log level to check
+     * @returns True if the message should be logged, false otherwise
+     */
+    private shouldLog;
+    /**
+     * Formats a log message with timestamp, level, and optional metadata
+     *
+     * @private
+     * @param level - The log level
+     * @param message - The main log message
+     * @param meta - Optional metadata object
+     * @returns Formatted log message string
+     */
+    private formatMessage;
+    /**
+     * Logs a debug message (lowest priority)
+     *
+     * Used for detailed information that's only needed when debugging issues.
+     * Only shown when LOG_LEVEL is set to 'debug'.
+     *
+     * @param message - The debug message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.debug('Processing user request', { userId: '123', action: 'search' });
+     * ```
+     */
+    debug(message: string, meta?: unknown): void;
+    /**
+     * Logs an informational message
+     *
+     * Used for general information about application flow and important events.
+     * Shown when LOG_LEVEL is 'debug' or 'info'.
+     *
+     * @param message - The info message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.info('Server started successfully', { port: 3000 });
+     * ```
+     */
+    info(message: string, meta?: unknown): void;
+    /**
+     * Logs a warning message
+     *
+     * Used for potentially problematic situations that don't prevent operation
+     * but should be noted. Shown when LOG_LEVEL is 'debug', 'info', or 'warn'.
+     *
+     * @param message - The warning message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.warn('Deprecated API endpoint used', { endpoint: '/old-api' });
+     * ```
+     */
+    warn(message: string, meta?: unknown): void;
+    /**
+     * Logs an error message (highest priority)
+     *
+     * Used for error conditions and exceptions that affect application operation.
+     * Always shown regardless of LOG_LEVEL setting.
+     *
+     * @param message - The error message
+     * @param error - Optional error object or metadata
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', error);
+     * logger.error('Invalid user input', { input: userData, validation: errors });
+     * ```
+     */
+    error(message: string, error?: unknown): void;
+}
+/**
+ * Global logger instance
+ *
+ * Pre-configured logger instance ready for use throughout the application.
+ * Respects the LOG_LEVEL environment variable for filtering messages.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from './utils/logger.js';
+ *
+ * logger.info('Application starting');
+ * logger.error('Something went wrong', error);
+ * ```
+ */
+export declare const logger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;;;;;GAOG;AACH,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,cAAM,MAAM;IACV,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,MAAM,CAKZ;IAEF;;;;OAIG;gBACS,QAAQ,GAAE,QAAiB;IAIvC;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAIjB;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAMrB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM5C;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;IAM3C;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;CAO9C;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,QAA8B,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,158 @@
+/**
+ * @fileoverview Centralized logging utility for FoundryVTT MCP Server
+ *
+ * This module provides a structured logging system with configurable log levels
+ * and consistent formatting across the application. It respects the LOG_LEVEL
+ * environment variable for controlling verbosity.
+ *
+ * @version 0.1.0
+ * @author FoundryVTT MCP Team
+ */
+import { config } from '../config/index.js';
+/**
+ * Centralized logger class for structured application logging
+ *
+ * Provides methods for different log levels and automatically filters
+ * messages based on the configured minimum log level.
+ *
+ * @class Logger
+ * @example
+ * ```typescript
+ * import { logger } from './utils/logger.js';
+ *
+ * logger.info('Server starting...');
+ * logger.error('Connection failed:', error);
+ * logger.debug('Detailed debug info', { data: someObject });
+ * ```
+ */
+class Logger {
+    logLevel;
+    levels = {
+        debug: 0,
+        info: 1,
+        warn: 2,
+        error: 3,
+    };
+    /**
+     * Creates a new Logger instance
+     *
+     * @param logLevel - Minimum log level to display (default: 'info')
+     */
+    constructor(logLevel = 'info') {
+        this.logLevel = logLevel;
+    }
+    /**
+     * Determines if a message should be logged based on current log level
+     *
+     * @private
+     * @param level - The log level to check
+     * @returns True if the message should be logged, false otherwise
+     */
+    shouldLog(level) {
+        return this.levels[level] >= this.levels[this.logLevel];
+    }
+    /**
+     * Formats a log message with timestamp, level, and optional metadata
+     *
+     * @private
+     * @param level - The log level
+     * @param message - The main log message
+     * @param meta - Optional metadata object
+     * @returns Formatted log message string
+     */
+    formatMessage(level, message, meta) {
+        const timestamp = new Date().toISOString();
+        const metaStr = meta ? ` ${JSON.stringify(meta)}` : '';
+        return `[${timestamp}] ${level.toUpperCase()}: ${message}${metaStr}`;
+    }
+    /**
+     * Logs a debug message (lowest priority)
+     *
+     * Used for detailed information that's only needed when debugging issues.
+     * Only shown when LOG_LEVEL is set to 'debug'.
+     *
+     * @param message - The debug message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.debug('Processing user request', { userId: '123', action: 'search' });
+     * ```
+     */
+    debug(message, meta) {
+        if (this.shouldLog('debug')) {
+            console.debug(this.formatMessage('debug', message, meta));
+        }
+    }
+    /**
+     * Logs an informational message
+     *
+     * Used for general information about application flow and important events.
+     * Shown when LOG_LEVEL is 'debug' or 'info'.
+     *
+     * @param message - The info message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.info('Server started successfully', { port: 3000 });
+     * ```
+     */
+    info(message, meta) {
+        if (this.shouldLog('info')) {
+            console.info(this.formatMessage('info', message, meta));
+        }
+    }
+    /**
+     * Logs a warning message
+     *
+     * Used for potentially problematic situations that don't prevent operation
+     * but should be noted. Shown when LOG_LEVEL is 'debug', 'info', or 'warn'.
+     *
+     * @param message - The warning message
+     * @param meta - Optional metadata object
+     * @example
+     * ```typescript
+     * logger.warn('Deprecated API endpoint used', { endpoint: '/old-api' });
+     * ```
+     */
+    warn(message, meta) {
+        if (this.shouldLog('warn')) {
+            console.warn(this.formatMessage('warn', message, meta));
+        }
+    }
+    /**
+     * Logs an error message (highest priority)
+     *
+     * Used for error conditions and exceptions that affect application operation.
+     * Always shown regardless of LOG_LEVEL setting.
+     *
+     * @param message - The error message
+     * @param error - Optional error object or metadata
+     * @example
+     * ```typescript
+     * logger.error('Database connection failed', error);
+     * logger.error('Invalid user input', { input: userData, validation: errors });
+     * ```
+     */
+    error(message, error) {
+        if (this.shouldLog('error')) {
+            const errorDetails = error instanceof Error ? { message: error.message, stack: error.stack } : error;
+            console.error(this.formatMessage('error', message, errorDetails));
+        }
+    }
+}
+/**
+ * Global logger instance
+ *
+ * Pre-configured logger instance ready for use throughout the application.
+ * Respects the LOG_LEVEL environment variable for filtering messages.
+ *
+ * @example
+ * ```typescript
+ * import { logger } from './utils/logger.js';
+ *
+ * logger.info('Application starting');
+ * logger.error('Something went wrong', error);
+ * ```
+ */
+export const logger = new Logger(config.logLevel);
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAY5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM;IACF,QAAQ,CAAW;IACnB,MAAM,GAA6B;QACzC,KAAK,EAAE,CAAC;QACR,IAAI,EAAE,CAAC;QACP,IAAI,EAAE,CAAC;QACP,KAAK,EAAE,CAAC;KACT,CAAC;IAEF;;;;OAIG;IACH,YAAY,WAAqB,MAAM;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACK,SAAS,CAAC,KAAe;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;OAQG;IACK,aAAa,CAAC,KAAe,EAAE,OAAe,EAAE,IAAc;QACpE,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,SAAS,KAAK,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,GAAG,OAAO,EAAE,CAAC;IACvE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,OAAe,EAAE,KAAe;QACpC,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,MAAM,YAAY,GAChB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;YAClF,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC"}