Skip to content

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

6.4 KB
Raw Blame
import { z } from "zod";
import { hasScope, type ScopeAction, type ScopeResource, type ScopeStatements } from "../../lib/scopes.js";
import { RybbitApiError } from "../apiClient.js";
import { toFiltersQuery, ToolInputError, toTimeQuery, type FilterArgs, type TimeArgs } from "../inputs.js";

export interface ToolRegistrationConfig {
  /** Sink for unexpected (non-API) tool errors; details are logged here, never returned to the client. */
  log?: (message: string) => void;
  /** The credential's scope statements; null/undefined = unrestricted. Tools outside the scopes are not registered. */
  scopes?: ScopeStatements | null;
}

export type ScopeCheck = (resource: ScopeResource, action: ScopeAction) => boolean;

/**
 * tools/list filtering is UX, not enforcement: tool calls proxy through the
 * REST guards, which enforce the same scopes authoritatively.
 */
export function createScopeCheck(scopes: ScopeStatements | null | undefined): ScopeCheck {
  return (resource, action) => hasScope(scopes ?? null, { resource, action });
}

export type ToolResult = {
  content: { type: "text"; text: string }[];
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
};

// Analytics labels (titles, paths, referrers, event names, traits) originate in
// tracked traffic and are untrusted. Strip control and bidi-override characters
// that could be used to disguise instructions to an AI client; keep tab/newline
// so legitimate multi-line values stay readable.
const UNSAFE_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u202a-\u202e\u2066-\u2069]/g;

function sanitizeValue(value: unknown): unknown {
  if (typeof value === "string") {
    return value.replace(UNSAFE_CHARS, " ");
  }
  if (Array.isArray(value)) {
    return value.map(item => sanitizeValue(item));
  }
  if (value && typeof value === "object") {
    const result: Record<string, unknown> = {};
    for (const [key, entry] of Object.entries(value)) {
      result[key] = sanitizeValue(entry);
    }
    return result;
  }
  return value;
}

export function ok(data: unknown): ToolResult {
  if (typeof data === "string") {
    return { content: [{ type: "text", text: data }] };
  }
  const sanitized = sanitizeValue(data);
  const structured =
    sanitized && typeof sanitized === "object" && !Array.isArray(sanitized)
      ? (sanitized as Record<string, unknown>)
      : { data: sanitized };
  return { content: [{ type: "text", text: JSON.stringify(structured) }], structuredContent: structured };
}

export function fail(message: string): ToolResult {
  return { content: [{ type: "text", text: message.replace(UNSAFE_CHARS, " ") }], isError: true };
}

const ERROR_HINTS: Record<number, string> = {
  401: "The API key is missing or invalid. Create one under Settings > Account > Personal API Keys and send it as 'Authorization: Bearer <key>'.",
  403: "The API key's user does not have access to this site or organization, or holds too low a role for this tool ('Insufficient role' names the role required). Check the site_id with list_sites; its role field shows the key's role per organization. If the message says 'Insufficient scope', the credential was created without the scope this tool needs β€” use a key or OAuth grant that has it.",
  429: "Rate limited. Wait before retrying, and prefer fewer, more aggregated queries.",
};

export type ToolGuard = <Args>(handler: (args: Args) => Promise<ToolResult>) => (args: Args) => Promise<ToolResult>;

export function createGuard(log?: (message: string) => void): ToolGuard {
  return handler => async args => {
    try {
      return await handler(args);
    } catch (error) {
      if (error instanceof RybbitApiError) {
        const hint = ERROR_HINTS[error.status];
        return fail(`Rybbit API error ${error.status}: ${error.message}${hint ? ` β€” ${hint}` : ""}`);
      }
      // Argument problems the caller can correct β€” surface the message so the
      // model can fix its next call.
      if (error instanceof ToolInputError) {
        return fail(error.message);
      }
      // Unexpected errors may carry internals (stack traces, hostnames); log
      // them server-side and return a generic message.
      log?.(`MCP tool failed: ${error instanceof Error ? error.stack || error.message : String(error)}`);
      return fail("Rybbit could not complete the request");
    }
  };
}

// MCP tool annotations. The spec defaults destructiveHint/openWorldHint to true
// when omitted, so every hint is set explicitly.
export const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
export const writeTool = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
export const idempotentWrite = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
export const destructiveTool = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };

/**
 * Prune each row in `response[key]` to the requested top-level fields. Rows
 * are wide (sessions and users carry 30+ columns) and every field costs the
 * client tokens twice, as text and as structuredContent. Unknown field names
 * are ignored so a stale name never fails the call.
 */
export function pickRowFields<T>(response: T, key: string, fields: string[] | undefined): T {
  if (!fields || !response || typeof response !== "object") {
    return response;
  }
  const rows = (response as Record<string, unknown>)[key];
  if (!Array.isArray(rows)) {
    return response;
  }
  const wanted = new Set(fields);
  const pruned = rows.map(row => {
    if (!row || typeof row !== "object" || Array.isArray(row)) {
      return row;
    }
    return Object.fromEntries(Object.entries(row).filter(([name]) => wanted.has(name)));
  });
  return { ...response, [key]: pruned };
}

export function siteQuery(args: TimeArgs & { filters?: FilterArgs }) {
  return { ...toTimeQuery(args), ...toFiltersQuery(args.filters) };
}

// Output schemas document structure for MCP clients. The SDK validates
// structuredContent against them on every call, and REST response shapes are
// owned by the dashboard endpoints, so schemas pin only the top-level shape
// and stay tolerant below it: known fields are partial, objects passthrough,
// and wide/dynamic rows are records.
export const looseRow = z.record(z.unknown());
export const looseRows = z.array(looseRow);
export const successOutput = z.object({ success: z.boolean() }).partial().passthrough();