Google Cloud MCP Server

Implementation Reference

• src/services/error-reporting/tools.ts:52-176 (handler)

  The main execution handler for the gcp-error-reporting-list-groups tool. Authenticates with GCP, queries the Error Reporting API for group stats with filters, processes the data, generates analysis and remediation suggestions, and formats a markdown response.

  async ({ timeRange, serviceFilter, order, pageSize }) => {
    try {
      const projectId = await getProjectId();
  
      // Initialize Google Auth client (same pattern as trace service)
      const auth = await initGoogleAuth(true);
      if (!auth) {
        throw new GcpMcpError(
          "Google Cloud authentication not available. Please configure authentication to access error reporting data.",
          "UNAUTHENTICATED",
          401,
        );
      }
      const client = await auth.getClient();
      const token = await client.getAccessToken();
  
      // Parse time range - ensure we have a valid timeRange value
      const actualTimeRange = timeRange || "1h";
      const actualOrder = order || "COUNT_DESC";
      const actualPageSize = pageSize || 20;
  
      // Map time range to Google Cloud Error Reporting periods
      let period: string;
      switch (actualTimeRange) {
        case "1h":
          period = "PERIOD_1_HOUR";
          break;
        case "6h":
          period = "PERIOD_6_HOURS";
          break;
        case "24h":
        case "1d":
          period = "PERIOD_1_DAY";
          break;
        case "7d":
          period = "PERIOD_1_WEEK";
          break;
        case "30d":
          period = "PERIOD_30_DAYS";
          break;
        default:
          // Default to 1 hour for any other time range
          period = "PERIOD_1_HOUR";
          break;
      }
  
      // Build query parameters
      const params = new URLSearchParams({
        "timeRange.period": period,
        order: actualOrder,
        pageSize: actualPageSize.toString(),
      });
  
      // Add service filter if provided
      if (serviceFilter) {
        params.set("serviceFilter.service", serviceFilter);
      }
  
      // Make REST API call using same fetch approach as trace service
      const apiUrl = `https://clouderrorreporting.googleapis.com/v1beta1/projects/${projectId}/groupStats?${params}`;
  
      const response = await fetch(apiUrl, {
        method: "GET",
        headers: {
          Authorization: `Bearer ${token.token}`,
          Accept: "application/json",
        },
      });
  
      if (!response.ok) {
        const errorText = await response.text();
        throw new GcpMcpError(
          `Failed to fetch error group stats: ${errorText}`,
          "FAILED_PRECONDITION",
          response.status,
        );
      }
  
      const data = await response.json();
      const errorGroupStats = data.errorGroupStats || [];
  
      if (!errorGroupStats || errorGroupStats.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `# Error Groups\n\nProject: ${projectId}\nTime Range: ${actualTimeRange}\n${serviceFilter ? `Service Filter: ${serviceFilter}\n` : ""}\nNo error groups found.`,
            },
          ],
        };
      }
  
      // errorGroupStats should already match our ErrorGroupStats interface
      const errorSummaries: ErrorGroupStats[] = errorGroupStats;
  
      // Generate analysis and recommendations
      const analysis =
        analyseErrorPatternsAndSuggestRemediation(errorSummaries);
  
      let content = `# Error Groups Analysis\n\nProject: ${projectId}\nTime Range: ${actualTimeRange}\n${serviceFilter ? `Service Filter: ${serviceFilter}\n` : ""}\n\n${analysis}\n\n`;
  
      content += `## Detailed Error Groups\n\n`;
  
      errorSummaries.forEach((errorSummary, index) => {
        content += `### ${index + 1}. ${formatErrorGroupSummary(errorSummary)}\n`;
      });
  
      return {
        content: [
          {
            type: "text",
            text: content,
          },
        ],
      };
    } catch (error: unknown) {
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error";
      throw new GcpMcpError(
        `Failed to list error groups: ${errorMessage}`,
        "INTERNAL_ERROR",
        500,
      );
    }
  },

• src/services/error-reporting/tools.ts:28-50 (schema)

  Zod-based input schema defining parameters for the tool: timeRange (optional, default 1h), serviceFilter (optional), order (optional, default COUNT_DESC), pageSize (optional, default 20, max 100).

    timeRange: z
      .string()
      .optional()
      .default("1h")
      .describe('Time range to query: "1h", "6h", "24h"/"1d", "7d", "30d"'),
    serviceFilter: z.string().optional().describe("Filter by service name"),
    order: z
      .enum([
        "COUNT_DESC",
        "LAST_SEEN_DESC",
        "CREATED_DESC",
        "AFFECTED_USERS_DESC",
      ])
      .optional()
      .default("COUNT_DESC")
      .describe("Sort order for error groups"),
    pageSize: z
      .number()
      .min(1)
      .max(100)
      .default(20)
      .describe("Maximum number of error groups to return"),
  },

