@hypequery/mcp 0.5.5 → 0.6.0

package/dist/tools/introspect.js

@@ -1,180 +1,57 @@
-/**
- * Get Dataset Schema Tool
- *
- * Returns the complete schema for a dataset including dimensions, measures,
- * named metrics, filters, and relationships.
- */
-import { getDatasetCatalog, listQueryableRelationshipFields } from '@hypequery/datasets';
+/** Agent-safe dataset discovery and separately authorized trusted debugging. */
+import { assertAgentSafeCatalogBudget, projectAgentSafeCatalog, projectTrustedDebugCatalog, } from '@hypequery/datasets';
+import { MCPToolError } from '../errors.js';
+import { projectLegacyAgentDataset } from './utils/legacy-agent-catalog.js';
+import { createMCPToolResponse } from './utils/tool-response.js';
+function datasetNameFromArgs(args) {
+    const datasetName = args && typeof args === 'object' && !Array.isArray(args)
+        ? args.dataset
+        : undefined;
+    if (typeof datasetName !== 'string' || datasetName.length === 0) {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'dataset parameter is required');
+    }
+    return datasetName;
+}
 function isDatasetInstance(value) {
     return !!value && typeof value === 'object' && value.__type === 'dataset';
 }
-export async function getDatasetSchemaTool(datasets, args, options = {}) {
-    // Parse and validate args
-    const validatedArgs = args;
-    const datasetName = validatedArgs.dataset;
-    if (!datasetName) {
-        throw new Error('dataset parameter is required');
-    }
+export async function getDatasetSchemaTool(datasets, args, _options = {}) {
+    const datasetName = datasetNameFromArgs(args);
     const dataset = datasets[datasetName];
     if (!dataset) {
-        throw new Error(`Dataset not found: ${datasetName}`);
+        throw new MCPToolError('MCP_NOT_FOUND', `Dataset not found: ${datasetName}`);
     }
-    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: {},
-        measures: {},
-        metrics: {},
-        filters: {},
-        relationships: {},
-        limits: datasetAny.limits,
-    };
-    if (isDatasetInstance(dataset)) {
-        const catalog = getDatasetCatalog(dataset);
-        schema.source = catalog.source;
-        schema.timeKey = catalog.timeKey ?? null;
-        schema.tenantKey = catalog.tenantKey ?? null;
-        schema.limits = catalog.limits;
-        for (const [name, dimension] of Object.entries(catalog.dimensions)) {
-            const dimSchema = {
-                type: dimension.type,
-                column: dimension.column ?? name,
-                sql: options.includeSql ? dimension.sql ?? null : null,
-                label: dimension.label || name,
-                description: dimension.description || '',
-                examples: [],
-                filterable: dimension.filterable,
-                groupable: dimension.groupable,
-            };
-            schema.dimensions[name] = dimSchema;
+    let schema;
+    try {
+        if (isDatasetInstance(dataset)) {
+            schema = projectAgentSafeCatalog({ [datasetName]: dataset }).datasets[0];
         }
-        for (const [name, measure] of Object.entries(catalog.measures)) {
-            const measureSchema = {
-                aggregation: measure.aggregation,
-                field: measure.field,
-                sql: options.includeSql ? measure.sql ?? null : null,
-                label: measure.label || name,
-                description: measure.description || '',
-            };
-            schema.measures[name] = measureSchema;
-        }
-        for (const [name, filter] of Object.entries(catalog.filters)) {
-            const filterSchema = {
-                field: filter.field,
-                label: filter.label || name,
-                description: filter.description || '',
-                operators: filter.operators ? [...filter.operators] : null,
-            };
-            schema.filters[name] = filterSchema;
-        }
-        for (const [name, metric] of Object.entries(catalog.metrics)) {
-            const metSchema = {
-                type: metric.kind,
-                aggregation: metric.measures?.join(', ') || '',
-                label: metric.label || name,
-                description: metric.description || '',
-                format: null,
-            };
-            schema.metrics[name] = metSchema;
-        }
-        for (const [name, relationship] of Object.entries(catalog.relationships)) {
-            const relSchema = {
-                type: relationship.kind,
-                target: relationship.target,
-                from: relationship.from,
-                to: relationship.to,
-                queryable: relationship.queryable,
-                fields: relationship.fields,
-                description: '',
-            };
-            schema.relationships[name] = relSchema;
+        else {
+            schema = projectLegacyAgentDataset(datasetName, dataset, datasets);
+            assertAgentSafeCatalogBudget({ datasets: [schema] });
         }
     }
-    else {
-        // Legacy object-shaped fixtures/configs.
-        if (datasetAny.dimensions) {
-            for (const [name, dimension] of Object.entries(datasetAny.dimensions)) {
-                const dimSchema = {
-                    type: dimension.fieldType || dimension.type || 'unknown',
-                    column: dimension.column || name,
-                    sql: options.includeSql ? dimension.sql || null : null,
-                    label: dimension.label || name,
-                    description: dimension.description || '',
-                    examples: dimension.examples || [],
-                    filterable: dimension.filterable !== false,
-                    groupable: dimension.groupable !== false,
-                };
-                schema.dimensions[name] = dimSchema;
-            }
-        }
-        if (datasetAny.measures) {
-            for (const [name, measure] of Object.entries(datasetAny.measures)) {
-                const measureSchema = {
-                    aggregation: measure.aggregation || measure.type || 'unknown',
-                    field: measure.field || name,
-                    sql: options.includeSql ? measure.sql || null : null,
-                    label: measure.label || name,
-                    description: measure.description || '',
-                };
-                schema.measures[name] = measureSchema;
-            }
-        }
-        if (datasetAny.filters) {
-            for (const [name, filter] of Object.entries(datasetAny.filters)) {
-                const filterSchema = {
-                    field: filter.field || name,
-                    label: filter.label || name,
-                    description: filter.description || '',
-                    operators: filter.operators || null,
-                };
-                schema.filters[name] = filterSchema;
-            }
-        }
-        if (datasetAny.relationships) {
-            for (const [name, relationship] of Object.entries(datasetAny.relationships)) {
-                const rel = relationship;
-                // Raw config relationships don't carry the catalog's computed
-                // queryable/fields metadata; derive it when the shape allows.
-                const kind = rel.type || rel.kind;
-                const hasResolvableTarget = typeof rel.target === 'function';
-                const relSchema = {
-                    type: kind || 'unknown',
-                    target: hasResolvableTarget ? rel.target()?.name || '' : rel.target || rel.dataset?.name || '',
-                    from: rel.from,
-                    to: rel.to,
-                    queryable: rel.queryable ?? (kind ? kind !== 'hasMany' : undefined),
-                    fields: rel.fields ?? (kind && hasResolvableTarget
-                        ? listQueryableRelationshipFields(name, { ...rel, kind })
-                        : kind && kind !== 'hasMany' ? [] : undefined),
-                    description: rel.description || '',
-                };
-                schema.relationships[name] = relSchema;
-            }
-        }
+    catch (error) {
+        if (!(error instanceof RangeError && error.message.startsWith('Agent-safe catalog exceeds ')))
+            throw error;
+        throw new MCPToolError('MCP_RESULT_TOO_LARGE', `Dataset schema exceeds the agent-safe catalog byte limit: ${datasetName}`);
     }
-    // Backward compatibility for legacy object-shaped dataset fixtures.
-    if (!isDatasetInstance(dataset) && 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;
-        }
+    return createMCPToolResponse(schema);
+}
+/**
+ * Physical catalog diagnostics for a caller that has already passed a
+ * separate authorization check. This projection is intentionally not
+ * registered as an agent-facing MCP tool.
+ */
+export async function getTrustedDatasetSchema(datasets, args, authorization) {
+    const datasetName = datasetNameFromArgs(args);
+    const dataset = datasets[datasetName];
+    if (!dataset) {
+        throw new MCPToolError('MCP_NOT_FOUND', `Dataset not found: ${datasetName}`);
+    }
+    if (!isDatasetInstance(dataset)) {
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'Trusted debugging requires a canonical dataset instance');
     }
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(schema, null, 2),
-            },
-        ],
-    };
+    const debug = projectTrustedDebugCatalog({ [datasetName]: dataset }, authorization);
+    return debug.kind === 'dataset-catalog' ? debug.datasets[datasetName] : debug;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"list-datasets.d.ts","sourceRoot":"","sources":["../../src/tools/list-datasets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAyC,MAAM,aAAa,CAAC;AAM3G,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA2C1F"}
+{"version":3,"file":"list-datasets.d.ts","sourceRoot":"","sources":["../../src/tools/list-datasets.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAyC,MAAM,aAAa,CAAC;AAO3G,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAoC1F"}

package/dist/tools/list-datasets.js

@@ -4,6 +4,7 @@
  * Returns a list of all available datasets with their descriptions.
  */
 import { getDatasetCatalog } from '@hypequery/datasets';
+import { createMCPToolResponse } from './utils/tool-response.js';
 function isDatasetInstance(value) {
     return !!value && typeof value === 'object' && value.__type === 'dataset';
 }
@@ -37,12 +38,5 @@ export async function listDatasetsTool(datasets) {
         datasets: datasetList,
         total: datasetList.length,
     };
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(response, null, 2),
-            },
-        ],
-    };
+    return createMCPToolResponse(response);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"query-dataset.d.ts","sourceRoot":"","sources":["../../src/tools/query-dataset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3G,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA8D1B"}
+{"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;AAEvE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAYtF,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CA2D1B"}

package/dist/tools/query-dataset.js

@@ -3,57 +3,53 @@
  *
  * Executes an ad-hoc dataset query with custom dimensions and measures.
  */
-import { parseToolArgs, queryDatasetArgsSchema, toMetricFilters } from './args.js';
+import { MCPToolError } from '../errors.js';
+import { parseToolArgs, toMetricFilters } from './args.js';
+import { buildMCPQuerySchemas } from './utils/canonical-query-schemas.js';
+import { applyQueryLimits } from './utils/query-limits.js';
+import { assertWithinBudget, executeWithinBudget, resolveExecutionBudget, } from './utils/execution-budget.js';
+import { buildMCPQueryResult } from './utils/query-result.js';
+import { createMCPToolResponse } from './utils/tool-response.js';
 export async function queryDatasetTool(datasets, analytics, args, options = {}) {
-    const validatedArgs = parseToolArgs(queryDatasetArgsSchema, 'query_dataset', args);
-    const { dataset: datasetName, dimensions, measures, filters, grain, orderBy, limit, offset } = validatedArgs;
+    const inputSchema = options.inputSchema ?? buildMCPQuerySchemas(datasets, options.limits).queryDataset;
+    const validatedArgs = parseToolArgs(inputSchema, 'query_dataset', args);
+    const { dataset: datasetName, dimensions, measures, filters, grain, orderBy } = validatedArgs;
     if (!datasetName) {
-        throw new Error('dataset parameter is required');
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'dataset parameter is required');
     }
     const dataset = datasets[datasetName];
     if (!dataset) {
-        throw new Error(`Dataset not found: ${datasetName}`);
+        throw new MCPToolError('MCP_NOT_FOUND', `Dataset not found: ${datasetName}`);
     }
     if (!dimensions?.length && !measures?.length) {
-        throw new Error('At least one dimension or measure must be specified');
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'At least one dimension or measure must be specified');
     }
