mixpanel

Instructions

Implementation Reference

• src/index.ts:1405-1470 (registration)

  Registration of the 'top_event_properties' MCP tool using server.tool(), including description, input schema, and handler function.

    "top_event_properties",
    "Get the top property names for an event. Useful for discovering which properties are most commonly associated with an event, prioritizing which dimensions to analyze, and understanding event structure.",
    {
      project_id: z.string().describe("The Mixpanel project ID").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"),
      limit: z.number().describe("The maximum number of properties to return. Defaults to 10").optional(),
    },
    async ({ 
      project_id = DEFAULT_PROJECT_ID, 
      workspace_id, 
      event, 
      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');
        
        // Construct base URL with required parameters
        let url = `https://mixpanel.com/api/query/events/properties/top?project_id=${project_id}&event=${encodeURIComponent(event)}`;
        
        // Add optional parameters if they exist
        if (workspace_id) url += `&workspace_id=${workspace_id}`;
        if (limit !== undefined) url += `&limit=${limit}`;
        
        // 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 fetching top event properties:', error);
        return {
          content: [
            {
              type: "text",
              text: `Error fetching top event properties: ${error}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:1413-1469 (handler)

  The core handler function for the top_event_properties tool. It authenticates with Mixpanel using service account credentials, constructs the API URL for /query/events/properties/top, fetches the data, and returns the JSON response or error.

  async ({ 
    project_id = DEFAULT_PROJECT_ID, 
    workspace_id, 
    event, 
    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');
      
      // Construct base URL with required parameters
      let url = `https://mixpanel.com/api/query/events/properties/top?project_id=${project_id}&event=${encodeURIComponent(event)}`;
      
      // Add optional parameters if they exist
      if (workspace_id) url += `&workspace_id=${workspace_id}`;
      if (limit !== undefined) url += `&limit=${limit}`;
      
      // 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 fetching top event properties:', error);
      return {
        content: [
          {
            type: "text",
            text: `Error fetching top event properties: ${error}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:1407-1412 (schema)

  Zod input schema validation for the top_event_properties tool parameters.

  {
    project_id: z.string().describe("The Mixpanel project ID").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"),
    limit: z.number().describe("The maximum number of properties to return. Defaults to 10").optional(),
  },

• .api/apis/mixpaneldevdocs/schemas.d.ts:705-750 (schema)

  JSON Schema for the underlying Mixpanel API endpoint /query/events/properties/top, which defines the request parameters and response format used by the tool handler.

  declare const QueryEventsTopProperties: {
      readonly metadata: {
          readonly allOf: readonly [{
              readonly type: "object";
              readonly properties: {
                  readonly project_id: {
                      readonly type: "integer";
                      readonly $schema: "http://json-schema.org/draft-04/schema#";
                      readonly description: "Required if using service account to authenticate request.";
                  };
                  readonly workspace_id: {
                      readonly type: "integer";
                      readonly $schema: "http://json-schema.org/draft-04/schema#";
                      readonly description: "The id of the workspace if applicable.";
                  };
                  readonly event: {
                      readonly type: "string";
                      readonly $schema: "http://json-schema.org/draft-04/schema#";
                      readonly description: "The event that you wish to get data for. Note: this is a single event name, not an array.";
                  };
                  readonly limit: {
                      readonly type: "integer";
                      readonly $schema: "http://json-schema.org/draft-04/schema#";
                      readonly description: "The maximum number of properties to return. Defaults to 10.";
                  };
              };
              readonly required: readonly ["project_id", "event"];
          }];
      };
      readonly response: {
          readonly "200": {
              readonly type: "object";
              readonly description: "The keys are the name of the properties";
              readonly additionalProperties: {
                  readonly type: "object";
                  readonly properties: {
                      readonly count: {
                          readonly type: "integer";
                          readonly description: "The number of events with that property";
                      };
                  };
              };
              readonly $schema: "http://json-schema.org/draft-04/schema#";
          };
      };
  };

• .api/apis/mixpaneldevdocs/index.js:216-219 (helper)

  Generated SDK helper method queryEventsTopProperties that wraps the Mixpanel API call to /events/properties/top, though not directly used in the MCP implementation.

   * @summary Top Event Properties
   */
  queryEventsTopProperties(metadata) {
      return this.core.fetch('/events/properties/top', 'get', metadata);