@hypequery/mcp 0.5.5 → 0.6.0

package/dist/tools/tool-manifest.js

@@ -0,0 +1,302 @@
+const semanticMetadataProperties = {
+    examples: { type: 'array', items: { type: 'string' } },
+    synonyms: { type: 'array', items: { type: 'string' } },
+    format: { type: 'string' },
+    unit: { type: 'string' },
+    currency: { type: 'string' },
+    timezone: { type: 'string' },
+    sensitivity: {
+        type: 'string',
+        enum: ['public', 'internal', 'confidential', 'restricted'],
+    },
+};
+const errorEnvelopeSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        error: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                code: {
+                    type: 'string',
+                    enum: [
+                        'MCP_INVALID_ARGUMENTS',
+                        'MCP_NOT_FOUND',
+                        'MCP_UNKNOWN_TOOL',
+                        'MCP_UNAUTHORIZED',
+                        'MCP_STALE_CONTRACT',
+                        'MCP_REQUEST_CANCELLED',
+                        'MCP_QUERY_TIMEOUT',
+                        'MCP_RESULT_TOO_LARGE',
+                        'MCP_EXECUTION_FAILED',
+                    ],
+                },
+                message: { type: 'string' },
+                category: {
+                    type: 'string',
+                    enum: [
+                        'correctable_input',
+                        'unauthorized',
+                        'stale_contract',
+                        'budget',
+                        'internal',
+                    ],
+                },
+                retryable: { type: 'boolean' },
+                correctable: { type: 'boolean' },
+            },
+            required: ['code', 'category', 'message', 'retryable', 'correctable'],
+        },
+    },
+    required: ['error'],
+};
+function resultSchema(successSchema) {
+    return {
+        type: 'object',
+        oneOf: [successSchema, errorEnvelopeSchema],
+    };
+}
+export const DATASET_LIST_OUTPUT_SCHEMA = resultSchema({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        datasets: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    description: { type: 'string' },
+                    dimensionCount: { type: 'integer', minimum: 0 },
+                    measureCount: { type: 'integer', minimum: 0 },
+                    metricCount: { type: 'integer', minimum: 0 },
+                },
+                required: ['name', 'description', 'dimensionCount', 'metricCount'],
+            },
+        },
+        total: { type: 'integer', minimum: 0 },
+    },
+    required: ['datasets', 'total'],
+});
+export const DATASET_SCHEMA_OUTPUT_SCHEMA = resultSchema({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        name: { type: 'string' },
+        description: { type: 'string' },
+        ...semanticMetadataProperties,
+        freshness: {
+            type: 'object',
+            additionalProperties: false,
+            properties: { maxAgeSeconds: { type: 'integer', minimum: 1 } },
+            required: ['maxAgeSeconds'],
+        },
+        owner: { type: 'string' },
+        defaults: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                dimensions: { type: 'array', items: { type: 'string' } },
+                timeGrain: { type: 'string', enum: ['day', 'week', 'month', 'quarter', 'year'] },
+            },
+        },
+        timeDimension: { type: ['string', 'null'] },
+        dimensions: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    type: { type: 'string', enum: ['boolean', 'number', 'string', 'timestamp'] },
+                    label: { type: 'string' },
+                    description: { type: 'string' },
+                    ...semanticMetadataProperties,
+                    filterable: { type: 'boolean' },
+                    groupable: { type: 'boolean' },
+                },
+                required: ['name', 'type', 'filterable', 'groupable'],
+            },
+        },
+        measures: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    label: { type: 'string' },
+                    description: { type: 'string' },
+                    ...semanticMetadataProperties,
+                },
+                required: ['name'],
+            },
+        },
+        metrics: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    label: { type: 'string' },
+                    description: { type: 'string' },
+                    ...semanticMetadataProperties,
+                    dimensions: { type: 'array', items: { type: 'string' } },
+                    filters: { type: 'array', items: { type: 'string' } },
+                    grains: { type: 'array', items: { type: 'string' } },
+                    grain: { type: 'string' },
+                },
+                required: ['name', 'dimensions', 'filters', 'grains'],
+            },
+        },
+        filters: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    type: { type: 'string', enum: ['boolean', 'number', 'string', 'timestamp'] },
+                    label: { type: 'string' },
+                    description: { type: 'string' },
+                    ...semanticMetadataProperties,
+                    operators: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['name', 'type', 'operators'],
+            },
+        },
+        relationships: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    name: { type: 'string' },
+                    target: { type: 'string' },
+                    fields: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['name', 'target', 'fields'],
+            },
+        },
+        limits: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                maxDimensions: { type: 'integer', minimum: 1 },
+                maxMeasures: { type: 'integer', minimum: 1 },
+                maxFilters: { type: 'integer', minimum: 1 },
+                maxResultSize: { type: 'integer', minimum: 1 },
+            },
+        },
+    },
+    required: [
+        'name',
+        'description',
+        'timeDimension',
+        'dimensions',
+        'measures',
+        'metrics',
+        'filters',
+        'relationships',
+    ],
+});
+export const QUERY_OUTPUT_SCHEMA = resultSchema({
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        data: {
+            type: 'array',
+            items: { type: 'object', additionalProperties: true },
+        },
+        meta: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                sql: { type: 'string' },
+                timingMs: { type: 'number', minimum: 0 },
+                rowCount: { type: 'integer', minimum: 0 },
+                pagination: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        limit: { type: 'integer', minimum: 1 },
+                        offset: { type: 'integer', minimum: 0 },
+                        hasMore: { type: 'boolean' },
+                    },
+                    required: ['limit', 'offset', 'hasMore'],
+                },
+                cache: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        status: { type: 'string', enum: ['hit', 'miss', 'bypass'] },
+                        ageMs: { type: 'number', minimum: 0 },
+                        stale: { type: 'boolean' },
+                    },
+                    required: ['status'],
+                },
+            },
+            required: ['rowCount', 'cache'],
+        },
+    },
+    required: ['data', 'meta'],
+});
+function annotations(title) {
+    return {
+        title,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
+}
+export function buildMCPToolManifest(querySchemas) {
+    return {
+        tools: [
+            {
+                name: 'list_datasets',
+                title: 'List datasets',
+                description: 'List all available datasets in the semantic layer',
+                inputSchema: { type: 'object', properties: {} },
+                outputSchema: DATASET_LIST_OUTPUT_SCHEMA,
+                annotations: annotations('List datasets'),
+            },
+            {
+                name: 'get_dataset_schema',
+                title: 'Inspect dataset schema',
+                description: 'Get the schema (dimensions, measures, named metrics, filters, relationships) for a specific dataset',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        dataset: {
+                            type: 'string',
+                            description: 'Name of the dataset to introspect',
+                        },
+                    },
+                    required: ['dataset'],
+                },
+                outputSchema: DATASET_SCHEMA_OUTPUT_SCHEMA,
+                annotations: annotations('Inspect dataset schema'),
+            },
+            {
+                name: 'query_metric',
+                title: 'Query named metric',
+                description: 'Execute a metric query with optional dimensions, filters, time grain, and sorting',
+                inputSchema: querySchemas.queryMetricJsonSchema,
+                outputSchema: QUERY_OUTPUT_SCHEMA,
+                annotations: annotations('Query named metric'),
+            },
+            {
+                name: 'query_dataset',
+                title: 'Query dataset',
+                description: 'Execute an ad-hoc dataset query with custom dimensions and measures',
+                inputSchema: querySchemas.queryDatasetJsonSchema,
+                outputSchema: QUERY_OUTPUT_SCHEMA,
+                annotations: annotations('Query dataset'),
+            },
+        ],
+    };
+}

