@hypequery/mcp 0.1.0 → 0.3.0

package/README.md

@@ -24,7 +24,7 @@ pnpm add @hypequery/mcp
 Create `mcp-config.ts`:
 
 ```typescript
-import { MetricExecutor } from '@hypequery/datasets';
+import { createDatasetClient } from '@hypequery/datasets';
 import { createQueryBuilder } from '@hypequery/clickhouse';
 import { OrdersDataset, CustomersDataset } from './datasets/index.js';
 
@@ -45,14 +45,15 @@ export const datasets = {
   },
 };
 
-// Export your executor
-const builderFactory = createQueryBuilder({
-  host: process.env.CLICKHOUSE_HOST,
+// Export the semantic runner consumed by the MCP server
+const db = createQueryBuilder({
+  url: process.env.CLICKHOUSE_URL,
   username: process.env.CLICKHOUSE_USER,
   password: process.env.CLICKHOUSE_PASSWORD,
+  database: process.env.CLICKHOUSE_DATABASE,
 });
 
-export const executor = new MetricExecutor({ builderFactory });
+export const analytics = createDatasetClient({ queryBuilder: db });
 ```
 
 ### 2. Run the MCP Server
@@ -107,6 +108,7 @@ Lists all available datasets with their descriptions.
       "name": "orders",
       "description": "Customer orders and revenue data",
       "dimensionCount": 5,
+      "measureCount": 4,
       "metricCount": 4
     }
   ],
@@ -136,8 +138,12 @@ Gets the complete schema for a dataset.
     "region": { "type": "string", "label": "Region" },
     "status": { "type": "string", "label": "Order Status" }
   },
+  "measures": {
+    "revenue": { "aggregation": "sum", "field": "amount", "label": "Revenue" },
+    "orderCount": { "aggregation": "count", "field": "id", "label": "Order Count" }
+  },
   "metrics": {
-    "revenue": { "type": "sum", "label": "Total Revenue", "format": "currency" }
+    "totalRevenue": { "type": "metric", "aggregation": "revenue", "label": "Total Revenue" }
   }
 }
 ```
@@ -183,7 +189,7 @@ Executes a pre-defined metric query.
 
 ### `query_dataset`
 
-Executes an ad-hoc dataset query with custom dimensions and metrics.
+Executes an ad-hoc dataset query with custom dimensions and measures.
 
 **Example:**
 ```typescript
@@ -192,7 +198,7 @@ Executes an ad-hoc dataset query with custom dimensions and metrics.
   "arguments": {
     "dataset": "orders",
     "dimensions": ["region", "status"],
-    "metrics": ["revenue", "orderCount"],
+    "measures": ["revenue", "orderCount"],
     "limit": 100
   }
 }
@@ -204,15 +210,19 @@ You can also use the MCP server programmatically in your application:
 
 ```typescript
 import { createMCPServer } from '@hypequery/mcp';
-import { MetricExecutor } from '@hypequery/datasets';
+import { createDatasetClient } from '@hypequery/datasets';
 import { datasets } from './datasets/index.js';
-import { queryBuilder } from './db/index.js';
 
-const executor = new MetricExecutor({ builderFactory: queryBuilder });
+const analytics = createDatasetClient({
+  url: process.env.CLICKHOUSE_URL,
+  username: process.env.CLICKHOUSE_USER,
+  password: process.env.CLICKHOUSE_PASSWORD,
+  database: process.env.CLICKHOUSE_DATABASE,
+});
 
 const server = await createMCPServer({
   datasets,
-  executor,
+  analytics,
   name: 'my-analytics-mcp',
   version: '1.0.0',
 });
@@ -250,8 +260,8 @@ The MCP server also exposes a `dataset_guide` prompt that provides natural langu
 Your config file can use environment variables for database credentials:
 
 ```typescript
