@malloy-publisher/server 0.0.181 → 0.0.182

package/src/mcp/tools/execute_query_tool.ts

@@ -24,6 +24,12 @@ const executeQueryShape = {
    query: z.string().optional().describe("Ad-hoc Malloy query code"),
    sourceName: z.string().optional().describe("Source name for a view"),
    queryName: z.string().optional().describe("Named query or view"),
+   filterParams: z
+      .record(z.union([z.string(), z.array(z.string())]))
+      .optional()
+      .describe(
+         "Filter parameter values keyed by filter name. Used with sources that declare #(filter) annotations.",
+      ),
 };
 
 // Type inference is handled automatically by the MCP server based on the executeQueryShape
@@ -49,6 +55,7 @@ export function registerExecuteQueryTool(
             query,
             sourceName,
             queryName,
+            filterParams,
          } = params;
 
          logger.info("[MCP Tool executeQuery] Received params:", { params });
@@ -120,6 +127,7 @@ export function registerExecuteQueryTool(
                   undefined,
                   undefined,
                   query,
+                  filterParams,
                );
                const { validateRenderTags } = await import(
                   "@malloydata/render-validator"
@@ -165,6 +173,7 @@ export function registerExecuteQueryTool(
                   sourceName,
                   queryName,
                   undefined,
+                  filterParams,
                );
                const { validateRenderTags } = await import(
                   "@malloydata/render-validator"

package/src/server.ts

@@ -817,12 +817,29 @@ app.get(
          // Express stores wildcard matches in params['0']
          const notebookPath = (req.params as Record<string, string>)["0"];
 
+         // Parse optional filter_params (JSON query string) and bypass_filters
+         let filterParams: Record<string, string | string[]> | undefined;
+         if (typeof req.query.filter_params === "string") {
+            try {
+               filterParams = JSON.parse(req.query.filter_params);
+            } catch {
+               res.status(400).json({
+                  error: "Invalid filter_params: must be valid JSON",
+               });
+               return;
+            }
+         }
+         const bypassFilters =
+            req.query.bypass_filters === "true" ? true : undefined;
+
          res.status(200).json(
             await modelController.executeNotebookCell(
                req.params.projectName,
                req.params.packageName,
                notebookPath,
                cellIndex,
+               filterParams,
+               bypassFilters,
             ),
          );
       } catch (error) {
@@ -879,6 +896,10 @@ app.post(
                req.body.queryName as string,
                req.body.query as string,
                req.body.compactJson === true,
+               (req.body.filterParams ?? req.body.sourceFilters) as
+                  | Record<string, string | string[]>
+                  | undefined,
+               req.body.bypassFilters === true ? true : undefined,
             ),
          );
       } catch (error) {

package/src/service/filter.spec.ts

@@ -0,0 +1,392 @@
+import { describe, expect, it } from "bun:test";
+import {
+   buildFilterClause,
+   injectFilterRefinement,
+   parseFilterAnnotation,
+   parseFilters,
+   FilterValidationError,
+   type FilterDefinition,
+   type FilterParams,
+} from "./filter";
+
+describe("service/filter", () => {
+   // -----------------------------------------------------------------------
+   // parseFilterAnnotation
+   // -----------------------------------------------------------------------
+   describe("parseFilterAnnotation", () => {
+      it("returns null for non-filter annotations", () => {
+         expect(parseFilterAnnotation("#(doc) Some docs")).toBeNull();
+         expect(parseFilterAnnotation("# bar_chart")).toBeNull();
+         expect(parseFilterAnnotation("")).toBeNull();
+      });
+
+      it("parses a minimal annotation (dimension + type)", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=status type=equal",
+         );
+         expect(result).toEqual({
+            name: "status",
+            dimension: "status",
+            type: "equal",
+            implicit: false,
+            required: false,
+         });
+      });
+
+      it("parses all fields including name, implicit, required", () => {
+         const result = parseFilterAnnotation(
+            '#(filter) name="Customer ID" dimension=customer_id type=equal implicit required',
+         );
+         expect(result).toEqual({
+            name: "Customer ID",
+            dimension: "customer_id",
+            type: "equal",
+            implicit: true,
+            required: true,
+         });
+      });
+
+      it("parses type=in", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=region type=in",
+         );
+         expect(result).toEqual({
+            name: "region",
+            dimension: "region",
+            type: "in",
+            implicit: false,
+            required: false,
+         });
+      });
+
+      it("parses type=like", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=name type=like",
+         );
+         expect(result!.type).toBe("like");
+      });
+
+      it("parses type=greater_than", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=created_at type=greater_than",
+         );
+         expect(result!.type).toBe("greater_than");
+      });
+
+      it("parses type=less_than", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=created_at type=less_than",
+         );
+         expect(result!.type).toBe("less_than");
+      });
+
+      it("parses required without implicit", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) dimension=tenant_id type=equal required",
+         );
+         expect(result).toEqual({
+            name: "tenant_id",
+            dimension: "tenant_id",
+            type: "equal",
+            implicit: false,
+            required: true,
+         });
+      });
+
+      it("handles single-quoted name values", () => {
+         const result = parseFilterAnnotation(
+            "#(filter) name='My Filter' dimension=col type=equal",
+         );
+         expect(result!.name).toBe("My Filter");
+      });
+
+      it("handles extra whitespace", () => {
+         const result = parseFilterAnnotation(
+            "  #(filter)   dimension=status   type=equal   required  ",
+         );
+         expect(result).toEqual({
+            name: "status",
+            dimension: "status",
+            type: "equal",
+            implicit: false,
+            required: true,
+         });
+      });
+
+      it("throws on missing dimension", () => {
+         expect(() => parseFilterAnnotation("#(filter) type=equal")).toThrow(
+            "missing required 'dimension'",
+         );
+      });
+
+      it("throws on missing type", () => {
+         expect(() =>
+            parseFilterAnnotation("#(filter) dimension=status"),
+         ).toThrow("missing required 'type'");
+      });
+
+      it("throws on invalid type", () => {
+         expect(() =>
+            parseFilterAnnotation("#(filter) dimension=status type=banana"),
+         ).toThrow('Invalid filter type "banana"');
+      });
+
+      it("throws on unknown parameter", () => {
+         expect(() =>
+            parseFilterAnnotation(
+               "#(filter) dimension=status type=equal foo=bar",
+            ),
+         ).toThrow('Unknown filter parameter "foo"');
+      });
+
+      it("throws on unknown flag", () => {
+         expect(() =>
+            parseFilterAnnotation(
+               "#(filter) dimension=status type=equal banana",
+            ),
+         ).toThrow('Unknown filter flag "banana"');
+      });
+   });
+
+   // -----------------------------------------------------------------------
+   // parseFilters
+   // -----------------------------------------------------------------------
+   describe("parseFilters", () => {
+      it("extracts filter annotations from a mixed list", () => {
+         const annotations = [
+            "#(doc) This is a source for orders",
+            "#(filter) dimension=status type=equal",
+            "# bar_chart",
+            "#(filter) dimension=region type=in required",
+         ];
+         const filters = parseFilters(annotations);
+         expect(filters).toHaveLength(2);
+         expect(filters[0].dimension).toBe("status");
+         expect(filters[1].dimension).toBe("region");
+         expect(filters[1].required).toBe(true);
+      });
+
+      it("returns empty array when no filter annotations", () => {
+         const filters = parseFilters(["#(doc) some docs", "# hidden"]);
+         expect(filters).toHaveLength(0);
+      });
+   });
+
+   // -----------------------------------------------------------------------
+   // buildFilterClause
+   // -----------------------------------------------------------------------
+   describe("buildFilterClause", () => {
+      const equalFilter: FilterDefinition = {
+         name: "status",
+         dimension: "status",
+         type: "equal",
+         implicit: false,
+         required: false,
+      };
+
+      const inFilter: FilterDefinition = {
+         name: "region",
+         dimension: "region",
+         type: "in",
+         implicit: false,
+         required: false,
+      };
+
+      const likeFilter: FilterDefinition = {
+         name: "name_search",
+         dimension: "customer_name",
+         type: "like",
+         implicit: false,
+         required: false,
+      };
+
+      const gtFilter: FilterDefinition = {
+         name: "start_date",
+         dimension: "created_at",
+         type: "greater_than",
+         implicit: false,
+         required: false,
+      };
+
+      const ltFilter: FilterDefinition = {
+         name: "end_date",
+         dimension: "created_at",
+         type: "less_than",
+         implicit: false,
+         required: false,
+      };
+
+      const requiredFilter: FilterDefinition = {
+         name: "tenant_id",
+         dimension: "tenant_id",
+         type: "equal",
+         implicit: true,
+         required: true,
+      };
+
+      it("returns empty string when no params provided", () => {
+         const clause = buildFilterClause([equalFilter], {});
+         expect(clause).toBe("");
+      });
+
+      it("returns empty string when param is empty string", () => {
+         const clause = buildFilterClause([equalFilter], { status: "" });
+         expect(clause).toBe("");
+      });
+
+      it("returns empty string when param is empty array", () => {
+         const clause = buildFilterClause([inFilter], { region: [] });
+         expect(clause).toBe("");
+      });
+
+      it("builds equal predicate", () => {
+         const clause = buildFilterClause([equalFilter], {
+            status: "active",
+         });
+         expect(clause).toBe("`status` = 'active'");
+      });
+
+      it("equal uses first element if given array", () => {
+         const clause = buildFilterClause([equalFilter], {
+            status: ["active", "pending"],
+         });
+         expect(clause).toBe("`status` = 'active'");
+      });
+
+      it("builds in predicate with single value", () => {
+         const clause = buildFilterClause([inFilter], {
+            region: ["US"],
+         });
+         expect(clause).toBe("`region` = 'US'");
+      });
+
+      it("builds in predicate with multiple values", () => {
+         const clause = buildFilterClause([inFilter], {
+            region: ["US", "EU", "APAC"],
+         });
+         expect(clause).toBe(
+            "(`region` = 'US' or `region` = 'EU' or `region` = 'APAC')",
+         );
+      });
+
+      it("builds like predicate with auto-wrapping (case-insensitive)", () => {
+         const clause = buildFilterClause([likeFilter], {
+            name_search: "Smith",
+         });
+         expect(clause).toBe("lower(`customer_name`) ~ '%smith%'");
+      });
+
+      it("builds like predicate preserving existing wildcards", () => {
+         const clause = buildFilterClause([likeFilter], {
+            name_search: "%Smith%",
+         });
+         expect(clause).toBe("lower(`customer_name`) ~ '%smith%'");
+      });
+
+      it("builds greater_than predicate", () => {
+         const clause = buildFilterClause([gtFilter], {
+            start_date: "2024-01-01",
+         });
+         expect(clause).toBe("`created_at` > @2024-01-01");
+      });
+
+      it("builds less_than predicate", () => {
+         const clause = buildFilterClause([ltFilter], {
+            end_date: "2024-12-31",
+         });
+         expect(clause).toBe("`created_at` < @2024-12-31");
+      });
+
+      it("combines multiple filters with AND", () => {
+         const params: FilterParams = {
+            status: "active",
+            region: ["US", "EU"],
+         };
+         const clause = buildFilterClause([equalFilter, inFilter], params);
+         expect(clause).toBe(
+            "`status` = 'active' and (`region` = 'US' or `region` = 'EU')",
+         );
+      });
+
+      it("skips optional filters with no value", () => {
+         const params: FilterParams = {
+            status: "active",
+         };
+         const clause = buildFilterClause([equalFilter, inFilter], params);
+         expect(clause).toBe("`status` = 'active'");
+      });
+
+      it("throws on missing required filter", () => {
+         expect(() => buildFilterClause([requiredFilter], {})).toThrow(
+            FilterValidationError,
+         );
+         expect(() => buildFilterClause([requiredFilter], {})).toThrow(
+            'Required filter "tenant_id"',
+         );
+      });
+
+      it("builds clause for required filter when value provided", () => {
+         const clause = buildFilterClause([requiredFilter], {
+            tenant_id: "abc123",
+         });
+         expect(clause).toBe("`tenant_id` = 'abc123'");
+      });
+
+      it("escapes single quotes in values", () => {
+         const clause = buildFilterClause([equalFilter], {
+            status: "it's active",
+         });
+         expect(clause).toBe("`status` = 'it\\'s active'");
+      });
+
+      it("escapes backslashes in values", () => {
+         const clause = buildFilterClause([likeFilter], {
+            name_search: "foo\\bar",
+         });
+         expect(clause).toBe("lower(`customer_name`) ~ '%foo\\\\bar%'");
+      });
+
+      it("ignores params that don't match any filter", () => {
+         const clause = buildFilterClause([equalFilter], {
+            status: "active",
+            unknown_param: "ignored",
+         });
+         expect(clause).toBe("`status` = 'active'");
+      });
+   });
+
+   // -----------------------------------------------------------------------
+   // injectFilterRefinement
+   // -----------------------------------------------------------------------
+   describe("injectFilterRefinement", () => {
+      it("returns original query when clause is empty", () => {
+         const query = "run: orders -> summary";
+         expect(injectFilterRefinement(query, "")).toBe(query);
+      });
+
+      it("appends refinement to named view query", () => {
+         const query = "run: orders -> summary";
+         const clause = "`status` = 'active'";
+         expect(injectFilterRefinement(query, clause)).toBe(
+            "run: orders -> summary + {where: `status` = 'active'}",
+         );
+      });
+
+      it("appends refinement to ad-hoc query", () => {
+         const query =
+            "run: orders -> { group_by: status; aggregate: order_count }";
+         const clause = "`region` = 'US'";
+         expect(injectFilterRefinement(query, clause)).toBe(
+            "run: orders -> { group_by: status; aggregate: order_count } + {where: `region` = 'US'}",
+         );
+      });
+
+      it("trims trailing whitespace before appending", () => {
+         const query = "run: orders -> summary   \n  ";
+         const clause = "`status` = 'active'";
+         expect(injectFilterRefinement(query, clause)).toBe(
+            "run: orders -> summary + {where: `status` = 'active'}",
+         );
+      });
+   });
+});