get_hourly_traffic

Instructions

Implementation Reference

• src/tools/analytics/getHourlyTraffic.ts:13-95 (handler)

  The core handler function that executes the get_hourly_traffic tool logic. It queries GA4 for hourly data, computes daily averages for users and page views, identifies peak and quiet hours based on thresholds, and returns structured output.

  export async function getHourlyTraffic(
    input: GetHourlyTrafficInput
  ): Promise<GetHourlyTrafficOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
    const dayCount = getDayCount(dateRange);
  
    const response = await executeReport({
      property,
      dateRanges: [dateRange],
      dimensions: [{ name: "hour" }],
      metrics: [{ name: "totalUsers" }, { name: "screenPageViews" }],
      orderBys: [{ dimension: { dimensionName: "hour" }, desc: false }],
      limit: 24,
    });
  
    // 時間ごとのデータを初期化（0-23時）
    const hourlyMap = new Map<number, { users: number; pageViews: number }>();
    for (let i = 0; i < 24; i++) {
      hourlyMap.set(i, { users: 0, pageViews: 0 });
    }
  
    // レスポンスからデータを収集
    for (const row of response.rows || []) {
      const hour = parseInt(row.dimensionValues?.[0]?.value || "0", 10);
      const users = row.metricValues?.[0]?.value
        ? parseFloat(row.metricValues[0].value)
        : 0;
      const pageViews = row.metricValues?.[1]?.value
        ? parseFloat(row.metricValues[1].value)
        : 0;
  
      hourlyMap.set(hour, { users, pageViews });
    }
  
    // 平均を計算してHourlyData配列を作成
    const hourlyData: HourlyData[] = [];
    let maxUsers = 0;
    let minUsers = Infinity;
  
    for (let hour = 0; hour < 24; hour++) {
      const data = hourlyMap.get(hour)!;
      const avgUsers = roundToDecimal(data.users / dayCount);
      const avgPageViews = roundToDecimal(data.pageViews / dayCount);
  
      if (avgUsers > maxUsers) maxUsers = avgUsers;
      if (avgUsers < minUsers) minUsers = avgUsers;
  
      hourlyData.push({
        hour,
        avgUsers,
        avgPageViews,
        peakIndicator: false, // 後で設定
      });
    }
  
    // ピーク判定の閾値（平均値の1.5倍以上）
    const avgAllHours =
      hourlyData.reduce((sum, h) => sum + h.avgUsers, 0) / 24;
    const peakThreshold = avgAllHours * 1.5;
    const quietThreshold = avgAllHours * 0.5;
  
    // ピーク時間帯と閑散時間帯を特定
    const peakHours: number[] = [];
    const quietHours: number[] = [];
  
    for (const data of hourlyData) {
      if (data.avgUsers >= peakThreshold) {
        data.peakIndicator = true;
        peakHours.push(data.hour);
      }
      if (data.avgUsers <= quietThreshold) {
        quietHours.push(data.hour);
      }
    }
  
    return {
      hourlyData,
      peakHours,
      quietHours,
    };
  }

• src/types.ts:331-347 (schema)

  TypeScript interfaces defining the input (GetHourlyTrafficInput), data structure (HourlyData), and output (GetHourlyTrafficOutput) for the get_hourly_traffic tool.

  // get_hourly_traffic
  export interface GetHourlyTrafficInput extends PropertyId {
    period: ShortPeriod;
  }
  
  export interface HourlyData {
    hour: number;
    avgUsers: number;
    avgPageViews: number;
    peakIndicator: boolean;
  }
  
  export interface GetHourlyTrafficOutput {
    hourlyData: HourlyData[];
    peakHours: number[];
    quietHours: number[];
  }

• src/server.ts:463-479 (registration)

  MCP tool registration in the tools array, defining name, description, and input schema for get_hourly_traffic.

  {
    name: "get_hourly_traffic",
    description:
      "時間帯別のアクセス状況を分析します。投稿やキャンペーンのタイミング最適化に活用できます。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["7days", "28days", "30days"],
          description: "集計期間",
        },
      },
      required: ["period"],
    },
  },

• src/server.ts:718-722 (registration)

  Dispatch handler in the switch statement that calls the getHourlyTraffic function when the tool is invoked.

  case "get_hourly_traffic":
    return await getHourlyTraffic({
      propertyId: args.propertyId as string | undefined,
      period: args.period as "7days" | "28days" | "30days",
    });

• src/tools/analytics/index.ts:11-11 (registration)

  Re-export of the getHourlyTraffic handler from its module for use in server.ts.

  export { getHourlyTraffic } from "./getHourlyTraffic.js";