get-filterable-attributes

Instructions

Implementation Reference

• build/index.js:166-259 (handler)

  The full handler function for the 'get-filterable-attributes' tool. It takes an entityType ('chart' or 'category'), fetches a sample entity from the API, extracts its attributes (name, type, example value, and available operators based on type), and returns them as filterable attributes with example usage.

  server.tool("get-filterable-attributes", "Get the list of attributes that can be used for filtering by examining a sample entity", {
      entityType: z.enum(["chart", "category"]).describe("Type of entity to examine (chart or category)")
  }, async ({ entityType }) => {
      try {
          if (!apiUrlSet || !authToken) {
              return {
                  isError: true,
                  content: [{
                          type: "text",
                          text: "Please set API URL and authenticate before using this tool."
                      }]
              };
          }
          let endpoint = "";
          // Get a sample entity
          if (entityType === "chart") {
              endpoint = "/charts";
          }
          else if (entityType === "category") {
              endpoint = "/categories";
          }
          // Get all entities (since pagination may not be supported)
          const listResponse = await authenticatedRequest(endpoint, "GET");
          if (listResponse &&
              typeof listResponse === 'object' &&
              'content' in listResponse &&
              Array.isArray(listResponse.content) &&
              listResponse.content.length > 0) {
              // Just use the first entity as our sample
              const sampleEntity = listResponse.content[0];
              // Extract the attributes from the sample entity
              const attributes = Object.keys(sampleEntity).map(key => {
                  const value = sampleEntity[key];
                  const type = typeof value;
                  // Determine which operators are suitable based on the value type
                  let availableOperators = [];
                  if (type === "string") {
                      // Prioritize 'like' for string fields since it's case-insensitive
                      availableOperators = ["like", "nlike", "eq", "ne"];
                  }
                  else if (type === "number") {
                      availableOperators = ["eq", "ne", "gt", "lt", "ge", "le"];
                  }
                  else if (type === "boolean") {
                      availableOperators = ["eq", "ne"];
                  }
                  return {
                      name: key,
                      type: type,
                      example: value !== null && value !== undefined ? String(value).substring(0, 30) : "null", // Show a sample value (truncated)
                      operators: availableOperators
                  };
              });
              // Find a string field for the example if possible
              const stringField = attributes.find(attr => attr.type === "string" && attr.example && attr.example !== "null");
              let exampleFilter = "";
              if (stringField) {
                  exampleFilter = `${stringField.name}(like)=${stringField.example}`;
              }
              else if (attributes.length > 0) {
                  const firstAttr = attributes[0];
                  exampleFilter = `${firstAttr.name}(${firstAttr.operators[0]})=${firstAttr.example}`;
              }
              let exampleMultipleFilter = "";
              if (attributes.length > 1) {
                  const secondAttr = attributes[1];
                  exampleMultipleFilter = `${exampleFilter}&${secondAttr.name}(${secondAttr.operators[0]})=${secondAttr.example}`;
              }
              return {
                  content: [{
                          type: "text",
                          text: `Filterable attributes for ${entityType}:\n${JSON.stringify(attributes, null, 2)}\n\n` +
                              `Example filter usage: '${exampleFilter}'\n\n` +
                              `Example with multiple filters: '${exampleMultipleFilter || "Not enough attributes for multiple filter example"}'\n\n` +
                              `Note: For text fields, the 'like' operator is recommended as it performs case-insensitive substring matching.`
                      }]
              };
          }
          else {
              return {
                  content: [{
                          type: "text",
                          text: `No ${entityType} entities found to analyze. Please ensure there is at least one ${entityType} in the system.`
                      }]
              };
          }
      }
      catch (error) {
          return {
              isError: true,
              content: [{ type: "text", text: `Error fetching ${entityType} attributes: ${getErrorMessage(error)}` }]
          };
      }
  });

• build/index.js:166-168 (registration)

  Registration of the 'get-filterable-attributes' tool on the MCP server via server.tool(), with zod schema defining the input parameter entityType.

  server.tool("get-filterable-attributes", "Get the list of attributes that can be used for filtering by examining a sample entity", {
      entityType: z.enum(["chart", "category"]).describe("Type of entity to examine (chart or category)")
  }, async ({ entityType }) => {

• build/index.js:167-167 (schema)

  Zod input schema for the tool. Defines a single required parameter 'entityType' which must be either 'chart' or 'category'.

  entityType: z.enum(["chart", "category"]).describe("Type of entity to examine (chart or category)")