-const queryBuilder = createQueryBuilder({
-  host: process.env.CLICKHOUSE_HOST || 'localhost',
+const analytics = createDatasetClient({
+  url: process.env.CLICKHOUSE_URL || 'http://localhost:8123',
   username: process.env.CLICKHOUSE_USER || 'default',
   password: process.env.CLICKHOUSE_PASSWORD,
   database: process.env.CLICKHOUSE_DATABASE || 'default',
@@ -263,7 +273,7 @@ const queryBuilder = createQueryBuilder({
 ### MCP server not connecting
 
 1. Check that the config file path is absolute, not relative
-2. Ensure the config file exports both `datasets` and `executor`
+2. Ensure the config file exports both `datasets` and `analytics`
 3. Check Claude Desktop logs for errors
 
 ### Queries failing

package/dist/bin.d.ts

@@ -3,10 +3,10 @@
  * MCP Server CLI
  *
  * This is a standalone executable that starts the MCP server.
- * Users can configure it by creating a config file that exports datasets and executor.
+ * Users can configure it by creating a config file that exports datasets and analytics.
  *
  * Usage:
- *   npx hypequery-mcp --config ./mcp-config.js
+ *   npx hypequery-mcp --config ./mcp-config.mjs
  */
 export {};
 //# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -3,10 +3,10 @@
  * MCP Server CLI
  *
  * This is a standalone executable that starts the MCP server.
- * Users can configure it by creating a config file that exports datasets and executor.
+ * Users can configure it by creating a config file that exports datasets and analytics.
  *
  * Usage:
- *   npx hypequery-mcp --config ./mcp-config.js
+ *   npx hypequery-mcp --config ./mcp-config.mjs
  */
 import { createMCPServer } from './server.js';
 import { pathToFileURL } from 'url';
@@ -29,29 +29,29 @@ async function main() {
     if (configIndex === -1 || !args[configIndex + 1]) {
         console.error('Error: --config flag is required');
         console.error('');
-        console.error('Usage: hypequery-mcp --config ./mcp-config.js');
+        console.error('Usage: hypequery-mcp --config ./mcp-config.mjs');
         console.error('');
-        console.error('The config file should export { datasets, executor }:');
+        console.error('The config file should export { datasets, analytics }:');
         console.error('');
         console.error('  export const datasets = { ... };');
-        console.error('  export const executor = new MetricExecutor(...);');
+        console.error('  export const analytics = createDatasetClient({ ... });');
         process.exit(1);
     }
     const configPath = resolve(process.cwd(), args[configIndex + 1]);
     try {
         // Dynamic import of the config file
         const configModule = await import(pathToFileURL(configPath).href);
-        const { datasets, executor } = configModule;
+        const { datasets, analytics } = configModule;
         if (!datasets) {
             throw new Error('Config file must export "datasets"');
         }
-        if (!executor) {
-            throw new Error('Config file must export "executor"');
+        if (!analytics) {
+            throw new Error('Config file must export "analytics"');
         }
         // Create and start the MCP server
         await createMCPServer({
             datasets,
-            executor,
+            analytics,
             name: 'hypequery-mcp-server',
             version: '0.1.0',
         });

package/dist/index.d.ts

@@ -10,6 +10,6 @@ export { getDatasetSchemaTool } from './tools/introspect.js';
 export { queryMetricTool } from './tools/query-metric.js';
 export { queryDatasetTool } from './tools/query-dataset.js';
 export { datasetGuidePrompt } from './prompts/dataset-guide.js';
-export type { DatasetRegistry, QueryMetricArgs, QueryDatasetArgs, GetDatasetSchemaArgs, MCPToolResponse, DatasetSchema, DimensionSchema, MetricSchema, RelationshipSchema, DatasetListItem, DatasetsListResponse, QueryResultResponse, QueryResultMeta, } from './types.js';
+export type { DatasetRegistry, QueryMetricArgs, QueryDatasetArgs, QueryToolOptions, GetDatasetSchemaArgs, MCPToolResponse, DatasetSchema, DimensionSchema, MetricSchema, RelationshipSchema, DatasetListItem, DatasetsListResponse, QueryResultResponse, QueryResultMeta, } from './types.js';
 export { MAX_QUERY_LIMIT, DEFAULT_QUERY_LIMIT } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/prompts/dataset-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataset-guide.d.ts","sourceRoot":"","sources":["../../src/prompts/dataset-guide.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,MAAM;;;;;;;;EAmIjF"}
+{"version":3,"file":"dataset-guide.d.ts","sourceRoot":"","sources":["../../src/prompts/dataset-guide.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,CAAC,EAAE,MAAM;;;;;;;;EAuIjF"}

package/dist/prompts/dataset-guide.js

@@ -12,12 +12,16 @@ export function datasetGuidePrompt(datasets, datasetName) {
         const datasetAny = dataset;
         // Generate dataset-specific guide
         const dimensions = datasetAny.dimensions ? Object.keys(datasetAny.dimensions) : [];
+        const measures = datasetAny.measures ? Object.keys(datasetAny.measures) : [];
         const metrics = datasetAny.metrics ? Object.keys(datasetAny.metrics) : [];
         const guide = `# Querying the ${datasetName} dataset
 
 ## Available Dimensions
 ${dimensions.map((d) => `- ${d}`).join('\n')}
 
+## Available Measures
+${measures.map((m) => `- ${m}`).join('\n')}
+
 ## Available Metrics
 ${metrics.map((m) => `- ${m}`).join('\n')}
 
@@ -46,7 +50,7 @@ Show "${metrics[0] || 'revenue'}" by month for the last year
 ## Tips
 - Use natural language to describe what you want to see
 - The system will translate your query into the appropriate dataset query
-- You can filter, group, and aggregate data using the available dimensions and metrics
+- You can filter, group, and aggregate data using the available dimensions, measures, and metrics
 `;
         return {
             messages: [
@@ -70,9 +74,9 @@ ${datasetList.map((name) => `- ${name}`).join('\n')}
 ## How to Query
 
 1. **List datasets**: Use the \`list_datasets\` tool to see all available datasets
-2. **Get schema**: Use the \`get_dataset_schema\` tool to see dimensions and metrics for a dataset
+2. **Get schema**: Use the \`get_dataset_schema\` tool to see dimensions, measures, and metrics for a dataset
 3. **Query metric**: Use the \`query_metric\` tool to execute a pre-defined metric
-4. **Query dataset**: Use the \`query_dataset\` tool for ad-hoc queries with custom dimensions and metrics
+4. **Query dataset**: Use the \`query_dataset\` tool for ad-hoc queries with custom dimensions and measures
 
 ## Example Workflow
 

package/dist/server.d.ts

@@ -4,7 +4,7 @@
  * Exposes datasets and metrics via Model Context Protocol (MCP)
  * for use with Claude Desktop, Cursor, and other MCP-compatible tools.
  */
-import type { MetricExecutor } from '@hypequery/datasets';
+import type { DatasetClient } from '@hypequery/datasets';
 import type { DatasetRegistry } from './types.js';
 export interface MCPServerConfig {
     /**
@@ -12,9 +12,9 @@ export interface MCPServerConfig {
      */
     datasets: DatasetRegistry;
     /**
-     * Metric executor for running queries
+     * Semantic analytics for running metric and dataset queries
      */
-    executor: MetricExecutor;
+    analytics: DatasetClient;
     /**
      * Server name (shown in MCP client)
      */
@@ -23,6 +23,10 @@ export interface MCPServerConfig {
      * Server version
      */
     version?: string;
+    /**
+     * Trusted tenant id used to scope tenant-keyed datasets.
+     */
+    tenantId?: string;
 }
 export declare class HypequeryMCPServer {
     private server;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;OAEG;IACH,QAAQ,EAAE,cAAc,CAAC;IAEzB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAmBnC,OAAO,CAAC,aAAa;IA6NrB;;OAEG;IACG,KAAK;IAQX;;OAEG;IACG,IAAI;CAGX;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAI1F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAMzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC;IAEzB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiCD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAoBnC,OAAO,CAAC,aAAa;IAuOrB;;OAEG;IACG,KAAK;IAQX;;OAEG;IACG,IAAI;CAGX;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAI1F"}

package/dist/server.js

@@ -12,10 +12,34 @@ import { getDatasetSchemaTool } from './tools/introspect.js';
 import { queryMetricTool } from './tools/query-metric.js';
 import { queryDatasetTool } from './tools/query-dataset.js';
 import { datasetGuidePrompt } from './prompts/dataset-guide.js';
+function isRecord(value) {
+    return !!value && typeof value === 'object';
+}
+function getTenantKey(dataset) {
+    if (!isRecord(dataset)) {
+        return undefined;
+    }
+    const config = dataset.config;
+    const configTenantKey = isRecord(config) ? config.tenantKey : undefined;
+    const tenantKey = dataset.tenantKey ?? configTenantKey;
+    return typeof tenantKey === 'string' && tenantKey.length > 0 ? tenantKey : undefined;
+}
+function validateTenantConfig(config) {
+    if (config.tenantId) {
+        return;
+    }
+    const tenantScopedDatasets = Object.entries(config.datasets ?? {})
+        .filter(([, ds]) => getTenantKey(ds))
+        .map(([name]) => name);
+    if (tenantScopedDatasets.length > 0) {
+        throw new Error(`MCP server tenantId is required for tenant-scoped datasets: ${tenantScopedDatasets.join(', ')}`);
+    }
+}
 export class HypequeryMCPServer {
     server;
     config;
     constructor(config) {
+        validateTenantConfig(config);
         this.config = config;
         this.server = new Server({
             name: config.name ?? 'hypequery-mcp-server',
@@ -42,7 +66,7 @@ export class HypequeryMCPServer {
                 },
                 {
                     name: 'get_dataset_schema',
-                    description: 'Get the schema (dimensions, metrics, relationships) for a specific dataset',
+                    description: 'Get the schema (dimensions, measures, named metrics, filters, relationships) for a specific dataset',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -110,13 +134,17 @@ export class HypequeryMCPServer {
                                 type: 'number',
                                 description: 'Maximum number of rows to return (optional)',
                             },
+                            offset: {
+                                type: 'number',
+                                description: 'Number of rows to skip before returning results (optional)',
+                            },
                         },
                         required: ['dataset', 'metric'],
                     },
                 },
                 {
                     name: 'query_dataset',
-                    description: 'Execute an ad-hoc dataset query with custom dimensions and metrics',
+                    description: 'Execute an ad-hoc dataset query with custom dimensions and measures',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -129,10 +157,10 @@ export class HypequeryMCPServer {
                                 items: { type: 'string' },
                                 description: 'Dimensions to select',
                             },
-                            metrics: {
+                            measures: {
                                 type: 'array',
                                 items: { type: 'string' },
-                                description: 'Metrics to calculate',
+                                description: 'Measures to calculate',
                             },
                             filters: {
                                 type: 'array',
@@ -171,6 +199,10 @@ export class HypequeryMCPServer {
                                 type: 'number',
                                 description: 'Maximum number of rows to return (optional)',
                             },
+                            offset: {
+                                type: 'number',
+                                description: 'Number of rows to skip before returning results (optional)',
+                            },
                         },
                         required: ['dataset'],
                     },
@@ -187,9 +219,9 @@ export class HypequeryMCPServer {
                     case 'get_dataset_schema':
                         return await getDatasetSchemaTool(this.config.datasets, args);
                     case 'query_metric':
-                        return await queryMetricTool(this.config.datasets, this.config.executor, args);
+                        return await queryMetricTool(this.config.datasets, this.config.analytics, args, { tenantId: this.config.tenantId });
                     case 'query_dataset':
-                        return await queryDatasetTool(this.config.datasets, this.config.executor, args);
+                        return await queryDatasetTool(this.config.datasets, this.config.analytics, args, { tenantId: this.config.tenantId });
                     default:
                         throw new Error(`Unknown tool: ${name}`);
                 }

package/dist/tools/args.d.ts

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+import { type MetricFilter } from '@hypequery/datasets';
+export declare const queryMetricArgsSchema: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"]>;
+        value: z.ZodEffects<z.ZodAny, any, any>;
+    }, "strict", z.ZodTypeAny, {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }, {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }>, "many">>;
+    grain: z.ZodOptional<z.ZodEnum<["day", "week", "month", "quarter", "year"]>>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strict", z.ZodTypeAny, {
+        field: string;
+        direction: "asc" | "desc";
+    }, {
+        field: string;
+        direction: "asc" | "desc";
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+} & {
+    dataset: z.ZodOptional<z.ZodString>;
+    metric: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    dataset?: string | undefined;
+    metric?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, {
+    dataset?: string | undefined;
+    metric?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}>;
+export declare const queryDatasetArgsSchema: z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        operator: z.ZodEnum<["eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "between", "like"]>;
+        value: z.ZodEffects<z.ZodAny, any, any>;
+    }, "strict", z.ZodTypeAny, {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }, {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }>, "many">>;
+    grain: z.ZodOptional<z.ZodEnum<["day", "week", "month", "quarter", "year"]>>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strict", z.ZodTypeAny, {
+        field: string;
+        direction: "asc" | "desc";
+    }, {
+        field: string;
+        direction: "asc" | "desc";
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+} & {
+    dataset: z.ZodOptional<z.ZodString>;
+    measures: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    dataset?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    measures?: string[] | undefined;
+}, {
+    dataset?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        field: string;
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    measures?: string[] | undefined;
+}>;
+export declare function parseToolArgs<T>(schema: z.ZodType<T>, toolName: string, args: unknown): T;
+export declare function toMetricFilters(filters?: Array<{
+    field: string;
+    operator: MetricFilter['operator'];
+    value?: unknown;
+}>): MetricFilter[];
+//# sourceMappingURL=args.d.ts.map

package/dist/tools/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/tools/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA6B,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAuBnF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGhC,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGjC,CAAC;AAWH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAMzF;AAED,wBAAgB,eAAe,CAC7B,OAAO,GAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAM,GAC1F,YAAY,EAAE,CAMhB"}

package/dist/tools/args.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { SEMANTIC_FILTER_OPERATORS } from '@hypequery/datasets';
+import { MAX_QUERY_LIMIT } from '../types.js';
+const filterSchema = z.object({
+    field: z.string().min(1),
+    operator: z.enum(SEMANTIC_FILTER_OPERATORS),
+    value: z.any().refine(value => value !== undefined, 'Required'),
+}).strict();
+const orderBySchema = z.object({
+    field: z.string().min(1),
+    direction: z.enum(['asc', 'desc']),
+}).strict();
+const baseQuerySchema = z.object({
+    dimensions: z.array(z.string().min(1)).optional(),
+    filters: z.array(filterSchema).optional(),
+    grain: z.enum(['day', 'week', 'month', 'quarter', 'year']).optional(),
+    orderBy: z.array(orderBySchema).optional(),
+    limit: z.number().int().nonnegative().max(MAX_QUERY_LIMIT).optional(),
+    offset: z.number().int().nonnegative().optional(),
+}).strict();
+export const queryMetricArgsSchema = baseQuerySchema.extend({
+    dataset: z.string().min(1).optional(),
+    metric: z.string().min(1).optional(),
+});
+export const queryDatasetArgsSchema = baseQuerySchema.extend({
+    dataset: z.string().min(1).optional(),
+    measures: z.array(z.string().min(1)).optional(),
+});
+function formatZodError(error) {
+    return error.issues
+        .map(issue => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : 'arguments';
+        return `${path}: ${issue.message}`;
+    })
+        .join('; ');
+}
+export function parseToolArgs(schema, toolName, args) {
+    const result = schema.safeParse(args);
+    if (!result.success) {
+        throw new Error(`Invalid ${toolName} arguments: ${formatZodError(result.error)}`);
+    }
+    return result.data;
+}
+export function toMetricFilters(filters = []) {
+    return filters.map(filter => ({
+        field: filter.field,
+        operator: filter.operator,
+        value: filter.value,
+    }));
+}

package/dist/tools/introspect.d.ts

@@ -1,8 +1,8 @@
 /**
  * Get Dataset Schema Tool
  *
- * Returns the complete schema for a dataset including dimensions, metrics,
- * and relationships.
+ * Returns the complete schema for a dataset including dimensions, measures,
+ * named metrics, filters, and relationships.
  */
 import type { DatasetRegistry, MCPToolResponse } from '../types.js';
 export declare function getDatasetSchemaTool(datasets: DatasetRegistry, args: unknown): Promise<MCPToolResponse>;

package/dist/tools/introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../../src/tools/introspect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAwB,eAAe,EAAoE,MAAM,aAAa,CAAC;AAE5J,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CA6E1B"}
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../../src/tools/introspect.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAOhB,MAAM,aAAa,CAAC;AAMrB,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CA+K1B"}

package/dist/tools/introspect.js

@@ -1,9 +1,13 @@
 /**
  * Get Dataset Schema Tool
  *
- * Returns the complete schema for a dataset including dimensions, metrics,
- * and relationships.
+ * Returns the complete schema for a dataset including dimensions, measures,
+ * named metrics, filters, and relationships.
  */
+import { getDatasetCatalog } from '@hypequery/datasets';
+function isDatasetInstance(value) {
+    return !!value && typeof value === 'object' && value.__type === 'dataset';
+}
 export async function getDatasetSchemaTool(datasets, args) {
     // Parse and validate args
     const validatedArgs = args;
@@ -15,7 +19,6 @@ export async function getDatasetSchemaTool(datasets, args) {
     if (!dataset) {
         throw new Error(`Dataset not found: ${datasetName}`);
     }
-    // Build schema response with proper types
     const datasetAny = dataset;
     const schema = {
         name: datasetName,
@@ -24,24 +27,129 @@ export async function getDatasetSchemaTool(datasets, args) {
         timeKey: datasetAny.timeKey || datasetAny.config?.timeKey || null,
         tenantKey: datasetAny.tenantKey || datasetAny.config?.tenantKey || null,
         dimensions: {},
+        measures: {},
         metrics: {},
+        filters: {},
         relationships: {},
+        limits: datasetAny.limits,
     };
-    // Extract dimensions with proper typing
-    if (datasetAny.dimensions) {
-        for (const [name, dimension] of Object.entries(datasetAny.dimensions)) {
+    if (isDatasetInstance(dataset)) {
+        const catalog = getDatasetCatalog(dataset);
+        schema.source = catalog.source;
+        schema.timeKey = catalog.timeKey ?? null;
+        schema.tenantKey = catalog.tenantKey ?? null;
+        schema.limits = catalog.limits;
+        for (const [name, dimension] of Object.entries(catalog.dimensions)) {
             const dimSchema = {
-                type: dimension.fieldType || dimension.type || 'unknown',
-                column: dimension.column || name,
+                type: dimension.type,
+                column: dimension.column ?? name,
+                sql: dimension.sql ?? null,
                 label: dimension.label || name,
                 description: dimension.description || '',
-                examples: dimension.examples || [],
+                examples: [],
+                filterable: dimension.filterable,
+                groupable: dimension.groupable,
             };
             schema.dimensions[name] = dimSchema;
         }
+        for (const [name, measure] of Object.entries(catalog.measures)) {
+            const measureSchema = {
+                aggregation: measure.aggregation,
+                field: measure.field,
+                sql: measure.sql ?? null,
+                label: measure.label || name,
+                description: measure.description || '',
+            };
+            schema.measures[name] = measureSchema;
+        }
+        for (const [name, filter] of Object.entries(catalog.filters)) {
+            const filterSchema = {
+                field: filter.field,
+                label: filter.label || name,
+                description: filter.description || '',
+                operators: filter.operators ? [...filter.operators] : null,
+            };
+            schema.filters[name] = filterSchema;
+        }
+        for (const [name, metric] of Object.entries(catalog.metrics)) {
+            const metSchema = {
+                type: metric.kind,
+                aggregation: metric.measures?.join(', ') || '',
+                label: metric.label || name,
+                description: metric.description || '',
+                format: null,
+            };
+            schema.metrics[name] = metSchema;
+        }
+        for (const [name, relationship] of Object.entries(catalog.relationships)) {
+            const relSchema = {
+                type: relationship.kind,
+                target: relationship.target,
+                from: relationship.from,
+                to: relationship.to,
+                execution: relationship.execution,
+                description: '',
+            };
+            schema.relationships[name] = relSchema;
+        }
+    }
+    else {
+        // Legacy object-shaped fixtures/configs.
+        if (datasetAny.dimensions) {
+            for (const [name, dimension] of Object.entries(datasetAny.dimensions)) {
+                const dimSchema = {
+                    type: dimension.fieldType || dimension.type || 'unknown',
+                    column: dimension.column || name,
+                    sql: dimension.sql || null,
+                    label: dimension.label || name,
+                    description: dimension.description || '',
+                    examples: dimension.examples || [],
+                    filterable: dimension.filterable !== false,
+                    groupable: dimension.groupable !== false,
+                };
+                schema.dimensions[name] = dimSchema;
+            }
+        }
+        if (datasetAny.measures) {
+            for (const [name, measure] of Object.entries(datasetAny.measures)) {
+                const measureSchema = {
+                    aggregation: measure.aggregation || measure.type || 'unknown',
+                    field: measure.field || name,
+                    sql: measure.sql || null,
+                    label: measure.label || name,
+                    description: measure.description || '',
+                };
+                schema.measures[name] = measureSchema;
+            }
+        }
+        if (datasetAny.filters) {
+            for (const [name, filter] of Object.entries(datasetAny.filters)) {
+                const filterSchema = {
+                    field: filter.field || name,
+                    label: filter.label || name,
+                    description: filter.description || '',
+                    operators: filter.operators || null,
+                };
+                schema.filters[name] = filterSchema;
+            }
+        }
+        if (datasetAny.relationships) {
+            for (const [name, relationship] of Object.entries(datasetAny.relationships)) {
+                const rel = relationship;
+                const relSchema = {
+                    type: rel.type || rel.kind || 'unknown',
+                    target: typeof rel.target === 'function' ? rel.target()?.name || '' : rel.target || rel.dataset?.name || '',
+                    from: rel.from,
+                    to: rel.to,
+                    execution: rel.execution,
+                    description: rel.description || '',
+                };
+                schema.relationships[name] = relSchema;
+            }
+        }
     }
-    // Extract metrics with proper typing
-    if (datasetAny.metrics) {
+    // Backward compatibility for legacy object-shaped dataset fixtures.
+    if (!isDatasetInstance(dataset) && datasetAny.metrics) {
         for (const [name, metric] of Object.entries(datasetAny.metrics)) {
             const metSchema = {
                 type: metric.spec?.__type || metric.type || 'unknown',
@@ -53,18 +161,6 @@ export async function getDatasetSchemaTool(datasets, args) {
             schema.metrics[name] = metSchema;
         }
     }
-    // Extract relationships with proper typing
-    if (datasetAny.relationships) {
-        for (const [name, relationship] of Object.entries(datasetAny.relationships)) {
-            const rel = relationship;
-            const relSchema = {
-                type: rel.type || rel.kind || 'unknown',
-                target: typeof rel.target === 'function' ? rel.target()?.name || '' : rel.target || rel.dataset?.name || '',
-                description: rel.description || '',
-            };
-            schema.relationships[name] = relSchema;
-        }
-    }
     return {
         content: [
             {

package/dist/tools/list-datasets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-datasets.d.ts","sourceRoot":"","sources":["../../src/tools/list-datasets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAyC,MAAM,aAAa,CAAC;AAE3G,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA6B1F"}
+{"version":3,"file":"list-datasets.d.ts","sourceRoot":"","sources":["../../src/tools/list-datasets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAyC,MAAM,aAAa,CAAC;AAM3G,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA2C1F"}

package/dist/tools/list-datasets.js

@@ -3,17 +3,33 @@
  *
  * Returns a list of all available datasets with their descriptions.
  */
+import { getDatasetCatalog } from '@hypequery/datasets';
+function isDatasetInstance(value) {
+    return !!value && typeof value === 'object' && value.__type === 'dataset';
+}
 export async function listDatasetsTool(datasets) {
     const datasetList = Object.entries(datasets).map(([name, dataset]) => {
         const datasetAny = dataset;
         // Try to extract description from dataset instance
         const description = datasetAny.description || datasetAny.config?.description || 'No description available';
+        if (isDatasetInstance(dataset)) {
+            const catalog = getDatasetCatalog(dataset);
+            return {
+                name,
+                description,
+                dimensionCount: Object.keys(catalog.dimensions).length,
+                measureCount: Object.keys(catalog.measures).length,
+                metricCount: Object.keys(catalog.metrics).length,
+            };
+        }
         const dimensionCount = datasetAny.dimensions ? Object.keys(datasetAny.dimensions).length : 0;
+        const measureCount = datasetAny.measures ? Object.keys(datasetAny.measures).length : 0;
         const metricCount = datasetAny.metrics ? Object.keys(datasetAny.metrics).length : 0;
         return {
             name,
             description,
             dimensionCount,
+            measureCount,
             metricCount,
         };
     });

package/dist/tools/query-dataset.d.ts

@@ -1,9 +1,9 @@
 /**
  * Query Dataset Tool
  *
- * Executes an ad-hoc dataset query with custom dimensions and metrics.
+ * Executes an ad-hoc dataset query with custom dimensions and measures.
  */
-import type { MetricExecutor } from '@hypequery/datasets';
-import type { DatasetRegistry, MCPToolResponse } from '../types.js';
-export declare function queryDatasetTool(datasets: DatasetRegistry, executor: MetricExecutor, args: unknown): Promise<MCPToolResponse>;
+import type { DatasetClient } from '@hypequery/datasets';
+import type { DatasetRegistry, MCPToolResponse, QueryToolOptions } from '../types.js';
+export declare function queryDatasetTool(datasets: DatasetRegistry, analytics: DatasetClient, args: unknown, options?: QueryToolOptions): Promise<MCPToolResponse>;
 //# sourceMappingURL=query-dataset.d.ts.map

package/dist/tools/query-dataset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-dataset.d.ts","sourceRoot":"","sources":["../../src/tools/query-dataset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,eAAe,EAAoB,eAAe,EAAwC,MAAM,aAAa,CAAC;AAE5H,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CAgE1B"}
+{"version":3,"file":"query-dataset.d.ts","sourceRoot":"","sources":["../../src/tools/query-dataset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3G,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}

package/dist/tools/query-dataset.js

@@ -1,13 +1,12 @@
 /**
  * Query Dataset Tool
  *
- * Executes an ad-hoc dataset query with custom dimensions and metrics.
+ * Executes an ad-hoc dataset query with custom dimensions and measures.
  */
-import { runDatasetQuery } from '@hypequery/datasets/internal';
-export async function queryDatasetTool(datasets, executor, args) {
-    // Parse and validate args
-    const validatedArgs = args;
-    const { dataset: datasetName, dimensions, metrics, filters, grain, orderBy, limit } = validatedArgs;
+import { parseToolArgs, queryDatasetArgsSchema, toMetricFilters } from './args.js';
+export async function queryDatasetTool(datasets, analytics, args, options = {}) {
+    const validatedArgs = parseToolArgs(queryDatasetArgsSchema, 'query_dataset', args);
+    const { dataset: datasetName, dimensions, measures, filters, grain, orderBy, limit, offset } = validatedArgs;
     if (!datasetName) {
         throw new Error('dataset parameter is required');
     }
@@ -15,30 +14,28 @@ export async function queryDatasetTool(datasets, executor, args) {
     if (!dataset) {
         throw new Error(`Dataset not found: ${datasetName}`);
     }
-    if (!dimensions?.length && !metrics?.length) {
-        throw new Error('At least one dimension or metric must be specified');
+    if (!dimensions?.length && !measures?.length) {
+        throw new Error('At least one dimension or measure must be specified');
     }
     // Build the query with proper types
     const query = {
         dimensions: dimensions || [],
-        measures: metrics || [],
-        filters: filters || [],
+        measures: measures || [],
+        filters: toMetricFilters(filters),
         orderBy: orderBy || [],
     };
     if (grain) {
         query.by = grain;
     }
-    // Apply limit with maximum cap
-    const MAX_LIMIT = 10000;
     if (limit !== undefined) {
-        query.limit = Math.min(limit, MAX_LIMIT);
+        query.limit = limit;
     }
-    const result = await runDatasetQuery(dataset, query, {
-        builderFactory: executor.getBuilderFactory(),
-        context: {
-            runtime: {
-                tenant: undefined,
-            },
+    if (offset !== undefined) {
+        query.offset = offset;
+    }
+    const result = await analytics.execute(dataset, query, {
+        runtime: {
+            tenant: options.tenantId ? { id: options.tenantId } : undefined,
         },
     });
     // Format the response with proper types
@@ -48,6 +45,7 @@ export async function queryDatasetTool(datasets, executor, args) {
             sql: result.meta?.sql,
             timingMs: result.meta?.timingMs,
             rowCount: result.data.length,
+            ...(result.meta?.pagination ? { pagination: result.meta.pagination } : {}),
         },
     };
     return {

package/dist/tools/query-metric.d.ts

@@ -3,7 +3,7 @@
  *
  * Executes a metric query with optional dimensions, filters, grain, and sorting.
  */
-import type { MetricExecutor } from '@hypequery/datasets';
-import type { DatasetRegistry, MCPToolResponse } from '../types.js';
-export declare function queryMetricTool(datasets: DatasetRegistry, executor: MetricExecutor, args: unknown): Promise<MCPToolResponse>;
+import type { DatasetClient } from '@hypequery/datasets';
+import type { DatasetRegistry, MCPToolResponse, QueryToolOptions } from '../types.js';
+export declare function queryMetricTool(datasets: DatasetRegistry, analytics: DatasetClient, args: unknown, options?: QueryToolOptions): Promise<MCPToolResponse>;
 //# sourceMappingURL=query-metric.d.ts.map

package/dist/tools/query-metric.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-metric.d.ts","sourceRoot":"","sources":["../../src/tools/query-metric.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAe,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAmB,eAAe,EAAwC,MAAM,aAAa,CAAC;AAE3H,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CAqE1B"}
+{"version":3,"file":"query-metric.d.ts","sourceRoot":"","sources":["../../src/tools/query-metric.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3G,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAqE1B"}

package/dist/tools/query-metric.js

@@ -3,10 +3,10 @@
  *
  * Executes a metric query with optional dimensions, filters, grain, and sorting.
  */
-export async function queryMetricTool(datasets, executor, args) {
-    // Parse and validate args
-    const validatedArgs = args;
-    const { dataset: datasetName, metric: metricName, dimensions, filters, grain, orderBy, limit } = validatedArgs;
+import { parseToolArgs, queryMetricArgsSchema, toMetricFilters } from './args.js';
+export async function queryMetricTool(datasets, analytics, args, options = {}) {
+    const validatedArgs = parseToolArgs(queryMetricArgsSchema, 'query_metric', args);
+    const { dataset: datasetName, metric: metricName, dimensions, filters, grain, orderBy, limit, offset } = validatedArgs;
     if (!datasetName) {
         throw new Error('dataset parameter is required');
     }
@@ -25,22 +25,22 @@ export async function queryMetricTool(datasets, executor, args) {
     // Build the query with proper types
     const query = {
         dimensions: dimensions || [],
-        filters: filters || [],
+        filters: toMetricFilters(filters),
         orderBy: orderBy || [],
     };
     if (grain) {
         query.by = grain;
     }
-    // Apply limit with maximum cap
-    const MAX_LIMIT = 10000;
     if (limit !== undefined) {
-        query.limit = Math.min(limit, MAX_LIMIT);
+        query.limit = limit;
+    }
+    if (offset !== undefined) {
+        query.offset = offset;
     }
     // Execute the query
-    const result = await executor.run(metric, query, {
+    const result = await analytics.execute(metric, query, {
         runtime: {
-            builderFactory: executor.getBuilderFactory(),
-            tenant: undefined,
+            tenant: options.tenantId ? { id: options.tenantId } : undefined,
         },
     });
     // Format the response with proper types
@@ -50,6 +50,7 @@ export async function queryMetricTool(datasets, executor, args) {
             sql: result.meta?.sql,
             timingMs: result.meta?.timingMs,
             rowCount: result.data.length,
+            ...(result.meta?.pagination ? { pagination: result.meta.pagination } : {}),
         },
     };
     return {

package/dist/types.d.ts

@@ -1,12 +1,11 @@
 /**
  * Type definitions for MCP Server
  */
-import type { MetricFilter, TimeGrain, MetricOrderBy } from '@hypequery/datasets';
+import type { AnyDatasetInstance, MetricFilter, TimeGrain, MetricOrderBy } from '@hypequery/datasets';
 /**
  * Registry of datasets - maps dataset names to dataset instances
- * Using flexible type to accommodate actual dataset structure
  */
-export type DatasetRegistry = Record<string, Record<string, unknown>>;
+export type DatasetRegistry = Record<string, AnyDatasetInstance | Record<string, unknown>>;
 /**
  * Arguments for query_metric tool
  */
@@ -18,6 +17,7 @@ export interface QueryMetricArgs {
     grain?: TimeGrain;
     orderBy?: MetricOrderBy[];
     limit?: number;
+    offset?: number;
 }
 /**
  * Arguments for query_dataset tool
@@ -25,11 +25,15 @@ export interface QueryMetricArgs {
 export interface QueryDatasetArgs {
     dataset: string;
     dimensions?: string[];
-    metrics?: string[];
+    measures?: string[];
     filters?: MetricFilter[];
     grain?: TimeGrain;
     orderBy?: MetricOrderBy[];
     limit?: number;
+    offset?: number;
+}
+export interface QueryToolOptions {
+    tenantId?: string;
 }
 /**
  * Arguments for get_dataset_schema tool
@@ -59,18 +63,48 @@ export interface DatasetSchema {
     timeKey: string | null;
     tenantKey: string | null;
     dimensions: Record<string, DimensionSchema>;
+    measures: Record<string, MeasureSchema>;
     metrics: Record<string, MetricSchema>;
+    filters: Record<string, FilterSchema>;
     relationships: Record<string, RelationshipSchema>;
+    limits?: {
+        maxDimensions?: number;
+        maxMeasures?: number;
+        maxFilters?: number;
+        maxResultSize?: number;
+    };
 }
 /**
  * Dimension schema in response
  */
 export interface DimensionSchema {
     type: string;
-    column: string;
+    column: string | null;
+    sql: string | null;
     label: string;
     description: string;
     examples: string[];
+    filterable: boolean;
+    groupable: boolean;
+}
+/**
+ * Measure schema in response
+ */
+export interface MeasureSchema {
+    aggregation: string;
+    field: string;
+    sql: string | null;
+    label: string;
+    description: string;
+}
+/**
+ * Filter schema in response
+ */
+export interface FilterSchema {
+    field: string;
+    label: string;
+    description: string;
+    operators: string[] | null;
 }
 /**
  * Metric schema in response
@@ -88,6 +122,9 @@ export interface MetricSchema {
 export interface RelationshipSchema {
     type: string;
     target: string;
+    from?: string;
+    to?: string;
+    execution?: string;
     description: string;
 }
 /**
@@ -97,6 +134,7 @@ export interface DatasetListItem {
     name: string;
     description: string;
     dimensionCount: number;
+    measureCount?: number;
     metricCount: number;
 }
 /**
@@ -113,6 +151,15 @@ export interface QueryResultMeta {
     sql?: string;
     timingMs?: number;
     rowCount: number;
+    /**
+     * Offset pagination state. Present when the query specified a `limit`.
+     * `hasMore` lets callers know whether to request the next `offset` page.
+     */
+    pagination?: {
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
 }
 /**
  * Query result response

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Model Context Protocol (MCP) server for Hypequery semantic layer",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,9 +20,9 @@
     "dist"
   ],
   "dependencies": {
+    "@hypequery/datasets": "^0.2.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.8",
-    "@hypequery/datasets": "0.1.0"
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",