@hypequery/mcp 0.5.5 → 0.6.0

package/dist/tools/utils/legacy-agent-catalog.js

@@ -0,0 +1,171 @@
+/**
+ * Grains the semantic planner can actually execute. A legacy registry is
+ * untyped, so anything outside this set is dropped rather than advertised.
+ */
+const TIME_GRAINS = new Set(['day', 'week', 'month', 'quarter', 'year']);
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function fieldType(value) {
+    return value === 'string' || value === 'number' || value === 'boolean' || value === 'timestamp'
+        ? value
+        : undefined;
+}
+function namedEntries(value) {
+    return Object.entries(record(value))
+        .map(([name, entry]) => [name, record(entry)])
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+}
+function optionalDescription(value) {
+    const label = text(value.label);
+    const description = text(value.description);
+    return {
+        ...(label !== undefined ? { label } : {}),
+        ...(description !== undefined ? { description } : {}),
+    };
+}
+function semanticMetadata(value) {
+    const list = (input) => Array.isArray(input)
+        ? [...new Set(input.filter((item) => typeof item === 'string'))].sort()
+        : undefined;
+    const sensitivity = ['public', 'internal', 'confidential', 'restricted'].includes(String(value.sensitivity))
+        ? value.sensitivity
+        : undefined;
+    return {
+        ...(list(value.examples) !== undefined ? { examples: list(value.examples) } : {}),
+        ...(list(value.synonyms) !== undefined ? { synonyms: list(value.synonyms) } : {}),
+        ...(text(value.format) !== undefined ? { format: text(value.format) } : {}),
+        ...(text(value.unit) !== undefined ? { unit: text(value.unit) } : {}),
+        ...(/^[A-Z]{3}$/.test(String(value.currency)) ? { currency: String(value.currency) } : {}),
+        ...(text(value.timezone) !== undefined ? { timezone: text(value.timezone) } : {}),
+        ...(sensitivity !== undefined ? { sensitivity } : {}),
+    };
+}
+function limits(value) {
+    const input = record(value);
+    const result = {};
+    for (const key of ['maxDimensions', 'maxMeasures', 'maxFilters', 'maxResultSize']) {
+        const candidate = input[key];
+        if (Number.isSafeInteger(candidate) && candidate > 0)
+            result[key] = candidate;
+    }
+    return result;
+}
+/** Keeps only the members of `value` that name something the agent may already see. */
+function declaredNames(value, declared) {
+    return Array.isArray(value)
+        ? [...new Set(value.filter((item) => (typeof item === 'string' && declared.has(item))))].sort()
+        : [];
+}
+/** The dimensions a legacy registry entry exposes, in the shape the agent sees. */
+function legacyDimensions(input) {
+    return namedEntries(input.dimensions)
+        .map(([dimensionName, dimension]) => ({
+        name: dimensionName,
+        type: fieldType(dimension.fieldType ?? dimension.type),
+        ...optionalDescription(dimension),
+        ...semanticMetadata(dimension),
+        filterable: dimension.filterable !== false,
+        groupable: dimension.groupable !== false,
+    }))
+        .filter((dimension) => (dimension.type !== undefined && (dimension.filterable || dimension.groupable)));
+}
+/**
+ * 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 function projectLegacyAgentDataset(name, input, registry = {}) {
+    const config = record(input.config);
+    const dimensions = legacyDimensions(input);
+    const dimensionTypes = new Map(dimensions.map(dimension => [dimension.name, dimension.type]));
+    const dimensionNames = new Set(dimensionTypes.keys());
+    const filters = namedEntries(input.filters)
+        .map(([filterName, filter]) => ({
+        name: filterName,
+        type: dimensionTypes.get(text(filter.field) ?? filterName),
+        ...optionalDescription(filter),
+        ...semanticMetadata(filter),
+        operators: Array.isArray(filter.operators)
+            ? [...new Set(filter.operators.filter((operator) => typeof operator === 'string'))].sort()
+            : [],
+    }))
+        .filter((filter) => filter.type !== undefined);
+    const filterNames = new Set(filters.map(filter => filter.name));
+    const timeKey = text(input.timeKey) ?? text(config.timeKey);
+    const freshnessInput = record(input.freshness);
+    const freshness = Number.isSafeInteger(freshnessInput.maxAgeSeconds)
+        && freshnessInput.maxAgeSeconds > 0
+        ? { maxAgeSeconds: freshnessInput.maxAgeSeconds }
+        : undefined;
+    const defaultsInput = record(input.defaults);
+    const defaultDimensions = Array.isArray(defaultsInput.dimensions)
+        ? declaredNames(defaultsInput.dimensions, dimensionNames)
+        : undefined;
+    const timeGrain = TIME_GRAINS.has(String(defaultsInput.timeGrain))
+        ? defaultsInput.timeGrain
+        : undefined;
+    const defaults = defaultDimensions !== undefined || timeGrain !== undefined
+        ? {
+            ...(defaultDimensions !== undefined ? { dimensions: defaultDimensions } : {}),
+            ...(timeGrain !== undefined ? { timeGrain } : {}),
+        }
+        : undefined;
+    return {
+        name,
+        description: text(input.description) ?? text(config.description) ?? `${name} analytics dataset.`,
+        ...semanticMetadata(input),
+        ...(freshness !== undefined ? { freshness } : {}),
+        ...(text(input.owner) !== undefined ? { owner: text(input.owner) } : {}),
+        ...(defaults !== undefined ? { defaults } : {}),
+        timeDimension: timeKey !== undefined && dimensionNames.has(timeKey) ? timeKey : null,
+        dimensions,
+        measures: namedEntries(input.measures).map(([measureName, measure]) => ({
+            name: measureName,
+            ...optionalDescription(measure),
+            ...semanticMetadata(measure),
+        })),
+        metrics: namedEntries(input.metrics).map(([metricName, metric]) => ({
+            name: metricName,
+            ...optionalDescription(metric),
+            ...semanticMetadata(metric),
+            dimensions: declaredNames(metric.dimensions, dimensionNames),
+            filters: declaredNames(metric.filters, filterNames),
+            grains: declaredNames(metric.grains, TIME_GRAINS),
+        })),
+        filters,
+        relationships: namedEntries(input.relationships)
+            .filter(([, relationship]) => relationship.queryable !== false && relationship.kind !== 'hasMany')
+            .map(([relationshipName, relationship]) => {
+            const target = text(relationship.target) ?? text(record(relationship.dataset).name);
+            if (target === undefined || !Object.prototype.hasOwnProperty.call(registry, target)) {
+                return undefined;
+            }
+            // A queryable relationship field is exactly `<relationship>.<dimension>`
+            // over a single hop, addressing a dimension the target already
+            // publishes. See `listQueryableRelationshipFields`.
+            const targetDimensions = new Set(legacyDimensions(record(registry[target])).map(dimension => dimension.name));
+            return {
+                name: relationshipName,
+                target,
+                fields: declaredNames(relationship.fields, new Set([...targetDimensions].map(field => `${relationshipName}.${field}`))),
+            };
+        })
+            .filter((relationship) => (relationship !== undefined)),
+        limits: limits(input.limits),
+    };
+}

package/dist/tools/utils/query-limits.d.ts

@@ -0,0 +1,25 @@
+import { type MCPQueryLimits } from '../../types.js';
+interface QueryCollections {
+    readonly dimensions?: readonly unknown[];
+    readonly measures?: readonly unknown[];
+    readonly filters?: readonly unknown[];
+    readonly orderBy?: readonly unknown[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+export interface EffectiveQueryLimits {
+    readonly defaultResultSize: number;
+    readonly maxResultSize: number;
+    readonly maxOffset: number;
+    readonly maxDimensions: number;
+    readonly maxMeasures: number;
+    readonly maxFilters: number;
+    readonly maxOrderBy: number;
+}
+export declare function resolveQueryLimits(dataset: unknown, configured?: MCPQueryLimits): EffectiveQueryLimits;
+export declare function applyQueryLimits(dataset: unknown, query: QueryCollections, configured?: MCPQueryLimits): {
+    readonly limit: number;
+    readonly offset?: number;
+};
+export {};
+//# sourceMappingURL=query-limits.d.ts.map

package/dist/tools/utils/query-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-limits.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/query-limits.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAExB,UAAU,gBAAgB;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAsCD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,cAAmB,GAC9B,oBAAoB,CAkCtB;AAeD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,gBAAgB,EACvB,UAAU,GAAE,cAAmB,GAC9B;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAqBtD"}

package/dist/tools/utils/query-limits.js

@@ -0,0 +1,69 @@
+import { MCPToolError } from '../../errors.js';
+import { DEFAULT_QUERY_LIMIT, MAX_QUERY_DIMENSIONS, MAX_QUERY_FILTERS, MAX_QUERY_LIMIT, MAX_QUERY_MEASURES, MAX_QUERY_OFFSET, MAX_QUERY_ORDER_BY, } from '../../types.js';
+function positiveInteger(value, fallback, maximum, name) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > maximum) {
+        throw new Error(`${name} must be an integer between 1 and ${maximum}`);
+    }
+    return resolved;
+}
+function nonNegativeInteger(value, fallback, maximum, name) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 0 || resolved > maximum) {
+        throw new Error(`${name} must be an integer between 0 and ${maximum}`);
+    }
+    return resolved;
+}
+function datasetLimits(dataset) {
+    if (!dataset || typeof dataset !== 'object' || Array.isArray(dataset))
+        return undefined;
+    const limits = dataset.limits;
+    return limits && typeof limits === 'object' && !Array.isArray(limits)
+        ? limits
+        : undefined;
+}
+function datasetPositiveInteger(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new Error(`Dataset ${name} must be a positive integer`);
+    }
+    return value;
+}
+function lowerLimit(...values) {
+    return Math.min(...values.filter((value) => value !== undefined));
+}
+export function resolveQueryLimits(dataset, configured = {}) {
+    const semantic = datasetLimits(dataset);
+    const maxResultSize = lowerLimit(positiveInteger(configured.maxResultSize, MAX_QUERY_LIMIT, MAX_QUERY_LIMIT, 'maxResultSize'), datasetPositiveInteger(semantic?.maxResultSize, 'maxResultSize'));
+    const defaultResultSize = lowerLimit(positiveInteger(configured.defaultResultSize, DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, 'defaultResultSize'), maxResultSize);
+    return Object.freeze({
+        defaultResultSize,
+        maxResultSize,
+        maxOffset: nonNegativeInteger(configured.maxOffset, MAX_QUERY_OFFSET, MAX_QUERY_OFFSET, 'maxOffset'),
+        maxDimensions: lowerLimit(positiveInteger(configured.maxDimensions, MAX_QUERY_DIMENSIONS, MAX_QUERY_DIMENSIONS, 'maxDimensions'), datasetPositiveInteger(semantic?.maxDimensions, 'maxDimensions')),
+        maxMeasures: lowerLimit(positiveInteger(configured.maxMeasures, MAX_QUERY_MEASURES, MAX_QUERY_MEASURES, 'maxMeasures'), datasetPositiveInteger(semantic?.maxMeasures, 'maxMeasures')),
+        maxFilters: lowerLimit(positiveInteger(configured.maxFilters, MAX_QUERY_FILTERS, MAX_QUERY_FILTERS, 'maxFilters'), datasetPositiveInteger(semantic?.maxFilters, 'maxFilters')),
+        maxOrderBy: positiveInteger(configured.maxOrderBy, MAX_QUERY_ORDER_BY, MAX_QUERY_ORDER_BY, 'maxOrderBy'),
+    });
+}
+function assertCollectionLimit(values, maximum, name) {
+    if ((values?.length ?? 0) > maximum) {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', `Invalid ${name}: maximum ${maximum} items`);
+    }
+}
+export function applyQueryLimits(dataset, query, configured = {}) {
+    const limits = resolveQueryLimits(dataset, configured);
+    assertCollectionLimit(query.dimensions, limits.maxDimensions, 'dimensions');
+    assertCollectionLimit(query.measures, limits.maxMeasures, 'measures');
+    assertCollectionLimit(query.filters, limits.maxFilters, 'filters');
+    assertCollectionLimit(query.orderBy, limits.maxOrderBy, 'orderBy');
+    const limit = query.limit ?? limits.defaultResultSize;
+    if (limit > limits.maxResultSize) {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', `Invalid limit: ${limit}. Max: ${limits.maxResultSize}`);
+    }
+    if (query.offset !== undefined && query.offset > limits.maxOffset) {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', `Invalid offset: ${query.offset}. Max: ${limits.maxOffset}`);
+    }
+    return Object.freeze({ limit, ...(query.offset === undefined ? {} : { offset: query.offset }) });
+}

package/dist/tools/utils/query-result.d.ts

@@ -0,0 +1,4 @@
+import type { DatasetQueryResult } from '@hypequery/datasets';
+import type { QueryResultResponse } from '../../types.js';
+export declare function buildMCPQueryResult(result: DatasetQueryResult, includeSql?: boolean): QueryResultResponse;
+//# sourceMappingURL=query-result.d.ts.map

package/dist/tools/utils/query-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-result.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/query-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAE1D,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,kBAAkB,EAC1B,UAAU,UAAQ,GACjB,mBAAmB,CAkBrB"}

package/dist/tools/utils/query-result.js

@@ -0,0 +1,19 @@
+export function buildMCPQueryResult(result, includeSql = false) {
+    const cache = result.meta?.cache;
+    return {
+        data: result.data,
+        meta: {
+            ...(includeSql && result.meta?.sql ? { sql: result.meta.sql } : {}),
+            ...(result.meta?.timingMs === undefined ? {} : { timingMs: result.meta.timingMs }),
+            rowCount: result.data.length,
+            ...(result.meta?.pagination ? { pagination: result.meta.pagination } : {}),
+            cache: cache
+                ? {
+                    status: cache.hit ? 'hit' : 'miss',
+                    ...(cache.ageMs === undefined ? {} : { ageMs: cache.ageMs }),
+                    ...(cache.stale === undefined ? {} : { stale: cache.stale }),
+                }
+                : { status: 'bypass' },
+        },
+    };
+}

package/dist/tools/utils/query-schema.d.ts

@@ -0,0 +1,8 @@
+import type { DatasetRegistry, MCPQueryLimits } from '../../types.js';
+export type JsonObject = Record<string, unknown>;
+/**
+ * Builds a dataset-discriminated query schema that advertises each dataset's
+ * effective server and semantic-layer limits to MCP clients.
+ */
+export declare function advertiseDatasetQueryLimits(schema: JsonObject, datasets: DatasetRegistry, configured: MCPQueryLimits | undefined, includeMeasures: boolean): JsonObject;
+//# sourceMappingURL=query-schema.d.ts.map

