@hypequery/mcp 0.0.0-canary-20260603161950

package/dist/prompts/dataset-guide.js

@@ -0,0 +1,130 @@
+/**
+ * Dataset Guide Prompt
+ *
+ * Provides natural language guidance for querying datasets.
+ */
+export function datasetGuidePrompt(datasets, datasetName) {
+    if (datasetName) {
+        const dataset = datasets[datasetName];
+        if (!dataset) {
+            throw new Error(`Dataset not found: ${datasetName}`);
+        }
+        const datasetAny = dataset;
+        // Generate dataset-specific guide
+        const dimensions = datasetAny.dimensions ? Object.keys(datasetAny.dimensions) : [];
+        const metrics = datasetAny.metrics ? Object.keys(datasetAny.metrics) : [];
+        const guide = `# Querying the ${datasetName} dataset
+
+## Available Dimensions
+${dimensions.map((d) => `- ${d}`).join('\n')}
+
+## Available Metrics
+${metrics.map((m) => `- ${m}`).join('\n')}
+
+## Example Queries
+
+### Simple metric query
+\`\`\`
+Query the "${metrics[0] || 'revenue'}" metric
+\`\`\`
+
+### Grouped by dimension
+\`\`\`
+Show "${metrics[0] || 'revenue'}" by "${dimensions[0] || 'region'}"
+\`\`\`
+
+### With filters
+\`\`\`
+Show "${metrics[0] || 'revenue'}" by "${dimensions[0] || 'region'}" where ${dimensions[1] || 'status'} = 'active'
+\`\`\`
+
+### Time-series
+\`\`\`
+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
+`;
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: guide,
+                    },
+                },
+            ],
+        };
+    }
+    // Generate general guide for all datasets
+    const datasetList = Object.keys(datasets);
+    const guide = `# Hypequery Semantic Layer Guide
+
+## Available Datasets
+${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
+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
+
+## Example Workflow
+
+1. First, explore available datasets:
+   \`\`\`
+   list_datasets()
+   \`\`\`
+
+2. Get the schema for a specific dataset:
+   \`\`\`
+   get_dataset_schema({ dataset: "orders" })
+   \`\`\`
+
+3. Query a metric:
+   \`\`\`
+   query_metric({
+     dataset: "orders",
+     metric: "revenue",
+     dimensions: ["region"],
+     filters: [{ field: "status", operator: "eq", value: "completed" }],
+     grain: "month"
+   })
+   \`\`\`
+
+## Filter Operators
+- \`eq\`: Equal to
+- \`neq\`: Not equal to
+- \`gt\`: Greater than
+- \`gte\`: Greater than or equal to
+- \`lt\`: Less than
+- \`lte\`: Less than or equal to
+- \`in\`: In list
+- \`notIn\`: Not in list
+- \`between\`: Between two values
+- \`like\`: Pattern match
+
+## Time Grains
+- \`day\`: Daily aggregation
+- \`week\`: Weekly aggregation
+- \`month\`: Monthly aggregation
+- \`quarter\`: Quarterly aggregation
+- \`year\`: Yearly aggregation
+`;
+    return {
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: guide,
+                },
+            },
+        ],
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * MCP Server for Hypequery Semantic Layer
+ *
+ * Exposes datasets and metrics via Model Context Protocol (MCP)
+ * for use with Claude Desktop, Cursor, and other MCP-compatible tools.
+ */
+import type { DatasetClient } from '@hypequery/datasets';
+import type { DatasetRegistry } from './types.js';
+export interface MCPServerConfig {
+    /**
+     * Dataset registry - map of dataset names to instances
+     */
+    datasets: DatasetRegistry;
+    /**
+     * Semantic analytics for running metric and dataset queries
+     */
+    analytics: DatasetClient;
+    /**
+     * Server name (shown in MCP client)
+     */
+    name?: string;
+    /**
+     * Server version
+     */
+    version?: string;
+}
+export declare class HypequeryMCPServer {
+    private server;
+    private config;
+    constructor(config: MCPServerConfig);
+    private setupHandlers;
+    /**
+     * Start the MCP server with stdio transport
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the MCP server
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Create and start an MCP server
+ */
+export declare function createMCPServer(config: MCPServerConfig): Promise<HypequeryMCPServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"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;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"}

package/dist/server.js