• src/services/error-reporting/tools.ts:22-177 (registration)

  MCP server.tool registration for 'gcp-error-reporting-list-groups', specifying title, description, inputSchema, and binding the handler function.

    "gcp-error-reporting-list-groups",
    {
      title: "List Error Groups",
      description:
        "List error groups from Google Cloud Error Reporting with optional filtering and time range",
      inputSchema: {
        timeRange: z
          .string()
          .optional()
          .default("1h")
          .describe('Time range to query: "1h", "6h", "24h"/"1d", "7d", "30d"'),
        serviceFilter: z.string().optional().describe("Filter by service name"),
        order: z
          .enum([
            "COUNT_DESC",
            "LAST_SEEN_DESC",
            "CREATED_DESC",
            "AFFECTED_USERS_DESC",
          ])
          .optional()
          .default("COUNT_DESC")
          .describe("Sort order for error groups"),
        pageSize: z
          .number()
          .min(1)
          .max(100)
          .default(20)
          .describe("Maximum number of error groups to return"),
      },
    },
    async ({ timeRange, serviceFilter, order, pageSize }) => {
      try {
        const projectId = await getProjectId();
  
        // Initialize Google Auth client (same pattern as trace service)
        const auth = await initGoogleAuth(true);
        if (!auth) {
          throw new GcpMcpError(
            "Google Cloud authentication not available. Please configure authentication to access error reporting data.",
            "UNAUTHENTICATED",
            401,
          );
        }
        const client = await auth.getClient();
        const token = await client.getAccessToken();
  
        // Parse time range - ensure we have a valid timeRange value
        const actualTimeRange = timeRange || "1h";
        const actualOrder = order || "COUNT_DESC";
        const actualPageSize = pageSize || 20;
  
        // Map time range to Google Cloud Error Reporting periods
        let period: string;
        switch (actualTimeRange) {
          case "1h":
            period = "PERIOD_1_HOUR";
            break;
          case "6h":
            period = "PERIOD_6_HOURS";
            break;
          case "24h":
          case "1d":
            period = "PERIOD_1_DAY";
            break;
          case "7d":
            period = "PERIOD_1_WEEK";
            break;
          case "30d":
            period = "PERIOD_30_DAYS";
            break;
          default:
            // Default to 1 hour for any other time range
            period = "PERIOD_1_HOUR";
            break;
        }
  
        // Build query parameters
        const params = new URLSearchParams({
          "timeRange.period": period,
          order: actualOrder,
          pageSize: actualPageSize.toString(),
        });
  
        // Add service filter if provided
        if (serviceFilter) {
          params.set("serviceFilter.service", serviceFilter);
        }
  
        // Make REST API call using same fetch approach as trace service
        const apiUrl = `https://clouderrorreporting.googleapis.com/v1beta1/projects/${projectId}/groupStats?${params}`;
  
        const response = await fetch(apiUrl, {
          method: "GET",
          headers: {
            Authorization: `Bearer ${token.token}`,
            Accept: "application/json",
          },
        });
  
        if (!response.ok) {
          const errorText = await response.text();
          throw new GcpMcpError(
            `Failed to fetch error group stats: ${errorText}`,
            "FAILED_PRECONDITION",
            response.status,
          );
        }
  
        const data = await response.json();
        const errorGroupStats = data.errorGroupStats || [];
  
        if (!errorGroupStats || errorGroupStats.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: `# Error Groups\n\nProject: ${projectId}\nTime Range: ${actualTimeRange}\n${serviceFilter ? `Service Filter: ${serviceFilter}\n` : ""}\nNo error groups found.`,
              },
            ],
          };
        }
  
        // errorGroupStats should already match our ErrorGroupStats interface
        const errorSummaries: ErrorGroupStats[] = errorGroupStats;
  
        // Generate analysis and recommendations
        const analysis =
          analyseErrorPatternsAndSuggestRemediation(errorSummaries);
  
        let content = `# Error Groups Analysis\n\nProject: ${projectId}\nTime Range: ${actualTimeRange}\n${serviceFilter ? `Service Filter: ${serviceFilter}\n` : ""}\n\n${analysis}\n\n`;
  
        content += `## Detailed Error Groups\n\n`;
  
        errorSummaries.forEach((errorSummary, index) => {
          content += `### ${index + 1}. ${formatErrorGroupSummary(errorSummary)}\n`;
        });
  
        return {
          content: [
            {
              type: "text",
              text: content,
            },
          ],
        };
      } catch (error: unknown) {
        const errorMessage =
          error instanceof Error ? error.message : "Unknown error";
        throw new GcpMcpError(
          `Failed to list error groups: ${errorMessage}`,
          "INTERNAL_ERROR",
          500,
        );
      }
    },
  );

