Google Cloud MCP Server

Implementation Reference

• src/services/profiler/tools.ts:366-462 (handler)

  Main handler function that authenticates to GCP Profiler API, fetches and filters profiles based on input parameters, generates trend analysis using helper function, and returns markdown report.
  async ({ target, profileType, pageSize }) => { try { const projectId = await getProjectId(); // Initialize Google Auth client const auth = await initGoogleAuth(true); if (!auth) { throw new GcpMcpError( "Google Cloud authentication not available. Please configure authentication to access profiler data.", "UNAUTHENTICATED", 401, ); } const client = await auth.getClient(); const token = await client.getAccessToken(); const actualPageSize = pageSize || 200; // Build query parameters const params = new URLSearchParams({ pageSize: actualPageSize.toString(), }); // Make REST API call to list profiles const apiUrl = `https://cloudprofiler.googleapis.com/v2/projects/${projectId}/profiles?${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 profiles for trend analysis: ${errorText}`, "FAILED_PRECONDITION", response.status, ); } const data: ListProfilesResponse = await response.json(); let profiles = data.profiles || []; // Apply filtering if (profileType) { profiles = profiles.filter((p) => p.profileType === profileType); } if (target) { profiles = profiles.filter((p) => p.deployment?.target?.toLowerCase().includes(target.toLowerCase()), ); } if (!profiles || profiles.length === 0) { return { content: [ { type: "text", text: `# Profile Trend Analysis\n\nProject: ${projectId}\n\nNo profiles found for trend analysis.`, }, ], }; } // Generate trend analysis let content = `# Profile Trend Analysis\n\nProject: ${projectId}\n`; if (profileType) content += `Profile Type: ${getProfileTypeDescription(profileType)}\n`; if (target) content += `Target: ${target}\n`; content += `Analysed: ${profiles.length} profiles\n\n`; // Analyse trends over time const trendAnalysis = analyseProfileTrends(profiles); content += trendAnalysis; return { content: [ { type: "text", text: content, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; throw new GcpMcpError( `Failed to analyse profile trends: ${errorMessage}`, "INTERNAL_ERROR", 500, ); } },
• src/services/profiler/tools.ts:336-463 (registration)

  Registers the 'gcp-profiler-compare-trends' tool with the MCP server, including title, description, Zod input schema, and handler reference.
  "gcp-profiler-compare-trends", { title: "Compare Profile Trends", description: "Compare profiles over time to identify performance trends, regressions, and improvements", inputSchema: { target: z .string() .optional() .describe("Focus comparison on specific deployment target"), profileType: z .enum([ ProfileType.CPU, ProfileType.WALL, ProfileType.HEAP, ProfileType.THREADS, ProfileType.CONTENTION, ProfileType.PEAK_HEAP, ProfileType.HEAP_ALLOC, ]) .optional() .describe("Focus comparison on specific profile type"), pageSize: z .number() .min(1) .max(1000) .default(200) .describe("Number of profiles to analyse for trends"), }, }, async ({ target, profileType, pageSize }) => { try { const projectId = await getProjectId(); // Initialize Google Auth client const auth = await initGoogleAuth(true); if (!auth) { throw new GcpMcpError( "Google Cloud authentication not available. Please configure authentication to access profiler data.", "UNAUTHENTICATED", 401, ); } const client = await auth.getClient(); const token = await client.getAccessToken(); const actualPageSize = pageSize || 200; // Build query parameters const params = new URLSearchParams({ pageSize: actualPageSize.toString(), }); // Make REST API call to list profiles const apiUrl = `https://cloudprofiler.googleapis.com/v2/projects/${projectId}/profiles?${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 profiles for trend analysis: ${errorText}`, "FAILED_PRECONDITION", response.status, ); } const data: ListProfilesResponse = await response.json(); let profiles = data.profiles || []; // Apply filtering if (profileType) { profiles = profiles.filter((p) => p.profileType === profileType); } if (target) { profiles = profiles.filter((p) => p.deployment?.target?.toLowerCase().includes(target.toLowerCase()), ); } if (!profiles || profiles.length === 0) { return { content: [ { type: "text", text: `# Profile Trend Analysis\n\nProject: ${projectId}\n\nNo profiles found for trend analysis.`, }, ], }; } // Generate trend analysis let content = `# Profile Trend Analysis\n\nProject: ${projectId}\n`; if (profileType) content += `Profile Type: ${getProfileTypeDescription(profileType)}\n`; if (target) content += `Target: ${target}\n`; content += `Analysed: ${profiles.length} profiles\n\n`; // Analyse trends over time const trendAnalysis = analyseProfileTrends(profiles); content += trendAnalysis; return { content: [ { type: "text", text: content, }, ], }; } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; throw new GcpMcpError( `Failed to analyse profile trends: ${errorMessage}`, "INTERNAL_ERROR", 500, ); } }, );
• src/services/profiler/tools.ts:341-364 (schema)

  Zod schema defining the input parameters for the tool: target (optional string), profileType (optional enum), pageSize (number default 200).
  inputSchema: { target: z .string() .optional() .describe("Focus comparison on specific deployment target"), profileType: z .enum([ ProfileType.CPU, ProfileType.WALL, ProfileType.HEAP, ProfileType.THREADS, ProfileType.CONTENTION, ProfileType.PEAK_HEAP, ProfileType.HEAP_ALLOC, ]) .optional() .describe("Focus comparison on specific profile type"), pageSize: z .number() .min(1) .max(1000) .default(200) .describe("Number of profiles to analyse for trends"), },
• src/services/profiler/tools.ts:606-678 (helper)

  Supporting helper function called by the handler to analyze profile trends over time, calculating frequency, type distribution per day, and providing recommendations based on data coverage.
  function analyseProfileTrends(profiles: Profile[]): string { const profilesByTime = profiles .filter((p) => p.startTime) .sort( (a, b) => new Date(a.startTime).getTime() - new Date(b.startTime).getTime(), ); if (profilesByTime.length < 2) { return "Insufficient time-series data for trend analysis. Need at least 2 time-stamped profiles.\n"; } let analysis = "## Trend Analysis\n\n"; // Analyse profile frequency over time analysis += "### Profile Collection Frequency\n\n"; const earliest = new Date(profilesByTime[0].startTime); const latest = new Date(profilesByTime[profilesByTime.length - 1].startTime); const timeSpan = latest.getTime() - earliest.getTime(); const timeSpanDays = timeSpan / (1000 * 60 * 60 * 24); analysis += `- **Time Span:** ${Math.round(timeSpanDays)} days (from ${earliest.toLocaleDateString()} to ${latest.toLocaleDateString()})\n`; analysis += `- **Collection Frequency:** ${Math.round(profiles.length / timeSpanDays)} profiles per day\n\n`; // Analyse profile type trends analysis += "### Profile Type Trends\n\n"; const typesByTime = profilesByTime.reduce( (acc, profile) => { const day = new Date(profile.startTime).toDateString(); if (!acc[day]) acc[day] = {}; acc[day][profile.profileType] = (acc[day][profile.profileType] || 0) + 1; return acc; }, {} as Record<string, Record<string, number>>, ); const days = Object.keys(typesByTime).sort(); if (days.length > 1) { analysis += `Collected profiles across ${days.length} different days:\n\n`; days.slice(-5).forEach((day) => { // Show last 5 days const typeCounts = typesByTime[day]; const totalForDay = Object.values(typeCounts).reduce( (sum, count) => sum + count, 0, ); analysis += `**${day}:** ${totalForDay} profiles (`; analysis += Object.entries(typeCounts) .map(([type, count]) => `${type}: ${count}`) .join(", "); analysis += `)\n`; }); analysis += `\n`; } // Recommendations based on trends analysis += "### Trend-Based Recommendations\n\n"; if (timeSpanDays < 1) { analysis += `- **Short timeframe:** Consider collecting profiles over a longer period for better trend analysis\n`; } else if (profiles.length / timeSpanDays < 1) { analysis += `- **Low frequency:** Consider increasing profile collection frequency for better insights\n`; } else { analysis += `- **Good coverage:** Profile collection frequency appears adequate for trend analysis\n`; } analysis += `- **Pattern monitoring:** Set up alerts for unusual changes in profile patterns\n`; analysis += `- **Performance baseline:** Use this trend data to establish performance baselines\n`; return analysis; }