get_conversion_funnel

Instructions

Implementation Reference

• src/tools/analytics/getConversionFunnel.ts:17-90 (handler)

  The core handler function that implements the get_conversion_funnel tool logic. It fetches user counts for each funnel step using GA4 reports, computes dropoff rates and conversion rates relative to the first step, and returns the funnel analysis results.

  export async function getConversionFunnel(
    input: GetConversionFunnelInput
  ): Promise<GetConversionFunnelOutput> {
    const propertyId = getPropertyId(input.propertyId);
    const property = formatPropertyPath(propertyId);
    const dateRange = periodToDateRange(input.period);
  
    if (input.steps.length < 2) {
      throw new Error("ファネル分析には少なくとも2つのステップが必要です");
    }
  
    const funnel: FunnelStepResult[] = [];
    let previousUsers = 0;
    let firstStepUsers = 0;
  
    // 各ステップのユーザー数を取得
    for (let i = 0; i < input.steps.length; i++) {
      const step = input.steps[i];
  
      const response = await executeReport({
        property,
        dateRanges: [dateRange],
        dimensions: [{ name: "pagePath" }],
        metrics: [{ name: "totalUsers" }],
        dimensionFilter: {
          filter: {
            fieldName: "pagePath",
            stringFilter: {
              matchType: "BEGINS_WITH",
              value: step.pagePath,
            },
          },
        },
      });
  
      const users =
        response.totals?.[0]?.metricValues?.[0]?.value
          ? Math.round(parseFloat(response.totals[0].metricValues[0].value))
          : 0;
  
      if (i === 0) {
        firstStepUsers = users;
        previousUsers = users;
      }
  
      // 離脱率の計算
      const dropoffRate =
        i === 0
          ? "0%"
          : calculatePercentage(previousUsers - users, previousUsers);
  
      // コンバージョン率の計算（最初のステップからの通過率）
      const conversionRate = calculatePercentage(users, firstStepUsers);
  
      funnel.push({
        step: i + 1,
        name: step.name,
        users,
        dropoffRate,
        conversionRate,
      });
  
      previousUsers = users;
    }
  
    // 全体のコンバージョン率（最初のステップから最後のステップへの通過率）
    const lastStepUsers = funnel[funnel.length - 1]?.users || 0;
    const overallConversionRate = calculatePercentage(lastStepUsers, firstStepUsers);
  
    return {
      funnel,
      overallConversionRate,
    };
  }

• src/server.ts:428-461 (registration)

  MCP tool registration entry for get_conversion_funnel, defining the tool name, description, and input schema used in the listTools response.

  {
    name: "get_conversion_funnel",
    description:
      "コンバージョンファネルの分析を行います。各ステップの通過率や離脱率を確認できます。",
    inputSchema: {
      type: "object" as const,
      properties: {
        propertyId: { type: "string", description: "GA4プロパティID" },
        period: {
          type: "string",
          enum: ["7days", "28days", "30days"],
          description: "集計期間",
        },
        steps: {
          type: "array",
          items: {
            type: "object",
            properties: {
              name: {
                type: "string",
                description: 'ステップ名（例: "商品詳細"）',
              },
              pagePath: {
                type: "string",
                description: 'マッチするページパス（例: "/product/"）',
              },
            },
            required: ["name", "pagePath"],
          },
          description: "ファネルのステップ定義（最低2つ必要）",
        },
      },
      required: ["period", "steps"],
    },

• src/types.ts:307-329 (schema)

  TypeScript type definitions for the get_conversion_funnel tool, including input interface (GetConversionFunnelInput), output interface (GetConversionFunnelOutput), and supporting types (FunnelStep, FunnelStepResult).

  // get_conversion_funnel
  export interface FunnelStep {
    name: string;
    pagePath: string;
  }
  
  export interface GetConversionFunnelInput extends PropertyId {
    period: ShortPeriod;
    steps: FunnelStep[];
  }
  
  export interface FunnelStepResult {
    step: number;
    name: string;
    users: number;
    dropoffRate: string;
    conversionRate: string;
  }
  
  export interface GetConversionFunnelOutput {
    funnel: FunnelStepResult[];
    overallConversionRate: string;
  }

• src/server.ts:711-716 (registration)

  Dispatch handler in the switch statement that routes calls to the get_conversion_funnel tool handler function.

  case "get_conversion_funnel":
    return await getConversionFunnel({
      propertyId: args.propertyId as string | undefined,
      period: args.period as "7days" | "28days" | "30days",
      steps: args.steps as Array<{ name: string; pagePath: string }>,
    });