package/dist/tools/utils/query-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-schema.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/query-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGtE,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,eAAe,EACzB,UAAU,EAAE,cAAc,GAAG,SAAS,EACtC,eAAe,EAAE,OAAO,GACvB,UAAU,CA8BZ"}

package/dist/tools/utils/query-schema.js

@@ -0,0 +1,36 @@
+import { resolveQueryLimits } from './query-limits.js';
+/**
+ * Builds a dataset-discriminated query schema that advertises each dataset's
+ * effective server and semantic-layer limits to MCP clients.
+ */
+export function advertiseDatasetQueryLimits(schema, datasets, configured, includeMeasures) {
+    const entries = Object.entries(datasets);
+    if (entries.length === 0)
+        return schema;
+    const properties = schema.properties;
+    return {
+        type: 'object',
+        anyOf: entries.map(([name, dataset]) => {
+            const limits = resolveQueryLimits(dataset, configured);
+            return {
+                ...schema,
+                properties: {
+                    ...properties,
+                    dataset: { ...properties.dataset, enum: [name] },
+                    dimensions: { ...properties.dimensions, maxItems: limits.maxDimensions },
+                    ...(includeMeasures ? {
+                        measures: { ...properties.measures, maxItems: limits.maxMeasures },
+                    } : {}),
+                    filters: { ...properties.filters, maxItems: limits.maxFilters },
+                    orderBy: { ...properties.orderBy, maxItems: limits.maxOrderBy },
+                    limit: {
+                        ...properties.limit,
+                        maximum: limits.maxResultSize,
+                        default: limits.defaultResultSize,
+                    },
+                    offset: { ...properties.offset, maximum: limits.maxOffset },
+                },
+            };
+        }),
+    };
+}

package/dist/tools/utils/tool-response.d.ts

@@ -0,0 +1,6 @@
+import type { MCPToolResponse } from '../../types.js';
+export declare function createMCPToolResponse<T extends object>(value: T, text?: string): MCPToolResponse;
+export declare function createMCPErrorResponse(error: unknown): MCPToolResponse;
+/** Smallest schema-valid error used when even the original error exceeds its budget. */
+export declare function createMCPResultTooLargeResponse(): MCPToolResponse;
+//# sourceMappingURL=tool-response.d.ts.map

package/dist/tools/utils/tool-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-response.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/tool-response.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,KAAK,EAAE,CAAC,EACR,IAAI,SAAwB,GAC3B,eAAe,CAKjB;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAOtE;AAED,wFAAwF;AACxF,wBAAgB,+BAA+B,IAAI,eAAe,CAgBjE"}

package/dist/tools/utils/tool-response.js

@@ -0,0 +1,33 @@
+import { classifyMCPToolError, formatMCPToolError } from '../../errors.js';
+export function createMCPToolResponse(value, text = JSON.stringify(value)) {
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: value,
+    };
+}
+export function createMCPErrorResponse(error) {
+    const details = classifyMCPToolError(error);
+    return {
+        content: [{ type: 'text', text: formatMCPToolError(error) }],
+        structuredContent: { error: details },
+        isError: true,
+    };
+}
+/** Smallest schema-valid error used when even the original error exceeds its budget. */
+export function createMCPResultTooLargeResponse() {
+    const details = {
+        code: 'MCP_RESULT_TOO_LARGE',
+        category: 'budget',
+        message: 'Result exceeds response byte limit',
+        retryable: false,
+        correctable: false,
+    };
+    return {
+        content: [{
+                type: 'text',
+                text: `Error [${details.code}]: ${details.message}`,
+            }],
+        structuredContent: { error: details },
+        isError: true,
+    };
+}

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 /**
  * Type definitions for MCP Server
  */
