@hypequery/mcp 0.8.6 → 0.10.0

package/dist/tools/tool-manifest.js

@@ -1,4 +1,5 @@
 import { SUPPORTED_TIME_GRAINS } from '@hypequery/datasets';
+import { resultSchema } from './utils/result-schema.js';
 const semanticMetadataProperties = {
     examples: { type: 'array', items: { type: 'string' } },
     synonyms: { type: 'array', items: { type: 'string' } },
@@ -10,53 +11,6 @@ const semanticMetadataProperties = {
         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,

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

@@ -1,4 +1,4 @@
-import { type CanonicalSemanticQuerySchemas } from '@hypequery/datasets';
+import { type CanonicalSemanticQuerySchemas } from '@hypequery/datasets/schemas';
 import type { DatasetRegistry, MCPQueryLimits } from '../../types.js';
 /**
  * Compile exact schemas for real Dataset registries. The shipped loose registry
@@ -13,5 +13,13 @@ export declare function buildMCPQuerySchemas(datasets: DatasetRegistry, configur
  * withheld as a direct target, which a hosted gateway needs when a caller is
  * entitled to a metric on a dataset it may not query itself.
  */
-queryableDatasets?: readonly string[]): CanonicalSemanticQuerySchemas;
+queryableDatasets?: readonly string[], 
+/**
+ * Advertise and accept `having` on `query_dataset`. On by default for every
+ * MCP surface: CORE-03 requires the hosted gateway to list exactly what the
+ * local executor runs, so hosted execution must support it too.
+ */
+features?: {
+    readonly having?: boolean;
+}): CanonicalSemanticQuerySchemas;
 //# sourceMappingURL=canonical-query-schemas.d.ts.map

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

@@ -1 +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;AAC3B;;;;;;GAMG;AACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,GACpC,6BAA6B,CAqG/B"}
+{"version":3,"file":"canonical-query-schemas.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/canonical-query-schemas.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA0BtE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,EACzB,UAAU,CAAC,EAAE,cAAc;AAC3B;;;;;;GAMG;AACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE;AACrC;;;;GAIG;AACH,QAAQ,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAqB,GACzD,6BAA6B,CAsG/B"}

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

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, } from '@hypequery/datasets';
+import { buildCanonicalSemanticQuerySchemas, toSemanticJsonSchema, } from '@hypequery/datasets/schemas';
 import { z } from 'zod';
 import { queryDatasetArgsSchema, queryMetricArgsSchema } from '../args.js';
 import { resolveQueryLimits } from './query-limits.js';
@@ -34,7 +34,13 @@ export function buildMCPQuerySchemas(datasets, configured,
  * withheld as a direct target, which a hosted gateway needs when a caller is
  * entitled to a metric on a dataset it may not query itself.
  */
-queryableDatasets) {
+queryableDatasets, 
+/**
+ * Advertise and accept `having` on `query_dataset`. On by default for every
+ * MCP surface: CORE-03 requires the hosted gateway to list exactly what the
+ * local executor runs, so hosted execution must support it too.
+ */
+features = { having: true }) {
     const limits = resolveQueryLimits(undefined, configured);
     const queryable = queryableDatasets === undefined ? undefined : new Set(queryableDatasets);
     const entries = Object.entries(datasets).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
@@ -58,6 +64,7 @@ queryableDatasets) {
             grainField: 'grain',
             ...limits,
             ...(queryableDatasets === undefined ? {} : { queryableDatasets }),
+            ...(features.having ? { having: true } : {}),
         });
     }
     const datasetSchemas = [];
