query_retention_report
Analyze user retention patterns to understand how well users are retained over time and identify cohort behavior in Mixpanel data.
Instructions
Analyze user retention patterns. Useful for understanding how well you retain users over time and identifying cohort behavior.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | The Mixpanel project ID. Optional since it has a default. | |
| from_date | Yes | The date in yyyy-mm-dd format to begin querying from (inclusive) | |
| to_date | Yes | The date in yyyy-mm-dd format to query to (inclusive) | |
| born_event | Yes | The event that defines when users are 'born' for retention analysis | |
| event | No | The event to measure retention for (optional, defaults to any event) | |
| born_where | No | JSON string representing additional filters for the born event | |
| where | No | JSON string representing additional filters for the retention event | |
| interval | No | The time interval for retention analysis, defaults to day | |
| interval_count | No | Number of intervals to analyze, defaults to 30 |
Implementation Reference
- src/index.ts:977-1044 (handler)The handler function that implements the core logic for the 'query_retention_report' tool. It constructs a Mixpanel API URL for retention analysis, authenticates with service account credentials, fetches the report data, and returns it as JSON or an error message.async function handleQueryRetentionReport(args: any, config: any) { const { project_id = config.DEFAULT_PROJECT_ID, from_date, to_date, born_event, event, born_where, where, interval = "day", interval_count = 30 } = args; try { const credentials = `${config.SERVICE_ACCOUNT_USER_NAME}:${config.SERVICE_ACCOUNT_PASSWORD}`; const encodedCredentials = Buffer.from(credentials).toString('base64'); let url = `${config.MIXPANEL_BASE_URL}/retention?project_id=${project_id}&from_date=${from_date}&to_date=${to_date}&born_event=${encodeURIComponent(born_event)}&interval=${interval}&interval_count=${interval_count}`; if (event) { url += `&event=${encodeURIComponent(event)}`; } if (born_where) { url += `&born_where=${encodeURIComponent(born_where)}`; } if (where) { url += `&where=${encodeURIComponent(where)}`; } const options = { method: 'GET', headers: { 'accept': 'application/json', 'authorization': `Basic ${encodedCredentials}` } }; 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 querying retention report:", error); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error querying retention report: ${errorMessage}` } ], isError: true }; } }
- src/index.ts:406-447 (schema)Input schema defining parameters, types, descriptions, and required fields for the query_retention_report tool.inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, born_event: { type: "string", description: "The event that defines when users are 'born' for retention analysis" }, event: { type: "string", description: "The event to measure retention for (optional, defaults to any event)" }, born_where: { type: "string", description: "JSON string representing additional filters for the born event" }, where: { type: "string", description: "JSON string representing additional filters for the retention event" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for retention analysis, defaults to day" }, interval_count: { type: "number", description: "Number of intervals to analyze, defaults to 30" } }, required: ["from_date", "to_date", "born_event"]
- src/index.ts:403-449 (registration)Tool registration in the MCP tools list, including name, description, and input schema.{ name: "query_retention_report", description: "Analyze user retention patterns. Useful for understanding how well you retain users over time and identifying cohort behavior.", inputSchema: { type: "object", properties: { project_id: { type: "string", description: "The Mixpanel project ID. Optional since it has a default." }, from_date: { type: "string", description: "The date in yyyy-mm-dd format to begin querying from (inclusive)" }, to_date: { type: "string", description: "The date in yyyy-mm-dd format to query to (inclusive)" }, born_event: { type: "string", description: "The event that defines when users are 'born' for retention analysis" }, event: { type: "string", description: "The event to measure retention for (optional, defaults to any event)" }, born_where: { type: "string", description: "JSON string representing additional filters for the born event" }, where: { type: "string", description: "JSON string representing additional filters for the retention event" }, interval: { type: "string", enum: ["day", "week", "month"], description: "The time interval for retention analysis, defaults to day" }, interval_count: { type: "number", description: "Number of intervals to analyze, defaults to 30" } }, required: ["from_date", "to_date", "born_event"] } },
- src/index.ts:626-628 (registration)Dispatcher case in the main CallToolRequestHandler switch statement that routes calls to the specific handler function.case "query_retention_report": return await handleQueryRetentionReport(args, { SERVICE_ACCOUNT_USER_NAME, SERVICE_ACCOUNT_PASSWORD, DEFAULT_PROJECT_ID, MIXPANEL_BASE_URL });