-import type { AnyDatasetInstance, MetricFilter, TimeGrain, MetricOrderBy } from '@hypequery/datasets';
+import type { AgentCatalogDataset, AgentCatalogDimension, AgentCatalogFilter, AgentCatalogMeasure, AgentCatalogMetric, AgentCatalogRelationship, AnyDatasetInstance, MetricFilter, TimeGrain, MetricOrderBy } from '@hypequery/datasets';
+import type { ZodTypeAny } from 'zod';
 /**
  * Registry of datasets - maps dataset names to dataset instances
  */
@@ -35,8 +36,38 @@ export interface QueryDatasetArgs {
 export interface QueryToolOptions {
     tenantId?: string;
     includeSql?: boolean;
+    limits?: MCPQueryLimits;
+    executionBudget?: MCPExecutionBudget;
+    signal?: AbortSignal;
+    /** Canonical catalog-derived validator supplied by the owning server. */
+    inputSchema?: ZodTypeAny;
+}
+/** Per-query wall-clock and serialized-response ceilings. */
+export interface MCPExecutionBudget {
+    /** Maximum query duration in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Maximum UTF-8 bytes in the serialized query response. Defaults to 1 MiB. */
+    maxResponseBytes?: number;
+}
+/** Server-side ceilings applied in addition to Dataset limits. */
+export interface MCPQueryLimits {
+    /** Rows used when a tool call omits `limit`. Defaults to 100. */
+    defaultResultSize?: number;
+    /** Maximum explicit or default row limit. Cannot exceed 10,000. */
+    maxResultSize?: number;
+    /** Maximum pagination offset. Cannot exceed 10,000. */
+    maxOffset?: number;
+    /** Maximum selected dimensions. Cannot exceed 50. */
+    maxDimensions?: number;
+    /** Maximum selected measures. Cannot exceed 50. */
+    maxMeasures?: number;
+    /** Maximum filters. Cannot exceed 100. */
+    maxFilters?: number;
+    /** Maximum order clauses. Cannot exceed 50. */
+    maxOrderBy?: number;
 }
 export interface SchemaToolOptions {
+    /** @deprecated Agent-facing introspection is always safe. Use getTrustedDatasetSchema separately. */
     includeSql?: boolean;
 }
 /**
@@ -54,84 +85,34 @@ export interface MCPToolResponse {
         type: 'text';
         text: string;
     }>;
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
     [key: string]: unknown;
 }
 /**
  * Dataset schema response structure
  */
-export interface DatasetSchema {
-    name: string;
-    description: string;
-    source: string;
-    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;
-    };
-}
+export type DatasetSchema = AgentCatalogDataset;
 /**
  * Dimension schema in response
  */
