list-categories

Instructions

Implementation Reference

• build/index.js:601-625 (handler)

  The async handler function for the 'list-categories' tool. It builds query params with pagination (page, pageSize), optionally parses filter strings via parseFilters(), makes a GET request to /categories, and returns the result.

  }, async ({ filter, page, pageSize }) => {
      try {
          let queryParams = {
              page: page.toString(),
              pageSize: pageSize.toString()
          };
          // Parse and add filter parameters
          if (filter) {
              const filterParams = parseFilters(filter);
              queryParams = { ...queryParams, ...filterParams };
          }
          const categories = await authenticatedRequest("/categories", "GET", null, queryParams);
          return {
              content: [{
                      type: "text",
                      text: `Categories retrieved successfully:\n${JSON.stringify(categories, null, 2)}`
                  }]
          };
      }
      catch (error) {
          return {
              isError: true,
              content: [{ type: "text", text: `Error fetching categories: ${getErrorMessage(error)}` }]
          };
      }

• build/index.js:597-626 (registration)

  Registration of the 'list-categories' tool on the MCP server using server.tool() with name 'list-categories', description, Zod schema for inputs (filter, page, pageSize), and the handler function.

  server.tool("list-categories", "List all categories with filtering support", {
      filter: z.string().optional().describe("Filter criteria in the format 'fieldName(operator)=value'. Multiple filters can be combined with & (e.g., 'description(like)=dashboard&orgId(eq)=1'). Available operators: eq, ne, gt, lt, ge, le, like, nlike. Use get-filterable-attributes tool to see available fields."),
      page: z.number().optional().default(1).describe("Page number for pagination"),
      pageSize: z.number().optional().default(20).describe("Number of items per page")
  }, async ({ filter, page, pageSize }) => {
      try {
          let queryParams = {
              page: page.toString(),
              pageSize: pageSize.toString()
          };
          // Parse and add filter parameters
          if (filter) {
              const filterParams = parseFilters(filter);
              queryParams = { ...queryParams, ...filterParams };
          }
          const categories = await authenticatedRequest("/categories", "GET", null, queryParams);
          return {
              content: [{
                      type: "text",
                      text: `Categories retrieved successfully:\n${JSON.stringify(categories, null, 2)}`
                  }]
          };
      }
      catch (error) {
          return {
              isError: true,
              content: [{ type: "text", text: `Error fetching categories: ${getErrorMessage(error)}` }]
          };
      }
  });

• build/index.js:598-600 (schema)

  Input schema for the 'list-categories' tool: filter (optional string), page (optional number, default 1), pageSize (optional number, default 20).

  filter: z.string().optional().describe("Filter criteria in the format 'fieldName(operator)=value'. Multiple filters can be combined with & (e.g., 'description(like)=dashboard&orgId(eq)=1'). Available operators: eq, ne, gt, lt, ge, le, like, nlike. Use get-filterable-attributes tool to see available fields."),
  page: z.number().optional().default(1).describe("Page number for pagination"),
  pageSize: z.number().optional().default(20).describe("Number of items per page")

• build/index.js:127-142 (helper)

  The parseFilters() helper function that converts a filter string like 'field(op)=value&field2(op2)=val2' into query parameters.

  function parseFilters(filterString) {
      const queryParams = {};
      if (!filterString)
          return queryParams;
      // Split by & to handle multiple filters
      const filters = filterString.split('&');
      for (const filter of filters) {
          // Match the pattern fieldName(operator)=value
          const match = filter.match(/([a-zA-Z]+)\(([a-zA-Z]+)\)=(.+)/);
          if (match) {
              const [_, field, operator, value] = match;
              queryParams[`${field}(${operator})`] = value;
          }
      }
      return queryParams;
  }

• build/index.js:57-125 (helper)

  The authenticatedRequest() helper that makes HTTP requests with the auth token, adds orgId, handles JSON/binary/text responses.

  async function authenticatedRequest(endpoint, method = "GET", body = null, queryParams = {}) {
      if (!apiUrlSet) {
          throw new Error("API URL not set. Please set the API URL using the set-api-url tool.");
      }
      if (!authToken) {
          throw new Error("Not authenticated. Please authenticate first.");
      }
      // Build URL with query parameters
      let url = `${API_BASE_URL}${endpoint}`;
      // Add orgId if available
      if (orgId !== null) {
          queryParams.orgId = orgId.toString();
      }
      // Add query parameters if any
      if (Object.keys(queryParams).length > 0) {
          const queryString = Object.entries(queryParams)
              .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
              .join("&");
          url = `${url}?${queryString}`;
      }
      logInfo(`Making ${method} request to ${url}`);
      const headers = {
          "Authorization": `bearer ${authToken}`,
          "Content-Type": "application/json"
      };
      const options = {
          method,
          headers
      };
      if (body !== null && ["POST", "PUT"].includes(method)) {
          options.body = JSON.stringify(body);
          logInfo(`Request body: ${JSON.stringify(body)}`);
      }
      try {
          const response = await fetch(url, options);
          if (!response.ok) {
              const errorText = await response.text();
              logError(`API request failed with status ${response.status}: ${errorText}`);
              throw new Error(`API request failed with status ${response.status}: ${response.statusText}`);
          }
          // Check if the response is JSON or binary
          const contentType = response.headers.get("content-type") || "";
          if (contentType.includes("application/json")) {
              const jsonData = await response.json();
              logInfo(`Received JSON response: ${JSON.stringify(jsonData).substring(0, 200)}...`);
              return jsonData;
          }
          else if (contentType.includes("text/csv")) {
              // For binary/file responses, return a base64 encoded string
              const buffer = await response.arrayBuffer();
              const base64 = Buffer.from(buffer).toString("base64");
              logInfo(`Received binary response of type ${contentType}, length: ${base64.length}`);
              return {
                  contentType,
                  data: base64
              };
          }
          else {
              // Otherwise, return as text
              const text = await response.text();
              logInfo(`Received text response: ${text.substring(0, 200)}...`);
              return text;
          }
      }
      catch (error) {
          logError(`API request error: ${getErrorMessage(error)}`);
          throw error;
      }
  }