Google Cloud MCP Server

Instructions

Implementation Reference

• src/services/iam/tools.ts:468-470 (registration)

  Registers the 'gcp-iam-analyse-permission-gaps' tool on the MCP server instance.

  // Tool to analyse permission gaps for a specific resource and operation
  server.registerTool(
    "gcp-iam-analyse-permission-gaps",

• src/services/iam/tools.ts:471-490 (schema)

  Defines the input schema for the tool using Zod, including optional project ID, array of required permissions, and optional operation description.

  {
    title: "Analyse Permission Gaps",
    description:
      "Compare current permissions against required permissions for specific operations and identify gaps",
    inputSchema: {
      project: z
        .string()
        .optional()
        .describe("Project ID (defaults to current project)"),
      requiredPermissions: z
        .array(z.string())
        .describe("List of permissions required for the intended operation"),
      operationDescription: z
        .string()
        .optional()
        .describe(
          "Description of the operation being attempted (for context)",
        ),
    },
  },

• src/services/iam/tools.ts:491-614 (handler)

  Executes the tool logic: retrieves project ID, tests IAM permissions via GCP API, identifies gaps between required and granted permissions, and outputs a comprehensive Markdown analysis including suggestions for roles.

  async ({ project, requiredPermissions, operationDescription }) => {
    try {
      const projectId = project || (await getProjectId());
      const resourceManager = getResourceManagerClient();
  
      const [response] = await resourceManager.testIamPermissions({
        resource: `projects/${projectId}`,
        permissions: requiredPermissions,
      });
  
      const grantedPermissions = response.permissions || [];
      const missingPermissions = requiredPermissions.filter(
        (p) => !grantedPermissions.includes(p),
      );
  
      let result = `# Permission Gap Analysis\n\n`;
      result += `**Project:** ${projectId}\n`;
      if (operationDescription) {
        result += `**Operation:** ${operationDescription}\n`;
      }
      result += `**Total Required Permissions:** ${requiredPermissions.length}\n\n`;
  
      // Overall status
      const hasAllPermissions = missingPermissions.length === 0;
      result += `## 🎯 Status: ${hasAllPermissions ? "✅ AUTHORISED" : "❌ INSUFFICIENT PERMISSIONS"}\n\n`;
  
      if (hasAllPermissions) {
        result += `✅ You have all required permissions for this operation.\n\n`;
      } else {
        result += `❌ Missing ${missingPermissions.length} permission(s). Operation will likely fail.\n\n`;
      }
  
      // Detailed breakdown
      result += `## Permission Analysis\n\n`;
  
      result += `### ✅ Granted Permissions (${grantedPermissions.length})\n\n`;
      if (grantedPermissions.length > 0) {
        grantedPermissions.forEach((permission) => {
          result += `- ${permission}\n`;
        });
      } else {
        result += `*No permissions granted*\n`;
      }
  
      result += `\n### ❌ Missing Permissions (${missingPermissions.length})\n\n`;
      if (missingPermissions.length > 0) {
        missingPermissions.forEach((permission) => {
          result += `- ${permission}\n`;
        });
      } else {
        result += `*No missing permissions*\n`;
      }
  
      // Recommendations
      if (missingPermissions.length > 0) {
        result += `\n## 📋 Recommendations\n\n`;
        result += `1. **Contact your GCP administrator** to request the missing permissions\n`;
        result += `2. **Use predefined roles** that include these permissions:\n`;
  
        // Suggest some common roles that might contain these permissions
        const suggestedRoles = [];
        if (missingPermissions.some((p) => p.startsWith("compute."))) {
          suggestedRoles.push(
            "roles/compute.admin",
            "roles/compute.instanceAdmin",
          );
        }
        if (missingPermissions.some((p) => p.startsWith("storage."))) {
          suggestedRoles.push(
            "roles/storage.admin",
            "roles/storage.objectAdmin",
          );
        }
        if (missingPermissions.some((p) => p.startsWith("run."))) {
          suggestedRoles.push("roles/run.admin", "roles/run.developer");
        }
        if (missingPermissions.some((p) => p.startsWith("container."))) {
          suggestedRoles.push(
            "roles/container.admin",
            "roles/container.developer",
          );
        }
        if (missingPermissions.some((p) => p.startsWith("iam."))) {
          suggestedRoles.push(
            "roles/iam.serviceAccountUser",
            "roles/iam.serviceAccountAdmin",
          );
        }
  
        if (suggestedRoles.length > 0) {
          suggestedRoles.forEach((role) => {
            result += `   - ${role}\n`;
          });
        } else {
          result += `   - Contact administrator for custom role assignment\n`;
        }
  
        result += `3. **Create a custom role** with exactly these permissions if predefined roles are too broad\n`;
      }
  
      return {
        content: [
          {
            type: "text",
            text: result,
          },
        ],
      };
    } catch (error: unknown) {
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error";
      logger.error(`Error analysing permission gaps: ${errorMessage}`);
  
      return {
        content: [
          {
            type: "text",
            text: `# Error Analysing Permission Gaps\n\nFailed to analyse permissions: ${errorMessage}\n\nPlease ensure the project ID is correct and accessible.`,
          },
        ],
        isError: true,
      };
    }
  },