Adjust MCP

Instructions

Implementation Reference

• src/mcp-adjust.ts:162-268 (handler)

  The main handler function for the 'adjust-standard-report' tool. It selects predefined metrics and dimensions based on the report_type parameter, constructs the query for the Adjust API, fetches the report data using AdjustApiClient.fetchReports, generates a markdown report using analyzeReportData, and handles errors.
  }, async (params, extra) => { try { // Set up metrics and dimensions based on report type let metrics: string[] = []; let dimensions: string[] = []; switch (params.report_type) { case "performance": metrics = ["installs", "clicks", "impressions", "network_cost", "network_ecpi", "sessions"]; dimensions = ["app", "partner_name", "campaign", "day"]; break; case "retention": metrics = ["installs", "retention_rate_d1", "retention_rate_d7", "retention_rate_d30"]; dimensions = ["app", "partner_name", "campaign", "day"]; break; case "cohort": metrics = ["installs", "sessions_per_user", "revenue_per_user"]; dimensions = ["app", "partner_name", "campaign", "cohort"]; break; case "revenue": metrics = ["installs", "revenue", "arpu", "arpdau"]; dimensions = ["app", "partner_name", "campaign", "day"]; break; } // Build query parameters const queryParams: Record<string, any> = { date_period: params.date_range, metrics: metrics.join(','), dimensions: dimensions.join(','), ad_spend_mode: "network" }; // Handle app tokens if (params.app_tokens) { queryParams.app_token__in = params.app_tokens; } // Fetch data from Adjust const reportData = await client.fetchReports(params.date_range, queryParams); // Generate a report title based on the type const reportTitle = `## Adjust ${params.report_type.charAt(0).toUpperCase() + params.report_type.slice(1)} Report`; const dateRangeInfo = `### Date Range: ${params.date_range}`; // Analyze the data const analysis = analyzeReportData(reportData); return { isError: false, content: [ { type: "text" as const, text: `${reportTitle}\n${dateRangeInfo}\n\n${analysis}\n\n\`\`\`json\n${JSON.stringify(reportData, null, 2)}\n\`\`\``, } ], }; } catch (error) { console.error("Error fetching standard Adjust report:", error); // Extract status code and message (same error handling as before) let statusCode = 500; let errorMessage = "Unknown error"; if (error instanceof Error) { errorMessage = error.message; if ('response' in error && error.response && typeof error.response === 'object') { const axiosError = error as any; statusCode = axiosError.response.status; // Provide helpful messages based on status code switch (statusCode) { case 400: errorMessage = "Bad request: Your query contains invalid parameters or is malformed."; break; case 401: errorMessage = "Unauthorized: Please check your API credentials."; break; case 403: errorMessage = "Forbidden: You don't have permission to access this data."; break; case 429: errorMessage = "Too many requests: You've exceeded the rate limit."; break; case 503: errorMessage = "Service unavailable: The Adjust API is currently unavailable."; break; case 504: errorMessage = "Gateway timeout: The query took too long to process."; break; default: errorMessage = axiosError.response.data?.message || errorMessage; } } } return { isError: true, content: [ { type: "text" as const, text: `## Error Fetching Adjust Standard Report\n\n**Status Code**: ${statusCode}\n\n**Error**: ${errorMessage}\n\nPlease check your parameters and try again.`, }, ], }; }
• src/mcp-adjust.ts:152-162 (schema)

  Zod schema defining the input parameters for the tool: app_tokens (comma-separated list), date_range (e.g., last_7_days), report_type (performance, retention, cohort, revenue with default 'performance').
  server.tool("adjust-standard-report", "Get a standard Adjust report with common metrics", { app_tokens: z.string() .describe("Comma-separated list of app tokens to include") .default(""), date_range: z.string() .describe("Date range (e.g., 2023-01-01:2023-01-31, yesterday, last_7_days, this_month)") .default("last_7_days"), report_type: z.enum(["performance", "retention", "cohort", "revenue"]) .describe("Type of standard report to generate") .default("performance"), }, async (params, extra) => {
• src/mcp-adjust.ts:152-152 (registration)

  Registration of the 'adjust-standard-report' tool on the MCP server.
  server.tool("adjust-standard-report", "Get a standard Adjust report with common metrics", {
• src/mcp-adjust.ts:272-329 (helper)

  Helper function used by the tool handler to analyze and format the raw report data into a human-readable markdown summary with totals, breakdowns, and warnings.
  function analyzeReportData(data: any) { let analysis = ""; if (!data || !data.rows || data.rows.length === 0) { return "No data available for analysis."; } // Add totals summary if (data.totals) { analysis += "## Summary\n"; Object.entries(data.totals).forEach(([metric, value]) => { analysis += `**Total ${metric}**: ${value}\n`; }); analysis += "\n"; } // Add row analysis analysis += "## Breakdown\n"; // Get all metrics (non-dimension fields) from the first row const firstRow = data.rows[0]; const metrics = Object.keys(firstRow).filter(key => !['attr_dependency', 'app', 'partner_name', 'campaign', 'campaign_id_network', 'campaign_network', 'adgroup', 'creative', 'country', 'os_name', 'day', 'week', 'month', 'year'].includes(key) ); // Analyze each row data.rows.forEach((row: any, index: number) => { // Create a title for this row based on available dimensions let rowTitle = ""; if (row.campaign) rowTitle += `Campaign: ${row.campaign} `; if (row.partner_name) rowTitle += `(${row.partner_name}) `; if (row.app) rowTitle += `- App: ${row.app} `; if (row.country) rowTitle += `- Country: ${row.country} `; if (row.os_name) rowTitle += `- OS: ${row.os_name} `; analysis += `### ${rowTitle || `Row ${index + 1}`}\n`; // Add metrics for this row metrics.forEach(metric => { if (row[metric] !== undefined) { analysis += `**${metric}**: ${row[metric]}\n`; } }); analysis += "\n"; }); // Add warnings if any if (data.warnings && data.warnings.length > 0) { analysis += "## Warnings\n"; data.warnings.forEach((warning: string) => { analysis += `- ${warning}\n`; }); } return analysis; }