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;
  }