RAD Security

Instructions

Implementation Reference

• src/index.ts:637-642 (registration)

  Registration of the 'radql_query_builder' tool in the MCP server, defining its name, description, and input schema.

  {
    name: "radql_query_builder",
    description:
      "Helper tool to build RadQL queries programmatically from structured conditions. Useful when you need to construct complex filter or stats queries from structured inputs.",
    inputSchema: zodToJsonSchema(radql.RadQLQueryBuilderSchema),
  },

• src/index.ts:1574-1583 (handler)

  MCP tool dispatch handler that parses arguments using the schema and calls the buildRadQLQuery function.

  case "radql_query_builder": {
    const args = radql.RadQLQueryBuilderSchema.parse(
      request.params.arguments
    );
    const response = radql.buildRadQLQuery(args);
    return {
      content: [
        { type: "text", text: JSON.stringify(response, null, 2) },
      ],
    };

• src/operations/radql.ts:73-99 (schema)

  Zod schema defining the input parameters for the radql_query_builder tool.

  export const RadQLQueryBuilderSchema = z.object({
    data_type: z.string()
      .describe("The data type to build a query for"),
  
    conditions: z.array(z.object({
      field: z.string(),
      operator: z.enum([":", "=", "!=", "!:", "<>", ">", ">=", "<", "<=", "contains", "starts_with", "ends_with"]),
      value: z.union([z.string(), z.number(), z.boolean()]),
      negate: z.boolean().optional()
    })).optional()
      .describe("Filter conditions to combine into a RadQL query"),
  
    logic: z.enum(["AND", "OR"]).optional().default("AND")
      .describe("Logical operator to combine conditions"),
  
    aggregation: z.enum(["count", "sum", "avg", "min", "max", "median"]).optional()
      .describe("Aggregation function to apply"),
  
    aggregate_field: z.string().optional()
      .describe("Field to aggregate (omit for count(*))"),
  
    group_by: z.array(z.string()).optional()
      .describe("Fields to group by"),
  
    time_group: z.enum(["second", "minute", "hour", "day", "month", "year"]).optional()
      .describe("Time-based grouping interval for datetime fields")
  });

• src/operations/radql.ts:334-432 (handler)

  Core handler function that implements the tool logic: constructs RadQL filters_query and stats_query from structured conditions, handling operators, quoting rules for special cases (dates, hyphens, wildcards), aggregations, and grouping.

  export function buildRadQLQuery(
    args: z.infer<typeof RadQLQueryBuilderSchema>
  ): { filters_query?: string; stats_query?: string } {
    const result: { filters_query?: string; stats_query?: string } = {};
  
    if (args.conditions && args.conditions.length > 0) {
      const conditions = args.conditions.map(cond => {
        let query = "";
  
        if (cond.negate) {
          query += "NOT ";
        }
  
        query += cond.field;
  
        // Map operator to RadQL syntax
        if (cond.operator === "contains") {
          // Quote wildcard values if they contain special characters
          const needsQuoting = typeof cond.value === "string" && (
            cond.value.includes("-") || cond.value.includes(" ") || cond.value.includes(":")
          );
          const valueStr = needsQuoting ? `"*${cond.value}*"` : `*${cond.value}*`;
          query += `:${valueStr}`;
        } else if (cond.operator === "starts_with") {
          const needsQuoting = typeof cond.value === "string" && (
            cond.value.includes("-") || cond.value.includes(" ") || cond.value.includes(":")
          );
          const valueStr = needsQuoting ? `"${cond.value}*"` : `${cond.value}*`;
          query += `:${valueStr}`;
        } else if (cond.operator === "ends_with") {
          const needsQuoting = typeof cond.value === "string" && (
            cond.value.includes("-") || cond.value.includes(" ") || cond.value.includes(":")
          );
          const valueStr = needsQuoting ? `"*${cond.value}"` : `*${cond.value}`;
          query += `:${valueStr}`;
        } else {
          // Quote string values to handle dates, hyphens, and special characters
          // The RadQL parser requires quoting for:
          // - Dates/timestamps (contain hyphens): "2024-01-01"
          // - UUIDs (contain hyphens): "550e8400-e29b-41d4-a716-446655440000"
          // - Strings with special characters: colons, spaces, etc.
          // - Any value that's not a simple alphanumeric string
          const value = cond.value;
          let valueStr: string;
  
          if (typeof value === "string") {
            // Check if the string needs quoting
            // Quote if it contains: spaces, hyphens, colons, or other special chars
            // Or if it looks like a date/timestamp
            const needsQuoting =
              value.includes(" ") ||
              value.includes("-") ||
              value.includes(":") ||
              value.includes("(") ||
              value.includes(")") ||
              /^\d{4}-\d{2}-\d{2}/.test(value) ||
              /[<>=!]/.test(value);
  
            valueStr = needsQuoting ? `"${value}"` : value;
          } else {
            valueStr = String(value);
          }
  
          query += `${cond.operator}${valueStr}`;
        }
  
        return query;
      });
  
      result.filters_query = conditions.join(` ${args.logic} `);
    }
  
    if (args.aggregation) {
      let statsQuery = "";
  
      if (args.aggregation === "count") {
        statsQuery = args.aggregate_field ? `count(${args.aggregate_field})` : "count()";
      } else {
        if (!args.aggregate_field) {
          throw new Error(`${args.aggregation} requires an aggregate_field`);
        }
        statsQuery = `${args.aggregation}(${args.aggregate_field})`;
      }
  
      if (args.group_by && args.group_by.length > 0) {
        const groupByFields = args.group_by.map(field => {
          if (args.time_group && (field.includes("_at") || field.includes("timestamp") || field.includes("time"))) {
            return `${args.time_group}(${field})`;
          }
          return field;
        });
        statsQuery += ` by ${groupByFields.join(", ")}`;
      }
  
      result.stats_query = statsQuery;
    }
  
    return result;
  }