@fruition/fcp-mcp-server 1.24.1 → 1.26.0

package/dist/index.js

@@ -93,6 +93,7 @@ const TOOL_PERMISSIONS = {
     fcp_clone_to_staging: 'super_admin',
     fcp_clone_confirm: 'super_admin',
     fcp_shield_remove_domain: 'super_admin',
+    fcp_trusted_ip_remove_range: 'super_admin',
     fcp_backup_delete_pairing: 'super_admin',
     fcp_filesync_cancel_sync: 'super_admin',
     // --- admin+: mutating ops with real-world side effects ---
@@ -103,6 +104,8 @@ const TOOL_PERMISSIONS = {
     fcp_delete_checklist_item: 'admin',
     fcp_shield_add_domain: 'admin',
     fcp_shield_update_domain: 'admin',
+    fcp_trusted_ip_add_range: 'admin',
+    fcp_trusted_ip_update_range: 'admin',
     fcp_backup_enable: 'admin',
     fcp_backup_trigger: 'admin',
     fcp_backup_check_trigger: 'admin',
@@ -149,6 +152,8 @@ const TOOL_PERMISSIONS = {
     fcp_shield_list_domains: 'viewer',
     fcp_shield_get_domain: 'viewer',
     fcp_shield_get_metrics: 'viewer',
+    fcp_trusted_ip_list_ranges: 'viewer',
+    fcp_trusted_ip_export: 'viewer',
     fcp_backup_list_sites: 'viewer',
     fcp_backup_get_config: 'viewer',
     fcp_backup_list_eligible: 'viewer',
@@ -169,21 +174,43 @@ const TOOL_PERMISSIONS = {
     unroo_get_my_tasks: 'viewer',
     unroo_get_parking_lot: 'viewer',
     unroo_get_backlog: 'viewer',
+    // --- Alerting ---
+    // admin: hard-delete of a rule and client-facing bulk notifications are
+    // higher-stakes than internal alert create/close, so gate them tighter.
+    fcp_delete_alert_rule: 'admin',
+    fcp_bulk_notify_clients: 'admin',
+    // operator: routine alert/outage writes (create, close, update).
+    fcp_create_alert: 'operator',
+    fcp_update_alert: 'operator',
+    fcp_create_alert_rule: 'operator',
+    fcp_update_alert_rule: 'operator',
+    fcp_create_outage: 'operator',
+    fcp_update_outage: 'operator',
+    fcp_resolve_outage: 'operator',
+    // viewer: reads.
+    fcp_list_alerts: 'viewer',
+    fcp_get_alert: 'viewer',
+    fcp_get_alert_stats: 'viewer',
+    fcp_list_alert_rules: 'viewer',
+    fcp_get_alert_rule: 'viewer',
+    fcp_list_outages: 'viewer',
+    fcp_get_outage: 'viewer',
+    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 'none' for the rest of the session.
+// transient FCP outages don't pin us to a failure for the rest of the session.
 let cachedUserRole;
 async function fetchUserRole() {
     if (cachedUserRole !== undefined)
-        return cachedUserRole;
+        return { ok: true, role: 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 cachedUserRole;
+        return { ok: true, role: 'super_admin' };
     }
     if (!FCP_API_TOKEN) {
-        return 'none';
+        return { ok: false, kind: 'no_token' };
     }
     try {
         const res = await fetch(`${FCP_API_URL}/api/mcp/me`, {
@@ -192,17 +219,20 @@ async function fetchUserRole() {
         });
         if (!res.ok) {
             console.error(`[MCP Server] Role lookup failed: HTTP ${res.status}`);
-            return 'none';
+            // 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 };
         }
         const data = await res.json();
         const role = data?.role ?? 'none';
         cachedUserRole = role;
         console.error(`[MCP Server] Resolved user role: ${role} (${data?.email ?? 'unknown'})`);
-        return role;
+        return { ok: true, role };
     }
     catch (err) {
         console.error('[MCP Server] Role lookup error:', err);
-        return 'none';
+        return { ok: false, kind: 'transient' };
     }
 }
 function isRoleAtLeast(actual, required) {
@@ -216,7 +246,26 @@ function isRoleAtLeast(actual, required) {
 }
 async function enforceToolPermission(toolName) {
     const required = TOOL_PERMISSIONS[toolName] ?? 'viewer';
-    const actual = await fetchUserRole();
+    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;
     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) ` +
@@ -368,6 +417,97 @@ class FCPClient {
             method: 'DELETE',
         });
     }
+    // --- Alerting: incidents (alert_events), rules, outages, bulk notifications ---
+    // Thin wrappers over the FCP alerting HTTP API. Request bodies are camelCase
+    // (the API maps to snake_case DB columns internally).
+    // Build a query string from defined params (skips undefined/empty values).
+    buildQuery(q) {
+        const entries = Object.entries(q)
+            .filter(([, v]) => v !== undefined && v !== null && v !== '')
+            .map(([k, v]) => [k, String(v)]);
+        const qs = new URLSearchParams(entries).toString();
+        return qs ? `?${qs}` : '';
+    }
+    // Incidents (individual alerts).
+    async listAlerts(q = {}) {
+        return this.fetch(`/api/incidents${this.buildQuery(q)}`);
+    }
+    async getAlert(id) {
+        return this.fetch(`/api/incidents/${id}`);
+    }
+    async createAlert(input) {
+        return this.fetch('/api/incidents', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async updateAlert(id, updates) {
+        return this.fetch(`/api/incidents/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    async getAlertStats() {
+        return this.fetch('/api/incidents/stats');
+    }
+    // Alert rules (notification configuration).
+    async listAlertRules(accountId) {
+        return this.fetch(`/api/alerts/rules${this.buildQuery({ accountId })}`);
+    }
+    async getAlertRule(ruleId) {
+        return this.fetch(`/api/alerts/rules/${ruleId}`);
+    }
+    async createAlertRule(input) {
+        return this.fetch('/api/alerts/rules', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async updateAlertRule(ruleId, updates) {
+        return this.fetch(`/api/alerts/rules/${ruleId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    async deleteAlertRule(ruleId) {
+        return this.fetch(`/api/alerts/rules/${ruleId}`, {
+            method: 'DELETE',
+        });
+    }
+    // Outages (admin outage tracking).
+    async listOutages(q = {}) {
+        return this.fetch(`/api/alerts/outages${this.buildQuery(q)}`);
+    }
+    async getOutage(outageId) {
+        return this.fetch(`/api/alerts/outages/${outageId}`);
+    }
+    async createOutage(input) {
+        return this.fetch('/api/alerts/outages', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async updateOutage(outageId, updates) {
+        return this.fetch(`/api/alerts/outages/${outageId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    async resolveOutage(outageId) {
+        return this.fetch(`/api/alerts/outages/${outageId}`, {
+            method: 'DELETE',
+        });
+    }
+    // Bulk client notifications. Sends real emails/SMS to clients — handle with care.
+    async bulkNotifyClients(input) {
+        return this.fetch('/api/alerts/bulk-notify', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async getBulkNotifyHistory(limit) {
+        return this.fetch(`/api/alerts/bulk-notify${this.buildQuery({ limit })}`);
+    }
     async createLaunch(input) {
         return this.fetch('/api/launches', {
             method: 'POST',
@@ -586,6 +726,78 @@ class FCPClient {
         });
     }
     // ============================================================================
+    // Trusted IP Range Methods (FRUPRI-761)
+    // ============================================================================
+    // Text-returning sibling of fetch() for endpoints that emit text/plain or
+    // text/yaml (export) or an empty 204 body (delete). The base fetch() always
+    // calls response.json() and would throw on those.
+    async fetchText(path, options = {}, timeoutMs) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            ...(options.headers || {}),
+        };
+        if (this.token) {
+            if (this.token === 'dev_bypass') {
+                headers['X-Dev-Bypass'] = 'true';
+            }
+            else {
+                headers['X-API-Key'] = this.token;
+            }
+        }
+        const response = await fetch(url, {
+            ...options,
+            headers,
+            signal: AbortSignal.timeout(timeoutMs || this.defaultTimeout),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`FCP API error (${response.status}): ${error}`);
+        }
+        return response.text();
+    }
+    async trustedIpListRanges(filters) {
+        const params = new URLSearchParams();
+        if (filters?.group)
+            params.append('group', filters.group);
+        if (filters?.include_pending)
+            params.append('include_pending', 'true');
+        if (filters?.include_expired)
+            params.append('include_expired', 'true');
+        const qs = params.toString();
+        return this.fetch(`/api/infrastructure/trusted-ips/entries${qs ? `?${qs}` : ''}`);
+    }
+    async trustedIpAddRange(input) {
+        return this.fetch('/api/infrastructure/trusted-ips/entries', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async trustedIpUpdateRange(id, updates) {
+        return this.fetch(`/api/infrastructure/trusted-ips/entries/${id}`, {
+            method: 'PUT',
+            body: JSON.stringify(updates),
+        });
+    }
+    async trustedIpRemoveRange(id) {
+        await this.fetchText(`/api/infrastructure/trusted-ips/entries/${id}`, {
+            method: 'DELETE',
+        });
+        return { ok: true, id, message: `Removed trusted IP entry ${id}` };
+    }
+    async trustedIpExport(opts) {
+        const params = new URLSearchParams();
+        if (opts?.format)
+            params.append('format', opts.format);
+        if (opts?.group)
+            params.append('group', opts.group);
+        if (opts?.purpose)
+            params.append('purpose', opts.purpose);
+        if (opts?.separator)
+            params.append('separator', opts.separator);
+        const qs = params.toString();
+        return this.fetchText(`/api/infrastructure/trusted-ips/export${qs ? `?${qs}` : ''}`);
+    }
+    // ============================================================================
     // Backup Management Methods
     // ============================================================================
     async backupListSites() {
@@ -2161,7 +2373,7 @@ const TOOLS = [
     // Nuclei Security Scanning
     {
         name: 'fcp_trigger_nuclei_scan',
-        description: 'Trigger a Nuclei security scan for a website. Creates a Kubernetes Job that runs the scan and stores results in the FCP database.',
+        description: 'Trigger a Nuclei security scan for a website. Queues the scan as a pending record in the FCP database for the local scanner to pick up and run; findings are written back to the database. Returns the scan ID for follow-up queries with fcp_get_nuclei_results.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2179,7 +2391,7 @@ const TOOLS = [
                 },
                 templates: {
                     type: 'string',
-                    description: 'Comma-separated Nuclei template categories (default: cves,exposures,misconfiguration). Options: cves, vulnerabilities, exposures, misconfiguration, technologies',
+                    description: 'Comma-separated Nuclei template categories (default: cves,exposures,misconfiguration). Options: cves, vulnerabilities, exposures, misconfiguration, technologies, ssl, dns, headless',
                 },
             },
             required: ['website_id'],
@@ -2621,7 +2833,7 @@ const TOOLS = [
     },
     {
         name: 'fcp_shield_add_domain',
-        description: 'Add a domain to Fruition Shield WAF protection. Returns DNS records (traffic CNAME + cert validation CNAME) that must be added at the registrar.',
+        description: 'Add a domain to Fruition Shield WAF protection. Custom mode (default) fronts an origin server via the shared distribution. S3 mode (origin_type="s3") provisions a DEDICATED CloudFront distribution + OAC over a private S3 bucket (Steldris static hosting) and returns its distribution id + CloudFront domain. Returns DNS records to add at the registrar.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -2629,9 +2841,14 @@ const TOOLS = [
                     type: 'string',
                     description: 'Domain to protect (e.g., www.butterflies.org)',
                 },
+                origin_type: {
+                    type: 'string',
+                    enum: ['custom', 's3'],
+                    description: 'Origin mode: custom (shared distribution + origin server, default) or s3 (dedicated distribution + OAC over a private S3 bucket).',
+                },
                 origin_host: {
                     type: 'string',
-                    description: 'Origin server IP or hostname (e.g., 146.190.2.169 for K8s prod)',
+                    description: 'Origin server IP or hostname (e.g., 146.190.2.169 for K8s prod). Required for origin_type=custom; ignored for s3.',
                 },
                 origin_port: {
                     type: 'number',
@@ -2641,6 +2858,18 @@ const TOOLS = [
                     type: 'string',
                     description: 'Origin protocol: http or https (default: https)',
                 },
+                s3_bucket: {
+                    type: 'string',
+                    description: 'S3 artifacts bucket (origin_type=s3, e.g. steldris-sites-prod). Required for s3 mode.',
+                },
+                s3_region: {
+                    type: 'string',
+                    description: 'S3 bucket region (origin_type=s3, e.g. us-east-1). Required for s3 mode.',
+                },
+                s3_origin_path: {
+                    type: 'string',
+                    description: 'CloudFront OriginPath — the per-tenant key prefix (origin_type=s3, e.g. /acme).',
+                },
                 website_id: {
                     type: 'number',
                     description: 'Link to existing FCP website ID',
@@ -2651,14 +2880,14 @@ const TOOLS = [
                 },
                 cache_profile: {
                     type: 'string',
-                    description: 'Cache profile: standard, aggressive, minimal, none (default: standard)',
+                    description: 'Cache profile: standard, aggressive, minimal, none (default: standard; s3 defaults to aggressive)',
                 },
                 notes: {
                     type: 'string',
                     description: 'Notes about this domain',
                 },
             },
-            required: ['domain', 'origin_host'],
+            required: ['domain'],
         },
     },
     {
@@ -2730,6 +2959,126 @@ const TOOLS = [
         },
     },
     // ============================================================================
+    // Trusted IP Range Tools (FRUPRI-761)
+    // ============================================================================
+    {
+        name: 'fcp_trusted_ip_list_ranges',
+        description: 'List trusted IP ranges (CIDR entries). Scope to a group by id or slug, or omit group to list entries for every group (each tagged with group_slug). By default only approved, non-expired entries are returned.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group: {
+                    type: 'string',
+                    description: 'Group id or slug to scope to (optional; omit for all groups)',
+                },
+                include_pending: {
+                    type: 'boolean',
+                    description: 'Include entries awaiting approval (default false)',
+                },
+                include_expired: {
+                    type: 'boolean',
+                    description: 'Include entries past their expires_at (default false)',
+                },
+            },
+        },
+    },
+    {
+        name: 'fcp_trusted_ip_add_range',
+        description: 'Add a CIDR to a trusted IP group. If the CIDR overlaps an existing entry the request is rejected with code=overlap unless override_reason (>=10 chars) is supplied to force-insert.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                group_id: { type: 'number', description: 'Target group id' },
+                cidr: {
+                    type: 'string',
+                    description: 'CIDR or bare IP (e.g. 73.241.16.0/24 or 73.241.16.5)',
+                },
+                label: { type: 'string', description: 'Human label for the range' },
+                purpose: {
+                    type: 'string',
+                    enum: ['employee-home', 'office', 'vendor', 'ci-runner', 'migration', 'partner', 'other'],
+                    description: 'Structured purpose',
+                },
+                ticket_ref: { type: 'string', description: 'Associated ticket reference' },
+                expires_at: {
+                    type: 'string',
+                    description: 'ISO-8601 expiry timestamp, or null for permanent',
+                },
+                override_reason: {
+                    type: 'string',
+                    description: 'Reason (>=10 chars) to force-insert past an overlap',
+                },
+            },
+            required: ['group_id', 'cidr'],
+        },
+    },
+    {
+        name: 'fcp_trusted_ip_update_range',
+        description: 'Update mutable fields of a trusted IP entry (label, purpose, ticket_ref, expires_at, approval_state). The CIDR itself is immutable; remove and re-add to change it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'Entry id to update' },
+                label: { type: 'string', description: 'New label' },
+                purpose: {
+                    type: 'string',
+                    enum: ['employee-home', 'office', 'vendor', 'ci-runner', 'migration', 'partner', 'other'],
+                    description: 'New purpose',
+                },
+                ticket_ref: { type: 'string', description: 'New ticket reference' },
+                expires_at: {
+                    type: 'string',
+                    description: 'New ISO-8601 expiry, or null for permanent',
+                },
+                approval_state: {
+                    type: 'string',
+                    enum: ['approved', 'pending', 'denied'],
+                    description: 'New approval state',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'fcp_trusted_ip_remove_range',
+        description: 'Remove a trusted IP entry by id. The next sync run withdraws the CIDR from any live ingress/WAF targets the group propagates to.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'Entry id to remove' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'fcp_trusted_ip_export',
+        description: 'Export approved, non-expired CIDRs for a group (or all groups) in a consumable form. format=plain (default) joins CIDRs with separator (use separator=comma for an ingress-nginx whitelist-source-range value); format=json and format=yaml are also supported.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                format: {
+                    type: 'string',
+                    enum: ['plain', 'json', 'yaml'],
+                    description: 'Output format (default plain)',
+                },
+                group: {
+                    type: 'string',
+                    description: 'Group id or slug to scope to (optional; omit for all groups)',
+                },
+                purpose: {
+                    type: 'string',
+                    enum: ['employee-home', 'office', 'vendor', 'ci-runner', 'migration', 'partner', 'other'],
+                    description: 'Optional purpose filter',
+                },
+                separator: {
+                    type: 'string',
+                    enum: ['newline', 'comma', 'space'],
+                    description: 'Separator for plain format (default newline)',
+                },
+            },
+        },
+    },
+    // ============================================================================
     // Backup Management Tools
     // ============================================================================
     {
@@ -3083,6 +3432,344 @@ const TOOLS = [
             required: ['siteId'],
         },
     },
+    // ===================== Alerting: incidents (alerts) =====================
+    {
+        name: 'fcp_list_alerts',
+        description: 'List alerts (incidents). Defaults to ACTIVE alerts (status firing,acknowledged). Pass status="resolved" for past alerts, or status="all" for everything. Alerts come from alertmanager, GCP monitoring, uptimerobot, cluster_health, or manual creation. Supports filtering by source, severity, cluster, namespace, domain, website, and time range.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    description: 'Comma-separated statuses. Default "firing,acknowledged" (active). Use "resolved" for past, "silenced", or "all" for everything.',
+                },
+                source: {
+                    type: 'string',
+                    enum: ['alertmanager', 'gcp_monitoring', 'uptimerobot', 'cluster_health', 'manual'],
+                    description: 'Filter by alert source',
+                },
+                severity: {
+                    type: 'string',
+                    description: 'Comma-separated severities: critical, high, medium, low, info',
+                },
+                cluster: { type: 'string', description: 'Filter by cluster name' },
+                namespace: { type: 'string', description: 'Filter by namespace' },
+                domain: { type: 'string', description: 'Filter by domain (partial match)' },
+                websiteId: { type: 'number', description: 'Filter by FCP website ID' },
+                environment: { type: 'string', description: 'Filter by site environment (production, staging)' },
+                from: { type: 'string', description: 'Start of time range (ISO timestamp), filters started_at' },
+                to: { type: 'string', description: 'End of time range (ISO timestamp), filters started_at' },
+                page: { type: 'number', description: 'Page number (default 1)' },
+                limit: { type: 'number', description: 'Results per page (default 50, max 200)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'fcp_get_alert',
+        description: 'Get full detail for a single alert (incident) by ID, including linked site/account info.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'The alert (incident) ID' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'fcp_create_alert',
+        description: 'Create a MANUAL alert (incident). Source is always "manual". Use this to manually raise an alert that did not come from automated monitoring. Returns the created alert with status "firing".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                alertName: { type: 'string', description: 'Short alert name/title (required)' },
+                severity: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    description: 'Severity (default: medium)',
+                },
+                summary: { type: 'string', description: 'Human-readable summary of the alert' },
+                cluster: { type: 'string', description: 'Affected cluster, if any' },
+                namespace: { type: 'string', description: 'Affected namespace, if any' },
+                domain: { type: 'string', description: 'Affected domain, if any' },
+                websiteId: { type: 'number', description: 'Link to an FCP website ID, if applicable' },
+            },
+            required: ['alertName'],
+        },
+    },
+    {
+        name: 'fcp_update_alert',
+        description: 'Update an alert (incident): acknowledge, silence, resolve (CLOSE), add admin notes, link a site, or link a Unroo task. To CLOSE an alert, set status="resolved". Silencing requires silencedUntil.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'The alert (incident) ID' },
+                status: {
+                    type: 'string',
+                    enum: ['acknowledged', 'resolved', 'silenced'],
+                    description: 'New status. "resolved" closes the alert; "silenced" requires silencedUntil.',
+                },
+                acknowledgedBy: { type: 'string', description: 'Who acknowledged (when status=acknowledged)' },
+                silencedUntil: { type: 'string', description: 'ISO timestamp to silence until (required when status=silenced)' },
+                silencedBy: { type: 'string', description: 'Who silenced (when status=silenced)' },
+                adminNotes: { type: 'string', description: 'Internal admin notes' },
+                websiteId: { type: 'number', description: 'Link/relink to an FCP website ID' },
+                unrooTaskId: { type: 'number', description: 'Link to a Unroo task ID' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'fcp_get_alert_stats',
+        description: 'Get alert summary statistics for the last 7 days: counts by status, by source, critical-active count, and per-cluster breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    // ===================== Alerting: rules (notification config) =====================
+    {
+        name: 'fcp_list_alert_rules',
+        description: 'List client alert rules (notification configuration). Optionally filter by account.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                accountId: { type: 'number', description: 'Filter rules by account ID' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'fcp_get_alert_rule',
+        description: 'Get a single alert rule by ID, with account and website context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ruleId: { type: 'number', description: 'The alert rule ID' },
+            },
+            required: ['ruleId'],
+        },
+    },
+    {
+        name: 'fcp_create_alert_rule',
+        description: 'Create a client alert rule defining which events trigger notifications, on which channels, with flapping/business-hours controls.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                accountId: { type: 'number', description: 'Account this rule belongs to (required)' },
+                websiteId: { type: 'number', description: 'Specific website, or omit/null for all sites in the account' },
+                name: { type: 'string', description: 'Rule name (required)' },
+                description: { type: 'string', description: 'Optional description' },
+                eventType: {
+                    type: 'string',
+                    enum: ['uptime_down', 'uptime_up', 'maintenance', 'cve', 'ssl_expiry', 'domain_expiry'],
+                    description: 'Event type that triggers this rule (required)',
+                },
+                severityThreshold: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    description: 'Minimum severity to trigger (default: info)',
+                },
+                notifyChannels: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['email', 'teams', 'slack', 'sms'] },
+                    description: 'Channels to notify on',
+                },
+                delaySeconds: { type: 'number', description: 'Delay before notifying (flap prevention)' },
+                cooldownSeconds: { type: 'number', description: 'Cooldown between repeat notifications' },
+                businessHoursOnly: { type: 'boolean', description: 'Only notify during business hours' },
+                businessHoursStart: { type: 'string', description: 'Business hours start (e.g. "09:00")' },
+                businessHoursEnd: { type: 'string', description: 'Business hours end (e.g. "17:00")' },
+                businessHoursTimezone: { type: 'string', description: 'IANA timezone for business hours' },
+                createdBy: { type: 'string', description: 'Who created the rule' },
+            },
+            required: ['accountId', 'name', 'eventType'],
+        },
+    },
+    {
+        name: 'fcp_update_alert_rule',
+        description: 'Update an existing alert rule. Only provided fields are changed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ruleId: { type: 'number', description: 'The alert rule ID (required)' },
+                name: { type: 'string', description: 'Rule name' },
+                description: { type: 'string', description: 'Description' },
+                severityThreshold: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    description: 'Minimum severity to trigger',
+                },
+                notifyChannels: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['email', 'teams', 'slack', 'sms'] },
+                    description: 'Channels to notify on',
+                },
+                delaySeconds: { type: 'number', description: 'Delay before notifying' },
+                cooldownSeconds: { type: 'number', description: 'Cooldown between repeat notifications' },
+                businessHoursOnly: { type: 'boolean', description: 'Only notify during business hours' },
+                businessHoursStart: { type: 'string', description: 'Business hours start' },
+                businessHoursEnd: { type: 'string', description: 'Business hours end' },
+                businessHoursTimezone: { type: 'string', description: 'IANA timezone' },
+                isActive: { type: 'boolean', description: 'Enable/disable the rule' },
+                updatedBy: { type: 'string', description: 'Who updated the rule' },
+            },
+            required: ['ruleId'],
+        },
+    },
+    {
+        name: 'fcp_delete_alert_rule',
+        description: 'Permanently DELETE an alert rule (hard delete). Requires admin. This cannot be undone.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ruleId: { type: 'number', description: 'The alert rule ID to delete' },
+            },
+            required: ['ruleId'],
+        },
+    },
+    // ===================== Alerting: outages =====================
+    {
+        name: 'fcp_list_outages',
+        description: 'List active outages (admin outage tracking). Filter by status (active/resolved/all), account, and limit.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: { type: 'string', description: 'Filter: active, resolved, or all (default: active)' },
+                accountId: { type: 'number', description: 'Filter by account ID' },
+                limit: { type: 'number', description: 'Max results' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'fcp_get_outage',
+        description: 'Get a single outage by ID, with its timeline updates, notification history, and affected client contacts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outageId: { type: 'number', description: 'The outage ID' },
+            },
+            required: ['outageId'],
+        },
+    },
+    {
+        name: 'fcp_create_outage',
+        description: 'Create an outage record for centralized outage management, optionally linked to an incident.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                incidentId: { type: 'number', description: 'Linked incident ID (from downtime_incidents)' },
+                websiteId: { type: 'number', description: 'Affected website ID' },
+                accountId: { type: 'number', description: 'Affected account ID' },
+                startedAt: { type: 'string', description: 'Outage start (ISO timestamp)' },
+                domain: { type: 'string', description: 'Affected domain' },
+                environment: { type: 'string', description: 'Environment (production, staging)' },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'investigating', 'identified', 'monitoring', 'resolved'],
+                    description: 'Outage status (default: active)',
+                },
+                severity: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    description: 'Severity',
+                },
+                likelyCause: { type: 'string', description: 'Likely cause description' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'fcp_update_outage',
+        description: 'Update an outage: status, severity, likely cause, admin notes, assignee. Optionally append a timeline updateMessage. ⚠️ Setting notifyClients=true SENDS REAL NOTIFICATIONS to affected clients.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outageId: { type: 'number', description: 'The outage ID (required)' },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'investigating', 'identified', 'monitoring', 'resolved'],
+                    description: 'New outage status',
+                },
+                severity: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'info'],
+                    description: 'New severity',
+                },
+                likelyCause: { type: 'string', description: 'Likely cause' },
+                adminNotes: { type: 'string', description: 'Internal admin notes' },
+                assignedTo: { type: 'string', description: 'Assignee' },
+                updateMessage: { type: 'string', description: 'Timeline update message to append' },
+                notifyClients: {
+                    type: 'boolean',
+                    description: '⚠️ If true, sends real notifications to affected clients. Default false.',
+                },
+                updatedBy: { type: 'string', description: 'Who made the update' },
+                confirm: {
+                    type: 'boolean',
+                    description: 'Safety gate for client notifications. Only consulted when notifyClients=true: must be explicitly true to actually send. notifyClients=true without confirm=true makes the tool refuse (the rest of the update is NOT applied). No effect when notifyClients is absent/false.',
+                },
+            },
+            required: ['outageId'],
+        },
+    },
+    {
+        name: 'fcp_resolve_outage',
+        description: 'Resolve and close an outage (soft resolve — sets status to resolved and stamps resolved_at). Adds a resolution timeline entry.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outageId: { type: 'number', description: 'The outage ID to resolve' },
+            },
+            required: ['outageId'],
+        },
+    },
+    // ===================== Alerting: bulk client notifications =====================
+    {
+        name: 'fcp_bulk_notify_clients',
+        description: '⚠️ SENDS REAL NOTIFICATIONS (email/Teams/Slack/SMS) to all clients affected by the given outages. Requires admin. Use deliberately — this contacts real people.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                outageIds: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Non-empty array of outage IDs whose affected clients should be notified',
+                },
+                notificationType: {
+                    type: 'string',
+                    enum: ['outage_initial', 'outage_update', 'recovery'],
+                    description: 'Type of notification',
+                },
+                subject: { type: 'string', description: 'Notification subject (required)' },
+                message: { type: 'string', description: 'Notification body (required)' },
+                channels: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['email', 'teams', 'slack', 'sms'] },
+                    description: 'Channels to send on (default: ["email"])',
+                },
+                sentBy: { type: 'string', description: 'Who sent the notification' },
+                confirm: {
+                    type: 'boolean',
+                    description: 'REQUIRED safety gate. Must be explicitly true to actually dispatch. Omitting or false makes the tool refuse and report who would be contacted — call again with confirm=true only after a human has approved sending.',
+                },
+            },
+            required: ['outageIds', 'notificationType', 'subject', 'message'],
+        },
+    },
+    {
+        name: 'fcp_get_bulk_notify_history',
+        description: 'Get history of bulk client notifications (batches sent), most recent first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: { type: 'number', description: 'Max results (default 20)' },
+            },
+            required: [],
+        },
+    },
 ];
 // Register tool handlers
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -4086,9 +4773,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'fcp_shield_add_domain': {
-                const { domain, origin_host, origin_port, origin_protocol, website_id, account_id, cache_profile, notes } = args;
+                const { domain, origin_type, origin_host, origin_port, origin_protocol, s3_bucket, s3_region, s3_origin_path, website_id, account_id, cache_profile, notes } = args;
                 const result = await client.shieldAddDomain({
-                    domain, origin_host, origin_port, origin_protocol, website_id, account_id, cache_profile, notes,
+                    domain, origin_type, origin_host, origin_port, origin_protocol, s3_bucket, s3_region, s3_origin_path, website_id, account_id, cache_profile, notes,
                 });
                 return {
                     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -4122,6 +4809,72 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             // ============================================================================
+            // Trusted IP Range Handlers (FRUPRI-761)
+            // ============================================================================
+            case 'fcp_trusted_ip_list_ranges': {
+                const { group, include_pending, include_expired } = args;
+                const result = await client.trustedIpListRanges({
+                    group,
+                    include_pending,
+                    include_expired,
+                });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_trusted_ip_add_range': {
+                const { group_id, cidr, label, purpose, ticket_ref, expires_at, override_reason, } = args;
+                const result = await client.trustedIpAddRange({
+                    group_id,
+                    cidr,
+                    label,
+                    purpose,
+                    ticket_ref,
+                    expires_at,
+                    override_reason,
+                });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_trusted_ip_update_range': {
+                const { id, label, purpose, ticket_ref, expires_at, approval_state } = args;
+                const updates = {};
+                if (label !== undefined)
+                    updates.label = label;
+                if (purpose !== undefined)
+                    updates.purpose = purpose;
+                if (ticket_ref !== undefined)
+                    updates.ticket_ref = ticket_ref;
+                if (expires_at !== undefined)
+                    updates.expires_at = expires_at;
+                if (approval_state !== undefined)
+                    updates.approval_state = approval_state;
+                const result = await client.trustedIpUpdateRange(id, updates);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_trusted_ip_remove_range': {
+                const { id } = args;
+                const result = await client.trustedIpRemoveRange(id);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_trusted_ip_export': {
+                const { format, group, purpose, separator } = args;
+                const text = await client.trustedIpExport({
+                    format,
+                    group,
+                    purpose,
+                    separator,
+                });
+                return {
+                    content: [{ type: 'text', text }],
+                };
+            }
+            // ============================================================================
             // Backup Management Handlers
             // ============================================================================
             case 'fcp_backup_list_sites': {
@@ -4287,6 +5040,180 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                 };
             }
+            // ===================== Alerting: incidents (alerts) =====================
+            case 'fcp_list_alerts': {
+                const result = await client.listAlerts(args);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_get_alert': {
+                const { id } = args;
+                const result = await client.getAlert(id);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_create_alert': {
+                const { alertName, severity, summary, cluster, namespace, domain, websiteId } = args;
+                const result = await client.createAlert({ alertName, severity, summary, cluster, namespace, domain, websiteId });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Alert created: "${alertName}"`, alert: result?.incident ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_update_alert': {
+                const { id, ...updates } = args;
+                const result = await client.updateAlert(id, updates);
+                const verb = updates.status === 'resolved' ? 'closed (resolved)' : `updated${updates.status ? ` to ${updates.status}` : ''}`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Alert ${id} ${verb}`, alert: result?.incident ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_get_alert_stats': {
+                const result = await client.getAlertStats();
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            // ===================== Alerting: rules =====================
+            case 'fcp_list_alert_rules': {
+                const { accountId } = args;
+                const result = await client.listAlertRules(accountId);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_get_alert_rule': {
+                const { ruleId } = args;
+                const result = await client.getAlertRule(ruleId);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_create_alert_rule': {
+                const result = await client.createAlertRule(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: 'Alert rule created', rule: result?.rule ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_update_alert_rule': {
+                const { ruleId, ...updates } = args;
+                const result = await client.updateAlertRule(ruleId, updates);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Alert rule ${ruleId} updated`, rule: result?.rule ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_delete_alert_rule': {
+                const { ruleId } = args;
+                const result = await client.deleteAlertRule(ruleId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Alert rule ${ruleId} deleted`, result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // ===================== Alerting: outages =====================
+            case 'fcp_list_outages': {
+                const result = await client.listOutages(args);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_get_outage': {
+                const { outageId } = args;
+                const result = await client.getOutage(outageId);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_create_outage': {
+                const result = await client.createOutage(args);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: 'Outage created', outage: result?.outage ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_update_outage': {
+                const { outageId, confirm, ...updates } = args;
+                // Safety gate: a notifying update must be explicitly confirmed. We refuse the
+                // WHOLE update (not just the notify) so a half-applied state can't occur.
+                if (updates.notifyClients === true && confirm !== true) {
+                    throw new Error(`Refusing to update: outage ${outageId} update has notifyClients=true, which SENDS REAL notifications ` +
+                        `to affected clients. Re-call with confirm=true to apply this update and notify, or drop notifyClients ` +
+                        `to update silently.`);
+                }
+                const result = await client.updateOutage(outageId, updates);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Outage ${outageId} updated`, outage: result?.outage ?? result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'fcp_resolve_outage': {
+                const { outageId } = args;
+                const result = await client.resolveOutage(outageId);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ success: true, message: `Outage ${outageId} resolved`, result }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // ===================== Alerting: bulk client notifications =====================
+            case 'fcp_bulk_notify_clients': {
+                const { outageIds, notificationType, subject, message, channels, sentBy, confirm } = args;
+                // Safety gate: refuse to email/SMS real clients unless explicitly confirmed.
+                if (confirm !== true) {
+                    const ch = (channels && channels.length ? channels : ['email']).join(', ');
+                    const n = Array.isArray(outageIds) ? outageIds.length : 0;
+                    throw new Error(`Refusing to send: fcp_bulk_notify_clients dispatches REAL ${ch} notifications to clients ` +
+                        `affected by ${n} outage(s) [${Array.isArray(outageIds) ? outageIds.join(', ') : ''}]. ` +
+                        `Confirm with a human, then re-call with confirm=true to proceed.`);
+                }
+                const result = await client.bulkNotifyClients({ outageIds, notificationType, subject, message, channels, sentBy });
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_get_bulk_notify_history': {
+                const { limit } = args;
+                const result = await client.getBulkNotifyHistory(limit);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/skills-sync.d.ts

@@ -105,6 +105,17 @@ export declare function discoverLocalSkills(skillsDir: string): Promise<ParsedSk
  * Returns null if pushable, or a reason string if not.
  */
 export declare function pushSkipReason(skill: ParsedSkill): string | null;
+/**
+ * Validate a slug that arrives from the *remote* knowledge graph before it is
+ * used to build a filesystem path on pull. `node.source_id`/`node.name` are
+ * attacker-influenceable (any team member or compromised KG can author a skill
+ * node with an arbitrary source_id), so an unchecked slug like
+ * `../../../.config/autostart/x` would let `join(skillsDir, slug, ...)` escape
+ * the skills directory and write attacker content anywhere the user can write.
+ * A safe slug is a single path component: no separators, no `..`, no leading
+ * dot/tilde, no control/whitespace. Returns null if safe, else a reason string.
+ */
+export declare function pullSlugReason(slug: string): string | null;
 /**
  * Detect control characters (other than tab, LF, CR) in the body. The Unroo
  * capture-skill endpoint 500s on null bytes — and they're never legitimate

package/dist/skills-sync.js

@@ -24,7 +24,7 @@
  */
 import { promises as fs, existsSync, readFileSync, writeFileSync, mkdirSync, } from 'fs';
 import { homedir } from 'os';
-import { join, basename } from 'path';
+import { join, basename, resolve, sep } from 'path';
 import { createHash } from 'crypto';
 // ---------------------------------------------------------------------------
 // Constants
@@ -268,6 +268,28 @@ export function pushSkipReason(skill) {
     }
     return null;
 }
+/**
+ * Validate a slug that arrives from the *remote* knowledge graph before it is
+ * used to build a filesystem path on pull. `node.source_id`/`node.name` are
+ * attacker-influenceable (any team member or compromised KG can author a skill
+ * node with an arbitrary source_id), so an unchecked slug like
+ * `../../../.config/autostart/x` would let `join(skillsDir, slug, ...)` escape
+ * the skills directory and write attacker content anywhere the user can write.
+ * A safe slug is a single path component: no separators, no `..`, no leading
+ * dot/tilde, no control/whitespace. Returns null if safe, else a reason string.
+ */
+export function pullSlugReason(slug) {
+    if (!slug)
+        return 'empty slug';
+    // Single, conservative path component. Mirrors the directory names the push
+    // side produces (kebab-case skill slugs) and rejects everything else.
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+        return 'slug is not a safe single path component';
+    }
+    if (slug.includes('..'))
+        return 'slug contains ".."';
+    return null;
+}
 /**
  * Detect control characters (other than tab, LF, CR) in the body. The Unroo
  * capture-skill endpoint 500s on null bytes — and they're never legitimate
@@ -421,6 +443,12 @@ async function pullOnce(ctx, state, result) {
         const slug = node.source_id || node.name;
         if (!slug)
             continue;
+        // Never let a remote-controlled slug escape the skills directory.
+        const unsafeReason = pullSlugReason(slug);
+        if (unsafeReason) {
+            result.skipped.push({ slug, why: unsafeReason });
+            continue;
+        }
         const props = node.properties ?? {};
         // The capture endpoint receives `bodyMarkdown` from the wire but persists
         // it to kg_nodes.properties as `body_md` (see knowledge-graph.ts upsertSkill).
@@ -437,6 +465,13 @@ async function pullOnce(ctx, state, result) {
             continue;
         }
         const localPath = join(ctx.skillsDir, slug, 'SKILL.md');
+        // Defense in depth: even with a validated slug, confirm the resolved path
+        // stays inside the skills directory before any mkdir/write.
+        const skillsRoot = resolve(ctx.skillsDir);
+        if (!resolve(localPath).startsWith(skillsRoot + sep)) {
+            result.skipped.push({ slug, why: 'resolved path escapes skills dir' });
+            continue;
+        }
         const existed = existsSync(localPath);
         const prev = state.skills[slug] ?? {};
         // Local doesn't exist — straight pull (clean install or new team skill)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruition/fcp-mcp-server",
-  "version": "1.24.1",
+  "version": "1.26.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",