rybbit-mcp

Instructions

Implementation Reference

• src/tools/users.ts:142-192 (handler)

  The handler function for the `rybbit_list_users` tool. It handles the logic for listing users, including a special case for sorting by 'duration' and a workaround for the 'event_name' filter limitation.

    async (args) => {
      try {
        if (args.sortBy === "duration") {
          const data = await fetchUsersByDuration(client, args.siteId, {
            startDate: args.startDate,
            endDate: args.endDate,
            timeZone: args.timeZone,
            filters: args.filters,
            pastMinutesStart: args.pastMinutesStart,
            pastMinutesEnd: args.pastMinutesEnd,
            sortOrder: args.sortOrder,
            limit: args.limit,
          });
          return {
            content: [{ type: "text" as const, text: truncateResponse(data) }],
          };
        }
  
        // Workaround: event_name filter crashes the backend getUsers endpoint
        // (applies session-level subquery to CTE outer query where session_id doesn't exist).
        // Strip it from filters and add a warning.
        const safeFilters = args.filters?.filter(
          (f) => f.parameter !== "event_name"
        );
        const hadEventFilter = safeFilters?.length !== args.filters?.length;
        const safeArgs = { ...args, filters: safeFilters };
  
        const params = client.buildAnalyticsParams(safeArgs);
        if (args.search) params.search = args.search;
        if (args.searchField) params.search_field = args.searchField;
        if (args.identifiedOnly) params.identified_only = "true";
        if (args.sortBy) params.sort_by = args.sortBy;
        if (args.sortOrder) params.sort_order = args.sortOrder;
        const data = await client.get(`/sites/${args.siteId}/users`, params);
  
        const warning = hadEventFilter
          ? "\n\nNote: event_name filter was removed (not supported for user listing due to backend limitation). Use rybbit_get_user_event_breakdown to find users by specific events."
          : "";
  
        return {
          content: [{ type: "text" as const, text: truncateResponse(data) + warning }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return {
          content: [{ type: "text" as const, text: `Error: ${message}` }],
          isError: true,
        };
      }
    }
  );

• src/tools/users.ts:110-141 (registration)

  The registration of the `rybbit_list_users` tool, including its description and input schema.

  server.registerTool(
    "rybbit_list_users",
    {
      title: "List Users",
      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false },
      description:
        "List users for a site. Returns user IDs, session counts, first/last seen dates, and user traits. Supports filtering by any analytics dimension. Use 'search' param to find users by username/email/name (case-insensitive partial match).",
      inputSchema: {
        ...analyticsInputSchema,
        ...paginationSchema,
        search: z
          .string()
          .optional()
          .describe("Search users by trait value (e.g. username, email). Uses case-insensitive partial matching (ILIKE)."),
        searchField: z
          .enum(["username", "name", "email", "user_id"])
          .optional()
          .describe("Which field to search in (default: 'username'). Only used when 'search' is provided."),
        identifiedOnly: z
          .boolean()
          .optional()
          .describe("Only return identified users (users with identified_user_id). Default: false."),
        sortBy: z
          .enum(["first_seen", "last_seen", "pageviews", "sessions", "events", "duration"])
          .optional()
          .describe("Sort field (default: 'last_seen'). 'duration' sorts by total time spent (aggregated from sessions, requires date range)."),
        sortOrder: z
          .enum(["asc", "desc"])
          .optional()
          .describe("Sort direction (default: 'desc')"),
      },
    },