Skip to content

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

6.8 KB
Raw Blame
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { RybbitApiClient } from "../apiClient.js";
import { organizationIdInput, siteFeatureInputs, siteIdInput } from "../inputs.js";
import { destructiveTool, idempotentWrite, looseRow, ok, readOnly, writeTool, type ScopeCheck, type ToolGuard } from "./shared.js";

const listSitesOutput = z.object({
  organizations: z.array(
    z.object({
      organization_id: z.string(),
      name: z.string(),
      slug: z.string(),
      role: z.string(),
      sites: z.array(
        z.object({
          site_id: z.union([z.number(), z.string()]),
          name: z.string(),
          domain: z.string(),
          public: z.boolean(),
        })
      ),
    })
  ),
});

const siteOutput = z
  .object({
    siteId: z.number(),
    name: z.string(),
    domain: z.string(),
    type: z.string().nullable(),
    public: z.boolean(),
  })
  .partial()
  .passthrough();

const updateSiteConfigOutput = z
  .object({ success: z.boolean(), message: z.string(), config: looseRow.optional() })
  .partial()
  .passthrough();

export function registerSiteTools(server: McpServer, api: RybbitApiClient, guard: ToolGuard, allowed: ScopeCheck): void {
  server.registerTool(
    "list_sites",
    {
      title: "List sites",
      description:
        "List the organizations and sites this API key can access. Call this first: it resolves the numeric site_id used by site tools and the organization_id used by organization tools, and its role field shows the key's role per organization (report-building tools need member or above, site configuration needs editor, site creation/deletion and member management need admin; site grants and teams can raise the role on individual sites).",
      inputSchema: {},
      outputSchema: listSitesOutput,
      annotations: readOnly,
    },
    guard(async () => {
      const orgs = await api.call<
        {
          id: string;
          name: string;
          slug: string;
          role: string;
          sites?: { id: string; name: string; domain: string; public: boolean }[];
        }[]
      >("GET", "/organizations");
      return ok({
        organizations: orgs.map(org => ({
          organization_id: org.id,
          name: org.name,
          slug: org.slug,
          role: org.role,
          sites: (org.sites ?? []).map(site => ({
            site_id: Number.isNaN(Number(site.id)) ? site.id : Number(site.id),
            name: site.name,
            domain: site.domain,
            // The column is nullable; coalesce so the strict boolean output
            // schema never throws and breaks this entry-point tool.
            public: site.public ?? false,
          })),
        })),
      });
    })
  );

  if (allowed("sites", "read"))
  server.registerTool(
    "get_site",
    {
      title: "Get site configuration",
      description:
        "Full configuration of one site: name, domain, type, visibility, and which tracking features (session replay, web vitals, error tracking, ...) are enabled.",
      inputSchema: { site_id: siteIdInput },
      outputSchema: siteOutput,
      annotations: readOnly,
    },
    guard(async ({ site_id }) => ok(await api.call("GET", `/sites/${site_id}`)))
  );

  if (allowed("sites", "write"))
  server.registerTool(
    "create_site",
    {
      title: "Create site",
      description:
        "Add a new site to an organization. Requires the API key's user to be an org admin or owner. Returns the created site including its numeric siteId.",
      inputSchema: {
        organization_id: organizationIdInput,
        domain: z.string().min(1).describe("The site's domain (example.com), or a bundle id like com.example.app for mobile"),
        name: z.string().min(1).describe("Display name"),
        type: z.enum(["web", "mobile"]).optional(),
        excludedIPs: z.array(z.string()).optional().describe("IPs or CIDR ranges to exclude from tracking"),
        excludedCountries: z.array(z.string()).optional().describe("Two-letter ISO country codes to exclude"),
        tags: z.array(z.string()).optional(),
        ...siteFeatureInputs,
      },
      outputSchema: z
        .object({ siteId: z.number(), name: z.string(), domain: z.string(), organizationId: z.string().nullable() })
        .partial()
        .passthrough(),
      annotations: writeTool,
    },
    guard(async ({ organization_id, ...body }) =>
      ok(await api.call("POST", `/organizations/${encodeURIComponent(organization_id)}/sites`, { body }))
    )
  );

  if (allowed("sites", "write"))
  server.registerTool(
    "update_site_config",
    {
      title: "Update site configuration",
      description:
        "Update a site's settings; only the fields you pass are changed. Requires the API key's user to hold the editor role or above on the site. Use get_site first to see current values.",
      inputSchema: {
        site_id: siteIdInput,
        name: z.string().optional(),
        domain: z.string().optional(),
        type: z.enum(["web", "mobile"]).optional(),
        embedEnabled: z.boolean().optional().describe("Allow embedding the stats widget"),
        firstPartyProxy: z
          .boolean()
          .optional()
          .describe(
            "Site is fronted by a first-party proxy (Cloudflare Worker, CloudFront, nginx); visitor IPs are read from forwarded headers"
          ),
        excludedIPs: z.array(z.string()).optional().describe("Replaces the exclusion list wholesale"),
        excludedCountries: z.array(z.string()).optional(),
        excludedPaths: z.array(z.string()).optional(),
        excludedHostnames: z.array(z.string()).optional(),
        excludedUserAgents: z.array(z.string()).optional(),
        excludedASNs: z
          .array(z.string())
          .optional()
          .describe("Autonomous system numbers to exclude, with or without AS prefix (e.g., AS13335)"),
        excludedQueryParams: z
          .array(z.string())
          .optional()
          .describe('Query param exclusions: "name" (param present) or "name=value" (value supports * glob)'),
        tags: z.array(z.string()).optional(),
        ...siteFeatureInputs,
      },
      outputSchema: updateSiteConfigOutput,
      annotations: idempotentWrite,
    },
    guard(async ({ site_id, ...body }) => ok(await api.call("PUT", `/sites/${site_id}/config`, { body })))
  );

  if (allowed("sites", "write"))
  server.registerTool(
    "delete_site",
    {
      title: "Delete site",
      description:
        "Permanently delete a site, its configuration, and its recorded data. Irreversible; data erasure completes asynchronously. Requires the API key's user to be an org admin or owner. Confirm with the user before calling.",
      inputSchema: { site_id: siteIdInput },
      outputSchema: z.object({ success: z.boolean() }).partial().passthrough(),
      annotations: destructiveTool,
    },
    guard(async ({ site_id }) => ok(await api.call("DELETE", `/sites/${site_id}`)))
  );
}