mixpanel

Instructions

Implementation Reference

• src/index.ts:1144-1230 (registration)

  Registration and complete implementation of the 'query_segmentation_report' tool, including schema validation with Zod and the async handler function that queries the Mixpanel segmentation API.

    "query_segmentation_report",
    "Get data for an event, segmented and filtered by properties. Useful for breaking down event data by user attributes, comparing performance across segments, and identifying which user groups perform specific actions.",
    {
      project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
      workspace_id: z.string().describe("The ID of the workspace if applicable").optional(),
      event: z.string().describe("The event that you wish to get data for. Note: this is a single event name, not an array"),
      from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"),
      to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"),
      on: z.string().describe("The property expression to segment the event on").optional(),
      unit: z.enum(["minute", "hour", "day", "month"]).describe("The buckets into which the property values that you segment on are placed. Default is 'day'").optional(),
      interval: z.number().describe("Optional parameter in lieu of 'unit' when 'type' is not 'general'. Determines the number of days your results are bucketed into").optional(),
      where: z.string().describe(`An expression to filter events by based on the grammar: <expression> ::= 'properties["' <property> '"]'
                  | <expression> <binary op> <expression>
                  | <unary op> <expression>
                  | <math op> '(' <expression> ')'
                  | <string literal>
     <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                    '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
                  | <unary op> ::= '-' | 'not'`),
      limit: z.number().describe("Return the top property values. Defaults to 60. Maximum value 10,000. This parameter does nothing if 'on' is not specified").optional(),
      type: z.enum(["general", "unique", "average"]).describe("The type of analysis to perform, either general, unique, or average, defaults to general").optional(),
      format: z.enum(["csv"]).describe("Can be set to 'csv'").optional(),
    },
    async ({ 
      project_id = DEFAULT_PROJECT_ID, 
      workspace_id, 
      event, 
      from_date, 
      to_date, 
      on, 
      unit, 
      interval, 
      where, 
      limit, 
      type, 
      format 
    }) => {
      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');
        
        // Construct base URL with required parameters
        let url = `https://mixpanel.com/api/query/segmentation?project_id=${project_id}&event=${encodeURIComponent(event)}&from_date=${from_date}&to_date=${to_date}`;
        
        // Add optional parameters if they exist
        if (workspace_id) url += `&workspace_id=${workspace_id}`;
        if (on) url += `&on=${encodeURIComponent(on)}`;
        if (unit) url += `&unit=${unit}`;
        if (interval !== undefined) url += `&interval=${interval}`;
        if (where) url += `&where=${encodeURIComponent(where)}`;
        if (limit !== undefined) url += `&limit=${limit}`;
        if (type) url += `&type=${type}`;
        if (format) url += `&format=${format}`;
        
        // 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(`API request failed with status ${response.status}: ${errorText}`);
        }
        
        const data = await response.json();
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(data)
            }
          ]
        };
      } catch (error) {
        console.error('Error querying segmentation report:', error);
        throw error;
      }
    }
  );

• src/index.ts:1167-1229 (handler)

  The async handler function that constructs the Mixpanel API request to /query/segmentation, handles authentication, parameters, fetches data, and returns JSON response.

  async ({ 
    project_id = DEFAULT_PROJECT_ID, 
    workspace_id, 
    event, 
    from_date, 
    to_date, 
    on, 
    unit, 
    interval, 
    where, 
    limit, 
    type, 
    format 
  }) => {
    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');
      
      // Construct base URL with required parameters
      let url = `https://mixpanel.com/api/query/segmentation?project_id=${project_id}&event=${encodeURIComponent(event)}&from_date=${from_date}&to_date=${to_date}`;
      
      // Add optional parameters if they exist
      if (workspace_id) url += `&workspace_id=${workspace_id}`;
      if (on) url += `&on=${encodeURIComponent(on)}`;
      if (unit) url += `&unit=${unit}`;
      if (interval !== undefined) url += `&interval=${interval}`;
      if (where) url += `&where=${encodeURIComponent(where)}`;
      if (limit !== undefined) url += `&limit=${limit}`;
      if (type) url += `&type=${type}`;
      if (format) url += `&format=${format}`;
      
      // 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(`API request failed with status ${response.status}: ${errorText}`);
      }
      
      const data = await response.json();
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(data)
          }
        ]
      };
    } catch (error) {
      console.error('Error querying segmentation report:', error);
      throw error;
    }
  }

• src/index.ts:1146-1166 (schema)

  Zod schema defining input parameters for the query_segmentation_report tool, including descriptions and types.

  {
    project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
    workspace_id: z.string().describe("The ID of the workspace if applicable").optional(),
    event: z.string().describe("The event that you wish to get data for. Note: this is a single event name, not an array"),
    from_date: z.string().describe("The date in yyyy-mm-dd format to begin querying from (inclusive)"),
    to_date: z.string().describe("The date in yyyy-mm-dd format to query to (inclusive)"),
    on: z.string().describe("The property expression to segment the event on").optional(),
    unit: z.enum(["minute", "hour", "day", "month"]).describe("The buckets into which the property values that you segment on are placed. Default is 'day'").optional(),
    interval: z.number().describe("Optional parameter in lieu of 'unit' when 'type' is not 'general'. Determines the number of days your results are bucketed into").optional(),
    where: z.string().describe(`An expression to filter events by based on the grammar: <expression> ::= 'properties["' <property> '"]'
                | <expression> <binary op> <expression>
                | <unary op> <expression>
                | <math op> '(' <expression> ')'
                | <string literal>
   <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                  '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
                | <unary op> ::= '-' | 'not'`),
    limit: z.number().describe("Return the top property values. Defaults to 60. Maximum value 10,000. This parameter does nothing if 'on' is not specified").optional(),
    type: z.enum(["general", "unique", "average"]).describe("The type of analysis to perform, either general, unique, or average, defaults to general").optional(),
    format: z.enum(["csv"]).describe("Can be set to 'csv'").optional(),
  },