list_reports

Instructions

Implementation Reference

• src/tools/reports.ts:6-22 (handler)

  The handler for the 'list_reports' tool. It registers a tool on the MCP server that lists all saved reports by calling GET /api/reports with optional page, pageSize, and orderBy query parameters.

  server.tool(
    "list_reports",
    "List all saved reports",
    {
      page: z.number().optional().describe("Page number (1-based)"),
      pageSize: z.number().optional().describe("Results per page"),
      orderBy: z.string().optional().describe("Field to order by"),
    },
    async ({ page, pageSize, orderBy }) => {
      const data = await client.call("GET", "/api/reports", undefined, {
        page,
        pageSize,
        orderBy,
      });
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/tools/reports.ts:6-22 (schema)

  The input schema for 'list_reports' defines optional parameters: page (number), pageSize (number), and orderBy (string), all validated with Zod.

  server.tool(
    "list_reports",
    "List all saved reports",
    {
      page: z.number().optional().describe("Page number (1-based)"),
      pageSize: z.number().optional().describe("Results per page"),
      orderBy: z.string().optional().describe("Field to order by"),
    },
    async ({ page, pageSize, orderBy }) => {
      const data = await client.call("GET", "/api/reports", undefined, {
        page,
        pageSize,
        orderBy,
      });
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/tools/reports.ts:5-119 (registration)

  The tool is registered via server.tool('list_reports', ...) inside the registerReportTools function, which is called from src/index.ts (line 33).

  export function registerReportTools(server: McpServer, client: UmamiClient) {
    server.tool(
      "list_reports",
      "List all saved reports",
      {
        page: z.number().optional().describe("Page number (1-based)"),
        pageSize: z.number().optional().describe("Results per page"),
        orderBy: z.string().optional().describe("Field to order by"),
      },
      async ({ page, pageSize, orderBy }) => {
        const data = await client.call("GET", "/api/reports", undefined, {
          page,
          pageSize,
          orderBy,
        });
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      }
    );
  
    server.tool(
      "get_report",
      "Get details of a specific saved report",
      {
        reportId: z.string().describe("Report UUID"),
      },
      async ({ reportId }) => {
        const data = await client.call("GET", `/api/reports/${reportId}`);
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      }
    );
  
    server.tool(
      "create_report",
      "Create and save a new report",
      {
        websiteId: z.string().describe("Website UUID"),
        name: z.string().describe("Report name"),
        type: z
          .enum(["funnel", "retention", "utm", "goals", "insights", "revenue", "journey", "attribution"])
          .describe("Report type"),
        description: z.string().optional().describe("Report description"),
        parameters: z
          .record(z.unknown())
          .optional()
          .describe("Report-specific parameters (JSON object)"),
      },
      async ({ websiteId, name, type, description, parameters }) => {
        const body: Record<string, unknown> = { websiteId, name, type };
        if (description) body.description = description;
        if (parameters) body.parameters = parameters;
        const data = await client.call("POST", "/api/reports", body);
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      }
    );
  
    server.tool(
      "update_report",
      "Update an existing saved report",
      {
        reportId: z.string().describe("Report UUID"),
        websiteId: z.string().optional().describe("Website UUID"),
        name: z.string().optional().describe("Report name"),
        type: z
          .enum(["funnel", "retention", "utm", "goals", "insights", "revenue", "journey", "attribution"])
          .optional()
          .describe("Report type"),
        description: z.string().optional().describe("Report description"),
        parameters: z
          .record(z.unknown())
          .optional()
          .describe("Report-specific parameters (JSON object)"),
      },
      async ({ reportId, websiteId, name, type, description, parameters }) => {
        const body: Record<string, unknown> = {};
        if (websiteId !== undefined) body.websiteId = websiteId;
        if (name !== undefined) body.name = name;
        if (type !== undefined) body.type = type;
        if (description !== undefined) body.description = description;
        if (parameters !== undefined) body.parameters = parameters;
        const data = await client.call("POST", `/api/reports/${reportId}`, body);
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      }
    );
  
    server.tool(
      "delete_report",
      "Delete a saved report",
      {
        reportId: z.string().describe("Report UUID to delete"),
      },
      async ({ reportId }) => {
        await client.call("DELETE", `/api/reports/${reportId}`);
        return { content: [{ type: "text", text: `Report ${reportId} deleted successfully.` }] };
      }
    );
  
    server.tool(
      "run_report",
      "Execute a report by type and get results (funnel, retention, utm, goals, insights, revenue, journey, attribution)",
      {
        type: z
          .enum(["funnel", "retention", "utm", "goals", "insights", "revenue", "journey", "attribution"])
          .describe("Report type to run"),
        websiteId: z.string().describe("Website UUID"),
        parameters: z
          .record(z.unknown())
          .describe("Report-specific parameters (varies by type)"),
      },
      async ({ type, websiteId, parameters }) => {
        const body: Record<string, unknown> = { websiteId, ...parameters };
        const data = await client.call("POST", `/api/reports/${type}`, body);
        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
      }
    );
  }

• src/tools/reports.ts:1-3 (helper)

  Imports used by the handler: McpServer from the MCP SDK, z from Zod for schema validation, and UmamiClient for API calls.

  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  import { z } from "zod";
  import { UmamiClient } from "../client.js";

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

  The registration call site: registerReportTools(server, client) is invoked in the main server setup, which registers the 'list_reports' tool.

  registerReportTools(server, client);