@@ -66,7 +73,7 @@ queryableDatasets) {
     const metricJsonSchemas = [];
     for (const [name, dataset] of entries) {
         if (isCanonicalSchemaSource(dataset)) {
-            const exact = buildCanonicalSemanticQuerySchemas(withLegacyDirectMetrics({ [name]: dataset }), { grainField: 'grain', ...limits });
+            const exact = buildCanonicalSemanticQuerySchemas(withLegacyDirectMetrics({ [name]: dataset }), { grainField: 'grain', ...limits, ...(features.having ? { having: true } : {}) });
             if (queryable === undefined || queryable.has(name)) {
                 datasetSchemas.push(exact.queryDataset);
                 datasetJsonSchemas.push(exact.queryDatasetJsonSchema);

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

@@ -0,0 +1,5 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+type ObjectSchema = Tool['outputSchema'] & Record<string, unknown>;
+export declare function resultSchema(successSchema: Record<string, unknown>): ObjectSchema;
+export {};
+//# sourceMappingURL=result-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"result-schema.d.ts","sourceRoot":"","sources":["../../../src/tools/utils/result-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAE/D,KAAK,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA4CnE,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAKjF"}

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

@@ -0,0 +1,47 @@
+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'],
+};
+export function resultSchema(successSchema) {
+    return {
+        type: 'object',
+        oneOf: [successSchema, errorEnvelopeSchema],
+    };
+}

package/dist/utils/http-client/arguments.d.ts

@@ -0,0 +1,3 @@
+/** Read only own data properties. Nested query values go through the shared bounded validator. */
+export declare function httpToolArguments(input: unknown, allowed: readonly string[]): Record<string, unknown>;
+//# sourceMappingURL=arguments.d.ts.map

package/dist/utils/http-client/arguments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arguments.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/arguments.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBrG"}

package/dist/utils/http-client/arguments.js

@@ -0,0 +1,26 @@
+import { MCPToolError } from '../../errors.js';
+/** Read only own data properties. Nested query values go through the shared bounded validator. */
+export function httpToolArguments(input, allowed) {
+    try {
+        const value = input === undefined ? {} : input;
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new Error();
+        const keys = Reflect.ownKeys(value);
+        if (keys.length > allowed.length || keys.some(key => typeof key !== 'string' || !allowed.includes(key)))
+            throw new Error();
+        const result = Object.create(null);
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor))
+                throw new Error();
+            result[key] = descriptor.value;
+        }
+        return result;
+    }
+    catch {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'Invalid client tool arguments.');
+    }
+}

package/dist/utils/http-client/discovery.d.ts

@@ -0,0 +1,6 @@
+import type { ProtocolClientContract } from '@hypequery/protocol';
+export declare function clientDatasetNames(contract: ProtocolClientContract): string[];
+/** Preserve endpoint-specific permissions instead of merging them into a synthetic dataset. */
+export declare function clientDatasetProfile(contract: ProtocolClientContract, dataset: string): Record<string, unknown>;
+export declare function clientDatasetList(contract: ProtocolClientContract): Record<string, unknown>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/utils/http-client/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,EAAE,CAE7E;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM/G;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAY3F"}

package/dist/utils/http-client/discovery.js

@@ -0,0 +1,24 @@
+export function clientDatasetNames(contract) {
+    return [...new Set(contract.endpoints.map(endpoint => endpoint.dataset))].sort();
+}
+/** Preserve endpoint-specific permissions instead of merging them into a synthetic dataset. */
+export function clientDatasetProfile(contract, dataset) {
+    const endpoints = contract.endpoints.filter(endpoint => endpoint.dataset === dataset);
+    return {
+        name: dataset, queryable: endpoints.some(endpoint => endpoint.kind === 'dataset'),
+        endpoints: endpoints.map(({ path: _path, schemaHash: _hash, ...profile }) => profile),
+    };
+}
+export function clientDatasetList(contract) {
+    const datasets = clientDatasetNames(contract).map(name => {
+        const endpoints = contract.endpoints.filter(endpoint => endpoint.dataset === name);
+        return {
+            name, description: 'Authorized client endpoints.',
+            queryable: endpoints.some(endpoint => endpoint.kind === 'dataset'),
+            dimensionCount: new Set(endpoints.flatMap(endpoint => Object.keys(endpoint.dimensions))).size,
+            measureCount: new Set(endpoints.flatMap(endpoint => Object.keys(endpoint.measures))).size,
+            metricCount: endpoints.filter(endpoint => endpoint.kind === 'metric').length,
+        };
+    });
+    return { datasets, total: datasets.length };
+}

package/dist/utils/http-client/json.d.ts

@@ -0,0 +1,6 @@
+export declare class HttpResultJsonBudgetError extends Error {
+    constructor();
+}
+/** Budget/duplicate scan before native JSON parsing. Scalars retain HTTP binary64 semantics, including -0. */
+export declare function decodeHttpResultJson(text: string): unknown;
+//# sourceMappingURL=json.d.ts.map

package/dist/utils/http-client/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/json.ts"],"names":[],"mappings":"AAAA,qBAAa,yBAA0B,SAAQ,KAAK;;CAEnD;AAED,8GAA8G;AAC9G,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAoD1D"}

package/dist/utils/http-client/json.js

