get_profile_analytics

Instructions

Implementation Reference

• src/index.ts:199-211 (handler)

  Handler function that builds the request body with filters (profile_ids, reporting_period) and metrics, optionally adds pagination, then POSTs to /analytics/profiles and returns the result.

  async ({ profile_ids, metrics, reporting_period_start, reporting_period_end, page }) => {
    const body: Record<string, unknown> = {
      filters: [
        `customer_profile_id.eq(${profile_ids.join(", ")})`,
        `reporting_period.in(${reporting_period_start}...${reporting_period_end})`,
      ],
      metrics,
    };
    if (page) body.page = page;
  
    const data = await sproutRequest("POST", "/analytics/profiles", body);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }

• src/index.ts:176-198 (schema)

  Zod schema defining input parameters: profile_ids (string array), metrics (string array), reporting_period_start (string), reporting_period_end (string), and optional page (number).

  {
    profile_ids: z
      .array(z.string())
      .describe(
        "Array of customer_profile_id values to query. Use get_profiles to discover available IDs."
      ),
    metrics: z
      .array(z.string())
      .describe(
        "Metrics to retrieve, e.g. ['impressions', 'engagements', 'reactions', 'post_link_clicks']. " +
          "Available metrics depend on profile type."
      ),
    reporting_period_start: z
      .string()
      .describe("Start date in YYYY-MM-DD format."),
    reporting_period_end: z
      .string()
      .describe("End date in YYYY-MM-DD format."),
    page: z
      .number()
      .optional()
      .describe("Page number for paginated results (default: 1)."),
  },

• src/index.ts:172-212 (registration)

  Registration of 'get_profile_analytics' tool on the MCP server with tool name, description, Zod schema, and async handler.

  server.tool(
    "get_profile_analytics",
    "Get owned profile-level analytics (impressions, engagements, etc.) for one or more profiles over a reporting period. " +
      "Requires a reporting_period filter in the format 'YYYY-MM-DD...YYYY-MM-DD' (max 1 year span).",
    {
      profile_ids: z
        .array(z.string())
        .describe(
          "Array of customer_profile_id values to query. Use get_profiles to discover available IDs."
        ),
      metrics: z
        .array(z.string())
        .describe(
          "Metrics to retrieve, e.g. ['impressions', 'engagements', 'reactions', 'post_link_clicks']. " +
            "Available metrics depend on profile type."
        ),
      reporting_period_start: z
        .string()
        .describe("Start date in YYYY-MM-DD format."),
      reporting_period_end: z
        .string()
        .describe("End date in YYYY-MM-DD format."),
      page: z
        .number()
        .optional()
        .describe("Page number for paginated results (default: 1)."),
    },
    async ({ profile_ids, metrics, reporting_period_start, reporting_period_end, page }) => {
      const body: Record<string, unknown> = {
        filters: [
          `customer_profile_id.eq(${profile_ids.join(", ")})`,
          `reporting_period.in(${reporting_period_start}...${reporting_period_end})`,
        ],
        metrics,
      };
      if (page) body.page = page;
  
      const data = await sproutRequest("POST", "/analytics/profiles", body);
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/index.ts:29-59 (helper)

  Helper function sproutRequest that constructs and executes HTTP requests to the Sprout Social API with authentication and error handling.

  async function sproutRequest(
    method: "GET" | "POST",
    path: string,
    body?: Record<string, unknown>
  ): Promise<unknown> {
    const { apiKey, customerId } = getConfig();
    const url = `${SPROUT_API_BASE}/v1/${customerId}${path}`;
  
    const headers: Record<string, string> = {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    };
  
    const options: RequestInit = { method, headers };
  
    if (body) {
      headers["Content-Type"] = "application/json";
      options.body = JSON.stringify(body);
    }
  
    const response = await fetch(url, options);
  
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(
        `Sprout Social API error (${response.status}): ${errorText}`
      );
    }
  
    return response.json();
  }