@fruition/fcp-mcp-server 1.26.0 → 1.27.0

package/dist/index.js

@@ -39,6 +39,8 @@ import { runBackgroundSync } from './skills-sync.js';
 // Configuration
 const FCP_API_URL = process.env.FCP_API_URL || 'https://fcp.fru.io';
 const FCP_API_TOKEN = process.env.FCP_API_TOKEN || '';
+// Small async sleep used by bounded polling loops (e.g. fcp_backup_get_database).
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // Unroo API can be called directly (legacy) or proxied through FCP (recommended)
 // When UNROO_API_KEY is not set, Unroo calls go through FCP's proxy at /api/mcp/unroo/*
 const UNROO_API_URL = process.env.UNROO_API_URL || 'https://app.unroo.io';
@@ -112,6 +114,7 @@ const TOOL_PERMISSIONS = {
     fcp_backup_update_pairing: 'admin',
     fcp_backup_download: 'admin',
     fcp_backup_download_prepared: 'admin',
+    fcp_backup_get_database: 'admin',
     fcp_kinsta_backup_download: 'admin',
     fcp_filesync_start_sync: 'admin',
     fcp_filesync_get_confirmation: 'admin',
@@ -198,19 +201,19 @@ const TOOL_PERMISSIONS = {
     fcp_get_bulk_notify_history: 'viewer',
 };
 // Resolved role for the current API key. Cached only on successful lookup so
-// transient FCP outages don't pin us to a failure for the rest of the session.
+// transient FCP outages don't pin us to 'none' for the rest of the session.
 let cachedUserRole;
 async function fetchUserRole() {
     if (cachedUserRole !== undefined)
-        return { ok: true, role: cachedUserRole };
+        return cachedUserRole;
     // dev_bypass is the local-dev token; treat as super_admin to avoid
     // gating local development against role lookup.
     if (FCP_API_TOKEN === 'dev_bypass') {
         cachedUserRole = 'super_admin';
-        return { ok: true, role: 'super_admin' };
+        return cachedUserRole;
     }
     if (!FCP_API_TOKEN) {
-        return { ok: false, kind: 'no_token' };
+        return 'none';
     }
     try {
         const res = await fetch(`${FCP_API_URL}/api/mcp/me`, {
@@ -219,20 +222,17 @@ async function fetchUserRole() {
         });
         if (!res.ok) {
             console.error(`[MCP Server] Role lookup failed: HTTP ${res.status}`);
-            // 401/403 => the API key itself is bad (invalid/expired/revoked).
-            // Everything else (5xx, 429, ...) is treated as a transient failure.
-            const kind = res.status === 401 || res.status === 403 ? 'auth' : 'transient';
-            return { ok: false, kind, status: res.status };
+            return 'none';
         }
         const data = await res.json();
         const role = data?.role ?? 'none';
         cachedUserRole = role;
         console.error(`[MCP Server] Resolved user role: ${role} (${data?.email ?? 'unknown'})`);
-        return { ok: true, role };
+        return role;
     }
     catch (err) {
         console.error('[MCP Server] Role lookup error:', err);
-        return { ok: false, kind: 'transient' };
+        return 'none';
     }
 }
 function isRoleAtLeast(actual, required) {
@@ -246,26 +246,7 @@ function isRoleAtLeast(actual, required) {
 }
 async function enforceToolPermission(toolName) {
     const required = TOOL_PERMISSIONS[toolName] ?? 'viewer';
-    const lookup = await fetchUserRole();
-    // A failed lookup is NOT a role problem. Surface the real cause so the user
-    // takes the right action instead of asking a super_admin for a role they
-    // may already effectively have.
-    if (!lookup.ok) {
-        switch (lookup.kind) {
-            case 'no_token':
-                throw new Error('FCP_API_TOKEN is not set. Add your FCP API key to this MCP server\'s ' +
-                    'env config (create one in FCP → Admin → API Keys).');
-            case 'auth':
-                throw new Error(`Your FCP API key is invalid, expired, or revoked (HTTP ${lookup.status}). ` +
-                    'Create a new key in FCP → Admin → API Keys and update your MCP server ' +
-                    'config. This is NOT a role/permission problem — do not request a role grant.');
-            case 'transient':
-                throw new Error('FCP role lookup is temporarily unavailable' +
-                    (lookup.status ? ` (HTTP ${lookup.status})` : '') +
-                    '. This is a transient FCP error — retry shortly.');
-        }
-    }
-    const actual = lookup.role;
+    const actual = await fetchUserRole();
     if (!isRoleAtLeast(actual, required)) {
         throw new Error(`Permission denied: tool '${toolName}' requires ${required} role; ` +
             `your role is '${actual}'. Contact a super_admin (Brad, Mattox, or Andrea) ` +
@@ -3240,6 +3221,36 @@ const TOOLS = [
             required: ['jobId'],
         },
     },
+    {
+        name: 'fcp_backup_get_database',
+        description: 'Return a database backup for a site in ONE call. Reuses the most recent completed backup if it is younger than maxAgeHours, otherwise triggers a fresh one and waits. Production data is sanitized by default. Returns a presigned download URL (1h expiry) when ready. If the backup or sanitization is still running when waitSeconds is exhausted, returns status:"pending" with a handle (backupId or sanitizeJobId) so you can poll fcp_backup_get_status / fcp_backup_sanitize_status and re-call. Admin only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                websiteId: {
+                    type: 'number',
+                    description: 'The website ID to back up',
+                },
+                maxAgeHours: {
+                    type: 'number',
+                    description: 'Reuse the latest completed backup if it is younger than this many hours (default: 24). Ignored when fresh=true.',
+                },
+                fresh: {
+                    type: 'boolean',
+                    description: 'Force a brand-new backup, ignoring any existing one (default: false).',
+                },
+                sanitize: {
+                    type: 'boolean',
+                    description: 'Whether to sanitize production data. Leave unset to use the server default (production is sanitized, non-production is returned raw). Set false to force a raw dump (admin, use with care).',
+                },
+                waitSeconds: {
+                    type: 'number',
+                    description: 'Total bounded wait budget in seconds across the trigger and sanitize polls (default: 180). On exhaustion the tool returns status:"pending" with a resume handle rather than hanging.',
+                },
+            },
+            required: ['websiteId'],
+        },
+    },
     {
         name: 'fcp_backup_list_pairings',
         description: 'List site pairings for backup management. Optionally filter by site ID. Shows production/staging/dev relationships grouped by account.',
@@ -4951,6 +4962,138 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                 };
             }
+            case 'fcp_backup_get_database': {
+                const { websiteId, maxAgeHours = 24, fresh = false, sanitize, waitSeconds = 180, } = args;
+                const siteId = `site-${websiteId}`;
+                const deadline = Date.now() + Math.max(0, waitSeconds) * 1000;
+                const pollIntervalMs = 10_000;
+                const isDbType = (t) => !!t && ['mysql', 'database', 'postgresql', 'mysqldump'].includes(String(t).toLowerCase());
+                const respond = (payload) => ({
+                    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+                });
+                let backupId;
+                let ageMinutes;
+                // 1. Reuse the most recent completed DB backup unless a fresh one is requested.
+                if (!fresh) {
+                    const list = await client.backupListBackups(siteId);
+                    const backups = Array.isArray(list) ? list : (list?.backups ?? []);
+                    const completed = backups
+                        .filter((b) => b?.status === 'completed' && isDbType(b?.backup_type) && b?.backup_location)
+                        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
+                    const latest = completed[0];
+                    if (latest?.created_at) {
+                        ageMinutes = (Date.now() - new Date(latest.created_at).getTime()) / 60_000;
+                        if (ageMinutes <= maxAgeHours * 60) {
+                            backupId = latest.backup_id;
+                        }
+                    }
+                }
+                // 2. Trigger a fresh backup if none reusable, then poll until completed.
+                if (!backupId) {
+                    const trig = await client.backupTrigger(websiteId, 'mcp');
+                    if (!trig?.backupId) {
+                        return respond({
+                            status: 'error',
+                            stage: 'trigger',
+                            message: trig?.error || trig?.message || 'Failed to trigger backup',
+                            detail: trig,
+                        });
+                    }
+                    backupId = trig.backupId;
+                    ageMinutes = 0;
+                    let backupStatus = trig.status || 'queued';
+                    while (backupStatus !== 'completed') {
+                        if (Date.now() >= deadline) {
+                            return respond({
+                                status: 'pending',
+                                stage: 'backup',
+                                backupId,
+                                message: `Backup still '${backupStatus}' after ${waitSeconds}s. Poll fcp_backup_get_status({ backupId: "${backupId}" }), then re-call fcp_backup_get_database to reuse it once completed.`,
+                            });
+                        }
+                        await sleep(pollIntervalMs);
+                        const st = await client.backupGetStatus({ backupId });
+                        const job = st?.job ?? st;
+                        backupStatus = job?.status || backupStatus;
+                        if (backupStatus === 'failed') {
+                            return respond({
+                                status: 'error',
+                                stage: 'backup',
+                                backupId,
+                                message: job?.error_message || 'Backup job failed',
+                            });
+                        }
+                    }
+                }
+                // 3. Prepare the download (sanitizes production data by default).
+                const prep = await client.backupDownloadPrepared({
+                    siteId,
+                    backupId: backupId,
+                    downloadType: 'database',
+                    sanitize,
+                });
+                // Non-production (or explicit sanitize:false): direct presigned URL.
+                if (prep?.downloadUrl && prep?.sanitized !== true) {
+                    return respond({
+                        status: 'ready',
+                        backupId,
+                        sanitized: false,
+                        downloadUrl: prep.downloadUrl,
+                        fileName: prep.fileName,
+                        sizeBytes: prep.sizeBytes,
+                        backupType: prep.backupType,
+                        ageMinutes: ageMinutes != null ? Math.round(ageMinutes) : undefined,
+                        expiresIn: 3600,
+                    });
+                }
+                // Production: poll the sanitization job until it produces a download URL.
+                if (prep?.jobId) {
+                    const sanitizeJobId = prep.jobId;
+                    for (;;) {
+                        if (Date.now() >= deadline) {
+                            return respond({
+                                status: 'pending',
+                                stage: 'sanitize',
+                                backupId,
+                                sanitizeJobId,
+                                message: `Sanitization still running after ${waitSeconds}s. Poll fcp_backup_sanitize_status({ jobId: "${sanitizeJobId}" }) for the download URL.`,
+                            });
+                        }
+                        await sleep(pollIntervalMs);
+                        const s = await client.backupSanitizeStatus(sanitizeJobId);
+                        if (s?.status === 'completed' && s?.downloadUrl) {
+                            return respond({
+                                status: 'ready',
+                                backupId,
+                                sanitizeJobId,
+                                sanitized: true,
+                                downloadUrl: s.downloadUrl,
+                                fileName: s.fileName,
+                                sizeBytes: s.sanitizedSizeBytes,
+                                ageMinutes: ageMinutes != null ? Math.round(ageMinutes) : undefined,
+                                expiresIn: 3600,
+                            });
+                        }
+                        if (s?.status === 'failed') {
+                            return respond({
+                                status: 'error',
+                                stage: 'sanitize',
+                                backupId,
+                                sanitizeJobId,
+                                message: s?.error || 'Sanitization failed',
+                            });
+                        }
+                    }
+                }
+                // Unexpected prepare response — surface it for debugging.
+                return respond({
+                    status: 'error',
+                    stage: 'prepare',
+                    backupId,
+                    message: 'Unexpected response from backup download preparation',
+                    detail: prep,
+                });
+            }
             case 'fcp_backup_list_pairings': {
                 const { siteId } = args;
                 const result = await client.backupListPairings(siteId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruition/fcp-mcp-server",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "MCP Server for FCP Launch Coordination System - enables Claude Code to interact with FCP launches and track development time",
   "main": "dist/index.js",
   "type": "module",