+    const pagination = applyQueryLimits(dataset, validatedArgs, options.limits);
+    const executionBudget = resolveExecutionBudget(options.executionBudget);
     // Build the query with proper types
     const query = {
         dimensions: dimensions || [],
         measures: measures || [],
         filters: toMetricFilters(filters),
         orderBy: orderBy || [],
+        limit: pagination.limit,
     };
     if (grain) {
         query.by = grain;
     }
-    if (limit !== undefined) {
-        query.limit = limit;
+    if (pagination.offset !== undefined) {
+        query.offset = pagination.offset;
     }
-    if (offset !== undefined) {
-        query.offset = offset;
-    }
-    const result = await analytics.execute(dataset, query, {
+    const result = await executeWithinBudget(signal => analytics.execute(dataset, query, {
         runtime: {
             tenant: options.tenantId ? { id: options.tenantId } : undefined,
         },
-    });
+        abortSignal: signal,
+        cache: false,
+    }), executionBudget, options.signal);
     // Format the response with proper types
-    const response = {
-        data: result.data,
-        meta: {
-            ...(options.includeSql ? { sql: result.meta?.sql } : {}),
-            timingMs: result.meta?.timingMs,
-            rowCount: result.data.length,
-            ...(result.meta?.pagination ? { pagination: result.meta.pagination } : {}),
-        },
-    };
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(response, null, 2),
-            },
-        ],
-    };
+    const response = buildMCPQueryResult(result, options.includeSql);
+    const toolResponse = createMCPToolResponse(response);
+    assertWithinBudget(toolResponse, executionBudget);
+    return toolResponse;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"query-metric.d.ts","sourceRoot":"","sources":["../../src/tools/query-metric.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG3G,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAqE1B"}
+{"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;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAYtF,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkE1B"}

package/dist/tools/query-metric.js

@@ -3,62 +3,58 @@
  *
  * Executes a metric query with optional dimensions, filters, grain, and sorting.
  */