-export interface DimensionSchema {
-    type: string;
-    column: string | null;
-    sql: string | null;
-    label: string;
-    description: string;
-    examples: string[];
-    filterable: boolean;
-    groupable: boolean;
-}
+export type DimensionSchema = AgentCatalogDimension;
 /**
  * Measure schema in response
  */
-export interface MeasureSchema {
-    aggregation: string;
-    field: string;
-    sql: string | null;
-    label: string;
-    description: string;
-}
+export type MeasureSchema = AgentCatalogMeasure;
 /**
  * Filter schema in response
  */
-export interface FilterSchema {
-    field: string;
-    label: string;
-    description: string;
-    operators: string[] | null;
-}
+export type FilterSchema = AgentCatalogFilter;
 /**
  * Metric schema in response
  */
-export interface MetricSchema {
-    type: string;
-    aggregation: string;
-    label: string;
-    description: string;
-    format: string | null;
-}
+export type MetricSchema = AgentCatalogMetric;
 /**
  * Relationship schema in response
  */
-export interface RelationshipSchema {
-    type: string;
-    target: string;
-    from?: string;
-    to?: string;
-    queryable?: boolean;
-    fields?: string[];
-    description: string;
-}
+export type RelationshipSchema = AgentCatalogRelationship;
 /**
  * Dataset list item
  */
