@hypequery/mcp 0.5.5 → 0.6.0

package/README.md

@@ -14,12 +14,11 @@ npm install @hypequery/mcp @hypequery/datasets @hypequery/clickhouse
 
 ```ts
 // mcp-config.ts
-export const datasets = {
-  orders: {
-    ...Orders,
-    metrics: { revenue },
-  },
-};
+import { publishDatasets } from '@hypequery/datasets';
+
+export const datasets = publishDatasets()
+  .publish(Orders, { metrics: { revenue } })
+  .build();
 
 export const analytics = createDatasetClient({ queryBuilder: db });
 ```
@@ -56,9 +55,34 @@ Now an agent can ask, “Show revenue by region for the last month,” using the
 - `query_metric` executes named KPIs;
 - `query_dataset` explores the fields you chose to publish.
 
+Every tool declares an output schema and returns the same result twice: MCP
+`structuredContent` for clients that support typed results, and compact JSON in
+the text content block for compatibility. Query metadata includes row count,
+timing when available, pagination state, and cache outcome. Tools also advertise
+human-readable titles and read-only, non-destructive, idempotent annotations.
+
+Tool failures use a stable structured envelope:
+
+```json
+{
+  "error": {
+    "code": "MCP_INVALID_ARGUMENTS",
+    "category": "correctable_input",
+    "message": "Invalid query_dataset arguments: ...",
+    "retryable": false,
+    "correctable": true
+  }
+}
+```
+
+Unclassified backend failures are redacted to `MCP_EXECUTION_FAILED`; database
+error details and physical SQL are not copied into agent-facing errors.
+
 ## Safer than raw SQL access
 
 - Tool schemas come from your TypeScript semantic layer.
+- Advertised schemas and runtime validation use the same canonical catalog
+  compiler and deterministic manifest hash.
 - Filters, fields, ordering, and limits are validated.
 - ClickHouse credentials remain in the server process.
 - SQL text stays hidden by default.
