mixpanel

Instructions

Implementation Reference

• src/index.ts:1339-1401 (handler)

  The asynchronous handler function that executes the core logic of the 'query_segmentation_average' tool. It constructs a URL for Mixpanel's /api/query/segmentation/average endpoint, authenticates with Basic Auth using service account credentials, fetches the data, and returns it as JSON or an error message.

  async ({ 
    project_id = DEFAULT_PROJECT_ID, 
    workspace_id, 
    event, 
    from_date, 
    to_date, 
    on, 
    unit, 
    where 
  }) => {
    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/average?project_id=${project_id}&event=${encodeURIComponent(event)}&from_date=${from_date}&to_date=${to_date}&on=${encodeURIComponent(on)}`;
      
      // Add optional parameters if they exist
      if (workspace_id) url += `&workspace_id=${workspace_id}`;
      if (unit) url += `&unit=${unit}`;
      if (where) url += `&where=${encodeURIComponent(where)}`;
      
      // 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)
          }
        ],
        isError: true
      };
    } catch (error) {
      console.error('Error querying segmentation average:', error);
      return {
        content: [
          {
            type: "text",
            text: `Error querying segmentation average: ${error}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:1322-1338 (schema)

  Zod schema defining the input parameters for the 'query_segmentation_average' tool, including project_id, event, dates, the expression to average ('on'), unit, and optional where filter.

  {
    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 expression to average per unit time. The result of the expression should be a numeric value"),
    unit: z.enum(["hour", "day"]).describe("The buckets [hour, day] into which the property values are placed. Default is 'day'").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'`).optional(),
  },

• src/index.ts:1319-1402 (registration)

  The server.tool() registration call that registers the 'query_segmentation_average' tool with the MCP server, providing name, description, input schema, and handler function.

  server.tool(
    "query_segmentation_average",
    "Averages an expression for events per unit time. Useful for calculating average values like purchase amounts, session durations, or any numeric metric, and tracking how these averages change over time.",
    {
      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 expression to average per unit time. The result of the expression should be a numeric value"),
      unit: z.enum(["hour", "day"]).describe("The buckets [hour, day] into which the property values are placed. Default is 'day'").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'`).optional(),
    },
    async ({ 
      project_id = DEFAULT_PROJECT_ID, 
      workspace_id, 
      event, 
      from_date, 
      to_date, 
      on, 
      unit, 
      where 
    }) => {
      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/average?project_id=${project_id}&event=${encodeURIComponent(event)}&from_date=${from_date}&to_date=${to_date}&on=${encodeURIComponent(on)}`;
        
        // Add optional parameters if they exist
        if (workspace_id) url += `&workspace_id=${workspace_id}`;
        if (unit) url += `&unit=${unit}`;
        if (where) url += `&where=${encodeURIComponent(where)}`;
        
        // 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)
            }
          ],
          isError: true
        };
      } catch (error) {
        console.error('Error querying segmentation average:', error);
        return {
          content: [
            {
              type: "text",
              text: `Error querying segmentation average: ${error}`
            }
          ],
          isError: true
        };
      }
    }
  );