@@ -0,0 +1,257 @@
+/**
+ * MCP Server for Hypequery Semantic Layer
+ *
+ * Exposes datasets and metrics via Model Context Protocol (MCP)
+ * for use with Claude Desktop, Cursor, and other MCP-compatible tools.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { listDatasetsTool } from './tools/list-datasets.js';
+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';
+export class HypequeryMCPServer {
+    server;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.server = new Server({
+            name: config.name ?? 'hypequery-mcp-server',
+            version: config.version ?? '0.1.0',
+        }, {
+            capabilities: {
+                tools: {},
+                prompts: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // List available tools
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'list_datasets',
+                    description: 'List all available datasets in the semantic layer',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {},
+                    },
+                },
+                {
+                    name: 'get_dataset_schema',
+                    description: 'Get the schema (dimensions, metrics, relationships) for a specific dataset',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            dataset: {
+                                type: 'string',
+                                description: 'Name of the dataset to introspect',
+                            },
+                        },
+                        required: ['dataset'],
+                    },
+                },
+                {
+                    name: 'query_metric',
+                    description: 'Execute a metric query with optional dimensions, filters, time grain, and sorting',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            dataset: {
+                                type: 'string',
+                                description: 'Name of the dataset containing the metric',
+                            },
+                            metric: {
+                                type: 'string',
+                                description: 'Name of the metric to query',
+                            },
+                            dimensions: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Dimensions to group by (optional)',
+                            },
+                            filters: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        operator: {
+                                            type: 'string',
+                                            enum: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like']
+                                        },
+                                        value: {},
+                                    },
+                                    required: ['field', 'operator', 'value'],
+                                },
+                                description: 'Filters to apply (optional)',
+                            },
+                            grain: {
+                                type: 'string',
+                                enum: ['day', 'week', 'month', 'quarter', 'year'],
+                                description: 'Time grain for time-series queries (optional)',
+                            },
+                            orderBy: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        direction: { type: 'string', enum: ['asc', 'desc'] },
+                                    },
+                                    required: ['field', 'direction'],
+                                },
+                                description: 'Sort order (optional)',
+                            },
+                            limit: {
+                                type: 'number',
+                                description: 'Maximum number of rows to return (optional)',
+                            },
+                        },
+                        required: ['dataset', 'metric'],
+                    },
+                },
+                {
+                    name: 'query_dataset',
+                    description: 'Execute an ad-hoc dataset query with custom dimensions and metrics',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            dataset: {
+                                type: 'string',
+                                description: 'Name of the dataset to query',
+                            },
+                            dimensions: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Dimensions to select',
+                            },
+                            metrics: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Metrics to calculate',
+                            },
+                            filters: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        operator: {
+                                            type: 'string',
+                                            enum: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like']
+                                        },
+                                        value: {},
+                                    },
+                                    required: ['field', 'operator', 'value'],
+                                },
+                                description: 'Filters to apply (optional)',
+                            },
+                            grain: {
+                                type: 'string',
+                                enum: ['day', 'week', 'month', 'quarter', 'year'],
+                                description: 'Time grain for time-series queries (optional)',
+                            },
+                            orderBy: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        field: { type: 'string' },
+                                        direction: { type: 'string', enum: ['asc', 'desc'] },
+                                    },
+                                    required: ['field', 'direction'],
+                                },
+                                description: 'Sort order (optional)',
+                            },
+                            limit: {
+                                type: 'number',
+                                description: 'Maximum number of rows to return (optional)',
+                            },
+                        },
+                        required: ['dataset'],
+                    },
+                },
+            ],
+        }));
+        // Handle tool calls
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                switch (name) {
+                    case 'list_datasets':
+                        return await listDatasetsTool(this.config.datasets);
+                    case 'get_dataset_schema':
+                        return await getDatasetSchemaTool(this.config.datasets, args);
+                    case 'query_metric':
+                        return await queryMetricTool(this.config.datasets, this.config.analytics, args);
+                    case 'query_dataset':
+                        return await queryDatasetTool(this.config.datasets, this.config.analytics, args);
+                    default:
+                        throw new Error(`Unknown tool: ${name}`);
+                }
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        // List available prompts
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+            prompts: [
+                {
+                    name: 'dataset_guide',
+                    description: 'Guide for querying datasets with natural language',
+                    arguments: [
+                        {
+                            name: 'dataset',
+                            description: 'Name of the dataset to get guidance for',
+                            required: false,
+                        },
+                    ],
+                },
+            ],
+        }));
+        // Get prompt content
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            if (name === 'dataset_guide') {
+                return datasetGuidePrompt(this.config.datasets, args?.dataset);
+            }
+            throw new Error(`Unknown prompt: ${name}`);
+        });
+    }
+    /**
+     * Start the MCP server with stdio transport
+     */
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        // Log to stderr (stdout is used for MCP protocol)
+        console.error('Hypequery MCP Server started');
+    }
+    /**
+     * Stop the MCP server
+     */
+    async stop() {
+        await this.server.close();
+    }
+}
+/**
+ * Create and start an MCP server
+ */
+export async function createMCPServer(config) {
+    const server = new HypequeryMCPServer(config);
+    await server.start();
+    return server;
+}

package/dist/tools/introspect.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Get Dataset Schema Tool
+ *
+ * Returns the complete schema for a dataset including dimensions, metrics,
+ * and relationships.
+ */
+import type { DatasetRegistry, MCPToolResponse } from '../types.js';
+export declare function getDatasetSchemaTool(datasets: DatasetRegistry, args: unknown): Promise<MCPToolResponse>;
+//# sourceMappingURL=introspect.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/introspect.js

