Google Cloud MCP Server

Implementation Reference

• src/services/trace/tools.ts:501-754 (handler)

  Complete inline handler for the 'gcp-trace-find-from-logs' MCP tool. Processes input filter (supporting relative times like -1d), queries GCP Cloud Logging API, extracts trace IDs from log entries using the helper extractTraceIdFromLog, deduplicates traces, and returns a formatted Markdown table with trace details including timestamp, severity, log name, and message preview.

  // Tool to find traces associated with logs
  server.tool(
    "gcp-trace-find-from-logs",
    {
      projectId: z
        .string()
        .optional()
        .describe("Optional Google Cloud project ID"),
      filter: z
        .string()
        .describe(
          'Filter for logs (e.g., "severity>=ERROR AND timestamp>\"-1d\"")',
        ),
      limit: z
        .number()
        .min(1)
        .max(100)
        .default(10)
        .describe("Maximum number of logs to check"),
    },
    async ({ projectId, filter, limit }, context) => {
      try {
        // Use provided project ID or get the default one from state manager first
        const actualProjectId =
          projectId ||
          stateManager.getCurrentProjectId() ||
          (await getProjectId());
  
        // Process the filter to handle relative time formats
        let processedFilter = filter;
  
        // Check for relative time patterns in the filter
        const relativeTimeRegex = /(timestamp[><]=?\s*["'])(-?\d+[hmd])(["'])/g;
        processedFilter = processedFilter.replace(
          relativeTimeRegex,
          (
            match: string,
            prefix: string,
            timeValue: string,
            suffix: string,
          ) => {
            logger.debug(
              `Found relative time in filter: ${match}, timeValue: ${timeValue}`,
            );
  
            // Parse the relative time
            const value = parseInt(timeValue.slice(1, -1));
            const unit = timeValue.slice(-1);
            const isNegative = timeValue.startsWith("-");
  
            // Calculate the absolute time
            const now = new Date();
            const targetDate = new Date(now);
  
            if (unit === "h") {
              targetDate.setHours(
                targetDate.getHours() + (isNegative ? -value : value),
              );
            } else if (unit === "d") {
              targetDate.setDate(
                targetDate.getDate() + (isNegative ? -value : value),
              );
            } else if (unit === "m") {
              targetDate.setMinutes(
                targetDate.getMinutes() + (isNegative ? -value : value),
              );
            }
  
            // Format as RFC3339
            const formattedTime = targetDate.toISOString();
            logger.debug(
              `Converted relative time ${timeValue} to absolute time: ${formattedTime}`,
            );
  
            // Return the updated filter part
            return `${prefix}${formattedTime}${suffix}`;
          },
        );
  
        logger.debug(`Original filter: ${filter}`);
        logger.debug(`Processed filter: ${processedFilter}`);
  
        // Initialize the logging client
        const logging = new Logging({
          projectId: actualProjectId,
        });
  
        // Fetch logs with the processed filter
        const [entries] = await logging.getEntries({
          filter: processedFilter,
          pageSize: limit,
        });
  
        if (!entries || entries.length === 0) {
          return {
            content: [
              {
                type: "text",
                text: `No logs found matching the filter: "${filter}" in project: ${actualProjectId}`,
              },
            ],
          };
        }
  
        // Extract trace IDs from logs
        const traceMap = new Map<
          string,
          {
            traceId: string;
            timestamp: string;
            severity: string;
            logName: string;
            message: string;
          }
        >();
  
        for (const entry of entries) {
          const metadata = entry.metadata;
          const traceId = extractTraceIdFromLog(metadata);
  
          if (traceId) {
            // Convert timestamp to string
            let timestampStr = "Unknown";
            if (metadata.timestamp) {
              if (typeof metadata.timestamp === "string") {
                timestampStr = metadata.timestamp;
              } else {
                try {
                  // Handle different timestamp formats
                  if (
                    typeof metadata.timestamp === "object" &&
                    metadata.timestamp !== null
                  ) {
                    if (
                      "seconds" in metadata.timestamp &&
                      "nanos" in metadata.timestamp
                    ) {
                      // Handle Timestamp proto format
                      const seconds = Number(metadata.timestamp.seconds);
                      const nanos = Number(metadata.timestamp.nanos || 0);
                      const milliseconds = seconds * 1000 + nanos / 1000000;
                      timestampStr = new Date(milliseconds).toISOString();
                    } else {
                      // Try to convert using JSON
                      timestampStr = JSON.stringify(metadata.timestamp);
                    }
                  } else {
                    timestampStr = String(metadata.timestamp);
                  }
                } catch (e) {
                  timestampStr = "Invalid timestamp";
                }
              }
            }
  
            // Convert severity to string
            let severityStr = "DEFAULT";
            if (metadata.severity) {
              severityStr = String(metadata.severity);
            }
  
            // Convert logName to string
            let logNameStr = "Unknown";
            if (metadata.logName) {
              logNameStr = String(metadata.logName);
            }
  
            // Extract message
            let messageStr = "No message";
            if (metadata.textPayload) {
              messageStr = String(metadata.textPayload);
            } else if (metadata.jsonPayload) {
              try {
                messageStr = JSON.stringify(metadata.jsonPayload);
              } catch (e) {
                messageStr = "Invalid JSON payload";
              }
            }
  
            traceMap.set(traceId, {
              traceId,
              timestamp: timestampStr,
              severity: severityStr,
              logName: logNameStr,
              message: messageStr,
            });
          }
        }
  
        if (traceMap.size === 0) {
          return {
            content: [
              {
                type: "text",
                text: `No traces found in the logs matching the filter: "${filter}" in project: ${actualProjectId}`,
              },
            ],
          };
        }
  
        // Format the traces for display
        let markdown = `# Traces Found in Logs\n\n`;
        markdown += `Project: ${actualProjectId}\n`;
        markdown += `Log Filter: ${filter}\n`;
        markdown += `Found ${traceMap.size} unique traces in ${entries.length} log entries:\n\n`;
  
        // Table header
        markdown +=
          "| Trace ID | Timestamp | Severity | Log Name | Message |\n";
        markdown += "|----------|-----------|----------|----------|--------|\n";
  
        // Table rows
        for (const trace of traceMap.values()) {
          const traceId = trace.traceId;
          // Handle timestamp formatting safely
          let timestamp = trace.timestamp;
          try {
            if (timestamp !== "Unknown" && timestamp !== "Invalid timestamp") {
              timestamp = new Date(trace.timestamp).toISOString();
            }
          } catch (e) {
            // Keep the original timestamp if conversion fails
          }
          const severity = trace.severity;
          const logName = trace.logName.split("/").pop() || trace.logName;
          const message =
            trace.message.length > 100
              ? trace.message.substring(0, 100) + "..."
              : trace.message;
  
          markdown += `| \`${traceId}\` | ${timestamp} | ${severity} | ${logName} | ${message} |\n`;
        }
  
        markdown +=
          "\n\nTo view a specific trace, use the `get-trace` tool with the trace ID.";
  
        return {
          content: [
            {
              type: "text",
              text: markdown,
            },
          ],
        };
      } catch (error: any) {
        // Error handling for find-traces-from-logs tool
        throw new GcpMcpError(
          `Failed to find traces from logs: ${error.message}`,
          error.code || "UNKNOWN",
          error.statusCode || 500,
        );
      }
    },
  );

• src/services/trace/tools.ts:504-520 (schema)

  Zod schema defining input parameters for the tool: optional projectId, required filter string for log query, and limit (default 10, max 100).

  {
    projectId: z
      .string()
      .optional()
      .describe("Optional Google Cloud project ID"),
    filter: z
      .string()
      .describe(
        'Filter for logs (e.g., "severity>=ERROR AND timestamp>\"-1d\"")',
      ),
    limit: z
      .number()
      .min(1)
      .max(100)
      .default(10)
      .describe("Maximum number of logs to check"),
  },

• src/services/trace/types.ts:777-812 (helper)

  Utility function to extract trace ID from GCP log entry. Checks logEntry.trace, labels['logging.googleapis.com/trace'], jsonPayload.traceId, and jsonPayload['logging.googleapis.com/trace'], parsing the hex ID from the full resource path.

  export function extractTraceIdFromLog(logEntry: any): string | undefined {
    // Check for trace in the standard logging.googleapis.com/trace field
    if (logEntry.trace) {
      // The trace field is typically in the format "projects/PROJECT_ID/traces/TRACE_ID"
      const match = logEntry.trace.match(/traces\/([a-f0-9]+)$/i);
      if (match && match[1]) {
        return match[1];
      }
    }
  
    // Check for trace in labels
    if (logEntry.labels && logEntry.labels["logging.googleapis.com/trace"]) {
      const traceLabel = logEntry.labels["logging.googleapis.com/trace"];
      const match = traceLabel.match(/traces\/([a-f0-9]+)$/i);
      if (match && match[1]) {
        return match[1];
      }
    }
  
    // Check for trace in jsonPayload
    if (logEntry.jsonPayload) {
      if (logEntry.jsonPayload.traceId) {
        return logEntry.jsonPayload.traceId;
      }
  
      if (logEntry.jsonPayload["logging.googleapis.com/trace"]) {
        const tracePayload = logEntry.jsonPayload["logging.googleapis.com/trace"];
        const match = tracePayload.match(/traces\/([a-f0-9]+)$/i);
        if (match && match[1]) {
          return match[1];
        }
      }
    }
  
    return undefined;
  }

• src/services/trace/index.ts:18-18 (registration)

  Calls registerTraceTools(server) which registers the gcp-trace-find-from-logs tool among others.

  await registerTraceTools(server);