• src/index.ts:213-213 (registration)

  Top-level call in main server setup to register all error reporting tools, including gcp-error-reporting-list-groups via the registerErrorReportingTools function.

  registerErrorReportingTools(server);

• src/services/error-reporting/types.ts:204-288 (helper)

  Helper function called in the handler to analyze error groups, compute totals and patterns, suggest remediations, and generate markdown analysis section.

  export function analyseErrorPatternsAndSuggestRemediation(
    errorGroups: ErrorGroupStats[],
  ): string {
    if (errorGroups.length === 0) {
      return "No errors found in the specified time range.";
    }
  
    let analysis = `# Error Analysis and Remediation Suggestions\n\n`;
    analysis += `**Total Error Groups:** ${errorGroups.length}\n\n`;
  
    // Calculate total errors and affected users
    const totalErrors = errorGroups.reduce(
      (sum, group) => sum + parseInt(group.count),
      0,
    );
    const totalAffectedUsers = errorGroups.reduce(
      (sum, group) => sum + parseInt(group.affectedUsersCount),
      0,
    );
  
    analysis += `**Summary:**\n`;
    analysis += `- Total errors: ${totalErrors.toLocaleString()}\n`;
    analysis += `- Total affected users: ${totalAffectedUsers.toLocaleString()}\n`;
    analysis += `- Error groups: ${errorGroups.length}\n\n`;
  
    // Sort by error count (most frequent first)
    const sortedErrors = [...errorGroups].sort(
      (a, b) => parseInt(b.count) - parseInt(a.count),
    );
  
    analysis += `## Top Error Groups by Frequency\n\n`;
  
    // Analyse top 5 errors
    sortedErrors.slice(0, 5).forEach((errorGroup, index) => {
      analysis += `### ${index + 1}. ${errorGroup.representative?.serviceContext?.service || "Unknown Service"}\n\n`;
      analysis += `**Error:** ${errorGroup.representative?.message || "No message"}\n\n`;
      analysis += `**Impact:** ${errorGroup.count} occurrences, ${errorGroup.affectedUsersCount} affected users\n\n`;
  
      // Suggest remediation based on error patterns
      const remediation = suggestRemediation(errorGroup);
      if (remediation) {
        analysis += `**Suggested Remediation:**\n${remediation}\n\n`;
      }
  
      analysis += `---\n\n`;
    });
  
    // Pattern analysis
    analysis += `## Pattern Analysis\n\n`;
  
    // Group by service
    const serviceGroups = new Map<string, ErrorGroupStats[]>();
    errorGroups.forEach((group) => {
      const service = group.representative?.serviceContext?.service || "Unknown";
      if (!serviceGroups.has(service)) {
        serviceGroups.set(service, []);
      }
      serviceGroups.get(service)!.push(group);
    });
  
    if (serviceGroups.size > 1) {
      analysis += `**Services Affected:** ${serviceGroups.size}\n`;
      serviceGroups.forEach((groups, service) => {
        const serviceErrors = groups.reduce(
          (sum, group) => sum + parseInt(group.count),
          0,
        );
        analysis += `- ${service}: ${groups.length} error groups, ${serviceErrors} total errors\n`;
      });
      analysis += `\n`;
    }
  
    // Time-based analysis
    const recentErrors = errorGroups.filter((group) => {
      const lastSeen = new Date(group.lastSeenTime);
      const oneHourAgo = new Date(Date.now() - 60 * 60 * 1000);
      return lastSeen > oneHourAgo;
    });
  
    if (recentErrors.length > 0) {
      analysis += `**Recent Activity:** ${recentErrors.length} error groups with activity in the last hour\n\n`;
    }
  
    return analysis;
  }