Kastell

Instructions

Implementation Reference

• src/mcp/tools/serverBackup.handlers.ts:96-153 (handler)

  The `handleBackupRestore` function is one of the handlers for `server_backup`, specifically managing the restoration process from a backup. Other handlers for different sub-actions (create, list, snapshot management) are also present in this file.

  export async function handleBackupRestore(
    server: ServerRecord,
    backupId: string | undefined,
  ): Promise<McpResponse> {
    if (isSafeMode()) {
      return mcpError(
        "Restore disabled in SAFE_MODE",
        "Set KASTELL_SAFE_MODE=false to enable restore operations",
      );
    }
  
    if (!backupId) {
      return mcpError(
        "backupId is required for backup-restore",
        "Use backup-list to see available backups",
        [{ command: `server_backup { action: 'backup-list', server: '${server.name}' }`, reason: "List available backups" }],
      );
    }
  
    const bare = isBareServer(server);
    const result = bare
      ? await restoreBareBackup(server.ip, server.name, backupId)
      : await restoreBackup(server.ip, server.name, backupId);
  
    if (!result.success) {
      return {
        content: [{ type: "text", text: JSON.stringify({
          server: server.name,
          ip: server.ip,
          backupId,
          error: result.error,
          steps: result.steps,
          ...(result.hint ? { hint: result.hint } : {}),
        }) }],
        isError: true,
      };
    }
  
    const successPayload: Record<string, unknown> = {
      success: true,
      server: server.name,
      ip: server.ip,
      backupId,
      steps: result.steps,
      suggested_actions: [
        {
          command: `server_info { action: 'health', server: '${server.name}' }`,
          reason: bare ? "Verify SSH access after restore" : "Verify Coolify is running",
        },
      ],
    };
  
    if (bare) {
      successPayload.hint = "Config restored. You may need to restart services (e.g., nginx, fail2ban) for changes to take effect.";
    }
  
    return mcpSuccess(successPayload);
  }

• src/mcp/tools/serverBackup.ts:19-35 (schema)

  The schema definition for the `server_backup` MCP tool, validating input actions and parameters.

  export const serverBackupSchema = {
    action: z.enum([
      "backup-create", "backup-list", "backup-restore",
      "snapshot-create", "snapshot-list", "snapshot-delete", "snapshot-restore",
    ]).describe(
      "Backup: 'backup-create' dumps Coolify DB+config via SSH (or system config for bare servers), 'backup-list' shows local backups, 'backup-restore' restores (SAFE_MODE blocks). Snapshot: 'snapshot-create'/'snapshot-list'/'snapshot-delete'/'snapshot-restore' manage cloud snapshots (requires API token). snapshot-restore restores server disk from a cloud snapshot (SAFE_MODE blocks, destructive).",
    ),
    server: z.string().optional().describe(
      "Server name or IP. Auto-selected if only one server exists.",
    ),
    backupId: z.string().regex(/^[\w-]+$/, "Invalid backupId: only alphanumeric, hyphens, underscores allowed").optional().describe(
      "Backup timestamp folder name (required for backup-restore).",
    ),
    snapshotId: z.string().regex(/^[\w./-]+$/, "Invalid snapshotId: only alphanumeric, hyphens, dots, slashes allowed").optional().describe(
      "Cloud snapshot ID (required for snapshot-delete and snapshot-restore).",
    ),
  };

• src/mcp/server.ts:131-146 (registration)

  Registration of the `server_backup` tool in the MCP server setup.

  server.registerTool("server_backup", {
    description:
      "Backup and snapshot Kastell servers. Backup: 'backup-create' dumps Coolify DB + config via SSH (Coolify servers) or system config files (bare servers), 'backup-list' shows local backups, 'backup-restore' restores from backup — bare servers restore system config, Coolify servers restore DB+config (SAFE_MODE blocks restore). Snapshot: 'snapshot-create'/'snapshot-list'/'snapshot-delete' manage cloud provider snapshots (requires provider API token). Snapshots not available for manually added servers.",
    inputSchema: serverBackupSchema,
    annotations: {
      title: "Server Backup & Snapshots",
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: false,
      openWorldHint: true,
    },
  }, async (params) => {
    return handleServerBackup(params);
  });
  
  server.registerTool("server_provision", {