package/dist/tools/utils/canonical-query-schemas.d.ts

@@ -0,0 +1,9 @@
+import { type CanonicalSemanticQuerySchemas } from '@hypequery/datasets';
+import type { DatasetRegistry, MCPQueryLimits } from '../../types.js';
+/**
+ * Compile exact schemas for real Dataset registries. The shipped loose registry
+ * type also accepts legacy metadata-only objects; retain a generic validator for
+ * those compatibility inputs until the publishing API replaces them.
+ */
+export declare function buildMCPQuerySchemas(datasets: DatasetRegistry, configured?: MCPQueryLimits): CanonicalSemanticQuerySchemas;
+//# sourceMappingURL=canonical-query-schemas.d.ts.map

package/dist/tools/utils/canonical-query-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-query-schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/canonical-query-schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,6BAA6B,EAEnC,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA0BtE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,UAAU,CAAC,EAAE,cAAc,GAC1B,6BAA6B,CAqF/B"}

package/dist/tools/utils/canonical-query-schemas.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, } from '@hypequery/datasets';
+import { z } from 'zod';
+import { queryDatasetArgsSchema, queryMetricArgsSchema } from '../args.js';
+import { resolveQueryLimits } from './query-limits.js';
+import { advertiseDatasetQueryLimits } from './query-schema.js';
+function withLegacyDirectMetrics(datasets) {
+    return Object.fromEntries(Object.entries(datasets).map(([name, dataset]) => {
+        if (!dataset || typeof dataset !== 'object')
+            return [name, dataset];
+        const directMetrics = Object.fromEntries(Object.entries(dataset).filter(([, value]) => (value && typeof value === 'object' && 'contract' in value
+            && typeof value.contract === 'function')));
+        return [name, {
+                ...dataset,
+                metrics: {
+                    ...('metrics' in dataset && dataset.metrics && typeof dataset.metrics === 'object'
+                        ? dataset.metrics
+                        : {}),
+                    ...directMetrics,
+                },
+            }];
+    }));
+}
+/**
+ * Compile exact schemas for real Dataset registries. The shipped loose registry
+ * type also accepts legacy metadata-only objects; retain a generic validator for
+ * those compatibility inputs until the publishing API replaces them.
+ */
+export function buildMCPQuerySchemas(datasets, configured) {
+    const limits = resolveQueryLimits(undefined, configured);
+    const entries = Object.entries(datasets).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+    if (entries.length === 0) {
+        const queryDatasetJsonSchema = toSemanticJsonSchema(queryDatasetArgsSchema);
+        const queryMetricJsonSchema = toSemanticJsonSchema(queryMetricArgsSchema);
+        const manifestHash = createHash('sha256').update(JSON.stringify({
+            query_dataset: queryDatasetJsonSchema,
+            query_metric: queryMetricJsonSchema,
+        })).digest('hex');
+        return Object.freeze({
+            queryDataset: queryDatasetArgsSchema,
+            queryMetric: queryMetricArgsSchema,
+            queryDatasetJsonSchema,
+            queryMetricJsonSchema,
+            manifestHash,
+        });
+    }
+    if (entries.every(([, dataset]) => isCanonicalSchemaSource(dataset))) {
+        return buildCanonicalSemanticQuerySchemas(withLegacyDirectMetrics(datasets), { grainField: 'grain', ...limits });
+    }
+    const datasetSchemas = [];
+    const metricSchemas = [];
+    const datasetJsonSchemas = [];
+    const metricJsonSchemas = [];
+    for (const [name, dataset] of entries) {
+        if (isCanonicalSchemaSource(dataset)) {
+            const exact = buildCanonicalSemanticQuerySchemas(withLegacyDirectMetrics({ [name]: dataset }), { grainField: 'grain', ...limits });
+            datasetSchemas.push(exact.queryDataset);
+            metricSchemas.push(exact.queryMetric);
+            datasetJsonSchemas.push(exact.queryDatasetJsonSchema);
+            metricJsonSchemas.push(exact.queryMetricJsonSchema);
+        }
+        else {
+            // Keep compatibility local to the legacy entry. A registry-wide fallback
+            // would erase exact contracts for every valid Dataset beside it.
+            const queryDataset = queryDatasetArgsSchema.extend({ dataset: z.literal(name) });
+            const queryMetric = queryMetricArgsSchema.extend({
+                dataset: z.literal(name),
+                metric: z.string().min(1),
+            });
+            datasetSchemas.push(queryDataset);
+            metricSchemas.push(queryMetric);
+            datasetJsonSchemas.push(advertiseDatasetQueryLimits(toSemanticJsonSchema(queryDataset), { [name]: dataset }, configured, true));
+            metricJsonSchemas.push(advertiseDatasetQueryLimits(toSemanticJsonSchema(queryMetric), { [name]: dataset }, configured, false));
+        }
+    }
+    const queryDataset = unionSchemas(datasetSchemas);
+    const queryMetric = unionSchemas(metricSchemas);
+    const queryDatasetJsonSchema = unionJsonSchemas(datasetJsonSchemas);
+    const queryMetricJsonSchema = unionJsonSchemas(metricJsonSchemas);
+    const manifestHash = createHash('sha256').update(JSON.stringify({
+        query_dataset: queryDatasetJsonSchema,
+        query_metric: queryMetricJsonSchema,
+    })).digest('hex');
+    return Object.freeze({
+        queryDataset,
+        queryMetric,
+        queryDatasetJsonSchema,
+        queryMetricJsonSchema,
+        manifestHash,
+    });
+}
+function isCanonicalSchemaSource(dataset) {
+    if (!dataset || typeof dataset !== 'object')
+        return false;
+    const source = dataset;
+    return source.__type === 'dataset'
+        || ('requiresTenant' in source && 'supportedGrains' in source && 'orderableFields' in source);
+}
+function unionSchemas(schemas) {
+    return schemas.length === 1
+        ? schemas[0]
+        : z.union(schemas);
+}
+function unionJsonSchemas(schemas) {
+    return schemas.length === 1
+        ? schemas[0]
+        : { type: 'object', anyOf: schemas };
+}

