mixpanel

Instructions

Implementation Reference

• src/index.ts:935-1051 (registration)

  Registration of the 'query_profiles' tool using server.tool(), including name, description, input schema, and handler function reference.

    "query_profiles",
    "Query Mixpanel user profiles with filtering options. Useful for retrieving detailed user profiles, filtering by specific properties, and analyzing user behavior across different dimensions.",
    {
      project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.. Optional since it has a default.").optional(),
      workspace_id: z.string().describe("The ID of the workspace if applicable").optional(),
      distinct_id: z.string().describe("A unique identifier used to distinguish an individual profile").optional(),
      distinct_ids: z.string().describe("A JSON array of distinct_ids to retrieve profiles for. Example: '[\"id1\", \"id2\"]'").optional(),
      data_group_id: z.string().describe("The ID of the group key, used when querying group profiles").optional(),
      where: z.string().describe(`An expression to filter users (or groups) by. Using the following grammar: <expression> ::= 'properties["' <property> '"]'
                  | <expression> <binary op> <expression>
                  | <unary op> <expression>
                  | <math op> '(' <expression> ')'
                  | <typecast op> '(' <expression> ')'
                  | '(' <expression> ')'
                  | <boolean literal>
                  | <numeric literal>
                  | <string literal>
    <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                    '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
     <unary op> ::= '-' | 'not'
      <math op> ::= 'floor' | 'round' | 'ceil'
  <typecast op> ::= 'boolean' | 'number' | 'string'
     <property> ::= 'properties["' <property name> '"]'`).optional(),
      output_properties: z.string().describe("A JSON array of names of properties you want returned. Example: '[\"$last_name\", \"$email\", \"Total Spent\"]'").optional(),
      session_id: z.string().describe("A string id provided in the results of a previous query. Using a session_id speeds up api response, and allows paging through results").optional(),
      page: z.number().describe("Which page of the results to retrieve. Pages start at zero. If the 'page' parameter is provided, the session_id parameter must also be provided").optional(),
      behaviors: z.number().describe("If you are exporting user profiles using an event selector, you use a 'behaviors' parameter in your request").optional(),
      as_of_timestamp: z.number().describe("This parameter is only useful when also using 'behaviors'").optional(),
      filter_by_cohort: z.string().describe("Takes a JSON object with a single key called 'id' whose value is the cohort ID. Example: '{\"id\":12345}'").optional(),
      include_all_users: z.boolean().describe("Only applicable with 'filter_by_cohort' parameter. Default is true").optional(),
    },
    async ({ 
      project_id = DEFAULT_PROJECT_ID, 
      workspace_id, 
      distinct_id, 
      distinct_ids, 
      data_group_id, 
      where, 
      output_properties, 
      session_id, 
      page, 
      behaviors, 
      as_of_timestamp, 
      filter_by_cohort, 
      include_all_users 
    }) => {
      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 project_id
        let url = `https://mixpanel.com/api/query/engage?project_id=${project_id}`;
        
        // Add optional workspace_id if provided
        if (workspace_id) {
          url += `&workspace_id=${workspace_id}`;
        }
        
        // Create form data for POST request
        const formData = new URLSearchParams();
        
        // Add optional parameters to form data if they exist
        if (distinct_id) formData.append('distinct_id', distinct_id);
        if (distinct_ids) formData.append('distinct_ids', distinct_ids);
        if (data_group_id) formData.append('data_group_id', data_group_id);
        if (where) formData.append('where', where);
        if (output_properties) formData.append('output_properties', output_properties);
        if (session_id) formData.append('session_id', session_id);
        if (page !== undefined) formData.append('page', page.toString());
        if (behaviors !== undefined) formData.append('behaviors', behaviors.toString());
        if (as_of_timestamp !== undefined) formData.append('as_of_timestamp', as_of_timestamp.toString());
        if (filter_by_cohort) formData.append('filter_by_cohort', filter_by_cohort);
        if (include_all_users !== undefined) formData.append('include_all_users', include_all_users.toString());
        
        // Set up request options
        const options = {
          method: 'POST',
          headers: {
            'accept': 'application/json',
            'authorization': `Basic ${encodedCredentials}`,
            'content-type': 'application/x-www-form-urlencoded'
          },
          body: formData
        };
        
        // 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 profiles:', error);
        return {
          content: [
            {
              type: "text",
              text: `Error querying profiles: ${error}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:937-965 (schema)

  Zod input schema for the 'query_profiles' tool, defining parameters like project_id, distinct_ids, where filter expression, output_properties, pagination (session_id, page), and cohort filtering.

    {
      project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.. Optional since it has a default.").optional(),
      workspace_id: z.string().describe("The ID of the workspace if applicable").optional(),
      distinct_id: z.string().describe("A unique identifier used to distinguish an individual profile").optional(),
      distinct_ids: z.string().describe("A JSON array of distinct_ids to retrieve profiles for. Example: '[\"id1\", \"id2\"]'").optional(),
      data_group_id: z.string().describe("The ID of the group key, used when querying group profiles").optional(),
      where: z.string().describe(`An expression to filter users (or groups) by. Using the following grammar: <expression> ::= 'properties["' <property> '"]'
                  | <expression> <binary op> <expression>
                  | <unary op> <expression>
                  | <math op> '(' <expression> ')'
                  | <typecast op> '(' <expression> ')'
                  | '(' <expression> ')'
                  | <boolean literal>
                  | <numeric literal>
                  | <string literal>
    <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                    '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
     <unary op> ::= '-' | 'not'
      <math op> ::= 'floor' | 'round' | 'ceil'
  <typecast op> ::= 'boolean' | 'number' | 'string'
     <property> ::= 'properties["' <property name> '"]'`).optional(),
      output_properties: z.string().describe("A JSON array of names of properties you want returned. Example: '[\"$last_name\", \"$email\", \"Total Spent\"]'").optional(),
      session_id: z.string().describe("A string id provided in the results of a previous query. Using a session_id speeds up api response, and allows paging through results").optional(),
      page: z.number().describe("Which page of the results to retrieve. Pages start at zero. If the 'page' parameter is provided, the session_id parameter must also be provided").optional(),
      behaviors: z.number().describe("If you are exporting user profiles using an event selector, you use a 'behaviors' parameter in your request").optional(),
      as_of_timestamp: z.number().describe("This parameter is only useful when also using 'behaviors'").optional(),
      filter_by_cohort: z.string().describe("Takes a JSON object with a single key called 'id' whose value is the cohort ID. Example: '{\"id\":12345}'").optional(),
      include_all_users: z.boolean().describe("Only applicable with 'filter_by_cohort' parameter. Default is true").optional(),
    },

• src/index.ts:966-1050 (handler)

  The handler function implements the tool logic: authenticates with Mixpanel service account, builds POST request to /api/query/engage with form-encoded parameters, fetches user profiles data, and returns JSON response or error message.

  async ({ 
    project_id = DEFAULT_PROJECT_ID, 
    workspace_id, 
    distinct_id, 
    distinct_ids, 
    data_group_id, 
    where, 
    output_properties, 
    session_id, 
    page, 
    behaviors, 
    as_of_timestamp, 
    filter_by_cohort, 
    include_all_users 
  }) => {
    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 project_id
      let url = `https://mixpanel.com/api/query/engage?project_id=${project_id}`;
      
      // Add optional workspace_id if provided
      if (workspace_id) {
        url += `&workspace_id=${workspace_id}`;
      }
      
      // Create form data for POST request
      const formData = new URLSearchParams();
      
      // Add optional parameters to form data if they exist
      if (distinct_id) formData.append('distinct_id', distinct_id);
      if (distinct_ids) formData.append('distinct_ids', distinct_ids);
      if (data_group_id) formData.append('data_group_id', data_group_id);
      if (where) formData.append('where', where);
      if (output_properties) formData.append('output_properties', output_properties);
      if (session_id) formData.append('session_id', session_id);
      if (page !== undefined) formData.append('page', page.toString());
      if (behaviors !== undefined) formData.append('behaviors', behaviors.toString());
      if (as_of_timestamp !== undefined) formData.append('as_of_timestamp', as_of_timestamp.toString());
      if (filter_by_cohort) formData.append('filter_by_cohort', filter_by_cohort);
      if (include_all_users !== undefined) formData.append('include_all_users', include_all_users.toString());
      
      // Set up request options
      const options = {
        method: 'POST',
        headers: {
          'accept': 'application/json',
          'authorization': `Basic ${encodedCredentials}`,
          'content-type': 'application/x-www-form-urlencoded'
        },
        body: formData
      };
      
      // 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 profiles:', error);
      return {
        content: [
          {
            type: "text",
            text: `Error querying profiles: ${error}`
          }
        ],
        isError: true
      };
    }
  }