Metric Breakdown

Instructions

Implementation Reference

• src/tools/metrics.ts:47-86 (handler)

  The async handler function for rybbit_get_metric. It destructures args (siteId, parameter, page, limit, and analytics params), builds query params via client.buildAnalyticsParams, sets the 'parameter' dimension, calls GET /sites/{siteId}/metric, and returns the data (truncated if needed). On error, returns an error message with isError:true.

    async (args) => {
      try {
        const { siteId, parameter, page, limit, ...rest } = args as {
          siteId: string;
          parameter: z.infer<typeof metricParameterSchema>;
          page?: number;
          limit?: number;
          startDate?: string;
          endDate?: string;
          timeZone?: string;
          filters?: Array<{ parameter: string; type: string; value: (string | number)[] }>;
          pastMinutesStart?: number;
          pastMinutesEnd?: number;
        };
  
        const params = client.buildAnalyticsParams({ ...rest, page, limit });
        params.parameter = parameter;
  
        const data = await client.get<MetricEntry[]>(
          `/sites/${siteId}/metric`,
          params
        );
  
        return {
          content: [
            {
              type: "text" as const,
              text: truncateResponse(data),
            },
          ],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/schemas.ts:139-175 (schema)

  metricParameterSchema — a Zod enum defining all valid dimensions for the 'parameter' input field: browser, browser_version, operating_system, operating_system_version, language, country, region, city, device_type, device_model, app_version, dimensions, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, timezone, company, company_type, asn_org, asn_type.

  export const metricParameterSchema = z
    .enum([
      "browser",
      "browser_version",
      "operating_system",
      "operating_system_version",
      "language",
      "country",
      "region",
      "city",
      "device_type",
      "device_model",
      "app_version",
      "dimensions",
      "referrer",
      "hostname",
      "pathname",
      "page_title",
      "querystring",
      "event_name",
      "channel",
      "utm_source",
      "utm_medium",
      "utm_campaign",
      "utm_term",
      "utm_content",
      "entry_page",
      "exit_page",
      "timezone",
      "company",
      "company_type",
      "asn_org",
      "asn_type",
    ])
    .describe(
      "Metric dimension to break down by. device_model and app_version apply only to app-type sites tracked via SDK."
    );

• src/schemas.ts:85-137 (schema)

  analyticsInputSchema — shared input schema providing siteId, startDate, endDate, timeZone, filters (array of filter objects), pastMinutesStart, pastMinutesEnd. Combined with metricParameterSchema and paginationSchema in the tool's inputSchema.

  export const analyticsInputSchema = {
    siteId: siteIdSchema,
    startDate: z
      .string()
      .optional()
      .describe("Start date in ISO format (YYYY-MM-DD)"),
    endDate: z
      .string()
      .optional()
      .describe("End date in ISO format (YYYY-MM-DD)"),
    timeZone: z
      .string()
      .optional()
      .describe("IANA timezone (e.g., Europe/Prague). Default: UTC"),
    filters: z
      .array(filterSchema)
      .optional()
      .describe("Array of filters. Example: [{parameter:'browser',type:'equals',value:['Chrome']},{parameter:'country',type:'equals',value:['US','DE']}]"),
    pastMinutesStart: z
      .number()
      .optional()
      .describe("Alternative to dates: minutes ago start (e.g., 60 = last hour)"),
    pastMinutesEnd: z
      .number()
      .optional()
      .describe("Alternative to dates: minutes ago end (default 0 = now)"),
  };
  
  export const bucketSchema = z
    .enum([
      "minute",
      "five_minutes",
      "ten_minutes",
      "fifteen_minutes",
      "hour",
      "day",
      "week",
      "month",
      "year",
    ])
    .optional()
    .describe("Time bucket granularity (default: day). Use 'hour' for last 24h, 'week'/'month' for long ranges");
  
  export const paginationSchema = {
    page: z.number().int().min(1).optional().describe("Page number, 1-indexed (default: 1)"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(200)
      .optional()
      .describe("Results per page (default: 20-50 depending on endpoint, max 200)"),
  };

• src/schemas.ts:128-137 (schema)

  paginationSchema — optional page (1-indexed integer) and limit (1-200 integer) for paginated results.

  export const paginationSchema = {
    page: z.number().int().min(1).optional().describe("Page number, 1-indexed (default: 1)"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(200)
      .optional()
      .describe("Results per page (default: 20-50 depending on endpoint, max 200)"),
  };

• src/tools/metrics.ts:29-86 (registration)

  Registration of the tool via server.registerTool('rybbit_get_metric', ...) with title, description, annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint), and inline inputSchema built from spread schemas.

  server.registerTool(
    "rybbit_get_metric",
    {
      title: "Metric Breakdown",
      description:
        "Get metric breakdown by dimension. Use parameter='pathname' for top pages, 'browser'/'operating_system'/'device_type' for tech stats, 'country'/'city' for geo, 'utm_source'/'utm_campaign' for marketing, 'referrer'/'channel' for traffic sources, 'entry_page'/'exit_page' for user flow. Returns sorted list with counts, percentages, bounce rate, and session duration.",
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
        openWorldHint: true,
        destructiveHint: false,
      },
      inputSchema: {
        ...analyticsInputSchema,
        parameter: metricParameterSchema,
        ...paginationSchema,
      },
    },
    async (args) => {
      try {
        const { siteId, parameter, page, limit, ...rest } = args as {
          siteId: string;
          parameter: z.infer<typeof metricParameterSchema>;
          page?: number;
          limit?: number;
          startDate?: string;
          endDate?: string;
          timeZone?: string;
          filters?: Array<{ parameter: string; type: string; value: (string | number)[] }>;
          pastMinutesStart?: number;
          pastMinutesEnd?: number;
        };
  
        const params = client.buildAnalyticsParams({ ...rest, page, limit });
        params.parameter = parameter;
  
        const data = await client.get<MetricEntry[]>(
          `/sites/${siteId}/metric`,
          params
        );
  
        return {
          content: [
            {
              type: "text" as const,
              text: truncateResponse(data),
            },
          ],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );