aggregate_event_counts

Instructions

Implementation Reference

• src/index.ts:219-302 (handler)

  The handler function that implements the tool logic: authenticates with Mixpanel using service account credentials, validates and parses input parameters (especially the JSON array of events), constructs query parameters for the /api/query/events endpoint, performs a GET request, parses the JSON response, and returns formatted content or error.

  async ({ project_id = DEFAULT_PROJECT_ID, event, type = "general", unit, interval, from_date, to_date }) => {
    try {
      // Create authorization header using base64 encoding of credentials
      const credentials = `${SERVICE_ACCOUNT_USER_NAME}:${SERVICE_ACCOUNT_PASSWORD}`;
      const encodedCredentials = Buffer.from(credentials).toString('base64');
      
      // Validate parameters
      if (!interval && (!from_date || !to_date)) {
        throw new Error("You must specify either interval or both from_date and to_date");
      }
      
      // Parse events to ensure it's a valid JSON array
      let parsedEvents;
      try {
        parsedEvents = JSON.parse(event);
        if (!Array.isArray(parsedEvents)) {
          throw new Error("Events must be a JSON array");
        }
      } catch (e: any) {
        throw new Error(`Invalid events format: ${e.message}`);
      }
      
      // Build query parameters
      const queryParams = new URLSearchParams({
        project_id: project_id || '',
        type: type,
        unit: unit
      });
      
      // Add either interval or date range
      if (interval) {
        queryParams.append('interval', interval.toString());
      } else {
        queryParams.append('from_date', from_date || '');
        queryParams.append('to_date', to_date || '');
      }
      
      // Add events parameter
      queryParams.append('event', event);
      
      // Construct URL with query parameters
      const url = `https://mixpanel.com/api/query/events?${queryParams.toString()}`;
      
      // Set up request options
      const options = {
        method: 'GET',
        headers: {
          'accept': 'application/json',
          'authorization': `Basic ${encodedCredentials}`
        }
      };
      
      // Make the API request
      const response = await fetch(url, options);
      
      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`HTTP error! status: ${response.status} - ${errorText}`);
      }
      
      const data = await response.json();
      
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(data)
          }
        ]
      };
    } catch (error: unknown) {
      console.error("Error fetching Mixpanel event counts:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error fetching Mixpanel event counts: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:210-218 (schema)

  Zod schema defining the input parameters for the tool, including project_id (optional), event (JSON string array), type, unit, interval/from_date/to_date options.

  {
    project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
    event: z.string().describe("The event or events that you wish to get data for, a string encoded as a JSON array. Example format: \"[\"play song\", \"log in\", \"add playlist\"]\""),
    type: z.enum(["general", "unique", "average"]).describe("The type of data to fetch, either general, unique, or average, defaults to general").optional(),
    unit: z.enum(["minute", "hour", "day", "week", "month"]).describe("The level of granularity of the data you get back"),
    interval: z.number().optional().describe("The number of units to return data for. Specify either interval or from_date and to_date"),
    from_date: z.string().optional().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"),
    to_date: z.string().optional().describe("The date in yyyy-mm-dd format to query to (inclusive)"),
  },

• src/index.ts:207-303 (registration)

  The server.tool() call that registers the 'aggregate_event_counts' tool with its description, input schema, and handler function on the MCP server.

  server.tool(
    "aggregate_event_counts",
    "Get unique, general, or average data for a set of events over N days, weeks, or months. Useful for trend analysis, comparing event performance over time, and creating time-series visualizations.",
    {
      project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
      event: z.string().describe("The event or events that you wish to get data for, a string encoded as a JSON array. Example format: \"[\"play song\", \"log in\", \"add playlist\"]\""),
      type: z.enum(["general", "unique", "average"]).describe("The type of data to fetch, either general, unique, or average, defaults to general").optional(),
      unit: z.enum(["minute", "hour", "day", "week", "month"]).describe("The level of granularity of the data you get back"),
      interval: z.number().optional().describe("The number of units to return data for. Specify either interval or from_date and to_date"),
      from_date: z.string().optional().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"),
      to_date: z.string().optional().describe("The date in yyyy-mm-dd format to query to (inclusive)"),
    },
    async ({ project_id = DEFAULT_PROJECT_ID, event, type = "general", unit, interval, from_date, to_date }) => {
      try {
        // Create authorization header using base64 encoding of credentials
        const credentials = `${SERVICE_ACCOUNT_USER_NAME}:${SERVICE_ACCOUNT_PASSWORD}`;
        const encodedCredentials = Buffer.from(credentials).toString('base64');
        
        // Validate parameters
        if (!interval && (!from_date || !to_date)) {
          throw new Error("You must specify either interval or both from_date and to_date");
        }
        
        // Parse events to ensure it's a valid JSON array
        let parsedEvents;
        try {
          parsedEvents = JSON.parse(event);
          if (!Array.isArray(parsedEvents)) {
            throw new Error("Events must be a JSON array");
          }
        } catch (e: any) {
          throw new Error(`Invalid events format: ${e.message}`);
        }
        
        // Build query parameters
        const queryParams = new URLSearchParams({
          project_id: project_id || '',
          type: type,
          unit: unit
        });
        
        // Add either interval or date range
        if (interval) {
          queryParams.append('interval', interval.toString());
        } else {
          queryParams.append('from_date', from_date || '');
          queryParams.append('to_date', to_date || '');
        }
        
        // Add events parameter
        queryParams.append('event', event);
        
        // Construct URL with query parameters
        const url = `https://mixpanel.com/api/query/events?${queryParams.toString()}`;
        
        // Set up request options
        const options = {
          method: 'GET',
          headers: {
            'accept': 'application/json',
            'authorization': `Basic ${encodedCredentials}`
          }
        };
        
        // Make the API request
        const response = await fetch(url, options);
        
        if (!response.ok) {
          const errorText = await response.text();
          throw new Error(`HTTP error! status: ${response.status} - ${errorText}`);
        }
        
        const data = await response.json();
        
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(data)
            }
          ]
        };
      } catch (error: unknown) {
        console.error("Error fetching Mixpanel event counts:", error);
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text",
              text: `Error fetching Mixpanel event counts: ${errorMessage}`
            }
          ],
          isError: true
        };
      }
    }
  )