package/dist/tools/utils/execution-budget.d.ts

@@ -0,0 +1,11 @@
+import { type MCPExecutionBudget } from '../../types.js';
+export declare const MIN_RESPONSE_BYTES: number;
+export interface EffectiveExecutionBudget {
+    readonly timeoutMs: number;
+    readonly maxResponseBytes: number;
+}
+export declare function resolveExecutionBudget(configured?: MCPExecutionBudget): EffectiveExecutionBudget;
+export declare function executeWithinBudget<T>(operation: (signal: AbortSignal) => Promise<T>, budget: EffectiveExecutionBudget, requestSignal?: AbortSignal): Promise<T>;
+export declare function serializeWithinBudget(value: unknown, budget: EffectiveExecutionBudget): string;
+export declare function assertWithinBudget(value: unknown, budget: EffectiveExecutionBudget): void;
+//# sourceMappingURL=execution-budget.d.ts.map

package/dist/tools/utils/execution-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-budget.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/execution-budget.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,kBAAkB,QAG9B,CAAC;AAEF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAgBD,wBAAgB,sBAAsB,CACpC,UAAU,GAAE,kBAAuB,GAClC,wBAAwB,CAe1B;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,MAAM,EAAE,wBAAwB,EAChC,aAAa,CAAC,EAAE,WAAW,GAC1B,OAAO,CAAC,CAAC,CAAC,CA0CZ;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,wBAAwB,GAC/B,MAAM,CAIR;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,wBAAwB,GAC/B,IAAI,CAEN"}

