@hypequery/mcp

Hosted error details on MCP tool errors: MCPToolError and its published error envelope carry optional retryAfterSeconds, relist and reason (a host's own stable code), and a new MCP_RATE_LIMITED code (category budget, retryable). mcpToolErrorFromSemanticFailure maps a semantic data-plane failure to the MCP error an agent receives, and createMCPErrorResponse is exported so hosts build tool errors exactly as the local server does.

Describe the package as a ClickHouse MCP server in its npm description, keywords and README, with a link to the five-minute quickstart.

Add mcpName (io.github.hypequery/hypequery) to the package manifest and a server.json, so the server can be published to the official MCP Registry. The build and the release version step write the package version into server.json, since the registry verifies mcpName against the npm release it names. No runtime change.

Strict client-query rejections say where they failed. validateProtocolClientQuery now sets a JSON Pointer on every HQ_CLIENT_QUERY error (/filters/0/value, /orderBy/1/field, /grain for agents) instead of the root for most of them. Pointers name contract members and item indexes only; an unknown member is still reported at the root because its name is submitted data. The shared conformance fixtures pin the pointers for TypeScript and Python.

The typed endpoint schemas from buildClientContractQuerySchemas carry the pointer as the zod issue path, and the MCP HTTP bridge names it in its error message (Invalid client query at /filters/0/value.).

Client contracts can carry an optional annotations member per endpoint: the dataset group's label/description and per-dimension/measure fields text (RFC 0018 amendment). Text follows the deployment contract's rules (non-blank, no control characters, at most 4096 UTF-8 bytes) and is excluded from schemaHash, so rewording a description never trips the execution-time schema pin; contentHash still covers it. The MCP HTTP bridge's list_datasets now shows each group's own description (and label) instead of the generic text, and get_dataset_schema returns the annotations with each endpoint profile. generate:client emits them as JSDoc on each ClientApi entry and output row field. Upgrade these packages before pointing them at a backend that emits annotations: earlier validators reject the new member.

Add isNull and isNotNull comparisons, which take no value (RFC 0023), so "has a churn date" is churned_at IS NOT NULL rather than a sentinel range. A protocol comparison using one is { kind: 'comparison', operator: 'isNotNull', left } with no right; a client query filter is { field, operator: 'isNull' } with no value. Validators reject a value on them and accept any field type. Measure fixed filters and segments can use them directly, including through the new isNull(field) and isNotNull(field) helpers (also re-exported by @hypequery/serve). Caller query filters are opt-in: a filter allows them only when its operators list names them, so default operator lists, and the identity of every existing deployment and client contract, are unchanged. The deployment data plane, the MCP dataset guide and the generated client input types support them, and the conformance corpus pins the new cases. Upgrade every consumer before publishing a contract that uses them: earlier validators reject the new operators.

Add an HTTP MCP executor over authorized Python client contracts, retaining endpoint-specific query permissions and schema pins. Bound discovery, tool manifests, streamed JSON results and execution time; reject redirects, stale views, private metadata and result fields outside the requested projection. Existing local and discovery-only executors remain supported. MCPToolExecutor.listTools, listPrompts and getPrompt accept an optional cancellation signal, which the protocol server now forwards from each request.

Exclude internal runtime and type-test programs from published package tarballs while preserving public runtime and declaration exports.

MCP tools refuse a limit above the endpoint's maxLimit with MCP_INVALID_ARGUMENTS instead of silently clamping it, so an agent never mistakes a shortened page for the whole answer. Tool schemas built from a client contract advertise that ceiling as the limit maximum, and validateProtocolClientQuery(..., 'mcp') enforces it. HTTP requests keep clamping, as both Serve implementations do.

Serve accepts your schemas from Zod 3 or Zod 4. Query inputs and outputs are typed against a structural ServeSchema instead of Zod 3's ZodTypeAny, so npm install zod (which now resolves Zod 4) works with the quick start, and existing Zod 3 projects keep compiling. Query-string coercion and the OpenAPI document read both majors. The optional zod peer range is now ^3.23.8 || ^4.0.0.

Serve and MCP now depend on zod@^4.6.6 (was ^3.23.8), clearing GHSA-mrhx-c7xc-m3w5. For dataset and metric endpoints, whose schemas Serve builds, VALIDATION_ERROR issue text and codes now follow Zod 4 (for example Invalid option: expected one of …, and no received field). Endpoints with your own schemas report whatever your Zod reports, as before.

hypequery init scaffolds zod@^4.6.6.

Expose dataset having conditions (HQ-329) on every consumption surface:

• Serve dataset endpoints accept and forward having. The input schema and OpenAPI enumerate each dataset's measures, and the endpoint description documents the field.
• MCP query_dataset advertises and applies having. Local servers and hosted discovery gateways list identical schemas (CORE-03), so hosted execution must support having once it is wired in.
• React useDataset, useInfiniteDataset and useQuery('dataset:…') accept having through the Serve API types, constrained to the dataset's measures. Metric hooks do not accept it.

Support one-hop relationship base measures in dataset queries through the query-builder client. Allow duplicate-insensitive aggregates through belongsTo and all base aggregates through declared hasOne relationships, preserve tenant and fixed-filter scoping, and exclude unmatched target rows from aggregate inputs. Advertise safe names and approximate metadata in runtime catalogs and input schemas, with typed projections through Serve and React.

Refresh production dependencies. Keep the ClickHouse adapter compatible with the client packages' bundled setting types.

Add measure.shift for period comparisons through the query-builder client. Shifted measures share window time-axis validation, gap filling, filters, tenant scope, and derived formulas. Catalogs and agent projections expose their intervals and time-range requirements.

Reject shifted source ranges that cross a skipped local calendar bucket, including empty populations, rather than duplicating comparison values.

Comparisons match partial query ranges and preserve endpoint operators. Catalogs and agent projections expose compatible grains for time measures and their formulas.

Add typed authoring definitions for trailing, to-date, and cumulative dataset measures. Validate base-measure references and cumulative aggregation support, and reject execution and Cloud publishing until RFC 0015 window planning is implemented.

Exclude window-dependent derived measures from executable catalogs and query schemas until window planning is available.

Keep base, derived, and window definitions together in the returned dataset's measures registry. Retain derivedMeasures as a deprecated compatibility alias, while default queries and standalone metrics continue to use only base measures.

Execute trailing, to-date, and cumulative dataset measures through the query-builder client, including sparse-series filling, lookback filters, and derived formulas. Expose window parameters and time-range requirements in catalogs and agent projections. MCP dataset guides list these measures with their time-axis requirements.

Reject ranges that cross a skipped local calendar bucket, including window lookback, instead of generating duplicate buckets and incorrect totals.

Add an execution timezone to dataset and metric queries, with a client default and UTC as the fallback. Buckets, local time-key filters, windows, and period comparisons use the selected IANA timezone. Cache entries are separated by execution timezone, and Serve and MCP accept query overrides.

Remove the metadata-only timezone field from semantic definitions. Set it on createDatasetClient or the query instead.

Add minute and hour time grains (RFC 0015, HQ-77). They bucket with toStartOfMinute/toStartOfHour and appear in catalogs, semantic query schemas, and the local MCP tools.

A new timeGrains dataset option restricts the grains a dataset supports, for example to refuse sub-day buckets on a Date time key. Queries, .by(), and the catalog honor it.

Publishing to Cloud still emits deployment contract 2:

• it refuses a sub-day defaults.timeGrain or pinned metric grain with an actionable error;
• it refuses dataset-level timeGrains restrictions it cannot preserve;
• published metric grain lists and rehydrated datasets stay at day through year.

Expose dataset segments on every query surface. Semantic input schemas, and therefore OpenAPI and the MCP tools, accept segments as an enum of the dataset's declared names. Serve dataset and metric endpoints, and the MCP query_dataset/query_metric tools, forward them to the query. Typed dataset and metric inputs infer declared segment names, including through Serve and React; MCP argument types can opt into a dataset-specific type. Datasets without segments keep their existing schemas.

Bound the tool manifest itself, not only the queries it describes.

Every existing budget limits one call. None limited what a client is handed before it makes one — and that is the part that grows with the deployment: query_dataset and query_metric carry exact enums of every published dataset, dimension, measure, and filter field, so the manifest scales with the catalog while the tool count stays at four. A two-dataset catalog already compiles to roughly 13.7 KiB, nearly all of it those enums. Every client pays it on every connection, and a model pays it out of context before a question is asked.

MCPCatalogBudget adds two ceilings, configurable on both HypequeryMCPExecutor and createMCPDiscoveryExecutor:

• maxTools — 64 by default, 256 maximum. The local server publishes a fixed four; this is for the hosted tool modes that publish one tool per dataset or per verified metric, where the count follows the catalog.
• maxManifestBytes — 256 KiB by default, 1 MiB maximum.

A breach raises MCPCatalogBudgetError, classified MCP_CATALOG_TOO_LARGE in the budget category and not retryable: the same catalog produces the same manifest every time. A hosted gateway is expected to catch it and choose a narrower tool mode.

The manifest is refused rather than truncated. A truncated manifest would show an agent fewer targets than the validators behind it accept, and the manifest hash would stop identifying the catalog it was compiled from — which is the property CORE-03 exists to preserve.

Discovery measures the catalog before _meta is attached, so the provenance a gateway stamps on a manifest is never what pushes it over.

Add createMCPDiscoveryExecutor(), a read-only tool executor that lists a catalog without being able to execute against it, and _meta provenance on the listed manifest.

A hosted gateway lists tools for one principal against one activated deployment, 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 when a dataset is tenant-scoped and no fixed tenantId is configured. Both are right 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 discovery executor shares the schema compiler and the catalog tools rather than introducing a second manifest generator, which is what CORE-03 exists to prevent — the schemas an agent is handed and the validators its query is checked against have to come from one catalog. A test pins that: the tools and manifest hash it produces are identical to the executor that can run them.

list_datasets, get_dataset_schema, and the prompts answer normally. query_dataset and query_metric are advertised with their exact schemas and refuse, rather than being hidden: the manifest a client caches should be the one it keeps seeing once execution is wired in behind it. The refusal is not MCP_UNKNOWN_TOOL, which would invite a client to stop asking for good.

queryableDatasets narrows which datasets are offered as a query_dataset target without removing them from the catalog, so a dataset a caller may not query directly still contributes its metrics and its joins. query_metric and list_datasets are unaffected. It threads through buildCanonicalSemanticQuerySchemas in @hypequery/datasets rather than being applied afterwards, so the manifest hash stays derived from one place.

meta attaches activationRevision, deploymentIdentity, and toolMode to listTools under the com.hypequery/ namespace the MCP spec requires of implementation-defined _meta, so a client can cache a manifest and tell when it went stale. Keys with no value are omitted rather than emitted empty.

Add output schemas, structured content with compact text fallback, tool titles and read-only annotations, query result metadata, and stable structured errors. Backend failure details and SQL remain redacted from agent-facing responses by default.

Add a public transport-neutral MCP executor and protocol server with injected transport support. Isolate stdio behind an explicit adapter while preserving the existing server, startup APIs, tool names, prompts, and behavior.

Bound MCP dataset and metric queries with effective default and maximum row, offset, and collection limits. Add configurable server query ceilings and use the package version in MCP server metadata.

Propagate semantic query cancellation through the datasets client and ClickHouse semantic backend, and enforce MCP query deadlines and serialized-response byte ceilings with stable budget error classifications.

Add bounded agent-oriented descriptions, examples, synonyms, formats, units, currency, timezone, freshness, ownership, sensitivity, and query defaults across dataset catalogs and deployment contracts.

Make MCP dataset introspection agent-safe by default and expose physical catalog diagnostics only through a separately authorized debug API.

Add a canonical catalog-derived semantic query schema compiler with shared Zod validators, JSON Schemas, exact field and operator constraints, bounded closed objects, and deterministic manifest hashing. Migrate Serve and MCP query schemas to the shared compiler.

Resolve the package version at build time instead of reading package.json at import time.

Importing @hypequery/mcp read its own manifest off import.meta.url as a side effect of module evaluation. A bundler rewrites that URL, so the URL handed to fs came from another realm and Node rejected it with ERR_INVALID_ARG_TYPE — which made the package impossible to import from a bundled server build at all. A Next.js route importing it failed while collecting page data.

MCP_PACKAGE_VERSION is unchanged and still cannot drift from the manifest: it is generated before every build, asserted against package.json in tests, and regenerated by prepack so the published artifact reports the version it was published under. A release builds before Changesets rewrites package.json, so without that hook the tarball would have carried the previous version's string. Importing the package now touches no filesystem.

Refresh every npm package page with a concise README and complete HypeQuery homepage and repository metadata.

Relationship-aware semantics: to-one relationships are now queryable end to end, and every metadata surface advertises them.

Querying (@hypequery/datasets, @hypequery/clickhouse): dataset and metric queries can select, filter, and order by to-one related fields one hop deep (dimensions: ['customer.country']). Traversal executes as a ClickHouse LEFT ANY JOIN (new leftAnyJoin query-builder method), so base rows survive, duplicate target join keys can never fan out aggregates, and production matches the in-memory backend's first-match semantics. When runtime tenancy is active, joined targets with a tenantKey are scoped inside the join condition. hasMany remains metadata-only, and result row types include qualified fields (row['customer.country'] is typed).

Metadata: the catalog and semantic contract expose queryable and fields per relationship (replacing execution: 'metadata_only'; SEMANTIC_CONTRACT_VERSION is now 2). Generated agent tools, Serve's Zod/OpenAPI input schemas, and MCP get_dataset_schema all advertise the same qualified field names the validators accept — including for config-shaped datasets in MCP. Serve no longer advertises dimensions as filterable when a dataset explicitly declares filters: {}.

Validation: dataset() now rejects relationship names that match the dataset's source table (the join alias would shadow the base table) or contain dots — both configurations previously failed confusingly at query time.

Deprecations (no removals, no behavior changes): the plan/backend execution path is frozen in favor of createDatasetClient({ queryBuilder }). createBackend, the backend client option, createInMemoryBackend, and the PlanNode/SemanticBackend protocol exports are @deprecated and receive bug fixes only.

Add catalog-backed semantic tool generation and harden SQL exposure across MCP and generated tools.

@hypequery/datasets:

• Add generateDatasetTools with catalog, per-dataset, and per-metric modes, plus toOpenAITools, toAISDKTools, and toMcpTools adapters. Generated tools validate agent inputs against catalog metadata and redact SQL from results by default.
• Expand the dataset catalog with default filter operators, filter value types, supported time grains, tenant requirement, orderable fields, max result limit, and measure filter counts.
• Export SEMANTIC_FILTER_OPERATORS and SUPPORTED_TIME_GRAINS and use the shared operator list across packages.

@hypequery/serve:

• Build semantic input schemas and endpoint descriptions from catalog metadata, including supported grains, filters, relationships, and tenant scoping.

@hypequery/mcp:

• Distinguish measures from named metrics in dataset listing and introspection (metricCount no longer falls back to the measure count).
• Add an includeSql server option (default false) so get_dataset_schema, query_dataset, and query_metric no longer expose generated SQL to agents unless explicitly enabled for trusted debugging.

Add dataset catalog metadata for measures, filters, relationships, limits, and attached named metrics. Update MCP dataset introspection and dataset querying metadata to distinguish measures from named metrics.

Breaking MCP change: query_dataset now accepts measures only. The previous metrics argument for dataset queries has been removed so named metrics remain reserved for query_metric.

Move MCP metric and dataset tools onto the unified DatasetClient runtime.

Query arguments are now validated consistently, tenant-scoped datasets require a trusted server-side tenantId, and explicit tenant-filter overrides are rejected. Metric and dataset responses also expose pagination metadata so MCP clients can continue querying while hasMore is true.