@@ -165,6 +146,12 @@ export interface QueryResultMeta {
         offset: number;
         hasMore: boolean;
     };
+    /** Cache outcome for agent observability. */
+    cache?: {
+        status: 'hit' | 'miss' | 'bypass';
+        ageMs?: number;
+        stale?: boolean;
+    };
 }
 /**
  * Query result response
@@ -178,4 +165,13 @@ export interface QueryResultResponse {
  */
 export declare const MAX_QUERY_LIMIT = 10000;
 export declare const DEFAULT_QUERY_LIMIT = 100;
+export declare const MAX_QUERY_OFFSET = 10000;
+export declare const MAX_QUERY_DIMENSIONS = 50;
+export declare const MAX_QUERY_MEASURES = 50;
+export declare const MAX_QUERY_FILTERS = 100;
+export declare const MAX_QUERY_ORDER_BY = 50;
+export declare const DEFAULT_QUERY_TIMEOUT_MS = 30000;
+export declare const MAX_QUERY_TIMEOUT_MS = 120000;
+export declare const DEFAULT_RESPONSE_BYTES = 1048576;
+export declare const MAX_RESPONSE_BYTES = 10485760;
 //# sourceMappingURL=types.d.ts.map

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/dist/types.js

@@ -6,3 +6,12 @@
  */
 export const MAX_QUERY_LIMIT = 10000;
 export const DEFAULT_QUERY_LIMIT = 100;
+export const MAX_QUERY_OFFSET = 10000;
+export const MAX_QUERY_DIMENSIONS = 50;
+export const MAX_QUERY_MEASURES = 50;
+export const MAX_QUERY_FILTERS = 100;
+export const MAX_QUERY_ORDER_BY = 50;
+export const DEFAULT_QUERY_TIMEOUT_MS = 30_000;
+export const MAX_QUERY_TIMEOUT_MS = 120_000;
+export const DEFAULT_RESPONSE_BYTES = 1_048_576;
+export const MAX_RESPONSE_BYTES = 10_485_760;

package/dist/utils/tenant-config.d.ts

@@ -0,0 +1,3 @@
+import type { MCPExecutorConfig } from '../executor.js';
+export declare function validateMCPServerTenantConfig(config: MCPExecutorConfig): void;
+//# sourceMappingURL=tenant-config.d.ts.map

package/dist/utils/tenant-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-config.d.ts","sourceRoot":"","sources":["../../src/utils/tenant-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAiBxD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAc7E"}

package/dist/utils/tenant-config.js

@@ -0,0 +1,23 @@
+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;
+}
+export function validateMCPServerTenantConfig(config) {
+    if (config.tenantId) {
+        return;
+    }
+    const tenantScopedDatasets = Object.entries(config.datasets ?? {})
+        .filter(([, dataset]) => getTenantKey(dataset))
+        .map(([name]) => name);
+    if (tenantScopedDatasets.length > 0) {
+        throw new Error(`MCP server tenantId is required for tenant-scoped datasets: ${tenantScopedDatasets.join(', ')}`);
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const MCP_PACKAGE_VERSION = "0.6.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,5 @@
+// Generated by scripts/generate-version.mjs. Do not edit.
+//
+// Resolved at build time rather than read from package.json at import time, so
+// importing this package touches no filesystem and survives bundling.
+export const MCP_PACKAGE_VERSION = '0.6.0';