@cyanheads/eurostat-mcp-server 0.10.0 → 0.11.0

package/dist/config/server-config.js

@@ -5,6 +5,10 @@
 import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
+    clampLimits: z
+        .stringbool()
+        .default(true)
+        .describe('Clamp positive read limits to preview 500, search 100 and dimension values 1,000 with a notice. False restores rejecting maximum schemas.'),
     baseUrl: z
         .string()
         .url()
@@ -20,13 +24,13 @@ const ServerConfigSchema = z.object({
         .int()
         .positive()
         .default(30_000)
-        .describe('HTTP request timeout in milliseconds'),
+        .describe('Total allowance for one Eurostat request, including retries, backoff and body consumption, in milliseconds'),
     metadataTimeoutMs: z.coerce
         .number()
         .int()
         .positive()
         .default(120_000)
-        .describe("HTTP timeout for one dataset's SDMX dataflow structure, in milliseconds. Held separate from EUROSTAT_REQUEST_TIMEOUT_MS because the structure carries a label for every code the dataset uses: 23 MB, uncompressed, for the CN8 trade collection DS-045409. Defaults to 2 minutes."),
+        .describe("Total allowance for one dataset's SDMX dataflow structure, including retries, backoff and body consumption, in milliseconds. Held separate from EUROSTAT_REQUEST_TIMEOUT_MS because the structure carries a label for every code the dataset uses: 23 MB, uncompressed, for the CN8 trade collection DS-045409. Defaults to 2 minutes."),
     tocCacheTtlMs: z.coerce
         .number()
         .int()
@@ -38,7 +42,7 @@ const ServerConfigSchema = z.object({
         .int()
         .positive()
         .default(120_000)
-        .describe('HTTP timeout for one SDMX bulk download, in milliseconds. Held separate from EUROSTAT_REQUEST_TIMEOUT_MS because a bulk body streams for minutes where a metadata call answers in seconds. Defaults to 2 minutes.'),
+        .describe('Total allowance for one SDMX bulk download, including request retries, backoff and streaming body consumption, in milliseconds. Held separate from EUROSTAT_REQUEST_TIMEOUT_MS because a bulk body can take longer than a metadata call. Defaults to 2 minutes.'),
     bulkMaxBytes: z.coerce
         .number()
         .int()
@@ -48,11 +52,12 @@ const ServerConfigSchema = z.object({
     dataframeDropEnabled: z
         .stringbool()
         .default(false)
-        .describe('Register eurostat_dataframe_drop, which removes one staged table from a dataframe canvas. Off by default: a drop cannot be undone, and staged tables already expire with their canvas. Takes effect only with CANVAS_PROVIDER_TYPE=duckdb.'),
+        .describe('Register eurostat_dataframe_drop, which removes one staged table from a dataframe canvas. Off by default: a drop cannot be undone, and staged tables already expire with their canvas. Has no effect with CANVAS_PROVIDER_TYPE=none.'),
 });
 let _config;
 export function getServerConfig() {
     _config ??= parseEnvConfig(ServerConfigSchema, {
+        clampLimits: 'EUROSTAT_CLAMP_LIMITS',
         baseUrl: 'EUROSTAT_BASE_URL',
         comextBaseUrl: 'EUROSTAT_COMEXT_BASE_URL',
         requestTimeoutMs: 'EUROSTAT_REQUEST_TIMEOUT_MS',

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,iDAAiD,CAAC;SAC1D,QAAQ,CAAC,uBAAuB,CAAC;IACpC,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,wDAAwD,CAAC;SACjE,QAAQ,CACP,mMAAmM,CACpM;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CAAC,sCAAsC,CAAC;IACnD,iBAAiB,EAAE,CAAC,CAAC,MAAM;SACxB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CACP,oRAAoR,CACrR;IACH,aAAa,EAAE,CAAC,CAAC,MAAM;SACpB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,qLAAqL,CACtL;IACH,aAAa,EAAE,CAAC,CAAC,MAAM;SACpB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CACP,mNAAmN,CACpN;IACH,YAAY,EAAE,CAAC,CAAC,MAAM;SACnB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,0QAA0Q,CAC3Q;IACH,oBAAoB,EAAE,CAAC;SACpB,UAAU,EAAE;SACZ,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,4OAA4O,CAC7O;CACJ,CAAC,CAAC;AAEH,IAAI,OAAuD,CAAC;AAE5D,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,mBAAmB;QAC5B,aAAa,EAAE,0BAA0B;QACzC,gBAAgB,EAAE,6BAA6B;QAC/C,iBAAiB,EAAE,8BAA8B;QACjD,aAAa,EAAE,2BAA2B;QAC1C,aAAa,EAAE,0BAA0B;QACzC,YAAY,EAAE,yBAAyB;QACvC,oBAAoB,EAAE,iCAAiC;KACxD,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,WAAW,EAAE,CAAC;SACX,UAAU,EAAE;SACZ,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CACP,2IAA2I,CAC5I;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,iDAAiD,CAAC;SAC1D,QAAQ,CAAC,uBAAuB,CAAC;IACpC,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,wDAAwD,CAAC;SACjE,QAAQ,CACP,mMAAmM,CACpM;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM;SACvB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,MAAM,CAAC;SACf,QAAQ,CACP,4GAA4G,CAC7G;IACH,iBAAiB,EAAE,CAAC,CAAC,MAAM;SACxB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CACP,wUAAwU,CACzU;IACH,aAAa,EAAE,CAAC,CAAC,MAAM;SACpB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,qLAAqL,CACtL;IACH,aAAa,EAAE,CAAC,CAAC,MAAM;SACpB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CACP,iQAAiQ,CAClQ;IACH,YAAY,EAAE,CAAC,CAAC,MAAM;SACnB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,0QAA0Q,CAC3Q;IACH,oBAAoB,EAAE,CAAC;SACpB,UAAU,EAAE;SACZ,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,sOAAsO,CACvO;CACJ,CAAC,CAAC;AAEH,IAAI,OAAuD,CAAC;AAE5D,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,WAAW,EAAE,uBAAuB;QACpC,OAAO,EAAE,mBAAmB;QAC5B,aAAa,EAAE,0BAA0B;QACzC,gBAAgB,EAAE,6BAA6B;QAC/C,iBAAiB,EAAE,8BAA8B;QACjD,aAAa,EAAE,2BAA2B;QAC1C,aAAa,EAAE,0BAA0B;QACzC,YAAY,EAAE,yBAAyB;QACvC,oBAAoB,EAAE,iCAAiC;KACxD,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -4,22 +4,26 @@
  * @module index
  */
 import { createApp, disabledTool } from '@cyanheads/mcp-ts-core';
-import { config } from '@cyanheads/mcp-ts-core/config';
+import { config, parseConfig, resetConfig } from '@cyanheads/mcp-ts-core/config';
 import { getServerConfig } from './config/server-config.js';
 import { eurostatDatasetResource } from './mcp-server/resources/definitions/eurostat-dataset.resource.js';
 import { eurostatBrowseThemes } from './mcp-server/tools/definitions/eurostat-browse-themes.tool.js';
 import { eurostatDataframeDescribe } from './mcp-server/tools/definitions/eurostat-dataframe-describe.tool.js';
 import { eurostatDataframeDrop } from './mcp-server/tools/definitions/eurostat-dataframe-drop.tool.js';
 import { eurostatDataframeQuery } from './mcp-server/tools/definitions/eurostat-dataframe-query.tool.js';
-import { eurostatDownloadDataset } from './mcp-server/tools/definitions/eurostat-download-dataset.tool.js';
+import { createEurostatDownloadDataset } from './mcp-server/tools/definitions/eurostat-download-dataset.tool.js';
 import { eurostatGetDatasetInfo } from './mcp-server/tools/definitions/eurostat-get-dataset-info.tool.js';
-import { eurostatGetDimensionValues } from './mcp-server/tools/definitions/eurostat-get-dimension-values.tool.js';
-import { eurostatQueryDataset } from './mcp-server/tools/definitions/eurostat-query-dataset.tool.js';
-import { eurostatSearchDatasets } from './mcp-server/tools/definitions/eurostat-search-datasets.tool.js';
+import { createEurostatGetDimensionValues } from './mcp-server/tools/definitions/eurostat-get-dimension-values.tool.js';
+import { createEurostatQueryDataset } from './mcp-server/tools/definitions/eurostat-query-dataset.tool.js';
+import { createEurostatSearchDatasets } from './mcp-server/tools/definitions/eurostat-search-datasets.tool.js';
 import { setCanvas } from './services/canvas-accessor.js';
 import { initEurostatBulkService } from './services/eurostat-bulk/eurostat-bulk-service.js';
 import { initEurostatCatalogueService } from './services/eurostat-catalogue/eurostat-catalogue-service.js';
 import { initEurostatDataService } from './services/eurostat-data/eurostat-data-service.js';
+parseConfig();
+// DataCanvas defaults on; set CANVAS_PROVIDER_TYPE=none to disable it.
+process.env.CANVAS_PROVIDER_TYPE ||= 'duckdb';
+resetConfig();
 /**
  * The dataframe tools address tables on a canvas, so without one they have
  * nothing to talk to. `disabledTool` keeps a gated tool off `tools/list` —
@@ -67,6 +71,20 @@ function dataframeDropTool() {
             hint: DROP_OFF_HINT,
         });
 }
+/**
+ * Registration is provisional until setup validates this same memoized config.
+ * Invalid parses are never cached: setup repeats the failure inside createApp's
+ * configuration boundary, prints its banner and exits before serving a call.
+ */
+function readClampLimits() {
+    try {
+        return getServerConfig().clampLimits;
+    }
+    catch {
+        return true;
+    }
+}
+const clampLimits = readClampLimits();
 await createApp({
     name: 'eurostat-mcp-server',
     title: 'eurostat-mcp-server',
@@ -77,25 +95,20 @@ await createApp({
      */
     sessionMode: 'stateless',
     tools: [
-        eurostatSearchDatasets,
+        createEurostatSearchDatasets(clampLimits),
         eurostatBrowseThemes,
         eurostatGetDatasetInfo,
-        eurostatGetDimensionValues,
-        eurostatQueryDataset,
-        eurostatDownloadDataset,
+        createEurostatGetDimensionValues(clampLimits),
+        createEurostatQueryDataset(clampLimits),
+        createEurostatDownloadDataset(clampLimits),
         canvasEnabled ? eurostatDataframeDescribe : disabledTool(eurostatDataframeDescribe, CANVAS_OFF),
         canvasEnabled ? eurostatDataframeQuery : disabledTool(eurostatDataframeQuery, CANVAS_OFF),
         dataframeDropTool(),
     ],
     resources: [eurostatDatasetResource],
     prompts: [],
-    instructions: `Eurostat MCP server — EU statistical data across the Eurostat catalogue.
-Workflow: eurostat_search_datasets or eurostat_browse_themes to find a dataset code → eurostat_get_dataset_info to see dimensions → eurostat_get_dimension_values to list valid filter values → eurostat_query_dataset to fetch observations.
-Apply dimension filters to keep queries small: an unfiltered query on a large dataset is slow and can return an async response error instead of data.
-The catalogue covers two hosts. Most datasets come from the Eurostat dissemination table of contents; the DS-* codes — detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM — come from the Comext host, and every tool routes a DS-* code there by its prefix. Comext collections are large: filter every request (freq included, since the trade flows mix annual and monthly series), and expect eurostat_get_dimension_values to page a long list such as the 37,069 CN8 product codes — pass filter with words of the code or label to find one value, or follow nextCursor. A collection on neither host, such as the legacy DS-056120, is not disseminated.
-Two paths past eurostat_query_dataset's 5,000-observation inline cap. For a slice of a dataset, keep using eurostat_query_dataset: when the match is larger than the cap and this deployment runs a dataframe canvas, the whole match is also staged as a SQL table named in the response. For a whole dataset, use eurostat_download_dataset, which reads the SDMX bulk endpoint instead — about half the bytes — and stages every observation the same way, bounded by a byte budget it reports back. Read either staged table with eurostat_dataframe_query (eurostat_dataframe_describe lists the table and column names); the two stage different column sets, since the bulk endpoint carries dimension codes with no labels. To label a download's codes, pass its canvasId to eurostat_get_dimension_values as canvas_id: the dimension's values are staged beside it as a code/label table to join on.
-Staged tables expire with their canvas. eurostat_dataframe_drop removes one sooner, leaving the canvas and its other tables in place; it is opt-in, listed only where the deployment also sets EUROSTAT_DATAFRAME_DROP_ENABLED=true.
-The dataframe tools are not listed when the canvas is off. There, narrowing the filters is what brings a capped match into reach, and eurostat_download_dataset retains only its inline preview.`,
+    skills: 'skills',
+    instructions: 'Eurostat statistical data, including Comext DS-* collections; no API key required. Resolve dataset codes with eurostat_search_datasets or eurostat_browse_themes, inspect dimensions with eurostat_get_dataset_info, and resolve their values with eurostat_get_dimension_values before fetching observations. Filter large requests, including frequency on Comext, and keep units and aggregation levels comparable. Previews and incomplete bulk transfers cannot support complete totals; inspect notices and flags before concluding data is absent. When a response includes tableName, pass its canvasId as canvas_id to eurostat_dataframe_describe before eurostat_dataframe_query; reuse that canvas for joins. Staging and dataframe tools depend on the deployment canvas. Read eurostat-guide for statistical interpretation and SQL workflows.',
     landing: { requireAuth: false },
     setup(core) {
         // Parsed here so a bad value fails startup with the configuration banner, not every call.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/clamp-read-limit.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Bound read previews and search pages, disclosing each applied clamp.
+ * @module mcp-server/tools/clamp-read-limit
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+/** Returns the effective limit and records one clamp, labelled only by tool. */
+export declare function clampReadLimit(requested: number, maximum: number, field: 'preview_limit' | 'limit', toolName: 'eurostat_query_dataset' | 'eurostat_download_dataset' | 'eurostat_search_datasets' | 'eurostat_get_dimension_values', ctx: Pick<Context, 'log'>): {
+    value: number;
+    notice?: string;
+};
+//# sourceMappingURL=clamp-read-limit.d.ts.map

package/dist/mcp-server/tools/clamp-read-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp-read-limit.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/clamp-read-limit.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAStD,gFAAgF;AAChF,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,GAAG,OAAO,EAChC,QAAQ,EACJ,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,+BAA+B,EACnC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GACxB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAQpC"}

package/dist/mcp-server/tools/clamp-read-limit.js

@@ -0,0 +1,14 @@
+import { createCounter } from '@cyanheads/mcp-ts-core/utils';
+const clamps = createCounter('eurostat.limit_clamps', 'Read limits clamped to their supported maximum', '{clamps}');
+/** Returns the effective limit and records one clamp, labelled only by tool. */
+export function clampReadLimit(requested, maximum, field, toolName, ctx) {
+    if (requested <= maximum)
+        return { value: requested };
+    ctx.log.info('Read limit clamped', { tool: toolName, field, requested, applied: maximum });
+    clamps.add(1, { tool: toolName });
+    return {
+        value: maximum,
+        notice: `${field} requested ${requested}; applied ${maximum}, the supported maximum.`,
+    };
+}
+//# sourceMappingURL=clamp-read-limit.js.map

package/dist/mcp-server/tools/clamp-read-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clamp-read-limit.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/clamp-read-limit.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,MAAM,MAAM,GAAG,aAAa,CAC1B,uBAAuB,EACvB,gDAAgD,EAChD,UAAU,CACX,CAAC;AAEF,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,OAAe,EACf,KAAgC,EAChC,QAImC,EACnC,GAAyB;IAEzB,IAAI,SAAS,IAAI,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACtD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3F,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClC,OAAO;QACL,KAAK,EAAE,OAAO;QACd,MAAM,EAAE,GAAG,KAAK,cAAc,SAAS,aAAa,OAAO,0BAA0B;KACtF,CAAC;AACJ,CAAC"}

package/dist/mcp-server/tools/definitions/eurostat-browse-themes.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eurostat-browse-themes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-browse-themes.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAiB,MAAM,+BAA+B,CAAC;AAIhF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiO/B,CAAC"}
+{"version":3,"file":"eurostat-browse-themes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-browse-themes.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAiB,MAAM,+BAA+B,CAAC;AAIhF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuO/B,CAAC"}

package/dist/mcp-server/tools/definitions/eurostat-browse-themes.tool.js

@@ -14,7 +14,7 @@ export const eurostatBrowseThemes = tool('eurostat_browse_themes', {
         theme_code: z
             .string()
             .optional()
-            .describe('Folder code to expand (e.g., "economy", "reg"). Omit to list the top-level theme folders.'),
+            .describe('Folder code to expand (e.g., "economy", "reg"). Exact codes take precedence, then case-insensitive matching applies. Omit to list the top-level theme folders.'),
     }),
     output: z.object({
         items: z
@@ -122,11 +122,12 @@ export const eurostatBrowseThemes = tool('eurostat_browse_themes', {
                 });
             }
             if (data?.reason === 'not_a_folder') {
+                const canonicalThemeCode = data.themeCode;
                 throw ctx.fail('not_a_folder', err.message, {
-                    themeCode,
+                    themeCode: canonicalThemeCode,
                     entryType: data.entryType,
                     recovery: {
-                        hint: `Pass "${themeCode}" as dataset_code to eurostat_get_dataset_info to inspect its dimensions, then eurostat_query_dataset to retrieve data.`,
+                        hint: `Pass "${canonicalThemeCode}" as dataset_code to eurostat_get_dataset_info to inspect its dimensions, then eurostat_query_dataset to retrieve data.`,
                     },
                 });
             }
@@ -140,11 +141,11 @@ export const eurostatBrowseThemes = tool('eurostat_browse_themes', {
             }
             throw err;
         }
-        const { comextListMissing, catalogueLoadedAt, ...listing } = browsed;
+        const { comextListMissing, catalogueLoadedAt, themeCode: canonicalThemeCode, ...listing } = browsed;
         ctx.log.info('Theme browse complete', { themeCode, itemCount: listing.items.length });
         ctx.enrich({
             itemCount: listing.items.length,
-            ...(themeCode && { themeCode }),
+            ...(canonicalThemeCode && { themeCode: canonicalThemeCode }),
             ...(comextListMissing && { comextListMissing }),
             ...(catalogueLoadedAt && { catalogueLoadedAt }),
         });

package/dist/mcp-server/tools/definitions/eurostat-browse-themes.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"eurostat-browse-themes.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-browse-themes.tool.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"eurostat-browse-themes.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-browse-themes.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/eurostat-dataframe-query.tool.d.ts

@@ -30,5 +30,7 @@ export declare const eurostatDataframeQuery: import("@cyanheads/mcp-ts-core").To
     readonly code: JsonRpcErrorCode.NotFound;
     readonly when: "The SQL names a table that is not staged on this canvas, or that has expired.";
     readonly recovery: "Call eurostat_dataframe_describe for the staged table names, or re-run the tool that staged them (eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values with canvas_id).";
-}], undefined>;
+}], {
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
 //# sourceMappingURL=eurostat-dataframe-query.tool.d.ts.map

package/dist/mcp-server/tools/definitions/eurostat-dataframe-query.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eurostat-dataframe-query.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-dataframe-query.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;cAuIjC,CAAC"}
+{"version":3,"file":"eurostat-dataframe-query.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-dataframe-query.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0CjE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+GjC,CAAC"}

package/dist/mcp-server/tools/definitions/eurostat-dataframe-query.tool.js

@@ -7,9 +7,39 @@ import { tool, z } from '@cyanheads/mcp-ts-core';
 import { CanvasIdSchema } from '@cyanheads/mcp-ts-core/canvas';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { acquireCanvas, getCanvas, isCanvasFailure } from '../../../services/canvas-accessor.js';
+const QueryOutputSchema = z.object({
+    canvasId: z.string().describe('Canvas identifier the query ran against.'),
+    columns: z.array(z.string()).describe('Column names in projection order.'),
+    rows: z
+        .array(z.record(z.string(), z.unknown()))
+        .describe('Complete result rows, keyed by column name, bounded by the canvas row limit. Nested cells render as JSON; 64-bit integers arrive as strings so they survive intact. Cast to DOUBLE in SQL if a number is wanted.'),
+    rowCount: z
+        .number()
+        .describe('Complete rows returned after the canvas row limit. Advance SQL OFFSET by this actual count.'),
+    truncated: z
+        .boolean()
+        .describe('True when the canvas row limit omitted rows. Follow notice for SQL paging.'),
+});
+/** JSON cells preserve nested values, string quoting and escaped line breaks. */
+function renderRow(columns, row) {
+    return columns.map((column) => `${column}=${JSON.stringify(row[column])}`).join(' | ');
+}
+/** Render every complete row without changing cell values. */
+function renderText(result) {
+    return [
+        `# Query result (canvas \`${result.canvasId}\`)`,
+        `**Rows:** ${result.rowCount} | **Truncated:** ${result.truncated}`,
+        `**Columns:** ${result.columns.join(', ')}\n`,
+        ...result.rows.map((row) => renderRow(result.columns, row)),
+    ].join('\n');
+}
+/** Paging depends on a fixed deterministic SELECT over unchanged staged tables. */
+function cutNotice(rows) {
+    return `Returned ${rows.toLocaleString('en-US')} complete rows; the canvas row limit cut this result. Page with the same deterministic SELECT and a total ORDER BY (add tie-breakers for tied keys), using LIMIT/OFFSET and advancing OFFSET by the actual returned rowCount, not the requested LIMIT. If the first page had no ORDER BY, restart sorted at OFFSET 0. Volatile expressions and changing or expired tables do not support stable paging.`;
+}
 export const eurostatDataframeQuery = tool('eurostat_dataframe_query', {
     title: 'Query Eurostat Dataframes',
-    description: 'Run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas — the way to reach observations past the 5,000-row inline cap of eurostat_query_dataset and past the inline preview of a eurostat_download_dataset bulk download, and to aggregate, group, or join across staged tables without re-fetching from Eurostat. Call eurostat_dataframe_describe first for the table and column names, which differ between the tools that stage them. Only a single SELECT statement runs: statement chaining, non-SELECT verbs, and functions that read files or external data are rejected. Columns are flat — every dimension is a code column named after the dimension, the measure is obs_value, the observation flag is obs_flag / obs_flag_label and the confidentiality marker is conf_status / conf_status_label; a "_label" companion per dimension exists only on tables eurostat_query_dataset staged. Both observation stagers write the same five measure columns with the same codes, so join their tables on dimension codes and time and compare obs_flag or conf_status across them directly; a DS-* table also carries obs_value_text, a value published as text (e.g. a PRODCOM unit "KG"). A value list eurostat_get_dimension_values staged has two columns, code and label: join it to the code column of a download (e.g. JOIN df_x g ON d.geo = g.code) to label that table.',
+    description: 'Run a read-only SQL SELECT against tables staged on a Eurostat dataframe canvas, reaching observations beyond an inline preview and aggregating or joining tables without re-fetching Eurostat. Call eurostat_dataframe_describe first for table and column names. Only a single SELECT runs: statement chaining, non-SELECT verbs, and functions reading files or external data are rejected. Columns are flat: dimension codes, obs_value, obs_flag / obs_flag_label, and conf_status / conf_status_label. Tables eurostat_query_dataset staged also carry dimension _label companions; DS-* tables also carry obs_value_text for published text values. Join observation tables on dimension codes and time. A staged dimension value list has code and label columns; join it to an observation dimension code to add labels. Returns every complete row the canvas supplies, bounded only by the canvas row limit; nested cells render as lossless JSON. A row-limit cut sets truncated and adds a notice: page the same deterministic SELECT over unchanged tables with a total ORDER BY and LIMIT/OFFSET, advancing by actual rowCount. Restart an unordered first page sorted at offset zero; tied keys need tie-breakers. Volatile SQL and changing or expired tables cannot provide stable paging.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     input: z.object({
         canvas_id: CanvasIdSchema.describe('Canvas identifier returned as canvasId by eurostat_query_dataset, eurostat_download_dataset, or eurostat_get_dimension_values. Identifies the workspace holding the staged tables.'),
@@ -18,19 +48,13 @@ export const eurostatDataframeQuery = tool('eurostat_dataframe_query', {
             .min(1)
             .describe("A single read-only SELECT statement. Reference tables by the names eurostat_dataframe_describe reports. Example: SELECT geo, geo_label, AVG(obs_value) AS mean FROM df_a1b2c3d4 WHERE time >= '2020' GROUP BY geo, geo_label ORDER BY mean DESC."),
     }),
-    output: z.object({
-        canvasId: z.string().describe('Canvas identifier the query ran against.'),
-        columns: z.array(z.string()).describe('Column names in projection order.'),
-        rows: z
-            .array(z.record(z.string(), z.unknown()))
-            .describe('Result rows, each keyed by column name. Bounded by the canvas row limit. 64-bit integer results — COUNT(*) among them — arrive as strings so values outside the JSON number range survive intact; cast to DOUBLE in the SQL if a number is wanted.'),
-        rowCount: z
-            .number()
-            .describe('Rows materialized into this response. Equals the full result size unless truncated is true.'),
-        truncated: z
-            .boolean()
-            .describe('True when the result exceeded the canvas row limit and was cut short. Add a LIMIT, an aggregate, or a narrower WHERE clause to see the rest.'),
-    }),
+    output: QueryOutputSchema,
+    enrichment: {
+        notice: z
+            .string()
+            .optional()
+            .describe('Whole-row cut disclosure and deterministic SQL paging guidance. Omitted when no rows were omitted.'),
+    },
     errors: [
         {
             reason: 'canvas_disabled',
@@ -81,30 +105,22 @@ export const eurostatDataframeQuery = tool('eurostat_dataframe_query', {
          * reasons with a vaguer message.
          */
         const result = await instance.query(input.sql, { signal: ctx.signal }).catch(asDeclared);
-        ctx.log.info('Canvas query complete', {
-            canvasId: instance.canvasId,
-            rowCount: result.rowCount,
-            truncated: result.truncated === true,
-        });
-        return {
+        const output = {
             canvasId: instance.canvasId,
             columns: result.columns,
             rows: result.rows,
-            rowCount: result.rowCount,
+            rowCount: result.rows.length,
             truncated: result.truncated === true,
         };
+        if (output.truncated)
+            ctx.enrich.notice(cutNotice(output.rowCount));
+        ctx.log.info('Canvas query complete', {
+            canvasId: instance.canvasId,
+            rowCount: output.rowCount,
+            truncated: output.truncated,
+        });
+        return output;
     },
-    format: (result) => {
-        const lines = [
-            `# Query result (canvas \`${result.canvasId}\`)`,
-            `**Rows:** ${result.rowCount} | **Truncated:** ${result.truncated}${result.truncated ? ' — add a LIMIT, an aggregate, or a narrower WHERE clause' : ''}`,
-            `**Columns:** ${result.columns.join(', ')}\n`,
-        ];
-        // Every row renders, so content[] carries the same set structuredContent does.
-        for (const row of result.rows) {
-            lines.push(result.columns.map((col) => `${col}=${row[col] === null ? 'NULL' : row[col]}`).join(' | '));
-        }
-        return [{ type: 'text', text: lines.join('\n') }];
-    },
+    format: (result) => [{ type: 'text', text: renderText(result) }],
 });
 //# sourceMappingURL=eurostat-dataframe-query.tool.js.map

package/dist/mcp-server/tools/definitions/eurostat-dataframe-query.tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"eurostat-dataframe-query.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-dataframe-query.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAE1F,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC,0BAA0B,EAAE;IACrE,KAAK,EAAE,2BAA2B;IAClC,WAAW,EACT,o1CAAo1C;IACt1C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAC/E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,SAAS,EAAE,cAAc,CAAC,QAAQ,CAChC,oLAAoL,CACrL;QACD,GAAG,EAAE,CAAC;aACH,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CACP,kPAAkP,CACnP;KACJ,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACzE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC1E,IAAI,EAAE,CAAC;aACJ,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;aACxC,QAAQ,CACP,oPAAoP,CACrP;QACH,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,CACP,6FAA6F,CAC9F;QACH,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,CACP,8IAA8I,CAC/I;KACJ,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,iBAAiB;YACzB,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,gFAAgF;YACtF,SAAS,EAAE,KAAK;YAChB,QAAQ,EACN,uGAAuG;SAC1G;QACD;YACE,MAAM,EAAE,kBAAkB;YAC1B,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,uDAAuD;YAC7D,QAAQ,EACN,2LAA2L;SAC9L;QACD;YACE,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,+EAA+E;YACrF,QAAQ,EACN,wMAAwM;SAC3M;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACpC,CAAC;QAED;;;;WAIG;QACH,MAAM,UAAU,GAAG,CAAC,GAAY,EAAS,EAAE;YACzC,IAAI,eAAe,CAAC,GAAG,EAAE,kBAAkB,CAAC,EAAE,CAAC;gBAC7C,MAAM,GAAG,CAAC,IAAI,CACZ,kBAAkB,EAClB,GAAG,CAAC,OAAO,EACX,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,EAC7B,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;YACD,IAAI,eAAe,CAAC,GAAG,EAAE,eAAe,CAAC,EAAE,CAAC;gBAC1C,MAAM,GAAG,CAAC,IAAI,CACZ,eAAe,EACf,GAAG,CAAC,OAAO,EACX,EAAE,SAAS,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,EAClC,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAErF;;;;;;;WAOG;QACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAEzF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE;YACpC,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS,KAAK,IAAI;SACrC,CAAC,CAAC;QAEH,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS,KAAK,IAAI;SACrC,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa;YACtB,4BAA4B,MAAM,CAAC,QAAQ,KAAK;YAChD,aAAa,MAAM,CAAC,QAAQ,qBAAqB,MAAM,CAAC,SAAS,GAC/D,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,0DAA0D,CAAC,CAAC,CAAC,EAClF,EAAE;YACF,gBAAgB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;SAC9C,CAAC;QACF,+EAA+E;QAC/E,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CACR,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAC3F,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"eurostat-dataframe-query.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-dataframe-query.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/eurostat-download-dataset.tool.d.ts

@@ -5,6 +5,100 @@
  */
 import { z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+/** Selects the advertised limit policy before registration. */
+export declare const createEurostatDownloadDataset: (clampLimits: boolean) => import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    dataset_code: z.ZodString;
+    filters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    since_period: z.ZodOptional<z.ZodString>;
+    until_period: z.ZodOptional<z.ZodString>;
+    preview_limit: z.ZodDefault<z.ZodNumber>;
+    canvas_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    datasetCode: z.ZodString;
+    dimensionsUsed: z.ZodArray<z.ZodString>;
+    rowCount: z.ZodNumber;
+    missingCount: z.ZodNumber;
+    periodRange: z.ZodObject<{
+        start: z.ZodOptional<z.ZodString>;
+        end: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    bytesRead: z.ZodNumber;
+    compressed: z.ZodBoolean;
+    budgetExceeded: z.ZodBoolean;
+    observations: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodNull]>>>;
+    canvasId: z.ZodOptional<z.ZodString>;
+    tableName: z.ZodOptional<z.ZodString>;
+    stagedRowCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "byte_budget_exceeded";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The decoded TSV byte budget was exhausted before a complete header and usable observation could be read.";
+    readonly recovery: "Add dimension filters or narrow since_period/until_period to reduce the transfer, or raise EUROSTAT_BULK_MAX_BYTES.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The dataset code is not available for dissemination (HTTP 404, SDMX faultcode 100).";
+    readonly recovery: "Use eurostat_search_datasets or eurostat_browse_themes to find a valid dataset code.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "invalid_dimension";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "A filter names a dimension the dataset does not have, or a value or period range Eurostat rejects (SDMX faultcode 150).";
+    readonly recovery: "Check dimension codes with eurostat_get_dataset_info and their values with eurostat_get_dimension_values, and keep the period range inside the dataset coverage.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "filter_arity";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "Eurostat rejected the positional dimension key because it carried the wrong number of positions (SDMX faultcode 140, INVALID_QUERY_NB_FILTERS), meaning the dataset structure has changed since the metadata call.";
+    readonly recovery: "Retry without filters to download the whole dataset, or re-read the dimensions with eurostat_get_dataset_info.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "invalid_period";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "since_period or until_period is not a period literal, or names a month, quarter, semester, trimester, week or day that does not exist, or since_period starts after until_period ends. Checked before any request — the bulk endpoint would otherwise roll an out-of-range period into a neighbouring one, and answer an inverted range with the whole series — and SDMX faultcode 140 TIME_PERIOD_FILTER_SPEC_INVALID maps here too.";
+    readonly recovery: "Write since_period/until_period as YYYY, YYYY-MM, YYYY-MM-DD, YYYY-Qn (1–4), YYYY-Sn (1–2), YYYY-Tn (1–3), YYYY-Mnn (01–12), YYYY-Wnn (a week the year has, up to 53) or YYYY-Dnnn (a day the year has, up to 366), for example \"2020\", \"2020-01\" or \"2020-Q1\", with since_period starting no later than until_period ends.";
+}, {
+    readonly reason: "async_queued";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Eurostat answered HTTP 200 with a SOAP syncResponse queue ticket (status SUBMITTED) instead of data, because the extraction was too costly to serve synchronously.";
+    readonly retryable: false;
+    readonly recovery: "Add dimension filters or a period range so Eurostat serves the extraction inline; the queued result cannot be collected here.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "no_results";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The download completed but carried no populated observation cells. Nothing is staged, and no canvas is created or touched.";
+    readonly recovery: "Verify the filter values with eurostat_get_dimension_values and keep since_period/until_period inside the series' coverage — a combination that exists in no cell and a range that misses the series both download as an empty table.";
+}, {
+    readonly reason: "extraction_too_big";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Eurostat refused the extraction as too large (SDMX faultcode 413, HTTP 413): past its 5,000,000-row extraction limit, or an unfiltered download of a large DS-* Comext collection, which Eurostat serves only filtered. Covers every dataset, on either host.";
+    readonly retryable: false;
+    readonly recovery: "Add dimension filters or a narrower since_period/until_period range to shrink the extraction; the same request fails the same way on every retry.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "upstream_fault";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The SDMX data endpoint returned a fault this server does not model, or a body that is not a TSV table; or the data endpoint — or, for a filtered download, the structure endpoint — answered HTTP 5xx or could not be reached on every retry, which the error marks retryable.";
+    readonly recovery: "Retry in a few minutes, or narrow the request with dimension filters.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "canvas_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "A canvas_id was supplied for staging but is unknown or its lifetime has elapsed.";
+    readonly recovery: "Omit canvas_id so the download starts a fresh canvas and returns its canvasId.";
+}], {
+    readonly totalCount: z.ZodNumber;
+    readonly appliedQuery: z.ZodObject<{
+        filters: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+        sincePeriod: z.ZodOptional<z.ZodString>;
+        untilPeriod: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+    }, z.core.$strip>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+/** Default-on read-limit policy; startup selects the deployment policy explicitly. */
 export declare const eurostatDownloadDataset: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     dataset_code: z.ZodString;
     filters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
@@ -29,6 +123,12 @@ export declare const eurostatDownloadDataset: import("@cyanheads/mcp-ts-core").T
     tableName: z.ZodOptional<z.ZodString>;
     stagedRowCount: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, readonly [{
+    readonly reason: "byte_budget_exceeded";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The decoded TSV byte budget was exhausted before a complete header and usable observation could be read.";
+    readonly recovery: "Add dimension filters or narrow since_period/until_period to reduce the transfer, or raise EUROSTAT_BULK_MAX_BYTES.";
+    readonly thrownBy: "service";
+}, {
     readonly reason: "not_found";
     readonly code: JsonRpcErrorCode.NotFound;
     readonly when: "The dataset code is not available for dissemination (HTTP 404, SDMX faultcode 100).";

package/dist/mcp-server/tools/definitions/eurostat-download-dataset.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"eurostat-download-dataset.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-download-dataset.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAiB,MAAM,+BAA+B,CAAC;AA4ChF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAydlC,CAAC"}
+{"version":3,"file":"eurostat-download-dataset.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-download-dataset.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAiB,MAAM,+BAA+B,CAAC;AA6ChF,+DAA+D;AAC/D,eAAO,MAAM,6BAA6B,gBAAiB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+e9D,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAsC,CAAC"}