-import { parseToolArgs, queryMetricArgsSchema, toMetricFilters } from './args.js';
+import { MCPToolError } from '../errors.js';
+import { parseToolArgs, toMetricFilters } from './args.js';
+import { buildMCPQuerySchemas } from './utils/canonical-query-schemas.js';
+import { applyQueryLimits } from './utils/query-limits.js';
+import { assertWithinBudget, executeWithinBudget, resolveExecutionBudget, } from './utils/execution-budget.js';
+import { buildMCPQueryResult } from './utils/query-result.js';
+import { createMCPToolResponse } from './utils/tool-response.js';
 export async function queryMetricTool(datasets, analytics, args, options = {}) {
-    const validatedArgs = parseToolArgs(queryMetricArgsSchema, 'query_metric', args);
-    const { dataset: datasetName, metric: metricName, dimensions, filters, grain, orderBy, limit, offset } = validatedArgs;
+    const inputSchema = options.inputSchema ?? buildMCPQuerySchemas(datasets, options.limits).queryMetric;
+    const validatedArgs = parseToolArgs(inputSchema, 'query_metric', args);
+    const { dataset: datasetName, metric: metricName, dimensions, filters, grain, orderBy } = validatedArgs;
     if (!datasetName) {
-        throw new Error('dataset parameter is required');
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'dataset parameter is required');
     }
     if (!metricName) {
-        throw new Error('metric parameter is required');
+        throw new MCPToolError('MCP_INVALID_ARGUMENTS', 'metric parameter is required');
     }
     const dataset = datasets[datasetName];
     if (!dataset) {
-        throw new Error(`Dataset not found: ${datasetName}`);
+        throw new MCPToolError('MCP_NOT_FOUND', `Dataset not found: ${datasetName}`);
     }
     // Get the metric from the dataset
     const metric = dataset[metricName] || dataset.metrics?.[metricName];
     if (!metric) {
-        throw new Error(`Metric not found: ${metricName} in dataset ${datasetName}`);
+        throw new MCPToolError('MCP_NOT_FOUND', `Metric not found: ${metricName} in dataset ${datasetName}`);
     }
+    const pagination = applyQueryLimits(dataset, validatedArgs, options.limits);
+    const executionBudget = resolveExecutionBudget(options.executionBudget);
     // Build the query with proper types
     const query = {
         dimensions: dimensions || [],
         filters: toMetricFilters(filters),
         orderBy: orderBy || [],
+        limit: pagination.limit,
     };
     if (grain) {
         query.by = grain;
     }
-    if (limit !== undefined) {
-        query.limit = limit;
-    }
-    if (offset !== undefined) {
-        query.offset = offset;
+    if (pagination.offset !== undefined) {
+        query.offset = pagination.offset;
     }
     // Execute the query
-    const result = await analytics.execute(metric, query, {
+    const result = await executeWithinBudget(signal => analytics.execute(metric, query, {
         runtime: {
             tenant: options.tenantId ? { id: options.tenantId } : undefined,
         },
-    });
+        abortSignal: signal,
+        cache: false,
+    }), executionBudget, options.signal);
     // Format the response with proper types
-    const response = {
-        data: result.data,
-        meta: {
-            ...(options.includeSql ? { sql: result.meta?.sql } : {}),
-            timingMs: result.meta?.timingMs,
-            rowCount: result.data.length,
-            ...(result.meta?.pagination ? { pagination: result.meta.pagination } : {}),
-        },
-    };
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(response, null, 2),
-            },
-        ],
-    };
+    const response = buildMCPQueryResult(result, options.includeSql);
+    const toolResponse = createMCPToolResponse(response);
+    assertWithinBudget(toolResponse, executionBudget);
+    return toolResponse;
 }

package/dist/tools/tool-manifest.d.ts

@@ -0,0 +1,28 @@
+import type { CanonicalSemanticQuerySchemas } from '@hypequery/datasets';
+import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+export declare const DATASET_LIST_OUTPUT_SCHEMA: {
+    [x: string]: unknown;
+    type: "object";
+    properties?: {
+        [x: string]: object;
+    } | undefined;
+    required?: string[] | undefined;
+} & Record<string, unknown>;
+export declare const DATASET_SCHEMA_OUTPUT_SCHEMA: {
+    [x: string]: unknown;
+    type: "object";
+    properties?: {
+        [x: string]: object;
+    } | undefined;
+    required?: string[] | undefined;
+} & Record<string, unknown>;
+export declare const QUERY_OUTPUT_SCHEMA: {
+    [x: string]: unknown;
+    type: "object";
+    properties?: {
+        [x: string]: object;
+    } | undefined;
+    required?: string[] | undefined;
+} & Record<string, unknown>;
+export declare function buildMCPToolManifest(querySchemas: CanonicalSemanticQuerySchemas): ListToolsResult;
+//# sourceMappingURL=tool-manifest.d.ts.map

package/dist/tools/tool-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-manifest.d.ts","sourceRoot":"","sources":["../../src/tools/tool-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAQ,MAAM,oCAAoC,CAAC;AAkEhF,eAAO,MAAM,0BAA0B;;;;;;;2BAsBrC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;2BA0HvC,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;2BAwC9B,CAAC;AAYH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,6BAA6B,GAC1C,eAAe,CA8CjB"}