@@ -0,0 +1,76 @@
+/**
+ * Get Dataset Schema Tool
+ *
+ * Returns the complete schema for a dataset including dimensions, metrics,
+ * and relationships.
+ */
+export async function getDatasetSchemaTool(datasets, args) {
+    // Parse and validate args
+    const validatedArgs = args;
+    const datasetName = validatedArgs.dataset;
+    if (!datasetName) {
+        throw new Error('dataset parameter is required');
+    }
+    const dataset = datasets[datasetName];
+    if (!dataset) {
+        throw new Error(`Dataset not found: ${datasetName}`);
+    }
+    // Build schema response with proper types
+    const datasetAny = dataset;
+    const schema = {
+        name: datasetName,
+        description: datasetAny.description || datasetAny.config?.description || '',
+        source: datasetAny.source || datasetAny.config?.source || '',
+        timeKey: datasetAny.timeKey || datasetAny.config?.timeKey || null,
+        tenantKey: datasetAny.tenantKey || datasetAny.config?.tenantKey || null,
+        dimensions: {},
+        metrics: {},
+        relationships: {},
+    };
+    // Extract dimensions with proper typing
+    if (datasetAny.dimensions) {
+        for (const [name, dimension] of Object.entries(datasetAny.dimensions)) {
+            const dimSchema = {
+                type: dimension.fieldType || dimension.type || 'unknown',
+                column: dimension.column || name,
+                label: dimension.label || name,
+                description: dimension.description || '',
+                examples: dimension.examples || [],
+            };
+            schema.dimensions[name] = dimSchema;
+        }
+    }
+    // Extract metrics with proper typing
+    if (datasetAny.metrics) {
+        for (const [name, metric] of Object.entries(datasetAny.metrics)) {
+            const metSchema = {
+                type: metric.spec?.__type || metric.type || 'unknown',
+                aggregation: metric.spec?.aggregation || metric.aggregation || metric.type || '',
+                label: metric.label || name,
+                description: metric.description || '',
+                format: metric.format || null,
+            };
+            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: [
+            {
+                type: 'text',
+                text: JSON.stringify(schema, null, 2),
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * List Datasets Tool
+ *
+ * Returns a list of all available datasets with their descriptions.
+ */
+import type { DatasetRegistry, MCPToolResponse } from '../types.js';
+export declare function listDatasetsTool(datasets: DatasetRegistry): Promise<MCPToolResponse>;
+//# sourceMappingURL=list-datasets.d.ts.map

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

@@ -0,0 +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"}

package/dist/tools/list-datasets.js

@@ -0,0 +1,32 @@
+/**
+ * List Datasets Tool
+ *
+ * Returns a list of all available datasets with their descriptions.
+ */
+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';
+        const dimensionCount = datasetAny.dimensions ? Object.keys(datasetAny.dimensions).length : 0;
+        const metricCount = datasetAny.metrics ? Object.keys(datasetAny.metrics).length : 0;
+        return {
+            name,
+            description,
+            dimensionCount,
+            metricCount,
+        };
+    });
+    const response = {
+        datasets: datasetList,
+        total: datasetList.length,
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(response, null, 2),
+            },
+        ],
+    };
+}

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

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

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

@@ -0,0 +1 @@
+{"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,EAAoB,eAAe,EAAwC,MAAM,aAAa,CAAC;AAE5H,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CA6D1B"}

package/dist/tools/query-dataset.js

@@ -0,0 +1,57 @@
+/**
+ * Query Dataset Tool
+ *
+ * Executes an ad-hoc dataset query with custom dimensions and metrics.
+ */
+export async function queryDatasetTool(datasets, analytics, args) {
+    // Parse and validate args
+    const validatedArgs = args;
+    const { dataset: datasetName, dimensions, metrics, filters, grain, orderBy, limit } = validatedArgs;
+    if (!datasetName) {
+        throw new Error('dataset parameter is required');
+    }
+    const dataset = datasets[datasetName];
+    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');
+    }
+    // Build the query with proper types
+    const query = {
+        dimensions: dimensions || [],
+        measures: metrics || [],
+        filters: 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);
+    }
+    const result = await analytics.execute(dataset, query, {
+        runtime: {
+            tenant: undefined,
+        },
+    });
+    // Format the response with proper types
+    const response = {
+        data: result.data,
+        meta: {
+            sql: result.meta?.sql,
+            timingMs: result.meta?.timingMs,
+            rowCount: result.data.length,
+        },
+    };
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(response, null, 2),
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Query Metric Tool
+ *
+ * Executes a metric query with optional dimensions, filters, grain, and sorting.
+ */
+import type { DatasetClient } from '@hypequery/datasets';
+import type { DatasetRegistry, MCPToolResponse } from '../types.js';
+export declare function queryMetricTool(datasets: DatasetRegistry, analytics: DatasetClient, args: unknown): Promise<MCPToolResponse>;
+//# sourceMappingURL=query-metric.d.ts.map

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

@@ -0,0 +1 @@
+{"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,EAAmB,eAAe,EAAwC,MAAM,aAAa,CAAC;AAE3H,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,eAAe,CAAC,CAoE1B"}