@hypequery/mcp 0.5.5 → 0.7.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/discovery-executor.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Discovery without execution.
+ *
+ * A hosted gateway lists tools for one principal against one activated
+ * deployment, and does that before — and independently of — being able to run
+ * anything. `HypequeryMCPExecutor` cannot serve that: it requires a
+ * `DatasetClient` it would never call, and refuses to construct at all when a
+ * dataset is tenant-scoped and no fixed `tenantId` is configured. Both are
+ * correct for a local server, where one process serves one tenant and every
+ * listed tool is runnable. Neither holds for a gateway, which resolves a tenant
+ * per request through the deployment data plane.
+ *
+ * The alternative would be a second manifest generator in the gateway, which
+ * `CORE-03` exists to prevent: the tool schemas an agent is given and the
+ * validators a query is checked against have to come from one catalog.
+ *
+ * So this shares the schema compiler and the catalog tools, and refuses the two
+ * tools that need a query engine. Listing a tool it will not run is deliberate:
+ * the manifest a client caches must be the one it will keep seeing once
+ * execution is wired in behind it, or every client re-lists on the day that
+ * lands.
+ */
+import type { CallToolResult, GetPromptResult, ListPromptsResult, ListToolsResult } from '@modelcontextprotocol/sdk/types.js';
+import type { MCPToolExecutor } from './executor.js';
+import type { DatasetRegistry, MCPQueryLimits } from './types.js';
+/**
+ * Provenance a client needs to cache a manifest and know when it went stale.
+ *
+ * Namespaced under `com.hypequery/` in the result's `_meta`, as the MCP spec
+ * requires of implementation-defined keys.
+ */
+export interface MCPToolManifestMeta {
+    /** The immutable generation these tools were listed from. */
+    readonly activationRevision?: string;
+    /** Content-addressed identity of the contract behind them. */
+    readonly deploymentIdentity?: string;
+    /** How the tools were shaped — `catalog` for the fixed compatibility set. */
+    readonly toolMode?: string;
+}
+export interface MCPDiscoveryExecutorConfig {
+    /** Datasets to advertise. Already narrowed to what the caller may see. */
+    datasets: DatasetRegistry;
+    /**
+     * Datasets offered as a `query_dataset` target. Defaults to all of them.
+     *
+     * A deployment authorizes a dataset and each of its metrics through separate
+     * endpoint policies, so a caller can be entitled to a metric on a dataset it
+     * may not query directly. Such a dataset still belongs in `datasets` — its
+     * metrics are reachable, and it may be joined to — but naming it here would
+     * advertise a target execution refuses.
+     */
+    queryableDatasets?: readonly string[];
+    /** Server-side query ceilings, so advertised schemas match what will run. */
+    queryLimits?: MCPQueryLimits;
+    /** Attached to `listTools`, so a client can pin what it listed. */
+    meta?: MCPToolManifestMeta;
+}
+/**
+ * A read-only executor over a catalog.
+ *
+ * `list_datasets`, `get_dataset_schema`, and the prompts read the agent-safe
+ * catalog and need no query engine, so they answer normally. `query_dataset`
+ * and `query_metric` are advertised with their exact schemas and refuse.
+ */
+export declare class HypequeryMCPDiscoveryExecutor implements MCPToolExecutor {
+    private readonly config;
+    private readonly querySchemas;
+    private readonly meta;
+    constructor(config: MCPDiscoveryExecutorConfig);
+    /** The catalog these tools were compiled from, for caching by content. */
+    getManifestHash(): string;
+    listTools(): Promise<ListToolsResult>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<CallToolResult>;
+    listPrompts(): Promise<ListPromptsResult>;
+    getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult>;
+}
+export declare function createMCPDiscoveryExecutor(config: MCPDiscoveryExecutorConfig): MCPToolExecutor;
+//# sourceMappingURL=discovery-executor.d.ts.map

package/dist/discovery-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-executor.d.ts","sourceRoot":"","sources":["../src/discovery-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAOrD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,0EAA0E;IAC1E,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,mEAAmE;IACnE,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAeD;;;;;;GAMG;AACH,qBAAa,6BAA8B,YAAW,eAAe;IAIvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgC;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqC;gBAE7B,MAAM,EAAE,0BAA0B;IAW/D,0EAA0E;IAC1E,eAAe,IAAI,MAAM;IAInB,SAAS,IAAI,OAAO,CAAC,eAAe,CAAC;IAKrC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC;IAyB/E,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAczC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;CAMvF;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,eAAe,CAEjB"}

