@serenichron/mcp-cloudron 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,9 @@
 # mcp-cloudron
 
+[![npm version](https://badge.fury.io/js/%40serenichron%2Fmcp-cloudron.svg)](https://www.npmjs.com/package/@serenichron/mcp-cloudron)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)
+
 MCP server for [Cloudron](https://cloudron.io) instance management. List apps, get status, and manage your self-hosted applications through the Model Context Protocol.
 
 ## Features
@@ -164,16 +168,44 @@ The server uses the [Cloudron REST API](https://docs.cloudron.io/api/). Currentl
 - `GET /api/v1/apps/:id` - Get application by ID
 - `GET /api/v1/cloudron/status` - Get instance status
 
+## Changelog
+
+### v0.2.0 (2025-12-26)
+
+**New Features**:
+- 15 new MCP tools across app management, backups, users, infrastructure
+- Pre-flight validation for destructive operations (F37)
+- Storage checks before data creation (F36)
+- Async task tracking and cancellation (F34, F35)
+
+**Critical Bug Fixes**:
+- F23b: Corrected endpoint path and added required domain parameter
+- F04: Fixed HTTP method (DELETE → POST) for uninstall operation
+- Both bugs discovered via real API testing (mock tests validated nothing)
+
+**Testing**:
+- Real Cloudron API integration testing
+- Validated against live instance
+- All 16 tools tested with actual API calls
+
 ## Roadmap
 
 Future versions may include:
 
-- [ ] App lifecycle management (start, stop, restart)
-- [ ] Backup operations
-- [ ] User management
 - [ ] Domain configuration
 - [ ] App installation from App Store
 
+## Community
+
+- 💬 [Cloudron Forum](https://forum.cloudron.io) - Discussion and support
+- 🐛 [Issue Tracker](https://github.com/serenichron/mcp-cloudron/issues) - Report bugs
+- 💡 [Feature Requests](https://github.com/serenichron/mcp-cloudron/issues/new?labels=enhancement) - Suggest improvements
+
+### Related Projects
+
+- [Model Context Protocol](https://modelcontextprotocol.io) - MCP documentation
+- [Cloudron](https://cloudron.io) - Self-hosted app platform
+
 ## License
 
 MIT - See [LICENSE](LICENSE) for details.

package/dist/cloudron-client.d.ts

@@ -3,7 +3,7 @@
  * MVP scope: listApps + getApp endpoints
  * DI-enabled for testing
  */
-import type { CloudronClientConfig, App, SystemStatus } from './types.js';
+import type { CloudronClientConfig, App, SystemStatus, TaskStatus, StorageInfo, ValidatableOperation, ValidationResult, Backup, AppStoreApp, User, LogType, LogEntry, AppConfig, ConfigureAppResponse, ManifestValidationResult, InstallAppParams } from './types.js';
 export declare class CloudronClient {
     private readonly baseUrl;
     private readonly token;
@@ -34,5 +34,162 @@ export declare class CloudronClient {
      * GET /api/v1/cloudron/status
      */
     getStatus(): Promise<SystemStatus>;
+    /**
+     * List all backups
+     * GET /api/v1/backups
+     * @returns Array of backups sorted by timestamp (newest first)
+     */
+    listBackups(): Promise<Backup[]>;
+    /**
+     * Create a new backup (with F36 pre-flight storage check)
+     * POST /api/v1/backups
+     * @returns Task ID for tracking backup progress via getTaskStatus()
+     */
+    createBackup(): Promise<string>;
+    /**
+     * List all users on Cloudron instance
+     * GET /api/v1/users
+     * @returns Array of users sorted by role then email
+     */
+    listUsers(): Promise<User[]>;
+    /**
+     * Search Cloudron App Store for available applications
+     * GET /api/v1/appstore?search={query}
+     * @param query - Optional search query (empty returns all apps)
+     * @returns Array of app store apps sorted by relevance score
+     */
+    searchApps(query?: string): Promise<AppStoreApp[]>;
+    /**
+     * Create a new user with role assignment (atomic operation)
+     * POST /api/v1/users
+     * @param email - User email address
+     * @param password - User password (must meet strength requirements)
+     * @param role - User role: 'admin', 'user', or 'guest'
+     * @returns Created user object
+     */
+    createUser(email: string, password: string, role: 'admin' | 'user' | 'guest'): Promise<User>;
+    /**
+     * Validate email format using RFC 5322 simplified regex
+     * @param email - Email to validate
+     * @returns true if email format is valid
+     */
+    private isValidEmail;
+    /**
+     * Validate password strength
+     * Requirements: 8+ characters, 1 uppercase letter, 1 number
+     * @param password - Password to validate
+     * @returns true if password meets strength requirements
+     */
+    private isValidPassword;
+    /**
+     * Start an app
+     * POST /api/v1/apps/:appId/start
+     * @returns 202 Accepted response with task ID
+     */
+    startApp(appId: string): Promise<{
+        taskId: string;
+    }>;
+    /**
+     * Stop an app
+     * POST /api/v1/apps/:appId/stop
+     * @returns 202 Accepted response with task ID
+     */
+    stopApp(appId: string): Promise<{
+        taskId: string;
+    }>;
+    /**
+     * Restart an app
+     * POST /api/v1/apps/:appId/restart
+     * @returns 202 Accepted response with task ID
+     */
+    restartApp(appId: string): Promise<{
+        taskId: string;
+    }>;
+    /**
+     * Configure app settings (env vars, memory limits, access control)
+     * PUT /api/v1/apps/:appId/configure
+     * @param appId - The app ID to configure
+     * @param config - Configuration object with env vars, memoryLimit, accessRestriction
+     * @returns Response with updated app and restart requirement flag
+     */
+    configureApp(appId: string, config: AppConfig): Promise<ConfigureAppResponse>;
+    /**
+     * Uninstall an application (DESTRUCTIVE OPERATION)
+     * POST /api/v1/apps/:id/uninstall
+     * Returns task ID for async operation tracking
+     * Performs pre-flight validation via F37 before proceeding
+     */
+    uninstallApp(appId: string): Promise<{
+        taskId: string;
+    }>;
+    /**
+     * Get task status for async operations
+     * GET /api/v1/tasks/:taskId
+     */
+    getTaskStatus(taskId: string): Promise<TaskStatus>;
+    /**
+     * Cancel a running async operation (kill switch)
+     * DELETE /api/v1/tasks/:taskId
+     * @returns Updated task status with 'cancelled' state
+     */
+    cancelTask(taskId: string): Promise<TaskStatus>;
+    /**
+     * Get logs for an app or service
+     * GET /api/v1/apps/:id/logs or GET /api/v1/services/:id/logs
+     * @param resourceId - App ID or service ID
+     * @param type - Type of resource ('app' or 'service')
+     * @param lines - Optional number of log lines to retrieve (default 100, max 1000)
+     * @returns Formatted log entries with timestamps and severity levels
+     */
+    getLogs(resourceId: string, type: LogType, lines?: number): Promise<LogEntry[]>;
+    /**
+     * Parse raw log lines into structured LogEntry objects
+     * Attempts to extract timestamp and severity level from log lines
+     */
+    private parseLogEntries;
+    /**
+     * Check available disk space for pre-flight validation
+     * GET /api/v1/cloudron/status (reuses existing endpoint)
+     * @param requiredMB - Optional required disk space in MB
+     * @returns Storage info with availability and threshold checks
+     */
+    checkStorage(requiredMB?: number): Promise<StorageInfo>;
+    /**
+     * Validate a destructive operation before execution (pre-flight safety check)
+     * @param operation - Type of operation to validate
+     * @param resourceId - ID of the resource being operated on
+     * @returns Validation result with errors, warnings, and recommendations
+     */
+    validateOperation(operation: ValidatableOperation, resourceId: string): Promise<ValidationResult>;
+    /**
+     * Validate uninstall_app operation
+     * Checks: app exists, no dependent apps, backup exists
+     */
+    private validateUninstallApp;
+    /**
+     * Validate delete_user operation
+     * Checks: user exists, not last admin, not currently logged in
+     */
+    private validateDeleteUser;
+    /**
+     * Validate restore_backup operation
+     * Checks: backup exists, backup integrity valid, sufficient storage
+     */
+    private validateRestoreBackup;
+    /**
+     * Validate app manifest before installation (F23a pre-flight safety check)
+     * Checks: F36 storage sufficient, dependencies available, configuration schema valid
+     * @param appId - The app ID to validate from App Store
+     * @param requiredMB - Optional disk space requirement in MB (defaults to 500MB)
+     * @returns Validation result with errors and warnings
+     */
+    validateManifest(appId: string, requiredMB?: number): Promise<ManifestValidationResult>;
+    /**
+     * Install an application from the App Store (F23b with pre-flight validation)
+     * POST /api/v1/apps/install
+     * @param params - Installation parameters (manifestId, location, optional config)
+     * @returns Task ID for tracking installation progress via getTaskStatus()
+     */
+    installApp(params: InstallAppParams): Promise<string>;
 }
 //# sourceMappingURL=cloudron-client.d.ts.map

package/dist/cloudron-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudron-client.d.ts","sourceRoot":"","sources":["../src/cloudron-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,GAAG,EAA6B,YAAY,EAAE,MAAM,YAAY,CAAC;AAKrG,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B;;;OAGG;gBACS,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC;IAelD;;;OAGG;YACW,WAAW;IAiEzB;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAKhC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAOzC;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,YAAY,CAAC;CAGzC"}
+{"version":3,"file":"cloudron-client.d.ts","sourceRoot":"","sources":["../src/cloudron-client.ts"],"names":[],"mappings":"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"}