@@ -0,0 +1,79 @@
+export class HttpResultJsonBudgetError extends Error {
+    constructor() { super('HTTP result JSON exceeds validation limits.'); }
+}
+/** Budget/duplicate scan before native JSON parsing. Scalars retain HTTP binary64 semantics, including -0. */
+export function decodeHttpResultJson(text) {
+    if (Buffer.byteLength(text) > 1_048_576)
+        throw new HttpResultJsonBudgetError();
+    const stack = [];
+    let nodes = 0;
+    let position = 0;
+    const value = () => {
+        if (++nodes > 10_000)
+            throw new HttpResultJsonBudgetError();
+        const parent = stack[stack.length - 1];
+        if (parent && !parent.object && ++parent.count > 1000)
+            throw new HttpResultJsonBudgetError();
+    };
+    while (position < text.length) {
+        const character = text[position];
+        if (' \t\r\n:'.includes(character)) {
+            position++;
+            continue;
+        }
+        if (character === ',') {
+            const parent = stack[stack.length - 1];
+            if (parent?.object)
+                parent.key = true;
+            position++;
+            continue;
+        }
+        if (character === '{' || character === '[') {
+            value();
+            if (stack.length >= 16)
+                throw new HttpResultJsonBudgetError();
+            stack.push({ object: character === '{', keys: new Set(), key: character === '{', count: 0 });
+            position++;
+            continue;
+        }
+        if (character === '}' || character === ']') {
+            stack.pop();
+            position++;
+            continue;
+        }
+        if (character === '"') {
+            const start = position++;
+            let closed = false;
+            while (position < text.length) {
+                const current = text[position++];
+                if (current === '\\')
+                    position++;
+                else if (current === '"') {
+                    closed = true;
+                    break;
+                }
+            }
+            if (!closed)
+                throw new Error('Invalid JSON string');
+            const parent = stack[stack.length - 1];
+            if (parent?.object && parent.key) {
+                const key = JSON.parse(text.slice(start, position));
+                if (parent.keys.has(key))
+                    throw new Error('Duplicate JSON member');
+                parent.keys.add(key);
+                if (parent.keys.size > 1000)
+                    throw new HttpResultJsonBudgetError();
+                parent.key = false;
+            }
+            else
+                value();
+            continue;
+        }
+        value();
+        position++;
+        while (position < text.length && !' \t\r\n,]}:{["'.includes(text[position]))
+            position++;
+    }
+    // Native parsing owns JSON grammar validation; the scan only adds budgets and duplicate refusal.
+    return JSON.parse(text);
+}

package/dist/utils/http-client/manifest.d.ts

@@ -0,0 +1,5 @@
+import type { ClientContractQuerySchemas } from '@hypequery/datasets';
+import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+/** Fixed tool names, canonical client input schemas, and the actual public HTTP result envelope. */
+export declare function clientHttpManifest(schemas: ClientContractQuerySchemas, authorizedHash: string): ListToolsResult;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/utils/http-client/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAkC1E,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,GAAG,eAAe,CAiB/G"}

package/dist/utils/http-client/manifest.js