package/dist/discovery-executor.js

@@ -0,0 +1,111 @@
+/**
+ * Discovery without execution.
+ *
+ * A hosted gateway lists tools for one principal against one activated
+ * deployment, and does that before — and independently of — being able to run
+ * anything. `HypequeryMCPExecutor` cannot serve that: it requires a
+ * `DatasetClient` it would never call, and refuses to construct at all when a
+ * dataset is tenant-scoped and no fixed `tenantId` is configured. Both are
+ * correct for a local server, where one process serves one tenant and every
+ * listed tool is runnable. Neither holds for a gateway, which resolves a tenant
+ * per request through the deployment data plane.
+ *
+ * The alternative would be a second manifest generator in the gateway, which
+ * `CORE-03` exists to prevent: the tool schemas an agent is given and the
+ * validators a query is checked against have to come from one catalog.
+ *
+ * So this shares the schema compiler and the catalog tools, and refuses the two
+ * tools that need a query engine. Listing a tool it will not run is deliberate:
+ * the manifest a client caches must be the one it will keep seeing once
+ * execution is wired in behind it, or every client re-lists on the day that
+ * lands.
+ */
+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 { buildMCPToolManifest } from './tools/tool-manifest.js';
+import { buildMCPQuerySchemas } from './tools/utils/canonical-query-schemas.js';
+import { createMCPErrorResponse } from './tools/utils/tool-response.js';
+const NOT_EXECUTABLE = 'This endpoint lists datasets and metrics but does not execute queries.';
+function metaEntries(meta) {
+    if (meta === undefined)
+        return undefined;
+    const entries = Object.entries({
+        'com.hypequery/activationRevision': meta.activationRevision,
+        'com.hypequery/deploymentIdentity': meta.deploymentIdentity,
+        'com.hypequery/toolMode': meta.toolMode,
+    }).filter((entry) => entry[1] !== undefined);
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+}
+/**
+ * A read-only executor over a catalog.
+ *
+ * `list_datasets`, `get_dataset_schema`, and the prompts read the agent-safe
+ * catalog and need no query engine, so they answer normally. `query_dataset`
+ * and `query_metric` are advertised with their exact schemas and refuse.
+ */
+export class HypequeryMCPDiscoveryExecutor {
+    config;
+    querySchemas;
+    meta;
+    constructor(config) {
+        this.config = config;
+        // Deliberately no tenant assertion. A gateway has no fixed tenant to
+        // declare, and none is needed: nothing here reaches a table.
+        this.querySchemas = buildMCPQuerySchemas(config.datasets ?? {}, config.queryLimits, config.queryableDatasets);
+        this.meta = metaEntries(config.meta);
+    }
+    /** The catalog these tools were compiled from, for caching by content. */
+    getManifestHash() {
+        return this.querySchemas.manifestHash;
+    }
+    async listTools() {
+        const manifest = buildMCPToolManifest(this.querySchemas);
+        return this.meta === undefined ? manifest : { ...manifest, _meta: this.meta };
+    }
+    async callTool(name, args) {
+        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_dataset':
+                case 'query_metric':
+                    // Not `MCP_UNKNOWN_TOOL`: the tool exists and is listed, and telling a
+                    // client it does not would invite it to stop asking for good.
+                    throw new MCPToolError('MCP_EXECUTION_FAILED', NOT_EXECUTABLE, {
+                        retryable: false,
+                    });
+                default:
+                    throw new MCPToolError('MCP_UNKNOWN_TOOL', `Unknown tool: ${name}`);
+            }
+        }
+        catch (error) {
+            return createMCPErrorResponse(error);
+        }
+    }
+    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 createMCPDiscoveryExecutor(config) {
+    return new HypequeryMCPDiscoveryExecutor(config);
+}

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,17 @@
  * 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 { HypequeryMCPDiscoveryExecutor, createMCPDiscoveryExecutor, type MCPDiscoveryExecutorConfig, type MCPToolManifestMeta, } from './discovery-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,6BAA6B,EAC7B,0BAA0B,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AACjC,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"}