@fruition/fcp-mcp-server 1.30.0 → 1.32.0

package/README.md

@@ -33,6 +33,22 @@ MCP (Model Context Protocol) server that gives Claude Code direct access to the
 | `fcp_get_certificate` | Single certificate detail (issuer, SANs, expiry) |
 | `fcp_scan_certificates` | Trigger a cert-monitor scan run |
 
+### Cluster Gateway Tools
+
+| Tool | Description |
+|------|-------------|
+| `fcp_db_query` | Run a read-only SQL query (SELECT/SHOW/EXPLAIN/DESCRIBE) against a site's read-only DB replica |
+| `fcp_cluster_http` | GET/HEAD an in-cluster Kubernetes Service URL through FCP (devs firewalled off the cluster) |
+
+### Cluster Safe-Edit Action Tools
+
+Structural, audited mutations (operator tier). The caller supplies ONLY a site (+ optional revision); the target deployment is resolved from the site's stack server-side — no deployment name or raw command is ever accepted. Admin-gated REST routes, `CLUSTER_GATEWAY_DISABLED` kill-switch, prod-cluster Slack alert.
+
+| Tool | Description |
+|------|-------------|
+| `fcp_restart_varnish` | Restart a site's varnish deployment (rollout restart) |
+| `fcp_rollback_web` | Roll back a site's web (nginx + php-fpm) deployment (rollout undo), optional `to_revision` |
+
 ### Tasker Job Control Tools
 
 | Tool | Description |

package/dist/index.d.ts

@@ -416,6 +416,20 @@ export declare class FCPClient {
         enabled?: boolean;
         created_by?: string;
     }): Promise<any>;
+    clusterDbQuery(input: {
+        site?: number | string;
+        domain?: string;
+        sql: string;
+        limit?: number;
+    }): Promise<any>;
+    clusterHttp(input: {
+        cluster: string;
+        namespace: string;
+        service: string;
+        port: number;
+        path?: string;
+        method?: string;
+    }): Promise<any>;
     listCertificates(filters?: {
         status?: string;
         cluster?: string;
@@ -451,6 +465,55 @@ export declare class FCPClient {
         reason?: string;
         ttl_minutes?: number;
     }): Promise<any>;
+    clusterPods(input: {
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+        labelSelector?: string;
+    }): Promise<any>;
+    clusterLogs(input: {
+        pod: string;
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+    }): Promise<any>;
+    clusterIngress(input: {
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+    }): Promise<any>;
+    clusterDeployments(input: {
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+    }): Promise<any>;
+    clusterEvents(input: {
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+    }): Promise<any>;
+    clusterDescribe(input: {
+        kind: string;
+        name: string;
+        site?: string;
+        domain?: string;
+        cluster?: string;
+        namespace?: string;
+    }): Promise<any>;
+    restartVarnish(input: {
+        site?: string;
+        domain?: string;
+    }): Promise<any>;
+    rollbackWeb(input: {
+        site?: string;
+        domain?: string;
+        to_revision?: number;
+    }): Promise<any>;
     backupListSites(): Promise<any>;
     backupGetConfig(): Promise<any>;
     backupListEligible(): Promise<any>;

package/dist/index.js

@@ -167,7 +167,19 @@ const TOOL_PERMISSIONS = {
     fcp_trusted_ip_list_ranges: 'viewer',
     fcp_trusted_ip_export: 'viewer',
     fcp_list_freezes: 'viewer',
+    fcp_db_query: 'viewer',
+    fcp_cluster_http: 'viewer',
     fcp_list_certificates: 'viewer',
+    fcp_cluster_pods: 'viewer',
+    fcp_cluster_logs: 'viewer',
+    fcp_cluster_ingress: 'viewer',
+    fcp_cluster_deployments: 'viewer',
+    fcp_cluster_events: 'viewer',
+    fcp_cluster_describe: 'viewer',
+    // Cluster Safe-Edit Actions (Phase 2) — operator tier (developer tier is a
+    // separate cross-cutting follow-up).
+    fcp_restart_varnish: 'operator',
+    fcp_rollback_web: 'operator',
     fcp_dns_current: 'viewer',
     fcp_dns_history: 'viewer',
     fcp_list_deployments: 'viewer',
@@ -920,6 +932,21 @@ export class FCPClient {
         });
     }
     // ============================================================================
