@serenichron/mcp-cloudron 0.1.0 → 0.2.0

package/dist/server.js

@@ -42,6 +42,268 @@ const TOOLS = [
             required: [],
         },
     },
+    {
+        name: 'cloudron_task_status',
+        description: 'Get the status of an async operation (backup, install, restore, etc.) by task ID. Returns state (pending/running/success/error/cancelled), progress (0-100%), and message.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskId: {
+                    type: 'string',
+                    description: 'The unique identifier of the task to check',
+                },
+            },
+            required: ['taskId'],
+        },
+    },
+    {
+        name: 'cloudron_cancel_task',
+        description: 'Cancel a running async operation (kill switch). Returns updated task status with state "cancelled". Already completed tasks cannot be cancelled. Cancelled tasks cleanup resources (e.g., partial backups deleted).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                taskId: {
+                    type: 'string',
+                    description: 'The unique identifier of the task to cancel',
+                },
+            },
+            required: ['taskId'],
+        },
+    },
+    {
+        name: 'cloudron_check_storage',
+        description: 'Check available disk space before operations that create data (backup, install). Returns available/total/used disk space in MB, plus warning and critical threshold alerts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                requiredMB: {
+                    type: 'number',
+                    description: 'Optional: Required disk space in MB. If provided, checks if available >= requiredMB',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'cloudron_validate_operation',
+        description: 'Pre-flight validation for destructive operations (uninstall app, delete user, restore backup). Returns validation result with blocking errors, warnings, and recommendations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                operation: {
+                    type: 'string',
+                    enum: ['uninstall_app', 'delete_user', 'restore_backup'],
+                    description: 'Type of destructive operation to validate',
+                },
+                resourceId: {
+                    type: 'string',
+                    description: 'ID of the resource being operated on (appId, userId, or backupId)',
+                },
+            },
+            required: ['operation', 'resourceId'],
+        },
+    },
+    {
+        name: 'cloudron_control_app',
+        description: 'Control app lifecycle (start, stop, restart). Returns 202 Accepted with task ID for async operation tracking via cloudron_task_status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The unique identifier of the application to control',
+                },
+                action: {
+                    type: 'string',
+                    enum: ['start', 'stop', 'restart'],
+                    description: 'Action to perform on the app',
+                },
+            },
+            required: ['appId', 'action'],
+        },
+    },
+    {
+        name: 'cloudron_configure_app',
+        description: 'Update application configuration including environment variables, memory limits, and access control settings. Returns 200 OK with updated app config and restart requirement flag.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The unique identifier of the application to configure',
+                },
+                config: {
+                    type: 'object',
+                    description: 'Configuration object with env vars, memoryLimit, and/or accessRestriction',
+                    properties: {
+                        env: {
+                            type: 'object',
+                            description: 'Environment variables as key-value pairs (optional)',
+                            additionalProperties: { type: 'string' },
+                        },
+                        memoryLimit: {
+                            type: 'number',
+                            description: 'Memory limit in MB (optional)',
+                        },
+                        accessRestriction: {
+                            type: ['string', 'null'],
+                            description: 'Access control settings (optional)',
+                        },
+                    },
+                },
+            },
+            required: ['appId', 'config'],
+        },
+    },
+    {
+        name: 'cloudron_list_backups',
+        description: 'List all backups available on the Cloudron instance. Returns backup details including ID, timestamp, size, app count, and status. Backups are sorted by timestamp (newest first).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'cloudron_create_backup',
+        description: 'Create a new backup of the Cloudron instance. Performs F36 pre-flight storage check (requires 5GB minimum). Returns task ID for tracking backup progress via cloudron_task_status (F34).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'cloudron_list_users',
+        description: 'List all users on the Cloudron instance. Returns user details including ID, email, username, role, and creation date. Users are sorted by role (admin, user, guest) then email.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'cloudron_search_apps',
+        description: 'Search the Cloudron App Store for available applications. Returns app details including name, description, version, icon URL, and install count. Results are sorted by relevance score. Empty query returns all available apps.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Search query to filter apps (optional - empty returns all apps)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'cloudron_validate_manifest',
+        description: 'Validate app manifest before installation (pre-flight safety check). Checks storage sufficiency via F36, dependency availability, and manifest schema validity. Returns validation report with errors and warnings.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The App Store ID to validate',
+                },
+            },
+            required: ['appId'],
+        },
+    },
+    {
+        name: 'cloudron_create_user',
+        description: 'Create a new user on the Cloudron instance with role assignment (atomic operation). Password must be at least 8 characters long and contain at least 1 uppercase letter and 1 number. Returns 201 Created with user object.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email: {
+                    type: 'string',
+                    description: 'User email address (must be valid format)',
+                },
+                password: {
+                    type: 'string',
+                    description: 'User password (8+ characters, 1 uppercase, 1 number)',
+                },
+                role: {
+                    type: 'string',
+                    enum: ['admin', 'user', 'guest'],
+                    description: 'User role: admin (full access), user (standard access), or guest (limited access)',
+                },
+            },
+            required: ['email', 'password', 'role'],
+        },
+    },
+    {
+        name: 'cloudron_get_logs',
+        description: 'Get logs for an app or service. Logs are formatted with timestamps and severity levels for readability. Type parameter determines endpoint: "app" calls GET /api/v1/apps/:id/logs, "service" calls GET /api/v1/services/:id/logs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                resourceId: {
+                    type: 'string',
+                    description: 'App ID or service ID to retrieve logs for',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['app', 'service'],
+                    description: 'Type of resource: "app" for application logs, "service" for system service logs',
+                },
+                lines: {
+                    type: 'number',
+                    description: 'Optional: Number of log lines to retrieve (default 100, max 1000)',
+                },
+            },
+            required: ['resourceId', 'type'],
+        },
+    },
+    {
+        name: 'cloudron_uninstall_app',
+        description: 'Uninstall an application with pre-flight safety validation. DESTRUCTIVE OPERATION. First validates via cloudron_validate_operation (checks app exists, no dependencies, backup recommended), then calls DELETE /api/v1/apps/:id. Returns 202 Accepted with task ID for async operation tracking.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                appId: {
+                    type: 'string',
+                    description: 'The unique identifier of the application to uninstall',
+                },
+            },
+            required: ['appId'],
+        },
+    },
+    {
+        name: 'cloudron_install_app',
+        description: 'Install application from Cloudron App Store with pre-flight validation. Calls F23a (cloudron_validate_manifest) to verify app exists and F36 (cloudron_check_storage) to ensure sufficient disk space. Returns task ID for async operation tracking via cloudron_task_status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                manifestId: {
+                    type: 'string',
+                    description: 'App manifest ID from App Store',
+                },
+                location: {
+                    type: 'string',
+                    description: 'Subdomain for app installation',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Domain where app will be installed (REQUIRED)',
+                },
+                portBindings: {
+                    type: 'object',
+                    description: 'Optional port bindings',
+                },
+                accessRestriction: {
+                    type: ['string', 'null'],
+                    description: 'Access control setting (can be null for no restriction)',
+                },
+                env: {
+                    type: 'object',
+                    description: 'Environment variables',
+                },
+            },
+            required: ['manifestId', 'location', 'domain', 'accessRestriction'],
+        },
+    },
 ];
 // Create server instance
 const server = new Server({
@@ -119,6 +381,435 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'cloudron_task_status': {
+                const taskId = args.taskId;
+                const taskStatus = await cloudron.getTaskStatus(taskId);
+                let statusText = `Task Status:
+  ID: ${taskStatus.id}
+  State: ${taskStatus.state}
+  Progress: ${taskStatus.progress}%
+  Message: ${taskStatus.message}`;
+                if (taskStatus.state === 'success' && taskStatus.result) {
+                    statusText += `\n  Result: ${JSON.stringify(taskStatus.result, null, 2)}`;
+                }
+                if (taskStatus.state === 'error' && taskStatus.error) {
+                    statusText += `\n  Error: ${taskStatus.error.message}`;
+                    if (taskStatus.error.code) {
+                        statusText += `\n  Error Code: ${taskStatus.error.code}`;
+                    }
+                }
+                if (taskStatus.state === 'cancelled') {
+                    statusText += '\n  ℹ️  Task was cancelled by user request';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: statusText,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_cancel_task': {
+                const taskId = args.taskId;
+                const taskStatus = await cloudron.cancelTask(taskId);
+                let statusText = `Task Cancellation:
+  Task ID: ${taskStatus.id}
+  New State: ${taskStatus.state}
+  Message: ${taskStatus.message}`;
+                if (taskStatus.state === 'cancelled') {
+                    statusText += '\n\n✅ Task successfully cancelled. Resources have been cleaned up.';
+                }
+                else {
+                    statusText += `\n\n⚠️  Task is in state '${taskStatus.state}' (expected 'cancelled'). Cancellation may not have completed.`;
+                }
+                statusText += `\n\nUse cloudron_task_status with taskId '${taskId}' to verify final state.`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: statusText,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_check_storage': {
+                const requiredMB = args.requiredMB;
+                const storageInfo = await cloudron.checkStorage(requiredMB);
+                let statusText = `Storage Status:
+  Available: ${storageInfo.available_mb} MB
+  Total: ${storageInfo.total_mb} MB
+  Used: ${storageInfo.used_mb} MB`;
+                if (requiredMB !== undefined) {
+                    statusText += `\n  Required: ${requiredMB} MB`;
+                    statusText += `\n  Sufficient: ${storageInfo.sufficient ? 'Yes' : 'No'}`;
+                }
+                if (storageInfo.critical) {
+                    statusText += '\n  ⚠️  CRITICAL: Less than 5% disk space remaining!';
+                }
+                else if (storageInfo.warning) {
+                    statusText += '\n  ⚠️  WARNING: Less than 10% disk space remaining';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: statusText,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_validate_operation': {
+                const { operation, resourceId } = args;
+                const validationResult = await cloudron.validateOperation(operation, resourceId);
+                let statusText = `Validation Result for ${operation} on resource '${resourceId}':
+  Valid: ${validationResult.valid ? 'Yes' : 'No'}`;
+                if (validationResult.errors.length > 0) {
+                    statusText += '\n\nBlocking Errors:';
+                    validationResult.errors.forEach((error, i) => {
+                        statusText += `\n  ${i + 1}. ${error}`;
+                    });
+                }
+                if (validationResult.warnings.length > 0) {
+                    statusText += '\n\nWarnings:';
+                    validationResult.warnings.forEach((warning, i) => {
+                        statusText += `\n  ${i + 1}. ${warning}`;
+                    });
+                }
+                if (validationResult.recommendations.length > 0) {
+                    statusText += '\n\nRecommendations:';
+                    validationResult.recommendations.forEach((rec, i) => {
+                        statusText += `\n  ${i + 1}. ${rec}`;
+                    });
+                }
+                if (validationResult.valid) {
+                    statusText += '\n\n✅ Operation can proceed (warnings should be reviewed)';
+                }
+                else {
+                    statusText += '\n\n❌ Operation blocked due to errors listed above';
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: statusText,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_control_app': {
+                const { appId, action } = args;
+                // Validate action enum
+                if (!['start', 'stop', 'restart'].includes(action)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Invalid action: ${action}. Valid options: start, stop, restart`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Execute action
+                let result;
+                switch (action) {
+                    case 'start':
+                        result = await cloudron.startApp(appId);
+                        break;
+                    case 'stop':
+                        result = await cloudron.stopApp(appId);
+                        break;
+                    case 'restart':
+                        result = await cloudron.restartApp(appId);
+                        break;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `App ${action} initiated successfully.
+  App ID: ${appId}
+  Task ID: ${result.taskId}
+
+Use cloudron_task_status with taskId '${result.taskId}' to track completion.`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_configure_app': {
+                const { appId, config } = args;
+                // Validate config object is provided and not empty
+                if (!config || Object.keys(config).length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Config object is required and cannot be empty. Provide at least one of: env, memoryLimit, accessRestriction',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const result = await cloudron.configureApp(appId, config);
+                // Format config changes summary
+                const configChanges = Object.keys(config).map(key => {
+                    if (key === 'env') {
+                        const envCount = Object.keys(config.env).length;
+                        return `  - Environment variables: ${envCount} variable(s) updated`;
+                    }
+                    else if (key === 'memoryLimit') {
+                        return `  - Memory limit: ${config.memoryLimit} MB`;
+                    }
+                    else if (key === 'accessRestriction') {
+                        return `  - Access restriction: ${config.accessRestriction ?? 'none'}`;
+                    }
+                    else {
+                        return `  - ${key}: updated`;
+                    }
+                }).join('\n');
+                const restartNote = result.restartRequired
+                    ? '\n⚠️  App restart required for configuration changes to take effect. Use cloudron_control_app with action "restart".'
+                    : '\n✓ Configuration applied. No restart required.';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `App configuration updated successfully.
+App ID: ${appId}
+
+Configuration changes:
+${configChanges}
+${restartNote}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_list_backups': {
+                const backups = await cloudron.listBackups();
+                if (backups.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No backups found.',
+                            },
+                        ],
+                    };
+                }
+                const formatted = backups.map((backup, i) => {
+                    const timestamp = new Date(backup.creationTime).toLocaleString();
+                    const size = backup.size ? `${Math.round(backup.size / 1024 / 1024)} MB` : 'N/A';
+                    const appCount = backup.appCount !== undefined ? backup.appCount : 'N/A';
+                    return `${i + 1}. Backup ${backup.id}
+  Timestamp: ${timestamp}
+  Version: ${backup.version}
+  Type: ${backup.type}
+  State: ${backup.state}
+  Size: ${size}
+  App Count: ${appCount}${backup.errorMessage ? `\n  Error: ${backup.errorMessage}` : ''}`;
+                }).join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${backups.length} backup(s):\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_create_backup': {
+                // F36 pre-flight storage check performed in createBackup()
+                const taskId = await cloudron.createBackup();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Backup creation started successfully.
+
+Task ID: ${taskId}
+
+Use cloudron_task_status with taskId="${taskId}" to track backup progress.
+
+Note: Pre-flight storage check passed (5GB minimum required).`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_list_users': {
+                const users = await cloudron.listUsers();
+                if (users.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No users found.',
+                            },
+                        ],
+                    };
+                }
+                const formatted = users.map((user, i) => {
+                    const createdAt = new Date(user.createdAt).toLocaleString();
+                    return `${i + 1}. ${user.username} (${user.email})
+  ID: ${user.id}
+  Role: ${user.role}
+  Created: ${createdAt}`;
+                }).join('\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${users.length} user(s):\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_search_apps': {
+                const { query } = args;
+                const apps = await cloudron.searchApps(query);
+                if (apps.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: query
+                                    ? `No apps found matching query: "${query}"`
+                                    : 'No apps available in the App Store.',
+                            },
+                        ],
+                    };
+                }
+                const formatted = apps.map((app, i) => {
+                    const installCount = app.installCount !== undefined ? app.installCount : 'N/A';
+                    const iconUrl = app.iconUrl || 'N/A';
+                    const score = app.relevanceScore !== undefined ? app.relevanceScore.toFixed(2) : 'N/A';
+                    return `${i + 1}. ${app.name} (${app.id})
+  Version: ${app.version}
+  Description: ${app.description}
+  Install Count: ${installCount}
+  Icon URL: ${iconUrl}
+  Relevance Score: ${score}`;
+                }).join('\n\n');
+                const searchInfo = query ? `Search results for "${query}"` : 'All available apps';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${searchInfo}:\n\nFound ${apps.length} app(s):\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_validate_manifest': {
+                const { appId } = args;
+                const result = await cloudron.validateManifest(appId);
+                if (result.valid) {
+                    const warningText = result.warnings.length > 0
+                        ? `\n\nWarnings:\n${result.warnings.map(w => `  - ${w}`).join('\n')}`
+                        : '';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Manifest validation passed for app: ${appId}
+
+App is ready for installation.${warningText}`,
+                            },
+                        ],
+                    };
+                }
+                else {
+                    const errorsText = result.errors.map(e => `  - ${e}`).join('\n');
+                    const warningsText = result.warnings.length > 0
+                        ? `\n\nWarnings:\n${result.warnings.map(w => `  - ${w}`).join('\n')}`
+                        : '';
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Manifest validation failed for app: ${appId}
+
+Errors (must be resolved):
+${errorsText}${warningsText}`,
+                            },
+                        ],
+                    };
+                }
+            }
+            case 'cloudron_create_user': {
+                const { email, password, role } = args;
+                const user = await cloudron.createUser(email, password, role);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `User created successfully:
+  ID: ${user.id}
+  Email: ${user.email}
+  Username: ${user.username}
+  Role: ${user.role}
+  Created: ${new Date(user.createdAt).toLocaleString()}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_get_logs': {
+                const { resourceId, type, lines } = args;
+                const logEntries = await cloudron.getLogs(resourceId, type, lines);
+                // Format logs for display
+                const formattedLogs = logEntries.map(entry => `[${entry.timestamp}] [${entry.severity}] ${entry.message}`).join('\n');
+                const logType = type === 'app' ? 'Application' : 'Service';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${logType} logs for ${resourceId} (${logEntries.length} entries):\n\n${formattedLogs}`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_uninstall_app': {
+                const { appId } = args;
+                const result = await cloudron.uninstallApp(appId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Uninstall operation initiated for app: ${appId}
+  Task ID: ${result.taskId}
+  Status: Pending (202 Accepted)
+
+Use cloudron_task_status with taskId '${result.taskId}' to track uninstall progress.
+
+Note: This is a DESTRUCTIVE operation. The app and its data will be removed once the task completes.`,
+                        },
+                    ],
+                };
+            }
+            case 'cloudron_install_app': {
+                const { manifestId, location, domain, portBindings, accessRestriction, env } = args;
+                const params = { manifestId, location, domain, accessRestriction };
+                if (portBindings !== undefined)
+                    params.portBindings = portBindings;
+                if (env !== undefined)
+                    params.env = env;
+                const taskId = await cloudron.installApp(params);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Installation initiated for app: ${manifestId}
+  Location: ${location}
+  Task ID: ${taskId}
+  Status: Pending (202 Accepted)
+
+Use cloudron_task_status with taskId '${taskId}' to track installation progress.
+
+Note: Pre-flight validation (F23a + F36) passed. Installation is in progress.`,
+                        },
+                    ],
+                };
+            }
             default:
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],