package/dist/tools/utils/execution-budget.js

@@ -0,0 +1,71 @@
+import { MCPExecutionBudgetError } from '../../errors.js';
+import { DEFAULT_QUERY_TIMEOUT_MS, DEFAULT_RESPONSE_BYTES, MAX_QUERY_TIMEOUT_MS, MAX_RESPONSE_BYTES, } from '../../types.js';
+import { createMCPResultTooLargeResponse } from './tool-response.js';
+export const MIN_RESPONSE_BYTES = Buffer.byteLength(JSON.stringify(createMCPResultTooLargeResponse()), 'utf8');
+function positiveInteger(value, fallback, maximum, name) {
+    const resolved = value ?? fallback;
+    const minimum = name === 'maxResponseBytes' ? MIN_RESPONSE_BYTES : 1;
+    if (!Number.isSafeInteger(resolved) || resolved < minimum || resolved > maximum) {
+        throw new Error(`${name} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return resolved;
+}
+export function resolveExecutionBudget(configured = {}) {
+    return Object.freeze({
+        timeoutMs: positiveInteger(configured.timeoutMs, DEFAULT_QUERY_TIMEOUT_MS, MAX_QUERY_TIMEOUT_MS, 'timeoutMs'),
+        maxResponseBytes: positiveInteger(configured.maxResponseBytes, DEFAULT_RESPONSE_BYTES, MAX_RESPONSE_BYTES, 'maxResponseBytes'),
+    });
+}
+export async function executeWithinBudget(operation, budget, requestSignal) {
+    const controller = new AbortController();
+    const cancellationError = new MCPExecutionBudgetError('MCP_REQUEST_CANCELLED', 'The MCP request was cancelled');
+    const timeoutError = new MCPExecutionBudgetError('MCP_QUERY_TIMEOUT', `The query exceeded its ${budget.timeoutMs}ms execution deadline`);
+    const cancel = () => controller.abort(cancellationError);
+    if (requestSignal?.aborted) {
+        throw cancellationError;
+    }
+    requestSignal?.addEventListener('abort', cancel, { once: true });
+    const timeout = setTimeout(() => controller.abort(timeoutError), budget.timeoutMs);
+    let removeBudgetAbortListener = () => { };
+    const budgetAbort = new Promise((_, reject) => {
+        const rejectForAbort = () => reject(controller.signal.reason);
+        if (controller.signal.aborted) {
+            rejectForAbort();
+            return;
+        }
+        controller.signal.addEventListener('abort', rejectForAbort, { once: true });
+        removeBudgetAbortListener = () => {
+            controller.signal.removeEventListener('abort', rejectForAbort);
+        };
+    });
+    try {
+        const result = await Promise.race([operation(controller.signal), budgetAbort]);
+        if (controller.signal.aborted)
+            throw controller.signal.reason;
+        return result;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw controller.signal.reason;
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+        removeBudgetAbortListener();
+        requestSignal?.removeEventListener('abort', cancel);
+    }
+}
+export function serializeWithinBudget(value, budget) {
+    const serialized = JSON.stringify(value);
+    assertSerializedWithinBudget(serialized, budget);
+    return serialized;
+}
+export function assertWithinBudget(value, budget) {
+    assertSerializedWithinBudget(JSON.stringify(value), budget);
+}
+function assertSerializedWithinBudget(serialized, budget) {
+    const size = Buffer.byteLength(serialized, 'utf8');
+    if (size > budget.maxResponseBytes) {
+        throw new MCPExecutionBudgetError('MCP_RESULT_TOO_LARGE', `The serialized result is ${size} bytes; maximum is ${budget.maxResponseBytes} bytes`);
+    }
+}

package/dist/tools/utils/legacy-agent-catalog.d.ts

@@ -0,0 +1,19 @@
+import type { AgentCatalogDataset } from '@hypequery/datasets';
+type UnknownRecord = Record<string, unknown>;
+/**
+ * Safely adapts the pre-catalog, object-shaped MCP registry compatibility input.
+ *
+ * A legacy entry is arbitrary user data, so every name it carries is checked
+ * against what this projection already publishes before it is emitted:
+ * references that do not resolve to a declared dimension, filter, grain, or
+ * sibling dataset are dropped rather than passed through. Otherwise a physical
+ * column or tenant key sitting in a legacy `metrics`/`relationships` block
+ * would reach the agent through `get_dataset_schema`.
+ *
+ * `registry` is the surrounding dataset map, used to resolve relationship
+ * targets. A relationship whose target is not in it is unreachable, so it is
+ * omitted instead of advertising a name the agent cannot query.
+ */
+export declare function projectLegacyAgentDataset(name: string, input: UnknownRecord, registry?: Readonly<Record<string, unknown>>): AgentCatalogDataset;
+export {};
+//# sourceMappingURL=legacy-agent-catalog.d.ts.map

package/dist/tools/utils/legacy-agent-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-agent-catalog.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/legacy-agent-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EAQpB,MAAM,qBAAqB,CAAC;AAE7B,KAAK,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4F7C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,aAAa,EACpB,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAM,GAC/C,mBAAmB,CAuFrB"}