@@ -73,9 +97,62 @@ await createMCPServer({
   name: 'acme-analytics',
   version: '1.0.0',
   tenantId: session.accountId,
+  queryLimits: {
+    defaultResultSize: 100,
+    maxResultSize: 1_000,
+    maxOffset: 10_000,
+  },
+  executionBudget: {
+    timeoutMs: 30_000,
+    maxResponseBytes: 1_048_576,
+  },
 });
 ```
 
+Every query receives a server-side limit even when the agent omits one. The
+effective ceiling is the lowest applicable server or Dataset limit. Dimensions,
+measures, filters, ordering, and pagination offsets also have hard package
+ceilings that server configuration may lower but cannot raise.
+
+Query calls also have a hard wall-clock deadline and UTF-8 response-byte
+ceiling. Client cancellation and local deadlines propagate through the semantic
+client to the backing ClickHouse request. Budget failures use the stable
+`MCP_REQUEST_CANCELLED`, `MCP_QUERY_TIMEOUT`, and `MCP_RESULT_TOO_LARGE`
+classifications.
+
+## Embed in another MCP transport
+
+The semantic executor is independent of stdio and network lifecycle. A hosted
+gateway can inject its own MCP transport without reimplementing Hypequery's
+tools, prompts, catalog schemas, or validation:
+
+```ts
+import {
+  createMCPExecutor,
+  createMCPProtocolServer,
+} from '@hypequery/mcp';
+
+const executor = createMCPExecutor({
+  datasets,
+  analytics,
+  tenantId: trustedPrincipal.tenantId,
+});
+
+const server = createMCPProtocolServer({
+  executor,
+  name: 'acme-hosted-analytics',
+  version: '1.0.0',
+});
+
+await server.connect(hostTransport);
+```
+
+`hostTransport` can be an MCP SDK in-memory, stdio, or hosted transport. This
+package does not create an HTTP endpoint; authentication, routing, and network
+lifecycle remain responsibilities of the host. For an explicit local adapter,
+use `startStdioMCPServer(config)`. The existing `createMCPServer(config)` and
+`HypequeryMCPServer.start()` APIs remain available for compatibility.
+
 ## Learn more
 
 - [ClickHouse MCP overview](https://hypequery.com/clickhouse-mcp)

package/dist/api.type-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.type-test.d.ts.map

package/dist/api.type-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.type-test.d.ts","sourceRoot":"","sources":["../src/api.type-test.ts"],"names":[],"mappings":""}

package/dist/api.type-test.js

@@ -0,0 +1,14 @@
+import { expectTypeOf, it } from 'vitest';
+import { HypequeryMCPExecutor, HypequeryMCPProtocolServer, HypequeryMCPServer, MCPToolError, connectMCPServerStdio, createMCPExecutor, createMCPProtocolServer, createMCPServer, startStdioMCPServer, } from './index.js';
+it('exports the transport-neutral and backwards-compatible MCP APIs', () => {
+    expectTypeOf(HypequeryMCPExecutor).toBeConstructibleWith({});
+    expectTypeOf(HypequeryMCPProtocolServer).toBeConstructibleWith({});
+    expectTypeOf(HypequeryMCPServer).toBeConstructibleWith({});
+    expectTypeOf(createMCPExecutor).returns.toMatchTypeOf();
+    expectTypeOf(createMCPProtocolServer).returns.toMatchTypeOf();
+    expectTypeOf(connectMCPServerStdio).returns.toMatchTypeOf();
+    expectTypeOf(startStdioMCPServer).returns.toMatchTypeOf();
+    expectTypeOf(createMCPServer).returns.toMatchTypeOf();
+    expectTypeOf(new MCPToolError('MCP_UNAUTHORIZED', 'Forbidden').code)
+        .toMatchTypeOf();
+});

package/dist/bin.js

@@ -12,6 +12,7 @@ import { createMCPServer } from './server.js';
 import { pathToFileURL } from 'url';
 import { resolve } from 'path';
 import { format } from 'util';
+import { MCP_PACKAGE_VERSION } from './version.js';
 function routeConsoleOutputToStderr() {
     const write = (...args) => {
         process.stderr.write(`${format(...args)}\n`);
@@ -53,7 +54,7 @@ async function main() {
             datasets,
             analytics,
             name: 'hypequery-mcp-server',
-            version: '0.1.0',
+            version: MCP_PACKAGE_VERSION,
         });
         // Keep the process running
         process.on('SIGINT', () => {

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+export type MCPToolErrorCode = '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';
+export type MCPToolErrorCategory = 'correctable_input' | 'unauthorized' | 'stale_contract' | 'budget' | 'internal';
+/** @deprecated Use MCPToolErrorCode. */
+export type MCPExecutionErrorCode = Extract<MCPToolErrorCode, 'MCP_REQUEST_CANCELLED' | 'MCP_QUERY_TIMEOUT' | 'MCP_RESULT_TOO_LARGE'>;
+export interface MCPErrorDetails {
+    code: MCPToolErrorCode;
+    category: MCPToolErrorCategory;
+    message: string;
+    retryable: boolean;
+    correctable: boolean;
+}
+export declare class MCPToolError extends Error {
+    readonly code: MCPToolErrorCode;
+    readonly category: MCPToolErrorCategory;
+    readonly retryable: boolean;
+    readonly correctable: boolean;
+    constructor(code: MCPToolErrorCode, message: string, options?: {
+        category?: MCPToolErrorCategory;
+        retryable?: boolean;
+        correctable?: boolean;
+    });
+}
+export declare class MCPExecutionBudgetError extends MCPToolError {
+    readonly code: MCPExecutionErrorCode;
+    constructor(code: MCPExecutionErrorCode, message: string);
+}
+export declare function classifyMCPToolError(error: unknown): MCPErrorDetails;
+export declare function formatMCPToolError(error: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,uBAAuB,GACvB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,mBAAmB,GACnB,sBAAsB,GACtB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,cAAc,GACd,gBAAgB,GAChB,QAAQ,GACR,UAAU,CAAC;AAEf,wCAAwC;AACxC,MAAM,MAAM,qBAAqB,GAAG,OAAO,CACzC,gBAAgB,EAChB,uBAAuB,GAAG,mBAAmB,GAAG,sBAAsB,CACvE,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;CACtB;AAsBD,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAG5B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,QAAQ,CAAC,EAAE,oBAAoB,CAAC;QAChC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,WAAW,CAAC,EAAE,OAAO,CAAC;KAClB;CAUT;AAED,qBAAa,uBAAwB,SAAQ,YAAY;IACvD,SAAiB,IAAI,EAAE,qBAAqB,CAAC;gBAEjC,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM;CAOzD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAkBpE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAGzD"}

package/dist/errors.js

@@ -0,0 +1,65 @@
+function defaultErrorMetadata(code) {
+    switch (code) {
+        case 'MCP_INVALID_ARGUMENTS':
+        case 'MCP_NOT_FOUND':
+        case 'MCP_UNKNOWN_TOOL':
+            return { category: 'correctable_input', retryable: false, correctable: true };
+        case 'MCP_UNAUTHORIZED':
+            return { category: 'unauthorized', retryable: false, correctable: false };
+        case 'MCP_STALE_CONTRACT':
+            return { category: 'stale_contract', retryable: true, correctable: false };
+        case 'MCP_REQUEST_CANCELLED':
+        case 'MCP_RESULT_TOO_LARGE':
+            return { category: 'budget', retryable: false, correctable: false };
+        case 'MCP_QUERY_TIMEOUT':
+            return { category: 'budget', retryable: true, correctable: false };
+        case 'MCP_EXECUTION_FAILED':
+            return { category: 'internal', retryable: true, correctable: false };
+    }
+}
+export class MCPToolError extends Error {
+    code;
+    category;
+    retryable;
+    correctable;
+    constructor(code, message, options = {}) {
+        super(message);
+        const defaults = defaultErrorMetadata(code);
+        this.name = 'MCPToolError';
+        this.code = code;
+        this.category = options.category ?? defaults.category;
+        this.retryable = options.retryable ?? defaults.retryable;
+        this.correctable = options.correctable ?? defaults.correctable;
+    }
+}
+export class MCPExecutionBudgetError extends MCPToolError {
+    constructor(code, message) {
+        super(code, message, {
+            category: 'budget',
+            retryable: code === 'MCP_QUERY_TIMEOUT',
+        });
+        this.name = 'MCPExecutionBudgetError';
+    }
+}
+export function classifyMCPToolError(error) {
+    if (error instanceof MCPToolError) {
+        return {
+            code: error.code,
+            category: error.category,
+            message: error.message,
+            retryable: error.retryable,
+            correctable: error.correctable,
+        };
+    }
+    return {
+        code: 'MCP_EXECUTION_FAILED',
+        category: 'internal',
+        message: 'Query execution failed',
+        retryable: true,
+        correctable: false,
+    };
+}
+export function formatMCPToolError(error) {
+    const classified = classifyMCPToolError(error);
+    return `Error [${classified.code}]: ${classified.message}`;
+}

package/dist/executor.d.ts

@@ -0,0 +1,50 @@
+import type { CallToolResult, GetPromptResult, ListPromptsResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+import type { DatasetClient } from '@hypequery/datasets';
+import type { DatasetRegistry, MCPExecutionBudget, MCPQueryLimits } from './types.js';
+export interface MCPExecutorConfig {
+    /** Dataset registry - map of dataset names to instances. */
+    datasets: DatasetRegistry;
+    /** Semantic analytics client for running metric and dataset queries. */
+    analytics: DatasetClient;
+    /** Trusted tenant id used to scope tenant-keyed datasets. */
+    tenantId?: string;
+    /** Include generated SQL in trusted-debug responses. Defaults to false. */
+    includeSql?: boolean;
+    /** Server-side query ceilings applied in addition to Dataset limits. */
+    queryLimits?: MCPQueryLimits;
+    /** Query deadline and serialized-result byte ceilings. */
+    executionBudget?: MCPExecutionBudget;
+}
+export interface MCPServerConfig extends MCPExecutorConfig {
+    /** Server name shown to MCP clients. */
+    name?: string;
+    /** Server version shown to MCP clients. */
+    version?: string;
+}
+export interface MCPToolExecutor {
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<CallToolResult>;
+    listPrompts(): Promise<ListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
+    getManifestHash(): string;
+}
+/**
+ * Transport-neutral Hypequery MCP tool and prompt executor.
+ *
+ * This class owns semantic discovery and execution, but has no network or stdio
+ * lifecycle. It can be called directly or injected into any MCP transport
+ * adapter.
+ */
+export declare class HypequeryMCPExecutor implements MCPToolExecutor {
+    private readonly config;
+    private readonly querySchemas;
+    private readonly executionBudget;
+    constructor(config: MCPExecutorConfig);
+    getManifestHash(): string;
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<CallToolResult>;
+    listPrompts(): Promise<ListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
+}
+export declare function createMCPExecutor(config: MCPExecutorConfig): HypequeryMCPExecutor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAEV,aAAa,EACd,MAAM,qBAAqB,CAAC;AAe7B,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOtF,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,EAAE,eAAe,CAAC;IAC1B,wEAAwE;IACxE,SAAS,EAAE,aAAa,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,wEAAwE;IACxE,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,0DAA0D;IAC1D,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACtC,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3B,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjF,eAAe,IAAI,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,YAAW,eAAe;IAI9C,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;gBAE9B,MAAM,EAAE,iBAAiB;IAOtD,eAAe,IAAI,MAAM;IAInB,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAIrC,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC;IAwDpB,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAkBzC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;CAOvF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAEjF"}

package/dist/executor.js

@@ -0,0 +1,103 @@
+import { MCPToolError } from './errors.js';
+import { datasetGuidePrompt } from './prompts/dataset-guide.js';
+import { getDatasetSchemaTool } from './tools/introspect.js';
+import { listDatasetsTool } from './tools/list-datasets.js';
+import { queryDatasetTool } from './tools/query-dataset.js';
+import { queryMetricTool } from './tools/query-metric.js';
+import { buildMCPToolManifest } from './tools/tool-manifest.js';
+import { buildMCPQuerySchemas } from './tools/utils/canonical-query-schemas.js';
+import { assertWithinBudget, resolveExecutionBudget, } from './tools/utils/execution-budget.js';
+import { resolveQueryLimits } from './tools/utils/query-limits.js';
+import { validateMCPServerTenantConfig } from './utils/tenant-config.js';
+import { createMCPErrorResponse, createMCPResultTooLargeResponse, } from './tools/utils/tool-response.js';
+/**
+ * Transport-neutral Hypequery MCP tool and prompt executor.
+ *
+ * This class owns semantic discovery and execution, but has no network or stdio
+ * lifecycle. It can be called directly or injected into any MCP transport
+ * adapter.
+ */
+export class HypequeryMCPExecutor {
+    config;
+    querySchemas;
+    executionBudget;
+    constructor(config) {
+        this.config = config;
+        validateMCPServerTenantConfig(config);
+        resolveQueryLimits(undefined, config.queryLimits);
+        this.executionBudget = resolveExecutionBudget(config.executionBudget);
+        this.querySchemas = buildMCPQuerySchemas(config.datasets ?? {}, config.queryLimits);
+    }
+    getManifestHash() {
+        return this.querySchemas.manifestHash;
+    }
+    async listTools() {
+        return buildMCPToolManifest(this.querySchemas);
+    }
+    async callTool(name, args, signal) {
+        try {
+            switch (name) {
+                case 'list_datasets':
+                    return await listDatasetsTool(this.config.datasets);
+                case 'get_dataset_schema':
+                    return await getDatasetSchemaTool(this.config.datasets, args);
+                case 'query_metric':
+                    return await queryMetricTool(this.config.datasets, this.config.analytics, args, {
+                        tenantId: this.config.tenantId,
+                        includeSql: this.config.includeSql,
+                        limits: this.config.queryLimits,
+                        executionBudget: this.config.executionBudget,
+                        signal,
+                        inputSchema: this.querySchemas.queryMetric,
+                    });
+                case 'query_dataset':
+                    return await queryDatasetTool(this.config.datasets, this.config.analytics, args, {
+                        tenantId: this.config.tenantId,
+                        includeSql: this.config.includeSql,
+                        limits: this.config.queryLimits,
+                        executionBudget: this.config.executionBudget,
+                        signal,
+                        inputSchema: this.querySchemas.queryDataset,
+                    });
+                default:
+                    throw new MCPToolError('MCP_UNKNOWN_TOOL', `Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            const response = createMCPErrorResponse(error);
+            try {
+                assertWithinBudget(response, this.executionBudget);
+                return response;
+            }
+            catch {
+                return createMCPResultTooLargeResponse();
+            }
+        }
+    }
+    async listPrompts() {
+        return {
+            prompts: [
+                {
+                    name: 'dataset_guide',
+                    description: 'Guide for querying datasets with natural language',
+                    arguments: [
+                        {
+                            name: 'dataset',
+                            description: 'Name of the dataset to get guidance for',
+                            required: false,
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    async getPrompt(name, args) {
+        if (name === 'dataset_guide') {
+            return datasetGuidePrompt(this.config.datasets, args?.dataset);
+        }
+        throw new Error(`Unknown prompt: ${name}`);
+    }
+}
+export function createMCPExecutor(config) {
+    return new HypequeryMCPExecutor(config);
+}

package/dist/index.d.ts

@@ -5,11 +5,16 @@
  * Exposes datasets and metrics to AI agents via MCP tools.
  */
 export { HypequeryMCPServer, createMCPServer, type MCPServerConfig } from './server.js';
+export { HypequeryMCPExecutor, createMCPExecutor, type MCPExecutorConfig, type MCPToolExecutor, } from './executor.js';
+export { HypequeryMCPProtocolServer, createMCPProtocolServer, type MCPProtocolServerOptions, } from './protocol-server.js';
+export { connectMCPServerStdio, startStdioMCPServer } from './stdio.js';
 export { listDatasetsTool } from './tools/list-datasets.js';
-export { getDatasetSchemaTool } from './tools/introspect.js';
+export { getDatasetSchemaTool, getTrustedDatasetSchema } from './tools/introspect.js';
 export { queryMetricTool } from './tools/query-metric.js';
 export { queryDatasetTool } from './tools/query-dataset.js';
 export { datasetGuidePrompt } from './prompts/dataset-guide.js';
-export type { DatasetRegistry, QueryMetricArgs, QueryDatasetArgs, QueryToolOptions, SchemaToolOptions, GetDatasetSchemaArgs, MCPToolResponse, DatasetSchema, DimensionSchema, MetricSchema, RelationshipSchema, DatasetListItem, DatasetsListResponse, QueryResultResponse, QueryResultMeta, } from './types.js';
-export { MAX_QUERY_LIMIT, DEFAULT_QUERY_LIMIT } from './types.js';
+export type { DatasetRegistry, QueryMetricArgs, QueryDatasetArgs, QueryToolOptions, MCPExecutionBudget, MCPQueryLimits, SchemaToolOptions, GetDatasetSchemaArgs, MCPToolResponse, DatasetSchema, DimensionSchema, MetricSchema, RelationshipSchema, DatasetListItem, DatasetsListResponse, QueryResultResponse, QueryResultMeta, } from './types.js';
+export { MCPExecutionBudgetError, MCPToolError, classifyMCPToolError, formatMCPToolError, type MCPErrorDetails, type MCPExecutionErrorCode, type MCPToolErrorCode, type MCPToolErrorCategory, } from './errors.js';
+export { MAX_QUERY_LIMIT, DEFAULT_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_DIMENSIONS, MAX_QUERY_MEASURES, MAX_QUERY_FILTERS, MAX_QUERY_ORDER_BY, DEFAULT_QUERY_TIMEOUT_MS, MAX_QUERY_TIMEOUT_MS, DEFAULT_RESPONSE_BYTES, MAX_RESPONSE_BYTES, } from './types.js';
+export { MCP_PACKAGE_VERSION } from './version.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACtF,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGhE,YAAY,EACV,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -5,9 +5,14 @@
  * Exposes datasets and metrics to AI agents via MCP tools.
  */
 export { HypequeryMCPServer, createMCPServer } from './server.js';
+export { HypequeryMCPExecutor, createMCPExecutor, } from './executor.js';
+export { HypequeryMCPProtocolServer, createMCPProtocolServer, } from './protocol-server.js';
+export { connectMCPServerStdio, startStdioMCPServer } from './stdio.js';
 export { listDatasetsTool } from './tools/list-datasets.js';
-export { getDatasetSchemaTool } from './tools/introspect.js';
+export { getDatasetSchemaTool, getTrustedDatasetSchema } from './tools/introspect.js';
 export { queryMetricTool } from './tools/query-metric.js';
 export { queryDatasetTool } from './tools/query-dataset.js';
 export { datasetGuidePrompt } from './prompts/dataset-guide.js';
-export { MAX_QUERY_LIMIT, DEFAULT_QUERY_LIMIT } from './types.js';
+export { MCPExecutionBudgetError, MCPToolError, classifyMCPToolError, formatMCPToolError, } from './errors.js';
+export { MAX_QUERY_LIMIT, DEFAULT_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_DIMENSIONS, MAX_QUERY_MEASURES, MAX_QUERY_FILTERS, MAX_QUERY_ORDER_BY, DEFAULT_QUERY_TIMEOUT_MS, MAX_QUERY_TIMEOUT_MS, DEFAULT_RESPONSE_BYTES, MAX_RESPONSE_BYTES, } from './types.js';
+export { MCP_PACKAGE_VERSION } from './version.js';

package/dist/protocol-server.d.ts

@@ -0,0 +1,26 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { MCPToolExecutor } from './executor.js';
+export interface MCPProtocolServerOptions {
+    executor: MCPToolExecutor;
+    name?: string;
+    version?: string;
+}
+/**
+ * MCP protocol adapter for a transport-neutral Hypequery executor.
+ *
+ * The caller owns the transport. The same server can therefore be connected to
+ * stdio, an in-memory pair, or a hosted transport without changing tool logic.
+ */
+export declare class HypequeryMCPProtocolServer {
+    private readonly server;
+    protected readonly executor: MCPToolExecutor;
+    constructor(options: MCPProtocolServerOptions);
+    private setupHandlers;
+    getManifestHash(): string;
+    connect(transport: Transport): Promise<void>;
+    close(): Promise<void>;
+    /** Alias retained for the existing Hypequery MCP server lifecycle. */
+    stop(): Promise<void>;
+}
+export declare function createMCPProtocolServer(options: MCPProtocolServerOptions): HypequeryMCPProtocolServer;
+//# sourceMappingURL=protocol-server.d.ts.map

package/dist/protocol-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-server.d.ts","sourceRoot":"","sources":["../src/protocol-server.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAO/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;gBAEjC,OAAO,EAAE,wBAAwB;IAkB7C,OAAO,CAAC,aAAa;IAkBrB,eAAe,IAAI,MAAM;IAInB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,sEAAsE;IAChE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,0BAA0B,CAE5B"}

package/dist/protocol-server.js

@@ -0,0 +1,48 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { MCP_PACKAGE_VERSION } from './version.js';
+/**
+ * MCP protocol adapter for a transport-neutral Hypequery executor.
+ *
+ * The caller owns the transport. The same server can therefore be connected to
+ * stdio, an in-memory pair, or a hosted transport without changing tool logic.
+ */
+export class HypequeryMCPProtocolServer {
+    server;
+    executor;
+    constructor(options) {
+        this.executor = options.executor;
+        this.server = new Server({
+            name: options.name ?? 'hypequery-mcp-server',
+            version: options.version ?? MCP_PACKAGE_VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+                prompts: {},
+            },
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => (this.executor.listTools()));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => (this.executor.callTool(request.params.name, request.params.arguments, extra?.signal)));
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => (this.executor.listPrompts()));
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => (this.executor.getPrompt(request.params.name, request.params.arguments)));
+    }
+    getManifestHash() {
+        return this.executor.getManifestHash();
+    }
+    async connect(transport) {
+        await this.server.connect(transport);
+    }
+    async close() {
+        await this.server.close();
+    }
+    /** Alias retained for the existing Hypequery MCP server lifecycle. */
+    async stop() {
+        await this.close();
+    }
+}
+export function createMCPProtocolServer(options) {
+    return new HypequeryMCPProtocolServer(options);
+}

package/dist/server.d.ts

@@ -1,56 +1,27 @@
 /**
- * MCP Server for Hypequery Semantic Layer
+ * Backwards-compatible Hypequery MCP server facade.
  *
- * Exposes datasets and metrics via Model Context Protocol (MCP)
- * for use with Claude Desktop, Cursor, and other MCP-compatible tools.
+ * New integrations can compose HypequeryMCPExecutor with
+ * HypequeryMCPProtocolServer and supply their own transport. Existing callers
+ * can continue to construct this class and call start() for stdio.
  */
-import type { DatasetClient } from '@hypequery/datasets';
-import type { DatasetRegistry } from './types.js';
-export interface MCPServerConfig {
-    /**
-     * Dataset registry - map of dataset names to instances
-     */
-    datasets: DatasetRegistry;
-    /**
-     * Semantic analytics for running metric and dataset queries
-     */
-    analytics: DatasetClient;
-    /**
-     * Server name (shown in MCP client)
-     */
-    name?: string;
-    /**
-     * Server version
-     */
-    version?: string;
-    /**
-     * Trusted tenant id used to scope tenant-keyed datasets.
-     */
-    tenantId?: string;
-    /**
-     * Include generated SQL in query tool responses.
-     *
-     * Defaults to false so agent-facing responses do not expose SQL text unless
-     * explicitly enabled for trusted debugging.
-     */
-    includeSql?: boolean;
-}
-export declare class HypequeryMCPServer {
-    private server;
-    private config;
+import { type MCPServerConfig } from './executor.js';
+import { HypequeryMCPProtocolServer } from './protocol-server.js';
+export type { MCPServerConfig } from './executor.js';
+export declare class HypequeryMCPServer extends HypequeryMCPProtocolServer {
     constructor(config: MCPServerConfig);
-    private setupHandlers;
     /**
-     * Start the MCP server with stdio transport
+     * Start with the legacy stdio transport.
+     *
+     * @deprecated Prefer connect(transport) or startStdioMCPServer(config).
      */
     start(): Promise<void>;
-    /**
-     * Stop the MCP server
-     */
-    stop(): Promise<void>;
 }
 /**
- * Create and start an MCP server
+ * Create and start a backwards-compatible stdio MCP server.
+ *
+ * @deprecated Prefer createMCPExecutor with createMCPProtocolServer, or
+ * startStdioMCPServer for an explicit stdio lifecycle.
  */
 export declare function createMCPServer(config: MCPServerConfig): Promise<HypequeryMCPServer>;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAMzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;OAEG;IACH,SAAS,EAAE,aAAa,CAAC;IAEzB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAiCD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAoBnC,OAAO,CAAC,aAAa;IA2OrB;;OAEG;IACG,KAAK;IAQX;;OAEG;IACG,IAAI;CAGX;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAI1F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,qBAAa,kBAAmB,SAAQ,0BAA0B;gBACpD,MAAM,EAAE,eAAe;IASnC;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAI1F"}