User Retention

Instructions

Implementation Reference

• src/tools/metrics.ts:104-139 (handler)

  Handler function for the rybbit_get_retention tool. Extracts siteId and analytics params, calls GET /sites/{siteId}/retention API endpoint, and returns retention cohort data.

    async (args) => {
      try {
        const { siteId, ...rest } = args as {
          siteId: string;
          startDate?: string;
          endDate?: string;
          timeZone?: string;
          filters?: Array<{ parameter: string; type: string; value: (string | number)[] }>;
          pastMinutesStart?: number;
          pastMinutesEnd?: number;
        };
  
        const params = client.buildAnalyticsParams(rest);
  
        const data = await client.get<RetentionData[]>(
          `/sites/${siteId}/retention`,
          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/tools/metrics.ts:88-139 (registration)

  Registration of the 'rybbit_get_retention' tool with McpServer, including title 'User Retention', description, annotations (readOnlyHint, idempotentHint, openWorldHint), and inputSchema.

  server.registerTool(
    "rybbit_get_retention",
    {
      title: "User Retention",
      description:
        "Get user retention cohort analysis showing how many users return over time periods.",
      annotations: {
        readOnlyHint: true,
        idempotentHint: true,
        openWorldHint: true,
        destructiveHint: false,
      },
      inputSchema: {
        ...analyticsInputSchema,
      },
    },
    async (args) => {
      try {
        const { siteId, ...rest } = args as {
          siteId: string;
          startDate?: string;
          endDate?: string;
          timeZone?: string;
          filters?: Array<{ parameter: string; type: string; value: (string | number)[] }>;
          pastMinutesStart?: number;
          pastMinutesEnd?: number;
        };
  
        const params = client.buildAnalyticsParams(rest);
  
        const data = await client.get<RetentionData[]>(
          `/sites/${siteId}/retention`,
          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:85-85 (schema)

  analyticsInputSchema shared input schema used by rybbit_get_retention, defining siteId, startDate, endDate, timeZone, filters, pastMinutesStart, pastMinutesEnd.

  export const analyticsInputSchema = {

• src/index.ts:40-40 (registration)

  Entry point call to registerMetricsTools(server, client) which registers rybbit_get_retention among other metric tools.

  registerMetricsTools(server, client);

• src/client.ts:114-145 (helper)

  buildAnalyticsParams helper method on RybbitClient that transforms query parameters (startDate, endDate, filters, etc.) into API-compatible query params.

    buildAnalyticsParams(options: {
      startDate?: string;
      endDate?: string;
      timeZone?: string;
      filters?: FilterParam[];
      pastMinutesStart?: number;
      pastMinutesEnd?: number;
      bucket?: string;
      page?: number;
      limit?: number;
      offset?: number;
    }): QueryParams {
      const params: QueryParams = {};
  
      if (options.startDate) params.start_date = options.startDate;
      if (options.endDate) params.end_date = options.endDate;
      if (options.timeZone) params.time_zone = options.timeZone;
      if (options.filters && options.filters.length > 0) {
        params.filters = JSON.stringify(options.filters);
      }
      if (options.pastMinutesStart !== undefined)
        params.past_minutes_start = options.pastMinutesStart;
      if (options.pastMinutesEnd !== undefined)
        params.past_minutes_end = options.pastMinutesEnd;
      if (options.bucket) params.bucket = options.bucket;
      if (options.page !== undefined) params.page = options.page;
      if (options.limit !== undefined) params.limit = options.limit;
      if (options.offset !== undefined) params.offset = options.offset;
  
      return params;
    }
  }