custom_jql

Instructions

Implementation Reference

• src/index.ts:782-852 (registration)

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

  server.tool(
    "custom_jql",
    "Run a custom JQL (JSON Query Language) script against your Mixpanel data. Useful for complex custom analyses, advanced data transformations, and queries that can't be handled by standard report types.",
    {
      project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
      workspace_id: z.string().optional().describe("The ID of the workspace if applicable"),
      script: z.string().describe("The JQL script to run (JavaScript code that uses Mixpanel's JQL functions)"),
      params: z.string().optional().describe("A JSON string containing parameters to pass to the script (will be available as the 'params' variable)")
    },
    async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, script, params }) => {
      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 URL with query parameters
        const queryParams = new URLSearchParams();
        queryParams.append('project_id', project_id);
        if (workspace_id) queryParams.append('workspace_id', workspace_id);
        
        const url = `https://mixpanel.com/api/query/jql?${queryParams.toString()}`;
        
        // Prepare form data for POST request
        const formData = new URLSearchParams();
        formData.append('script', script);
        if (params) formData.append('params', params);
        
        // 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(`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 executing JQL query:", error);
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          content: [
            {
              type: "text",
              text: `Error executing JQL query: ${errorMessage}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/index.ts:791-851 (handler)

  The handler function for custom_jql tool. It authenticates with Mixpanel using service account credentials, constructs a POST request to the JQL endpoint with the provided script and params, fetches the data, and returns the JSON response or an error.

  async ({ project_id = DEFAULT_PROJECT_ID, workspace_id, script, params }) => {
    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 URL with query parameters
      const queryParams = new URLSearchParams();
      queryParams.append('project_id', project_id);
      if (workspace_id) queryParams.append('workspace_id', workspace_id);
      
      const url = `https://mixpanel.com/api/query/jql?${queryParams.toString()}`;
      
      // Prepare form data for POST request
      const formData = new URLSearchParams();
      formData.append('script', script);
      if (params) formData.append('params', params);
      
      // 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(`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 executing JQL query:", error);
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [
          {
            type: "text",
            text: `Error executing JQL query: ${errorMessage}`
          }
        ],
        isError: true
      };
    }
  }

• src/index.ts:786-789 (schema)

  Zod schema defining the input parameters for the custom_jql tool: project_id (optional), workspace_id (optional), script (required), params (optional).

  project_id: z.string().describe("The Mixpanel project ID. Optional since it has a default.").optional(),
  workspace_id: z.string().optional().describe("The ID of the workspace if applicable"),
  script: z.string().describe("The JQL script to run (JavaScript code that uses Mixpanel's JQL functions)"),
  params: z.string().optional().describe("A JSON string containing parameters to pass to the script (will be available as the 'params' variable)")