aggregated_event_property_values

Instructions

Implementation Reference

• src/index.ts:305-307 (registration)

  Registers the MCP tool named 'aggregated_event_property_values' with name, description, input schema, and handler function.

  server.tool(
    "aggregated_event_property_values",
    "Get unique, general, or average data for a single event and property over days, weeks, or months. Useful for analyzing how specific properties affect event performance, segmenting users, and identifying valuable user attributes.",

• src/index.ts:308-319 (schema)

  Zod input schema defining parameters for the aggregated_event_property_values tool.

  {
    project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
    event: z.string().describe("The event that you wish to get data for (a single event name, not an array)"),
    name: z.string().describe("The name of the property you would like to get data for"),
    values: z.string().optional().describe("The specific property values to get data for, encoded as a JSON array. Example: \"[\"female\", \"unknown\"]\""),
    type: z.enum(["general", "unique", "average"]).describe("The analysis type - general, unique, or average events, defaults to general").optional(),
    unit: z.enum(["minute", "hour", "day", "week", "month"]).describe("The level of granularity of the data (minute, hour, day, week, or month)"),
    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)"),
    limit: z.number().optional().describe("The maximum number of values to return (default: 255)"),
  },

• src/index.ts:320-414 (handler)

  The handler function that implements the tool logic: validates parameters, parses JSON values if provided, builds query params for Mixpanel's /api/query/events/properties endpoint, makes authenticated GET request, returns JSON data or error response.

  async ({ project_id = DEFAULT_PROJECT_ID, event, name, values, type = "general", unit, interval, from_date, to_date, limit }) => {
    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 values if provided
      let parsedValues;
      if (values) {
        try {
          parsedValues = JSON.parse(values);
          if (!Array.isArray(parsedValues)) {
            throw new Error("Values must be a JSON array");
          }
        } catch (e) {
          throw new Error(`Invalid values format: ${e instanceof Error ? e.message : String(e)}`);
        }
      }
      
      // Build query parameters
      const queryParams = new URLSearchParams({
        project_id: project_id || '',
        event: event,
        name: name,
        type: type,
        unit: unit
      });
      
      // Add values if provided
      if (values) {
        queryParams.append('values', values);
      }
      
      // 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 limit if provided
      if (limit) {
        queryParams.append('limit', limit.toString());
      }
      
      // Construct URL with query parameters
      const url = `https://mixpanel.com/api/query/events/properties?${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 property values:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error fetching Mixpanel event property values: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }