@hypequery/mcp 0.1.0 → 0.2.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
@@ -204,15 +205,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 +255,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 +268,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/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;AA6BD,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,31 @@ 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) {
+    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',
@@ -110,6 +131,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', 'metric'],
                     },
@@ -171,6 +196,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 +216,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, {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        value?: any;
+    }, {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        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?: {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        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?: {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        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, {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        value?: any;
+    }, {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        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>;
+    metrics: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    dataset?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    metrics?: string[] | undefined;
+}, {
+    dataset?: string | undefined;
+    dimensions?: string[] | undefined;
+    filters?: {
+        field: string;
+        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "between" | "like";
+        value?: any;
+    }[] | undefined;
+    grain?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    orderBy?: {
+        field: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    metrics?: 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,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAuBxD,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,49 @@
+import { z } from 'zod';
+import { MAX_QUERY_LIMIT } from '../types.js';
+const filterSchema = z.object({
+    field: z.string().min(1),
+    operator: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like']),
+    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(),
+    metrics: 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/query-dataset.d.ts

@@ -3,7 +3,7 @@
  *
  * Executes an ad-hoc dataset query with custom dimensions and metrics.
  */
-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

@@ -3,11 +3,10 @@
  *
  * Executes an ad-hoc dataset query with custom dimensions and metrics.
  */
-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, metrics, filters, grain, orderBy, limit, offset } = validatedArgs;
     if (!datasetName) {
         throw new Error('dataset parameter is required');
     }
@@ -22,23 +21,21 @@ export async function queryDatasetTool(datasets, executor, args) {
     const query = {
         dimensions: dimensions || [],
         measures: metrics || [],
-        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;
     }
-    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

@@ -18,6 +18,7 @@ export interface QueryMetricArgs {
     grain?: TimeGrain;
     orderBy?: MetricOrderBy[];
     limit?: number;
+    offset?: number;
 }
 /**
  * Arguments for query_dataset tool
@@ -30,6 +31,10 @@ export interface QueryDatasetArgs {
     grain?: TimeGrain;
     orderBy?: MetricOrderBy[];
     limit?: number;
+    offset?: number;
+}
+export interface QueryToolOptions {
+    tenantId?: string;
 }
 /**
  * Arguments for get_dataset_schema tool
@@ -113,6 +118,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.2.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.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.8",
-    "@hypequery/datasets": "0.1.0"
+    "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",