get_cases

Instructions

Implementation Reference

• src/index.ts:516-574 (registration)

  The tool 'get_cases' is registered using server.tool() with the MCP SDK. It registers the tool name, description, Zod schema for input validation, and the handler callback.

  server.tool(
    "get_cases",
    "Retrieve cases (customer inquiries/issues) from Sprout Social. " +
      "Cases represent customer interactions that may require action by a social care agent.",
    {
      updated_time_start: z
        .string()
        .optional()
        .describe("Filter by updated time start (YYYY-MM-DD format)."),
      updated_time_end: z
        .string()
        .optional()
        .describe("Filter by updated time end (YYYY-MM-DD format)."),
      priority: z
        .array(z.string())
        .optional()
        .describe(
          "Filter by priority. Valid values: 'HIGH', 'MEDIUM', 'LOW', 'UNDEFINED'."
        ),
      limit: z.number().optional().describe("Maximum cases to return per page."),
      sort: z
        .array(z.string())
        .optional()
        .describe("Sort order, e.g. ['created_time:asc']."),
      timezone: z
        .string()
        .optional()
        .describe(
          "Timezone for date filters (e.g. 'America/Chicago'). Defaults to UTC."
        ),
      page_cursor: z
        .string()
        .optional()
        .describe("Cursor for pagination (from previous response)."),
    },
    async ({ updated_time_start, updated_time_end, priority, limit, sort, timezone, page_cursor }) => {
      const filters: string[] = [];
  
      if (updated_time_start && updated_time_end) {
        filters.push(
          `updated_time.in(${updated_time_start}...${updated_time_end})`
        );
      }
  
      if (priority && priority.length > 0) {
        filters.push(`priority.eq(${priority.join(", ")})`);
      }
  
      const body: Record<string, unknown> = {};
      if (filters.length > 0) body.filters = filters;
      if (limit) body.limit = limit;
      if (sort) body.sort = sort;
      if (timezone) body.timezone = timezone;
      if (page_cursor) body.page_cursor = page_cursor;
  
      const data = await sproutRequest("POST", "/cases/filter", body);
      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
    }
  );

• src/index.ts:520-549 (schema)

  Input validation schema using Zod: optional updated_time_start/updated_time_end (strings, YYYY-MM-DD format), priority (array of 'HIGH'/'MEDIUM'/'LOW'/'UNDEFINED'), limit (number), sort (array of strings like 'created_time:asc'), timezone (string), and page_cursor (string for pagination).

  {
    updated_time_start: z
      .string()
      .optional()
      .describe("Filter by updated time start (YYYY-MM-DD format)."),
    updated_time_end: z
      .string()
      .optional()
      .describe("Filter by updated time end (YYYY-MM-DD format)."),
    priority: z
      .array(z.string())
      .optional()
      .describe(
        "Filter by priority. Valid values: 'HIGH', 'MEDIUM', 'LOW', 'UNDEFINED'."
      ),
    limit: z.number().optional().describe("Maximum cases to return per page."),
    sort: z
      .array(z.string())
      .optional()
      .describe("Sort order, e.g. ['created_time:asc']."),
    timezone: z
      .string()
      .optional()
      .describe(
        "Timezone for date filters (e.g. 'America/Chicago'). Defaults to UTC."
      ),
    page_cursor: z
      .string()
      .optional()
      .describe("Cursor for pagination (from previous response)."),

• src/index.ts:551-573 (handler)

  The handler function that executes the tool logic: builds filters from optional parameters, constructs a request body, calls sproutRequest('POST', '/cases/filter', body), and returns the JSON response.

  async ({ updated_time_start, updated_time_end, priority, limit, sort, timezone, page_cursor }) => {
    const filters: string[] = [];
  
    if (updated_time_start && updated_time_end) {
      filters.push(
        `updated_time.in(${updated_time_start}...${updated_time_end})`
      );
    }
  
    if (priority && priority.length > 0) {
      filters.push(`priority.eq(${priority.join(", ")})`);
    }
  
    const body: Record<string, unknown> = {};
    if (filters.length > 0) body.filters = filters;
    if (limit) body.limit = limit;
    if (sort) body.sort = sort;
    if (timezone) body.timezone = timezone;
    if (page_cursor) body.page_cursor = page_cursor;
  
    const data = await sproutRequest("POST", "/cases/filter", body);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }

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

  The sproutRequest helper function used by the handler. It constructs the API URL, attaches Authorization header, sends the HTTP request, and returns parsed JSON. For the 'get_cases' tool, it's called with method 'POST' and path '/cases/filter'.

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