foundryvtt-mcp 0.11.0

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,414 @@
+/**
+ * @fileoverview Type definitions for FoundryVTT diagnostics and logging
+ *
+ * This module provides TypeScript interfaces for log entries, system health metrics,
+ * and diagnostic data structures used by the MCP server for FoundryVTT monitoring.
+ *
+ * @version 0.1.0
+ * @author FoundryVTT MCP Team
+ */
+import { z } from 'zod';
+/**
+ * Log entry interface representing a single log message with metadata
+ *
+ * @interface LogEntry
+ * @example
+ * ```typescript
+ * const logEntry: LogEntry = {
+ *   timestamp: '2024-01-01T12:00:00.000Z',
+ *   level: 'error',
+ *   message: 'TypeError: Cannot read property of undefined',
+ *   stack: 'Error stack trace...',
+ *   source: 'module'
+ * };
+ * ```
+ */
+export interface LogEntry {
+    /** ISO timestamp when the log entry was created */
+    timestamp: string;
+    /** Log level indicating severity */
+    level: 'log' | 'warn' | 'error' | 'info' | 'notification';
+    /** The actual log message content */
+    message: string;
+    /** Optional stack trace for errors */
+    stack?: string;
+    /** Source component that generated the log */
+    source: 'foundry' | 'module' | 'system' | 'api' | 'unknown';
+}
+/**
+ * Server information including FoundryVTT and system versions
+ *
+ * @interface ServerInfo
+ */
+export interface ServerInfo {
+    /** FoundryVTT version string */
+    foundryVersion: string;
+    /** Game system version */
+    systemVersion: string;
+    /** Current world identifier */
+    worldId: string;
+    /** Server uptime in seconds (if available) */
+    uptime?: number;
+}
+/**
+ * User session information and statistics
+ *
+ * @interface UserInfo
+ */
+export interface UserInfo {
+    /** Total number of users */
+    total: number;
+    /** Number of currently active users */
+    active: number;
+    /** Number of GM users */
+    gm: number;
+}
+/**
+ * Module information and statistics
+ *
+ * @interface ModuleInfo
+ */
+export interface ModuleInfo {
+    /** Total number of installed modules */
+    total: number;
+    /** Number of currently active modules */
+    active: number;
+}
+/**
+ * Performance metrics for system monitoring
+ *
+ * @interface PerformanceInfo
+ */
+export interface PerformanceInfo {
+    /** Node.js memory usage (if available) */
+    memory?: NodeJS.MemoryUsage;
+    /** Number of connected WebSocket clients */
+    connectedClients: number;
+}
+/**
+ * Log buffer statistics and metrics
+ *
+ * @interface LogInfo
+ */
+export interface LogInfo {
+    /** Current number of entries in the log buffer */
+    bufferSize: number;
+    /** Number of recent error entries */
+    recentErrors: number;
+    /** Number of recent warning entries */
+    recentWarnings: number;
+    /** Error rate as a percentage */
+    errorRate: number;
+}
+/**
+ * Overall system health status and metrics
+ *
+ * @interface SystemHealth
+ * @example
+ * ```typescript
+ * const health: SystemHealth = {
+ *   timestamp: '2024-01-01T12:00:00.000Z',
+ *   server: { foundryVersion: '11.315', systemVersion: '5e 2.4.1', worldId: 'my-world' },
+ *   users: { total: 5, active: 3, gm: 1 },
+ *   modules: { total: 50, active: 35 },
+ *   performance: { connectedClients: 3 },
+ *   logs: { bufferSize: 500, recentErrors: 2, recentWarnings: 5, errorRate: 0.1 },
+ *   status: 'healthy'
+ * };
+ * ```
+ */
+export interface SystemHealth {
+    /** Timestamp when health data was collected */
+    timestamp: string;
+    /** Server information and versions */
+    server: ServerInfo;
+    /** User session information */
+    users: UserInfo;
+    /** Module information */
+    modules: ModuleInfo;
+    /** Performance metrics */
+    performance: PerformanceInfo;
+    /** Log statistics */
+    logs: LogInfo;
+    /** Overall health status */
+    status: 'healthy' | 'warning' | 'critical';
+}
+/**
+ * Error categorization for diagnostics
+ *
+ * @interface ErrorCategories
+ */
+export interface ErrorCategories {
+    [category: string]: number;
+}
+/**
+ * Diagnostic suggestion for resolving issues
+ *
+ * @interface DiagnosticSuggestion
+ */
+export interface DiagnosticSuggestion {
+    /** Error category this suggestion applies to */
+    category: string;
+    /** Human-readable suggestion text */
+    suggestion: string;
+    /** Priority level for addressing the issue */
+    priority: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Summary of error analysis
+ *
+ * @interface ErrorSummary
+ */
+export interface ErrorSummary {
+    /** Total number of errors in the analyzed timeframe */
+    totalErrors: number;
+    /** Number of unique error messages */
+    uniqueErrors: number;
+    /** Categorized error counts */
+    categories: ErrorCategories;
+}
+/**
+ * Complete error diagnosis with analysis and suggestions
+ *
+ * @interface ErrorDiagnosis
+ * @example
+ * ```typescript
+ * const diagnosis: ErrorDiagnosis = {
+ *   timestamp: '2024-01-01T12:00:00.000Z',
+ *   timeframe: '3600 seconds',
+ *   summary: {
+ *     totalErrors: 5,
+ *     uniqueErrors: 3,
+ *     categories: { 'TypeError': 2, 'Network': 3 }
+ *   },
+ *   recentErrors: [...],
+ *   suggestions: [...],
+ *   healthScore: 75
+ * };
+ * ```
+ */
+export interface ErrorDiagnosis {
+    /** Timestamp of the diagnosis */
+    timestamp: string;
+    /** Time window analyzed for errors */
+    timeframe: string;
+    /** Summary of errors found */
+    summary: ErrorSummary;
+    /** Most recent error entries */
+    recentErrors: LogEntry[];
+    /** Diagnostic suggestions based on error patterns */
+    suggestions: DiagnosticSuggestion[];
+    /** Overall health score (0-100) */
+    healthScore: number;
+}
+/**
+ * Parameters for searching logs
+ *
+ * @interface LogSearchParams
+ */
+export interface LogSearchParams {
+    /** Number of log lines to retrieve */
+    lines?: number;
+    /** Filter by specific log level */
+    level?: LogEntry['level'];
+    /** Filter logs since this timestamp */
+    since?: string;
+    /** Filter by log source */
+    source?: LogEntry['source'];
+    /** Include stack traces in results */
+    includeStack?: boolean;
+}
+/**
+ * Parameters for log pattern searching
+ *
+ * @interface LogPatternSearchParams
+ */
+export interface LogPatternSearchParams {
+    /** Regular expression pattern to search for */
+    pattern: string;
+    /** Time window in seconds to search within */
+    timeframe?: string;
+    /** Filter by specific log level */
+    level?: LogEntry['level'];
+    /** Case-sensitive search */
+    caseSensitive?: boolean;
+}
+/**
+ * Response structure for log retrieval operations
+ *
+ * @interface LogResponse
+ */
+export interface LogResponse {
+    /** Array of log entries */
+    logs: LogEntry[];
+    /** Total number of log entries returned */
+    total: number;
+    /** Current size of the log buffer */
+    bufferSize?: number;
+    /** Maximum size of the log buffer */
+    maxBufferSize?: number;
+}
+/**
+ * Response structure for log search operations
+ *
+ * @interface LogSearchResponse
+ */
+export interface LogSearchResponse {
+    /** Array of matching log entries */
+    logs: LogEntry[];
+    /** Number of matches found */
+    matches: number;
+    /** Search pattern used */
+    pattern: string;
+    /** Timeframe searched */
+    searchTimeframe: string;
+}
+export declare const LogEntrySchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    level: z.ZodEnum<{
+        info: "info";
+        warn: "warn";
+        error: "error";
+        log: "log";
+        notification: "notification";
+    }>;
+    message: z.ZodString;
+    stack: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<{
+        foundry: "foundry";
+        system: "system";
+        unknown: "unknown";
+        module: "module";
+        api: "api";
+    }>;
+}, z.core.$strip>;
+export declare const LogResponseSchema: z.ZodObject<{
+    logs: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        level: z.ZodEnum<{
+            info: "info";
+            warn: "warn";
+            error: "error";
+            log: "log";
+            notification: "notification";
+        }>;
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+        source: z.ZodEnum<{
+            foundry: "foundry";
+            system: "system";
+            unknown: "unknown";
+            module: "module";
+            api: "api";
+        }>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    bufferSize: z.ZodOptional<z.ZodNumber>;
+    maxBufferSize: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const LogSearchResponseSchema: z.ZodObject<{
+    logs: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        level: z.ZodEnum<{
+            info: "info";
+            warn: "warn";
+            error: "error";
+            log: "log";
+            notification: "notification";
+        }>;
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+        source: z.ZodEnum<{
+            foundry: "foundry";
+            system: "system";
+            unknown: "unknown";
+            module: "module";
+            api: "api";
+        }>;
+    }, z.core.$strip>>;
+    matches: z.ZodNumber;
+    pattern: z.ZodString;
+    searchTimeframe: z.ZodString;
+}, z.core.$strip>;
+export declare const SystemHealthSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    server: z.ZodObject<{
+        foundryVersion: z.ZodString;
+        systemVersion: z.ZodString;
+        worldId: z.ZodString;
+        uptime: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    users: z.ZodObject<{
+        total: z.ZodNumber;
+        active: z.ZodNumber;
+        gm: z.ZodNumber;
+    }, z.core.$strip>;
+    modules: z.ZodObject<{
+        total: z.ZodNumber;
+        active: z.ZodNumber;
+    }, z.core.$strip>;
+    performance: z.ZodObject<{
+        memory: z.ZodOptional<z.ZodObject<{
+            rss: z.ZodNumber;
+            heapTotal: z.ZodNumber;
+            heapUsed: z.ZodNumber;
+            external: z.ZodNumber;
+            arrayBuffers: z.ZodNumber;
+        }, z.core.$strip>>;
+        connectedClients: z.ZodNumber;
+    }, z.core.$strip>;
+    logs: z.ZodObject<{
+        bufferSize: z.ZodNumber;
+        recentErrors: z.ZodNumber;
+        recentWarnings: z.ZodNumber;
+        errorRate: z.ZodNumber;
+    }, z.core.$strip>;
+    status: z.ZodEnum<{
+        healthy: "healthy";
+        warning: "warning";
+        critical: "critical";
+    }>;
+}, z.core.$strip>;
+export declare const ErrorDiagnosisSchema: z.ZodObject<{
+    timestamp: z.ZodString;
+    timeframe: z.ZodString;
+    summary: z.ZodObject<{
+        totalErrors: z.ZodNumber;
+        uniqueErrors: z.ZodNumber;
+        categories: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>;
+    recentErrors: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodString;
+        level: z.ZodEnum<{
+            info: "info";
+            warn: "warn";
+            error: "error";
+            log: "log";
+            notification: "notification";
+        }>;
+        message: z.ZodString;
+        stack: z.ZodOptional<z.ZodString>;
+        source: z.ZodEnum<{
+            foundry: "foundry";
+            system: "system";
+            unknown: "unknown";
+            module: "module";
+            api: "api";
+        }>;
+    }, z.core.$strip>>;
+    suggestions: z.ZodArray<z.ZodObject<{
+        category: z.ZodString;
+        suggestion: z.ZodString;
+        priority: z.ZodEnum<{
+            critical: "critical";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+    }, z.core.$strip>>;
+    healthScore: z.ZodNumber;
+}, z.core.$strip>;
+export declare const ApiStatusResponseSchema: z.ZodObject<{
+    status: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/diagnostics/types.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Type definitions for FoundryVTT diagnostics and logging
+ *
+ * This module provides TypeScript interfaces for log entries, system health metrics,
+ * and diagnostic data structures used by the MCP server for FoundryVTT monitoring.
+ *
+ * @version 0.1.0
+ * @author FoundryVTT MCP Team
+ */
+import { z } from 'zod';
+export const LogEntrySchema = z.object({
+    timestamp: z.string(),
+    level: z.enum(['log', 'warn', 'error', 'info', 'notification']),
+    message: z.string(),
+    stack: z.string().optional(),
+    source: z.enum(['foundry', 'module', 'system', 'api', 'unknown']),
+});
+export const LogResponseSchema = z.object({
+    logs: z.array(LogEntrySchema),
+    total: z.number(),
+    bufferSize: z.number().optional(),
+    maxBufferSize: z.number().optional(),
+});
+export const LogSearchResponseSchema = z.object({
+    logs: z.array(LogEntrySchema),
+    matches: z.number(),
+    pattern: z.string(),
+    searchTimeframe: z.string(),
+});
+const ServerInfoSchema = z.object({
+    foundryVersion: z.string(),
+    systemVersion: z.string(),
+    worldId: z.string(),
+    uptime: z.number().optional(),
+});
+const UserInfoSchema = z.object({
+    total: z.number(),
+    active: z.number(),
+    gm: z.number(),
+});
+const ModuleInfoSchema = z.object({
+    total: z.number(),
+    active: z.number(),
+});
+const PerformanceInfoSchema = z.object({
+    memory: z
+        .object({
+        rss: z.number(),
+        heapTotal: z.number(),
+        heapUsed: z.number(),
+        external: z.number(),
+        arrayBuffers: z.number(),
+    })
+        .optional(),
+    connectedClients: z.number(),
+});
+const LogInfoSchema = z.object({
+    bufferSize: z.number(),
+    recentErrors: z.number(),
+    recentWarnings: z.number(),
+    errorRate: z.number(),
+});
+export const SystemHealthSchema = z.object({
+    timestamp: z.string(),
+    server: ServerInfoSchema,
+    users: UserInfoSchema,
+    modules: ModuleInfoSchema,
+    performance: PerformanceInfoSchema,
+    logs: LogInfoSchema,
+    status: z.enum(['healthy', 'warning', 'critical']),
+});
+const ErrorCategoriesSchema = z.record(z.string(), z.number());
+const DiagnosticSuggestionSchema = z.object({
+    category: z.string(),
+    suggestion: z.string(),
+    priority: z.enum(['low', 'medium', 'high', 'critical']),
+});
+const ErrorSummarySchema = z.object({
+    totalErrors: z.number(),
+    uniqueErrors: z.number(),
+    categories: ErrorCategoriesSchema,
+});
+export const ErrorDiagnosisSchema = z.object({
+    timestamp: z.string(),
+    timeframe: z.string(),
+    summary: ErrorSummarySchema,
+    recentErrors: z.array(LogEntrySchema),
+    suggestions: z.array(DiagnosticSuggestionSchema),
+    healthScore: z.number(),
+});
+export const ApiStatusResponseSchema = z.object({
+    status: z.string(),
+});
+//# sourceMappingURL=types.js.map

package/dist/diagnostics/types.js.map

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

package/dist/foundry/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * FoundryVTT authentication module
+ *
+ * Implements the proven 4-step authentication flow for direct WebSocket access:
+ * 1. GET /join → session cookie
+ * 2. Socket.IO connect + getJoinData → resolve user document _id
+ * 3. POST /join as JSON with document _id → authenticated session
+ * 4. Socket.IO reconnect with session → full game state access
+ */
+/**
+ * Authenticates with FoundryVTT using the proven 4-step flow.
+ *
+ * @returns Session cookie and resolved user document _id
+ */
+export declare function authenticateFoundry(baseUrl: string, user: string, password: string): Promise<{
+    session: string;
+    userId: string;
+}>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/foundry/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/foundry/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkGH;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoD9C"}

package/dist/foundry/auth.js

@@ -0,0 +1,135 @@
+/**
+ * FoundryVTT authentication module
+ *
+ * Implements the proven 4-step authentication flow for direct WebSocket access:
+ * 1. GET /join → session cookie
+ * 2. Socket.IO connect + getJoinData → resolve user document _id
+ * 3. POST /join as JSON with document _id → authenticated session
+ * 4. Socket.IO reconnect with session → full game state access
+ */
+import axios from 'axios';
+import { io } from 'socket.io-client';
+import { logger } from '../utils/logger.js';
+/**
+ * Extracts the session cookie value from a GET /join response.
+ */
+async function getSessionCookie(baseUrl) {
+    const res = await axios.get(`${baseUrl}/join`, {
+        // Accept 200 (join page) and 302 (redirect after cookie set)
+        validateStatus: (status) => status === 200 || status === 302,
+        maxRedirects: 0,
+    });
+    const cookies = res.headers['set-cookie'];
+    if (!cookies) {
+        throw new Error('No session cookie returned from /join');
+    }
+    const cookieString = Array.isArray(cookies) ? cookies.join(' ') : cookies;
+    const match = cookieString.match(/session=([^;]+)/);
+    if (!match?.[1]) {
+        throw new Error('Could not extract session cookie from response');
+    }
+    logger.debug('Session cookie obtained');
+    return match[1];
+}
+/**
+ * Resolves a user identifier to a FoundryVTT document _id.
+ *
+ * If the input is already a 16-character alphanumeric string (document _id format),
+ * returns it directly. Otherwise, connects via Socket.IO and emits getJoinData
+ * to look up the _id by display name.
+ */
+async function resolveUserId(baseUrl, user, session) {
+    // FoundryVTT document IDs are 16-character alphanumeric strings
+    if (/^[a-zA-Z0-9]{16}$/.test(user)) {
+        logger.debug('User identifier is already a document _id', { userId: user });
+        return user;
+    }
+    logger.debug('Resolving display name to document _id', { displayName: user });
+    return new Promise((resolve, reject) => {
+        const socket = io(baseUrl, {
+            transports: ['websocket'],
+            query: { session },
+        });
+        const cleanup = () => {
+            socket.off('session', onSession);
+            socket.off('connect_error', onConnectError);
+        };
+        const timeout = setTimeout(() => {
+            cleanup();
+            socket.disconnect();
+            reject(new Error('Timeout resolving user ID via getJoinData'));
+        }, 10000);
+        const onSession = () => {
+            socket.emit('getJoinData', (data) => {
+                clearTimeout(timeout);
+                cleanup();
+                socket.disconnect();
+                if (!data?.users || !Array.isArray(data.users)) {
+                    return reject(new Error('getJoinData returned no users'));
+                }
+                const found = data.users.find((u) => u.name.toLowerCase() === user.toLowerCase());
+                if (!found) {
+                    const available = data.users.map((u) => u.name).join(', ');
+                    logger.debug('User not found in FoundryVTT user list', { available });
+                    return reject(new Error(`User "${user}" not found`));
+                }
+                logger.debug('Resolved user document _id', { displayName: user, _id: found._id });
+                resolve(found._id);
+            });
+        };
+        const onConnectError = (err) => {
+            clearTimeout(timeout);
+            cleanup();
+            socket.disconnect();
+            reject(new Error(`Socket.IO connection failed during user resolution: ${err.message}`));
+        };
+        socket.on('session', onSession);
+        socket.on('connect_error', onConnectError);
+    });
+}
+/**
+ * Authenticates with FoundryVTT using the proven 4-step flow.
+ *
+ * @returns Session cookie and resolved user document _id
+ */
+export async function authenticateFoundry(baseUrl, user, password) {
+    // Warn when credentials are sent over plaintext HTTP to a non-localhost host
+    try {
+        const parsed = new URL(baseUrl);
+        if (parsed.protocol === 'http:' &&
+            parsed.hostname !== 'localhost' &&
+            parsed.hostname !== '127.0.0.1' &&
+            !parsed.hostname.startsWith('::1')) {
+            logger.warn('WARNING: Connecting to a non-localhost host over plain HTTP. ' +
+                'Your password will be transmitted in plaintext. ' +
+                'Use HTTPS for non-local FoundryVTT instances.', { host: parsed.hostname });
+        }
+    }
+    catch {
+        // URL already validated by config; ignore parse errors here
+    }
+    // Step 1: Get session cookie
+    const session = await getSessionCookie(baseUrl);
+    // Step 2: Resolve user to document _id
+    const userId = await resolveUserId(baseUrl, user, session);
+    // Step 3: POST /join as JSON with document _id
+    const joinRes = await axios.post(`${baseUrl}/join`, {
+        action: 'join',
+        userid: userId,
+        password,
+    }, {
+        headers: {
+            'Content-Type': 'application/json',
+            Cookie: `session=${session}`,
+        },
+        // Accept 200 (success JSON) and 302 (redirect to /game on success)
+        validateStatus: (status) => status === 200 || status === 302,
+    });
+    if (joinRes.data?.status !== 'success' && joinRes.data?.redirect !== '/game') {
+        const msg = joinRes.data?.message || joinRes.data?.error || 'Unknown error';
+        throw new Error(`FoundryVTT authentication failed: ${msg}`);
+    }
+    logger.info('FoundryVTT authentication successful', { userId });
+    return { session, userId };
+}
+//# sourceMappingURL=auth.js.map

package/dist/foundry/auth.js.map

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