Merge branch 'main' into claude/add-index-ts-to-mcp-key-files

Author: oatsandsugar

apps/framework-docs-v2/content/moosestack/reference/query-layer.mdx

@@ -29,19 +29,19 @@ const visitsModel = defineQueryModel({
   table: VisitsTable,
 
   dimensions: {
-    status: { column: "status" },
+    status: { column: "status", description: "Visit status category" },
     ...timeDimensions(VisitsTable.columns.timestamp),
   },
 
   metrics: {
-    totalVisits: { agg: count(), as: "total_visits" },
-    totalRevenue: { agg: sum(VisitsTable.columns.amount), as: "total_revenue" },
+    totalVisits: { agg: count(), as: "total_visits", description: "Total number of visits" },
+    totalRevenue: { agg: sum(VisitsTable.columns.amount), as: "total_revenue", description: "Sum of visit revenue" },
   },
 
   filters: {
-    status: { column: "status", operators: ["eq", "in"] as const },
-    amount: { column: "amount", operators: ["gte", "lte"] as const },
-    totalRevenue: { metric: "totalRevenue", operators: ["gte"] as const },
+    status: { column: "status", operators: ["eq", "in"] as const, description: "Filter by visit status" },
+    amount: { column: "amount", operators: ["gte", "lte"] as const, description: "Filter by amount range" },
+    totalRevenue: { metric: "totalRevenue", operators: ["gte"] as const, description: "Filter by minimum total revenue" },
   },
 
   columns: {
@@ -86,13 +86,40 @@ const visitsModel = defineQueryModel({
 | `column` | `keyof TModel` | Column name for simple fields |
 | `expression` | `Sql` | Custom SQL expression (alternative to `column`) |
 | `as` | `string` | Output alias |
+| `description` | `string` | Human-readable description (used for MCP tool generation and documentation) |
 
 ### MetricDef
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `agg` | `Sql` | Aggregation expression (e.g., `count()`, `sum(col)`) |
 | `as` | `string` | Output column alias |
+| `description` | `string` | Human-readable description (used for MCP tool generation and documentation) |
+
+#### Conditional metrics
+
+To define a metric that only aggregates rows matching a condition, use ClickHouse's
+[`-If` aggregate combinators](https://clickhouse.com/docs/en/sql-reference/aggregate-functions/combinators#-if)
+directly in the `agg` expression. This makes the metric self-contained — callers don't
+need to remember to add a filter.
+
+```typescript
+metrics: {
+  // Total revenue — only from completed events
+  revenue: {
+    agg: sql.fragment`sumIf(${Events.columns.amount}, ${Events.columns.status} = 'completed')`,
+    description: "Total revenue from completed events",
+  },
+  // Completion rate
+  completionRate: {
+    agg: sql.fragment`countIf(${Events.columns.status} = 'completed') / count(*)`,
+    description: "Fraction of events that completed",
+  },
+}
+```
+
+Common `-If` combinators: `sumIf`, `countIf`, `avgIf`, `minIf`, `maxIf`, `uniqIf`, `uniqExactIf`.
+Every ClickHouse aggregate function supports the `-If` suffix.
 
 ### ColumnDef
 
@@ -121,6 +148,7 @@ const visitsModel = defineQueryModel({
 | `operators` | `readonly FilterOperator[]` | Allowed operators |
 | `transform` | `(value) => SqlValue` | Optional value transformer |
 | `inputType` | `FilterInputTypeHint` | UI hint: `"text"`, `"number"`, `"date"`, `"select"`, `"multiselect"` |
+| `description` | `string` | Human-readable description (used for MCP tool generation and documentation) |
 | `required` | `true` | Make the `eq` parameter required for MCP |
 
 ### Filter Operators
@@ -148,8 +176,8 @@ The object returned by `defineQueryModel()`.
 | `defaults` | `object` | Default query behavior |
 | `filters` | `TFilters` | Filter definitions |
 | `sortable` | `readonly TSortable[]` | Sortable field names |
-| `dimensionNames` | `readonly string[]` | Dimension key names |
-| `metricNames` | `readonly string[]` | Metric key names |
+| `dimensions` | `TDimensions \| undefined` | Dimension definitions record (derive names via `Object.keys(model.dimensions)`) |
+| `metrics` | `TMetrics \| undefined` | Metric definitions record (derive names via `Object.keys(model.metrics)`) |
 | `columnNames` | `readonly string[]` | Column key names |
 
 ### Type Inference Helpers

examples/nextjs-moose/components/report-builder/prepare-model.ts

@@ -186,8 +186,6 @@ export function prepareModel<
         inputType?: FilterInputType;
       }
     >;
-    readonly dimensionNames?: readonly string[];
-    readonly metricNames?: readonly string[];
   },
 >(queryModel: TModel, options: PrepareModelOptions = {}): ReportModel {
   const {

examples/nextjs-moose/moose/src/query-examples/model.ts

@@ -8,39 +8,77 @@ export const eventsModel = defineQueryModel({
   // Dimensions: columns for grouping and filtering
   // Key names are used as SQL aliases automatically (no `as` needed)
   dimensions: {
-    status: { column: "status" },
+    status: {
+      column: "status",
+      description: "Event processing status",
+    },
     hour: {
       expression: sql.fragment`toStartOfHour(${Events.columns.event_time})`,
       as: "time",
+      description: "Event time truncated to the hour",
     },
     day: {
       expression: sql.fragment`toDate(${Events.columns.event_time})`,
       as: "time",
+      description: "Event date (day granularity)",
     },
     month: {
       expression: sql.fragment`toStartOfMonth(${Events.columns.event_time})`,
       as: "time",
+      description: "Event date truncated to the start of the month",
     },
   },
 
   // Metrics: aggregates computed over dimensions
   // Key names are used as SQL aliases automatically (no `as` needed)
   metrics: {
-    totalEvents: { agg: sql.fragment`count(*)` },
-    totalAmount: { agg: sql.fragment`sum(${Events.columns.amount})` },
-    avgAmount: { agg: sql.fragment`avg(${Events.columns.amount})` },
-    minAmount: { agg: sql.fragment`min(${Events.columns.amount})` },
-    maxAmount: { agg: sql.fragment`max(${Events.columns.amount})` },
+    totalEvents: {
+      agg: sql.fragment`count(*)`,
+      description: "Total number of events",
+    },
+    totalAmount: {
+      agg: sql.fragment`sum(${Events.columns.amount})`,
+      description: "Sum of event amounts",
+    },
+    avgAmount: {
+      agg: sql.fragment`avg(${Events.columns.amount})`,
+      description: "Average event amount",
+    },
+    minAmount: {
+      agg: sql.fragment`min(${Events.columns.amount})`,
+      description: "Minimum event amount",
+    },
+    maxAmount: {
+      agg: sql.fragment`max(${Events.columns.amount})`,
+      description: "Maximum event amount",
+    },
     highValueRatio: {
       agg: sql.fragment`countIf(${Events.columns.amount} > 100) / count(*)`,
+      description: "Ratio of events with amount greater than 100",
     },
   },
 
   filters: {
-    timestamp: { column: "event_time", operators: ["gte", "lte"] as const },
-    status: { column: "status", operators: ["eq", "in"] as const },
-    amount: { column: "amount", operators: ["gte", "lte"] as const },
-    id: { column: "id", operators: ["eq"] as const },
+    timestamp: {
+      column: "event_time",
+      operators: ["gte", "lte"] as const,
+      description: "Filter by event timestamp range",
+    },
+    status: {
+      column: "status",
+      operators: ["eq", "in"] as const,
+      description: "Filter by event processing status",
+    },
+    amount: {
+      column: "amount",
+      operators: ["gte", "lte"] as const,
+      description: "Filter by event amount range",
+    },
+    id: {
+      column: "id",
+      operators: ["eq"] as const,
+      description: "Filter by exact event ID",
+    },
   },
 
   // Sortable fields use the key names (camelCase)

examples/nextjs-moose/moose/src/query-layer/query-model.ts

@@ -205,11 +205,6 @@ export interface QueryModel<
   /** Metric definitions */
   readonly metrics?: TMetrics;
 
-  /** Available dimension names (runtime access) */
-  readonly dimensionNames: readonly string[];
-  /** Available metric names (runtime access) */
-  readonly metricNames: readonly string[];
-
   /**
    * Type inference helpers (similar to Drizzle's $inferSelect pattern).
    * These are type-only properties that don't exist at runtime.
@@ -419,9 +414,6 @@ export function defineQueryModel<
   const dimensionNamesSet = new Set(Object.keys(normalizedDimensions));
   const metricNamesSet = new Set(Object.keys(normalizedMetrics));
 
-  const dimensionNames = Object.keys(normalizedDimensions) as readonly string[];
-  const metricNames = Object.keys(normalizedMetrics) as readonly string[];
-
   // Build field SQL expression with alias
   const buildFieldExpr = (field: FieldDef, defaultAlias: string): Sql => {
     const expr =
@@ -737,8 +729,6 @@ export function defineQueryModel<
     sortable,
     dimensions: dimensions as TDimensions | undefined,
     metrics: metrics as TMetrics | undefined,
-    dimensionNames,
-    metricNames,
     query: async (request, client: QueryClient) => {
       const result = await client.execute(toSql(request));
       return result.json();

examples/nextjs-moose/moose/src/query-layer/types.ts

@@ -84,6 +84,8 @@ export interface DimensionDef<
   expression?: Sql;
   /** Output alias for the dimension */
   as?: string;
+  /** Human-readable description (used for MCP tool generation and documentation) */
+  description?: string;
 }
 
 /**
@@ -106,6 +108,8 @@ export interface MetricDef {
   agg: Sql;
   /** Output alias for the metric (defaults to the key name if not specified) */
   as?: string;
+  /** Human-readable description (used for MCP tool generation and documentation) */
+  description?: string;
 }
 
 // =============================================================================
@@ -154,6 +158,8 @@ export interface ModelFilterDef<
    * If not specified, will be inferred from the column's ClickHouse data type.
    */
   inputType?: FilterInputTypeHint;
+  /** Human-readable description (used for MCP tool generation and documentation) */
+  description?: string;
 }
 
 // =============================================================================

packages/ts-moose-lib/src/query-layer/model-tools.ts

@@ -21,6 +21,7 @@ export interface QueryModelFilter {
   operators: readonly string[];
   inputType?: FilterInputTypeHint;
   required?: true;
+  description?: string;
 }
 
 /**
@@ -44,8 +45,8 @@ export interface QueryModelBase {
   };
   readonly filters: Record<string, QueryModelFilter>;
   readonly sortable: readonly string[];
-  readonly dimensionNames: readonly string[];
-  readonly metricNames: readonly string[];
+  readonly dimensions?: Record<string, { description?: string }>;
+  readonly metrics?: Record<string, { description?: string }>;
   readonly columnNames: readonly string[];
   toSql(request: Record<string, unknown>): Sql;
 }
@@ -66,6 +67,17 @@ function titleFromName(name: string): string {
     .replace(/\b\w/g, (c) => c.toUpperCase());
 }
 
+function buildEnumDescription(
+  metadata: Record<string, { description?: string }>,
+): string | undefined {
+  const entries = Object.entries(metadata);
+  if (entries.length === 0) return undefined;
+  const lines = entries.map(([name, def]) => {
+    return def.description ? `- ${name}: ${def.description}` : `- ${name}`;
+  });
+  return lines.join("\n");
+}
+
 /** Map FilterInputTypeHint to a base Zod type */
 function zodBaseType(inputType?: FilterInputTypeHint): z.ZodType {
   if (inputType === "number") return z.number();
@@ -161,15 +173,21 @@ export function createModelTool(
   const filterParamMap: Record<string, { filterName: string; op: string }> = {};
 
   // --- Dimensions ---
-  if (model.dimensionNames.length > 0) {
-    const names = model.dimensionNames as readonly [string, ...string[]];
-    schema.dimensions = z.array(z.enum(names)).optional();
+  const dimensionNames = Object.keys(model.dimensions ?? {});
+  if (dimensionNames.length > 0) {
+    const names = dimensionNames as [string, ...string[]];
+    const desc = buildEnumDescription(model.dimensions!);
+    const dimSchema = z.array(z.enum(names)).optional();
+    schema.dimensions = desc ? dimSchema.describe(desc) : dimSchema;
   }
 
   // --- Metrics ---
-  if (model.metricNames.length > 0) {
-    const names = model.metricNames as readonly [string, ...string[]];
-    schema.metrics = z.array(z.enum(names)).optional();
+  const metricNames = Object.keys(model.metrics ?? {});
+  if (metricNames.length > 0) {
+    const names = metricNames as [string, ...string[]];
+    const desc = buildEnumDescription(model.metrics!);
+    const metSchema = z.array(z.enum(names)).optional();
+    schema.metrics = desc ? metSchema.describe(desc) : metSchema;
   }
 
   // --- Columns ---
@@ -203,9 +221,14 @@ export function createModelTool(
 
       // Required if filter is in requiredFilters AND op is eq
       if (requiredSet.has(filterName) && op === "eq") {
-        schema[paramName] = paramType;
+        schema[paramName] =
+          filterDef.description ?
+            paramType.describe(filterDef.description)
+          : paramType;
       } else {
-        schema[paramName] = paramType.optional();
+        const opt = paramType.optional();
+        schema[paramName] =
+          filterDef.description ? opt.describe(filterDef.description) : opt;
       }
 
       filterParamMap[paramName] = { filterName, op };
@@ -227,14 +250,14 @@ export function createModelTool(
     const request: Record<string, unknown> = {};
 
     // Dimensions
-    if (model.dimensionNames.length > 0) {
+    if (dimensionNames.length > 0) {
       request.dimensions =
         (params.dimensions as string[] | undefined) ??
         mergedDefaults.dimensions;
     }
 
     // Metrics
-    if (model.metricNames.length > 0) {
+    if (metricNames.length > 0) {
       request.metrics =
         (params.metrics as string[] | undefined) ?? mergedDefaults.metrics;
     }

packages/ts-moose-lib/src/query-layer/query-model.ts

@@ -258,8 +258,6 @@ export interface QueryModel<
   readonly metrics?: TMetrics;
   readonly columns?: TColumns;
 
-  readonly dimensionNames: readonly string[];
-  readonly metricNames: readonly string[];
   readonly columnNames: readonly string[];
 
   /** Type inference helpers (similar to Drizzle's $inferSelect pattern). */
@@ -859,8 +857,6 @@ export function defineQueryModel<
     dimensions,
     metrics,
     columns: columnDefs,
-    dimensionNames,
-    metricNames,
     columnNames,
     query: async (request, client: QueryClient) => {
       const result = await client.execute(toSql(request));

packages/ts-moose-lib/src/query-layer/types.ts

@@ -74,6 +74,7 @@ export interface DimensionDef<
   column?: TKey;
   expression?: Sql;
   as?: string;
+  description?: string;
 }
 
 /**
@@ -89,6 +90,7 @@ export interface DimensionDef<
 export interface MetricDef {
   agg: Sql;
   as?: string;
+  description?: string;
 }
 
 /**
@@ -167,6 +169,7 @@ export interface ModelFilterDef<
   inputType?: FilterInputTypeHint;
   /** When true, this filter's `eq` param is required in MCP tool schemas */
   required?: true;
+  description?: string;
 }
 
 // --- Type Inference Helpers ---