Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

5.2 KB
Raw Blame
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { RybbitApiClient } from "../apiClient.js";
import { fieldsInput, filtersInput, siteIdInput, timeInputs, traitsInput } from "../inputs.js";
import {
  destructiveTool,
  idempotentWrite,
  looseRow,
  looseRows,
  ok,
  pickRowFields,
  readOnly,
  siteQuery,
  successOutput,
  writeTool,
  type ScopeCheck, type ToolGuard,
} from "./shared.js";

const usersOutput = z
  .object({
    data: looseRows.optional(),
    totalCount: z.number().optional(),
    page: z.number().optional(),
    pageSize: z.number().optional(),
  })
  .passthrough();

const userOutput = z.object({ data: looseRow.optional() }).passthrough();

const userIdInput = z.string().min(1).describe("The user's id from get_users (device fingerprint id or identified user id)");

export function registerUserTools(server: McpServer, api: RybbitApiClient, guard: ToolGuard, allowed: ScopeCheck): void {
  if (allowed("users", "read"))
  server.registerTool(
    "get_users",
    {
      title: "List users",
      description:
        "The people behind the analytics: per-user aggregates (first/last seen, sessions, pageviews, events) with traits. Sortable, searchable, and filterable to identified users only.",
      inputSchema: {
        site_id: siteIdInput,
        page: z.number().int().min(1).default(1),
        page_size: z.number().int().min(1).max(100).default(25),
        sort_by: z.enum(["first_seen", "last_seen", "pageviews", "sessions", "events"]).default("last_seen"),
        sort_order: z.enum(["asc", "desc"]).default("desc"),
        identified_only: z.boolean().default(false).describe("Only users identified via identify()"),
        search: z.string().optional(),
        search_field: z.enum(["username", "name", "email", "user_id"]).optional().describe("Trait/id field the search matches against"),
        fields: fieldsInput,
        ...timeInputs,
        filters: filtersInput,
      },
      outputSchema: usersOutput,
      annotations: readOnly,
    },
    guard(async ({ site_id, page, page_size, sort_by, sort_order, identified_only, search, search_field, fields, ...rest }) =>
      ok(
        pickRowFields(
          await api.call("GET", `/sites/${site_id}/users`, {
            query: { page, page_size, sort_by, sort_order, identified_only, search, search_field, ...siteQuery(rest) },
          }),
          "data",
          fields
        )
      )
    )
  );

  if (allowed("users", "read"))
  server.registerTool(
    "get_user",
    {
      title: "User profile",
      description:
        "One person's profile: activity aggregates, traits, linked devices, web-vitals percentiles, and location/device breakdowns.",
      inputSchema: { site_id: siteIdInput, user_id: userIdInput },
      outputSchema: userOutput,
      annotations: readOnly,
    },
    guard(async ({ site_id, user_id }) =>
      ok(await api.call("GET", `/sites/${site_id}/users/${encodeURIComponent(user_id)}`))
    )
  );

  if (allowed("users", "write"))
  server.registerTool(
    "identify_user",
    {
      title: "Identify user",
      description:
        "Link an anonymous device id to your own user id and merge traits β€” the server-side equivalent of the SDK's identify() call. Event aggregates may take a moment to reflect the merge.",
      inputSchema: {
        site_id: siteIdInput,
        anonymous_id: z.string().min(1).describe("The anonymous device/user id recorded by the tracker"),
        user_id: z.string().min(1).describe("Your application's id for this user"),
        traits: traitsInput.optional(),
      },
      outputSchema: successOutput,
      annotations: writeTool,
    },
    guard(async ({ site_id, anonymous_id, user_id, traits }) =>
      ok(await api.call("POST", `/sites/${site_id}/users/identify`, { body: { anonymous_id, user_id, traits } }))
    )
  );

  if (allowed("users", "write"))
  server.registerTool(
    "update_user_traits",
    {
      title: "Update user traits",
      description:
        "Replace a person's traits wholesale (max 2KB serialized). Unlike identify_user, this does not merge β€” fetch current traits with get_user first and resend everything you want to keep.",
      inputSchema: { site_id: siteIdInput, user_id: userIdInput, traits: traitsInput },
      outputSchema: successOutput,
      annotations: idempotentWrite,
    },
    guard(async ({ site_id, user_id, traits }) =>
      ok(await api.call("PUT", `/sites/${site_id}/users/${encodeURIComponent(user_id)}/traits`, { body: { traits } }))
    )
  );

  if (allowed("users", "write"))
  server.registerTool(
    "delete_user",
    {
      title: "Delete user (GDPR erasure)",
      description:
        "Permanently delete one person's analytics data: events, session replays, profile, and device aliases. Irreversible; erasure completes asynchronously. Requires the API key's user to hold the editor role or above on the site. Confirm with the user before calling.",
      inputSchema: { site_id: siteIdInput, user_id: userIdInput },
      outputSchema: successOutput,
      annotations: destructiveTool,
    },
    guard(async ({ site_id, user_id }) =>
      ok(await api.call("DELETE", `/sites/${site_id}/users/${encodeURIComponent(user_id)}`))
    )
  );
}