@@ -0,0 +1,53 @@
+import { buildMCPToolManifest } from '../../tools/tool-manifest.js';
+import { resultSchema } from '../../tools/utils/result-schema.js';
+const profileOutput = resultSchema({
+    type: 'object', additionalProperties: false, required: ['name', 'queryable', 'endpoints'],
+    properties: { name: { type: 'string' }, queryable: { type: 'boolean' }, endpoints: { type: 'array', items: { type: 'object' } } },
+});
+const listOutput = resultSchema({
+    type: 'object', additionalProperties: false, required: ['datasets', 'total'],
+    properties: {
+        datasets: { type: 'array', items: { type: 'object', additionalProperties: false,
+                required: ['name', 'description', 'queryable', 'dimensionCount', 'measureCount', 'metricCount'],
+                properties: { name: { type: 'string' }, description: { type: 'string' }, queryable: { type: 'boolean' },
+                    dimensionCount: { type: 'integer', minimum: 0 }, measureCount: { type: 'integer', minimum: 0 }, metricCount: { type: 'integer', minimum: 0 } },
+            } }, total: { type: 'integer', minimum: 0 },
+    },
+});
+const queryOutput = resultSchema({
+    type: 'object', additionalProperties: false, required: ['data'],
+    properties: {
+        data: { type: 'array', maxItems: 1000, items: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean', 'null'] } } },
+        meta: { type: ['object', 'null'], additionalProperties: false,
+            required: ['requestId', 'timingMs', 'rowCount', 'pagination'],
+            properties: {
+                requestId: { type: 'string' }, timingMs: { type: 'number', minimum: 0 }, rowCount: { type: 'integer', minimum: 0 },
+                pagination: { type: 'object', additionalProperties: false, required: ['limit', 'offset', 'hasMore'],
+                    properties: { limit: { type: 'integer', minimum: 1 }, offset: { type: 'integer', minimum: 0 }, hasMore: { type: 'boolean' } } },
+                cache: { type: 'object', additionalProperties: false, required: ['hit'], properties: { hit: { type: 'boolean' } } },
+            },
+        },
+    },
+});
+/** Fixed tool names, canonical client input schemas, and the actual public HTTP result envelope. */
+export function clientHttpManifest(schemas, authorizedHash) {
+    const manifest = buildMCPToolManifest(schemas);
+    for (const tool of manifest.tools) {
+        if (tool.name === 'get_dataset_schema') {
+            tool.description = 'Inspect authorized endpoint profiles for a dataset group. Each endpoint retains its own permissions and defaults.';
+            tool.inputSchema = { type: 'object', additionalProperties: false, properties: { dataset: { type: 'string' } }, required: ['dataset'] };
+            tool.outputSchema = profileOutput;
+        }
+        else if (tool.name === 'list_datasets') {
+            tool.description = 'List authorized dataset groups, including metric-only groups whose queryable flag is false.';
+            tool.inputSchema = { type: 'object', additionalProperties: false, properties: {} };
+            tool.outputSchema = listOutput;
+        }
+        else
+            tool.outputSchema = queryOutput;
+    }
+    return { ...manifest, _meta: {
+            'com.hypequery/clientContractHash': authorizedHash,
+            'com.hypequery/manifestHash': schemas.manifestHash,
+        } };
+}

package/dist/utils/http-client/profile.d.ts

@@ -0,0 +1,5 @@
+import { type ProtocolClientContract } from '@hypequery/protocol';
+import type { MCPQueryLimits } from '../../types.js';
+/** Lower operational limits only; the backend's endpoint schema hashes stay identical. */
+export declare function mcpClientProfile(contract: ProtocolClientContract, configured?: MCPQueryLimits): ProtocolClientContract;
+//# sourceMappingURL=profile.d.ts.map

package/dist/utils/http-client/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,sBAAsB,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,sBAAsB,CAuBtH"}

package/dist/utils/http-client/profile.js

@@ -0,0 +1,29 @@
+import { prepareProtocolClientContract } from '@hypequery/protocol';
+import { resolveQueryLimits } from '../../tools/utils/query-limits.js';
+import { MCPToolError } from '../../errors.js';
+/** Lower operational limits only; the backend's endpoint schema hashes stay identical. */
+export function mcpClientProfile(contract, configured) {
+    const limits = resolveQueryLimits(undefined, configured);
+    try {
+        return prepareProtocolClientContract({
+            kind: contract.kind, version: contract.version, view: contract.view,
+            endpoints: contract.endpoints.map(({ schemaHash: _hash, ...endpoint }) => ({
+                ...endpoint,
+                limits: {
+                    ...endpoint.limits,
+                    maxLimit: Math.min(endpoint.limits.maxLimit, limits.maxResultSize, 1000),
+                    defaultLimit: Math.min(endpoint.limits.defaultLimit, limits.defaultResultSize, limits.maxResultSize, 1000),
+                    maxOffset: Math.min(endpoint.limits.maxOffset, limits.maxOffset),
+                    maxDimensions: Math.min(endpoint.limits.maxDimensions, limits.maxDimensions),
+                    maxMeasures: Math.min(endpoint.limits.maxMeasures, limits.maxMeasures),
+                    maxPredicates: Math.min(endpoint.limits.maxPredicates, limits.maxFilters),
+                    maxOrderBy: Math.min(endpoint.limits.maxOrderBy, limits.maxOrderBy),
+                    maxFilterValues: Math.min(endpoint.limits.maxFilterValues, 1000),
+                },
+            })),
+        }).contract;
+    }
+    catch {
+        throw new MCPToolError('MCP_CATALOG_TOO_LARGE', 'Client defaults exceed MCP query ceilings; publish a narrower profile.', { retryable: false });
+    }
+}

package/dist/utils/http-client/result.d.ts

@@ -0,0 +1,4 @@
+import type { ClientQueryPlan } from '@hypequery/protocol';
+/** Duplicate-aware bounded JSON, closed public metadata and exact requested row fields. */
+export declare function clientHttpResult(text: string, plan: ClientQueryPlan): Record<string, unknown>;
+//# sourceMappingURL=result.d.ts.map

package/dist/utils/http-client/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AA2B3D,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2C7F"}

package/dist/utils/http-client/result.js

@@ -0,0 +1,98 @@
+import { MCPExecutionBudgetError, MCPToolError } from '../../errors.js';
+import { decodeHttpResultJson, HttpResultJsonBudgetError } from './json.js';
+function invalid() {
+    throw new MCPToolError('MCP_EXECUTION_FAILED', 'Backend returned an invalid client result.', { retryable: false });
+}
+function record(value, allowed) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return invalid();
+    if (allowed && Object.keys(value).some(key => !allowed.includes(key)))
+        return invalid();
+    return value;
+}
+function integer(value, minimum = 0) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+}
+function string(value) {
+    if (typeof value !== 'string')
+        return false;
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const low = value.charCodeAt(++index);
+            if (!(low >= 0xdc00 && low <= 0xdfff))
+                return false;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
+/** Duplicate-aware bounded JSON, closed public metadata and exact requested row fields. */
+export function clientHttpResult(text, plan) {
+    let parsed;
+    try {
+        parsed = decodeHttpResultJson(text);
+    }
+    catch (error) {
+        if (error instanceof HttpResultJsonBudgetError)
+            throw new MCPExecutionBudgetError('MCP_RESULT_TOO_LARGE', 'Backend result exceeds JSON limits.');
+        return invalid();
+    }
+    const result = record(parsed, ['data', 'meta']);
+    if (!Array.isArray(result.data) || result.data.length > plan.effectiveLimit)
+        return invalid();
+    const dimensions = plan.body.dimensions;
+    const fields = [...dimensions, ...plan.selectedMeasures, ...(plan.body.by === undefined ? [] : ['period'])];
+    for (const item of result.data) {
+        const row = record(item, fields);
+        if (Object.keys(row).length !== fields.length || fields.some(field => !Object.hasOwn(row, field)))
+            return invalid();
+        for (const field of fields) {
+            const value = row[field];
+            if (typeof value === 'number' && !Number.isFinite(value))
+                return invalid();
+            if (field === 'period' && plan.body.by !== undefined && value !== null
+                && (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}(?: \d{2}:\d{2}:\d{2})?$/.test(value)))
+                return invalid();
+            const dimension = Object.hasOwn(plan.endpoint.dimensions, field) && dimensions.includes(field) ? plan.endpoint.dimensions[field] : undefined;
+            if (value === null) {
+                if (dimension?.nullable === false)
+                    return invalid();
+            }
+            else if (!dimension) {
+                if (!string(value))
+                    return invalid();
+            }
+            else if (dimension.wireType === 'number-or-string') {
+                if (!(string(value) || typeof value === 'number' && Number.isFinite(value)))
+                    return invalid();
+            }
+            else if (dimension.wireType === 'string') {
+                if (!string(value))
+                    return invalid();
+            }
+            else if (typeof value !== dimension.wireType)
+                return invalid();
+        }
+    }
+    if (result.meta !== undefined && result.meta !== null) {
+        if (!plan.endpoint.metadata)
+            return invalid();
+        const meta = record(result.meta, ['requestId', 'timingMs', 'rowCount', 'pagination', 'cache']);
+        if (!string(meta.requestId) || meta.requestId.length === 0 || meta.requestId.length > 1024
+            || typeof meta.timingMs !== 'number' || meta.timingMs < 0 || !Number.isFinite(meta.timingMs)
+            || meta.rowCount !== result.data.length)
+            return invalid();
+        const pagination = record(meta.pagination, ['limit', 'offset', 'hasMore']);
+        if (!integer(pagination.limit, 1) || pagination.limit > plan.effectiveLimit
+            || pagination.offset !== plan.body.offset || typeof pagination.hasMore !== 'boolean'
+            || result.data.length > pagination.limit || pagination.hasMore && result.data.length !== pagination.limit)
+            return invalid();
+        if (meta.cache !== undefined && typeof record(meta.cache, ['hit']).hit !== 'boolean')
+            return invalid();
+    }
+    else if (plan.body.includeMeta === true)
+        return invalid();
+    return result;
+}

package/dist/utils/http-client/transport.d.ts

@@ -0,0 +1,12 @@
+export type BackendHeaders = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+export interface HttpBackend {
+    readonly discovery: URL;
+    readonly headers?: BackendHeaders;
+    readonly fetchFn: typeof fetch;
+}
+export declare function backendUrl(input: string): URL;
+export declare function backendRequest(backend: HttpBackend, url: URL, signal: AbortSignal, body?: Readonly<Record<string, unknown>>, schemaHash?: string): Promise<Response>;
+export declare function discardBackendBody(response: Response): void;
+/** Bound decompressed streamed bytes, including when Content-Length is absent or dishonest. */
+export declare function backendText(response: Response, maximum: number, signal: AbortSignal): Promise<string>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/utils/http-client/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/utils/http-client/transport.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;AACvH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;CAChC;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAQ7C;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GACjH,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAE3D;AAED,+FAA+F;AAC/F,wBAAsB,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsC3G"}