+    // Cluster DB + HTTP Methods
+    // ============================================================================
+    async clusterDbQuery(input) {
+        return this.fetch('/api/cluster/db-query', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async clusterHttp(input) {
+        return this.fetch('/api/cluster/http', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    // ============================================================================
     // Certificate Methods
     // ============================================================================
     async listCertificates(filters) {
@@ -993,6 +1020,109 @@ export class FCPClient {
         return this.fetch(path, { method: 'POST', body: JSON.stringify(body) });
     }
     // ============================================================================
+    // Cluster Info (read-only) Methods
+    // ============================================================================
+    async clusterPods(input) {
+        const p = new URLSearchParams();
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        if (input.labelSelector)
+            p.append('labelSelector', input.labelSelector);
+        const qs = p.toString();
+        return this.fetch(`/api/cluster/info/pods${qs ? `?${qs}` : ''}`);
+    }
+    async clusterLogs(input) {
+        const p = new URLSearchParams();
+        p.append('pod', input.pod);
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        return this.fetch(`/api/cluster/info/logs?${p.toString()}`);
+    }
+    async clusterIngress(input) {
+        const p = new URLSearchParams();
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        const qs = p.toString();
+        return this.fetch(`/api/cluster/info/ingress${qs ? `?${qs}` : ''}`);
+    }
+    async clusterDeployments(input) {
+        const p = new URLSearchParams();
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        const qs = p.toString();
+        return this.fetch(`/api/cluster/info/deployments${qs ? `?${qs}` : ''}`);
+    }
+    async clusterEvents(input) {
+        const p = new URLSearchParams();
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        const qs = p.toString();
+        return this.fetch(`/api/cluster/info/events${qs ? `?${qs}` : ''}`);
+    }
+    async clusterDescribe(input) {
+        const p = new URLSearchParams();
+        p.append('kind', input.kind);
+        p.append('name', input.name);
+        if (input.site)
+            p.append('site', input.site);
+        if (input.domain)
+            p.append('domain', input.domain);
+        if (input.cluster)
+            p.append('cluster', input.cluster);
+        if (input.namespace)
+            p.append('namespace', input.namespace);
+        return this.fetch(`/api/cluster/info/describe?${p.toString()}`);
+    }
+    // ============================================================================
+    // Cluster Safe-Edit Actions (FCP Cluster Gateway, Phase 2)
+    // ============================================================================
+    async restartVarnish(input) {
+        return this.fetch('/api/cluster/actions/restart-varnish', {
+            method: 'POST',
+            body: JSON.stringify({ site: input.site, domain: input.domain }),
+        });
+    }
+    async rollbackWeb(input) {
+        return this.fetch('/api/cluster/actions/rollback-web', {
+            method: 'POST',
+            body: JSON.stringify({
+                site: input.site,
+                domain: input.domain,
+                to_revision: input.to_revision,
+            }),
+        });
+    }
+    // ============================================================================
     // Backup Management Methods
     // ============================================================================
     async backupListSites() {
@@ -3450,6 +3580,39 @@ const TOOLS = [
         },
     },
     // ============================================================================
+    // Cluster DB + HTTP Tools
+    // ============================================================================
+    {
+        name: 'fcp_db_query',
+        description: 'Run a READ-ONLY SQL query against a site\'s read-only DB replica. Provide either site (numeric id) or domain, plus a single SELECT/SHOW/EXPLAIN/DESCRIBE statement. Writes/DDL/multi-statement are rejected. Rows are capped (default 200). Use to inspect site data without cluster access.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'number', description: 'Site id (provide site OR domain)' },
+                domain: { type: 'string', description: 'Site domain (provide site OR domain)' },
+                sql: { type: 'string', description: 'Single read-only statement (SELECT/SHOW/EXPLAIN/DESCRIBE)' },
+                limit: { type: 'number', description: 'Max rows to return (default 200, max 1000)' },
+            },
+            required: ['sql'],
+        },
+    },
+    {
+        name: 'fcp_cluster_http',
+        description: 'Fetch an in-cluster Kubernetes Service URL through FCP (devs are firewalled off the cluster). Builds http://<service>.<namespace>:<port>/<path>. Only GET/HEAD allowed; response body is size-capped. Use to hit health/metrics/internal endpoints.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cluster: { type: 'string', description: 'Target cluster name (recorded for audit)' },
+                namespace: { type: 'string', description: 'Kubernetes namespace' },
+                service: { type: 'string', description: 'Kubernetes Service name' },
+                port: { type: 'number', description: 'Service port' },
+                path: { type: 'string', description: 'Request path (default /)' },
+                method: { type: 'string', enum: ['GET', 'HEAD'], description: 'HTTP method (default GET)' },
+            },
+            required: ['cluster', 'namespace', 'service', 'port'],
+        },
+    },
+    // ============================================================================
     // Certificate Tools
     // ============================================================================
     {
@@ -3548,6 +3711,122 @@ const TOOLS = [
         },
     },
     // ============================================================================
+    // Cluster Info (read-only) Tools
+    // ============================================================================
+    {
+        name: 'fcp_cluster_pods',
+        description: 'List pods in a namespace (read-only cluster gateway for firewalled devs). Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair. Optional labelSelector.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+                labelSelector: { type: 'string', description: 'Optional label selector (e.g. app=web)' },
+            },
+        },
+    },
+    {
+        name: 'fcp_cluster_logs',
+        description: 'Tail logs (last 1000 lines) for a pod (read-only cluster gateway). Requires pod. Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pod: { type: 'string', description: 'Pod name to read logs from' },
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+            },
+            required: ['pod'],
+        },
+    },
+    {
+        name: 'fcp_cluster_ingress',
+        description: 'List ingresses in a namespace (read-only cluster gateway). Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+            },
+        },
+    },
+    {
+        name: 'fcp_cluster_deployments',
+        description: 'List deployments in a namespace (read-only cluster gateway). Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+            },
+        },
+    },
+    {
+        name: 'fcp_cluster_events',
+        description: 'List namespace events sorted by lastTimestamp (read-only cluster gateway). Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+            },
+        },
+    },
+    {
+        name: 'fcp_cluster_describe',
+        description: 'kubectl describe <kind> <name> in a namespace (read-only cluster gateway). Requires kind + name. Target a namespace by EITHER a site (\"site\"/\"domain\") OR an explicit \"cluster\"+\"namespace\" pair.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', description: 'Resource kind (e.g. pod, deployment, ingress)' },
+                name: { type: 'string', description: 'Resource name to describe' },
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                cluster: { type: 'string', description: 'Explicit cluster name (with namespace)' },
+                namespace: { type: 'string', description: 'Explicit namespace (with cluster)' },
+            },
+            required: ['kind', 'name'],
+        },
+    },
+    // ============================================================================
+    // Cluster Safe-Edit Actions (FCP Cluster Gateway, Phase 2)
+    // Operator-tier, structurally-allowlisted: the caller supplies ONLY a site
+    // (+ optional revision). No deployment name, kind, or raw command is ever
+    // accepted — the deployment is resolved from the site's stack server-side.
+    // ============================================================================
+    {
+        name: 'fcp_restart_varnish',
+        description: "Safe-edit: restart a site's varnish deployment (rollout restart). Target the site by \"site\" (website id or domain) or \"domain\". The varnish deployment is resolved structurally from the site's stack — you do NOT (and cannot) specify a deployment name or command. Operator tier; admin-gated server-side. Honors the cluster-gateway kill-switch.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace+stack)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+            },
+        },
+    },
+    {
+        name: 'fcp_rollback_web',
+        description: "Safe-edit: roll back a site's web (nginx + php-fpm) deployment (rollout undo), optionally to a specific revision. Target the site by \"site\" (website id or domain) or \"domain\"; optional \"to_revision\" (positive integer). The web deployment is resolved structurally from the site's stack — you do NOT (and cannot) specify a deployment name or command. Operator tier; admin-gated server-side. Honors the cluster-gateway kill-switch.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                site: { type: 'string', description: 'Website id or domain (resolves cluster+namespace+stack)' },
+                domain: { type: 'string', description: 'Alias for site: a domain to resolve' },
+                to_revision: { type: 'number', description: 'Optional revision to roll back to (positive integer)' },
+            },
+        },
+    },
+    // ============================================================================
     // Backup Management Tools
     // ============================================================================
     {
@@ -5470,6 +5749,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             // ============================================================================
+            // Cluster DB + HTTP Handlers
+            // ============================================================================
+            case 'fcp_db_query': {
+                const result = await client.clusterDbQuery(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_http': {
+                const result = await client.clusterHttp(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            // ============================================================================
             // Certificate Handlers
             // ============================================================================
             case 'fcp_list_certificates': {
@@ -5518,6 +5808,44 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
             // ============================================================================
+            // Cluster Info (read-only) Handlers
+            // ============================================================================
+            case 'fcp_cluster_pods': {
+                const result = await client.clusterPods(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_logs': {
+                const result = await client.clusterLogs(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_ingress': {
+                const result = await client.clusterIngress(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_deployments': {
+                const result = await client.clusterDeployments(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_events': {
+                const result = await client.clusterEvents(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_cluster_describe': {
+                const result = await client.clusterDescribe(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            // ============================================================================
+            // Cluster Safe-Edit Action Handlers (FCP Cluster Gateway, Phase 2)
+            // ============================================================================
+            case 'fcp_restart_varnish': {
+                const result = await client.restartVarnish(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            case 'fcp_rollback_web': {
+                const result = await client.rollbackWeb(args);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            // ============================================================================
             // Backup Management Handlers
             // ============================================================================
             case 'fcp_backup_list_sites': {

package/package.json

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