run_realtime_report

Instructions

Implementation Reference

• src/tools/basic/runRealtimeReport.ts:15-82 (handler)

  The main handler function that implements the run_realtime_report tool logic. It executes a GA4 realtime report using the provided dimensions and metrics, processes the response into rows and totals.

  export async function runRealtimeReport(
    input: RunRealtimeReportInput
  ): Promise<RealtimeReportOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
  
    // デフォルト値の設定
    const dimensions = input.dimensions || ["country", "deviceCategory"];
    const metrics = input.metrics || ["activeUsers"];
  
    // レポート実行
    const response = await executeRealtimeReport({
      property,
      dimensions: dimensions.map((name) => ({ name })),
      metrics: metrics.map((name) => ({ name })),
    });
  
    // 結果を整形
    const rows: ReportRow[] = [];
    const dimensionHeaders = response.dimensionHeaders || [];
    const metricHeaders = response.metricHeaders || [];
  
    for (const row of response.rows || []) {
      const dimensionValues: Record<string, string> = {};
      const metricValues: Record<string, number | string> = {};
  
      // ディメンション値を取得
      (row.dimensionValues || []).forEach((value, index) => {
        const header = dimensionHeaders[index];
        if (header?.name) {
          dimensionValues[header.name] = value.value || "";
        }
      });
  
      // メトリクス値を取得
      (row.metricValues || []).forEach((value, index) => {
        const header = metricHeaders[index];
        if (header?.name) {
          const rawValue = value.value || "0";
          const numValue = parseFloat(rawValue);
          metricValues[header.name] = isNaN(numValue) ? rawValue : numValue;
        }
      });
  
      rows.push({ dimensions: dimensionValues, metrics: metricValues });
    }
  
    // 合計値の取得
    let totals: Record<string, number | string> | undefined;
    if (response.totals && response.totals.length > 0) {
      totals = {};
      const totalRow = response.totals[0];
      (totalRow.metricValues || []).forEach((value, index) => {
        const header = metricHeaders[index];
        if (header?.name) {
          const rawValue = value.value || "0";
          const numValue = parseFloat(rawValue);
          totals![header.name] = isNaN(numValue) ? rawValue : numValue;
        }
      });
    }
  
    return {
      rows,
      rowCount: rows.length,
      totals,
    };
  }

• src/server.ts:162-187 (registration)

  Tool registration in the tools array, defining the name, description, and input schema for listTools response.

  {
    name: "run_realtime_report",
    description:
      "リアルタイムレポートを実行し、現在のアクティブユーザー数などを取得します。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: {
          type: "string",
          description: "GA4プロパティID（省略時は環境変数を使用）",
        },
        dimensions: {
          type: "array",
          items: { type: "string" },
          description:
            'ディメンション（デフォルト: ["country", "deviceCategory"]）',
        },
        metrics: {
          type: "array",
          items: { type: "string" },
          description: 'メトリクス（デフォルト: ["activeUsers"]）',
        },
      },
      required: [],
    },
  },

• src/server.ts:607-612 (registration)

  Tool dispatcher in handleToolCall switch statement that calls the runRealtimeReport handler with parsed arguments.

  case "run_realtime_report":
    return await runRealtimeReport({
      propertyId: args.propertyId as string | undefined,
      dimensions: args.dimensions as string[] | undefined,
      metrics: args.metrics as string[] | undefined,
    });

• src/types.ts:83-93 (schema)

  TypeScript interfaces defining the input (RunRealtimeReportInput) and output (RealtimeReportOutput) types for the tool.

  // run_realtime_report
  export interface RunRealtimeReportInput extends PropertyId {
    dimensions?: string[];
    metrics?: string[];
  }
  
  export interface RealtimeReportOutput {
    rows: ReportRow[];
    rowCount: number;
    totals?: Record<string, number | string>;
  }

• src/tools/basic/index.ts:4-4 (helper)

  Re-export of the runRealtimeReport function for convenient import in server.ts.

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