@cyanheads/eurostat-mcp-server 0.8.1 → 0.10.0

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/eurostat-mcp-server</h1>
   <p><b>Search and query the Eurostat catalogue — EU economy, demography, trade, health, and NUTS regional data via MCP. STDIO or Streamable HTTP.</b>
-  <div>6 Tools (8 with the dataframe canvas) • 1 Resource</div>
+  <div>6 Tools (up to 9 with the dataframe canvas) • 1 Resource</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.8.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/eurostat-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/eurostat-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/eurostat-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.10.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/eurostat-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/eurostat-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/eurostat-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -35,18 +35,19 @@ The catalogue spans two Eurostat hosts. Most datasets come from the disseminatio
 
 ### Tools
 
-Two of the eight are listed only when the dataframe canvas is enabled (`CANVAS_PROVIDER_TYPE=duckdb`).
+Three of the nine are listed only when the dataframe canvas is enabled (`CANVAS_PROVIDER_TYPE=duckdb`), and `eurostat_dataframe_drop` also needs `EUROSTAT_DATAFRAME_DROP_ENABLED=true`.
 
 | Tool | Description |
 |:---|:---|
 | `eurostat_search_datasets` | Search the Eurostat catalogue by keyword — returns codes, descriptions, period coverage, and theme breadcrumbs |
 | `eurostat_browse_themes` | Navigate the Eurostat theme hierarchy — list root themes or drill into subthemes and datasets |
 | `eurostat_get_dataset_info` | Fetch dataset metadata: dimensions with sample values, time range, observation count, and last-update date |
-| `eurostat_get_dimension_values` | List all valid codes for one dataset dimension, with NUTS hierarchy filtering for `geo` |
+| `eurostat_get_dimension_values` | List all valid codes for one dataset dimension, paged, with a code/label word filter and NUTS hierarchy filtering for `geo` |
 | `eurostat_query_dataset` | Fetch a bounded preview of decoded observations with dimension filters, NUTS geo-level, and time-range controls |
 | `eurostat_download_dataset` | Download a whole dataset via the SDMX bulk endpoint and stage every observation on the dataframe canvas |
 | `eurostat_dataframe_describe` | List the tables staged on a dataframe canvas, with row counts and column types |
 | `eurostat_dataframe_query` | Run a read-only SQL SELECT across staged tables |
+| `eurostat_dataframe_drop` | Remove one staged table from a dataframe canvas, leaving its other tables in place (opt-in) |
 
 ### Resources
 
@@ -60,76 +61,77 @@ The same metadata is available through `eurostat_get_dataset_info` for tool-only
 
 ### `eurostat_search_datasets` <sub>tool</sub>
 
-- `query` tokens are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code; `limit` 1–100 (default 20), paged by passing `nextCursor` back as `cursor`
-- Results carry `code`, `label`, `type` (`dataset` / `table`), period coverage, `obsCount`, `lastUpdated`, and `themePath`; `totalMatches` counts every match
-- Searches the dissemination table of contents plus the Comext host's dataflow list, whose `DS-*` entries carry `lastUpdated` but no period coverage or `obsCount`. A collection on neither, such as the legacy PRODCOM `DS-056120`, is not disseminated and cannot be reached
-- Fails as `no_match` — for a query naming such a `DS-*` code, saying the collection is not disseminated rather than suggesting a broader search — or `invalid_cursor` when a cursor is reused with a different query or after the catalogue refreshes
+- `query` tokens are ANDed case-insensitively across each dataset's label, theme breadcrumb, and code, ignoring spacing beside punctuation in the catalogue (`Rev.2` finds `Rev. 2`); `limit` 1–100 (default 20), paged by passing `nextCursor` back as `cursor`
+- Results carry `code`, `label`, `type` (`dataset` / `table`), period coverage, `obsCount`, `lastUpdated`, and `themePath`, with `totalMatches` across every page; fails as `no_match` (naming each word whose removal alone finds matches, with the count), `invalid_cursor`, or a retryable `upstream_fault` when the server has no catalogue loaded yet and Eurostat's table of contents answers HTTP 5xx or cannot be reached on every retry
+- While the Comext dataflow list cannot be loaded, results come from the dissemination catalogue alone and carry `comextListMissing` and a `notice`; a catalogue a failed refresh could not replace carries `catalogueLoadedAt`, and a `no_match` hint names both
 
 ---
 
 ### `eurostat_browse_themes` <sub>tool</sub>
 
-- Omit `theme_code` for the top-level theme folders; pass a folder code for its immediate children
-- The Comext collections sit in two folders the table of contents lacks: `ext_go_detail` (detailed trade) under `ext_go`, and `prom` (PRODCOM) under `icts`
-- Items carry `code`, `label`, `type` (`folder` / `dataset` / `table`), and `hasChildren`, with a `parentPath` breadcrumb; `otherPlacements` names other branches that file the same folder code
-- Fails as `not_found` for an unknown code, `not_a_folder` for a dataset or table code
+- Omit `theme_code` for the top-level theme folders; pass a folder code for its immediate children. The Comext collections sit under `ext_go_detail` (detailed trade, in `ext_go`) and `prom` (PRODCOM, in `icts`)
+- Items carry `code`, `label`, `type` (`folder` / `dataset` / `table`), and `hasChildren`, with a `parentPath` breadcrumb and `otherPlacements` for a folder code filed in several branches; fails as `not_found` for an unknown code, `not_a_folder` for a dataset or table code, or a retryable `upstream_fault` when the server has no catalogue loaded yet and Eurostat's table of contents answers HTTP 5xx or cannot be reached on every retry
+- While the Comext dataflow list cannot be loaded, `ext_go` and `icts` carry `comextListMissing` and a `notice`, and `not_found` on a Comext folder or `DS-*` code says the list could not be loaded; a catalogue a failed refresh could not replace carries `catalogueLoadedAt`, and a `not_found` hint gives its load time
 
 ---
 
 ### `eurostat_get_dataset_info` <sub>tool</sub>
 
 - One `dataset_code`; returns every dimension with `valuesCount` and up to 10 `sampleValues`, plus `timeRange`, `obsCount`, `lastUpdated`, and the ESMS `metadataUrl`
-- The Comext host reports no `timeRange` or `obsCount` for a `DS-*` collection, so both read as unreported. Its structure carries a label for every code, 23 MB for `DS-045409`: parsed metadata is cached per dataset for an hour, within a 64 MiB memory budget, so only the first call pays for it
-- Fails as `not_found` for an unknown dataset, or `upstream_fault` when Eurostat returns a structure or content constraint the server cannot read; a failed read is not cached, so a later call downloads it afresh
+- Fails as `not_found` for an unknown dataset, or `upstream_fault` when Eurostat returns a structure or content constraint the server cannot read, or when the structure endpoint answers HTTP 5xx or cannot be reached on every retry (marked retryable)
 
 ---
 
 ### `eurostat_get_dimension_values` <sub>tool</sub>
 
-- `dataset_code` plus `dimension`; returns the dataset-available code/label pairs in `values`, with `totalCount`
-- At most 2,000 values come back inline, in Eurostat's order. A longer list — the 37,069 CN8 codes of `DS-045409`, a daily `time` dimension, the largest airport-pair lists — is cut there, with `truncated`, `shown`, `cap`, and a `notice` saying where the rest is
-- For `geo`, `geo_level` picks a NUTS level (`aggregate`, `country` by default, `nuts1`, `nuts2`, `nuts3`)
-- `canvas_id` also stages every value, past the inline cap too, on that canvas as a `code` / `label` table (`canvasId` / `tableName` / `stagedRowCount`), to search with SQL or to label a download's code-only columns through a join; this tool never starts a canvas of its own, and ignores `canvas_id` on a deployment without one
-- Fails as `not_found` for an unknown dataset or dimension, `no_results` for a NUTS level with no values, `conflicting_params` for `geo_level` on any other dimension, `upstream_fault` for a structure or content constraint the server cannot read, or `canvas_not_found` for an unknown or expired `canvas_id`
+- `dataset_code` plus `dimension`; for `geo`, `geo_level` picks a NUTS level (`aggregate`, `country` by default, `nuts1`, `nuts2`, `nuts3`). Values come back in Eurostat's order
+- `filter` keeps the values whose code and label contain every word given, ignoring case and accents (`palma frankfurt` finds `DE_EDDF_ES_LEPA`), with `matchCount` counting the matches
+- A long list comes back a page at a time: each response holds whole values within 64,000 bytes, up to an optional `limit`, and a page with more after it carries `truncated`, `nextCursor` (pass it back as `cursor`), and a `notice`. `totalCount` counts every value
+- Fails as `not_found`, `no_results`, `conflicting_params`, `invalid_cursor`, `upstream_fault` (a structure or content constraint the server cannot read, or, marked retryable, a structure endpoint that answers HTTP 5xx or cannot be reached on every retry), or `canvas_not_found`
+- `canvas_id` stages every value, whatever `filter` and `limit` are, on that canvas as a `code` / `label` table (`canvasId` / `tableName` / `stagedRowCount`) that labels a download's code columns through a join; this tool never starts a canvas of its own
 
 ---
 
 ### `eurostat_query_dataset` <sub>tool</sub>
 
-- `dataset_code` plus `filters` (`{dimension_code: [values]}`, codes in any case), `geo_level`, and either `since_period` / `until_period` (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, `YYYY-Qn`, `YYYY-Sn`, `YYYY-Tn`, `YYYY-Mnn`, `YYYY-Wnn`, `YYYY-Dnnn`; extra leading zeros after the letter are dropped, so `2020-Q01` is sent as `2020-Q1`, and `YYYY-A1` is sent as `YYYY`) or `last_n_periods`, which counts back from the dataset's latest period rather than the slice's; `preview_limit` 1–500 (default 50) sets the inline row count; `lang` is `EN`, `FR`, or `DE`
-- Each observation carries code/label pairs per dimension, a nullable `value`, an OBS_FLAG `status`, and a CONF_STATUS `confStatus`; `obsCount`, `missingObsCount`, and `timeRange` cover the whole match, `truncated` is true above 5,000 observations, and `unmatchedValues` names filter values that matched nothing
-- PRODCOM publishes its flag and unit indicators as text in the value itself: `:C` comes back as a null `value` with `confStatus` `C`, and anything else, such as the unit `KG`, verbatim in `valueText` with a null `value`
-- Fails as `not_found`, `no_results` (naming the filter values that matched nothing and, up to the newest 24 with a full count, the selected periods that carry no value), `invalid_dimension`, `invalid_period` (a malformed or non-existent period, or a `since_period` that starts after `until_period` ends, rejected before any request), `conflicting_params` (`geo` filter with `geo_level`, or a period range with `last_n_periods`), a non-retryable `async_response` for a query too large to serve inline, or `canvas_not_found` for an unknown or expired `canvas_id`
+- `dataset_code` plus `filters` (`{dimension_code: [values]}`), `geo_level`, and either `since_period` / `until_period` (`2020`, `2020-Q1`, `2020-01`, down to `YYYY-Wnn` and `YYYY-Dnnn`) or `last_n_periods`; `preview_limit` 1–500 (default 50) sets the inline rows; `lang` is `EN`, `FR`, or `DE`
+- Each observation carries code/label pairs per dimension, a nullable `value`, `status` (OBS_FLAG), and `confStatus` (CONF_STATUS); `obsCount`, `missingObsCount`, and `timeRange` cover the whole match, `truncated` is true above 5,000 observations, and `unmatchedValues` names filter values that matched nothing
+- Fails as `not_found`, `no_results` (naming the unmatched values and the periods that carry no value), `invalid_dimension`, `invalid_period`, `conflicting_params`, a non-retryable `async_response` for a query too large to serve inline, `canvas_not_found`, or a retryable `upstream_fault` when the Statistics API answers HTTP 5xx or cannot be reached on every retry
 
 ---
 
 ### `eurostat_download_dataset` <sub>tool</sub>
 
-- `dataset_code` plus the same `filters` map and `since_period` / `until_period` in the same period forms (no `last_n_periods`: the TSV keeps a column per period unless a range drops it); `preview_limit` 1–500 (default 50)
-- Returns `rowCount` (echoed as `totalCount`), `missingCount`, `periodRange`, and `bytesRead` for the whole download; the `EUROSTAT_BULK_MAX_BYTES` budget (default 50 MiB) stops a transfer mid-stream and returns what arrived with `budgetExceeded: true`
-- On a `DS-*` table, `obs_value_text` holds a value published as text (PRODCOM's `KG`), and a PRODCOM `:C` lands in `conf_status`
-- Fails as `not_found`, `invalid_dimension` (including a range wholly outside the dataset's coverage), `invalid_period` (a malformed or non-existent period, or a `since_period` that starts after `until_period` ends, rejected before any request), `filter_arity`, a non-retryable `async_queued` when Eurostat queues the extraction, a non-retryable `extraction_too_big` when Eurostat refuses it as too large (past its 5,000,000-row limit, or an unfiltered download of a large Comext collection) with the dimensions left to filter, `no_results` (including a range inside the dataset's coverage that misses the filtered series), `upstream_fault`, or `canvas_not_found` for an unknown or expired `canvas_id`
+- `dataset_code` plus the same `filters` map and `since_period` / `until_period` (no `last_n_periods`: the TSV keeps a column per period unless a range drops it); `preview_limit` 1–500 (default 50)
+- Returns `rowCount` (echoed as `totalCount`), `missingCount`, `periodRange`, and `bytesRead` for the whole download; fails as `not_found`, `invalid_dimension`, `invalid_period`, `filter_arity`, a non-retryable `async_queued` or `extraction_too_big`, `no_results`, `upstream_fault` (an unmodelled fault or a body that is not a TSV table, or, marked retryable, an SDMX endpoint that answers HTTP 5xx or cannot be reached on every retry), or `canvas_not_found`
+- The `EUROSTAT_BULK_MAX_BYTES` budget (default 50 MiB) stops a transfer mid-stream and returns what arrived with `budgetExceeded: true`
 
 ---
 
 ### `eurostat_dataframe_describe` <sub>tool</sub>
 
-- `canvas_id` from a staging response; lists each table's `name`, `rowCount`, and typed columns, plus canvas and table `expiresAt` (sliding `CANVAS_TTL_MS`, default 24h); fails as `canvas_not_found` for an unknown or expired ID, or `canvas_disabled` on a deployment without a canvas
-- `eurostat_query_dataset` tables carry a code and a `_label` column per dimension; `eurostat_download_dataset` tables carry codes only, plus `time`. Both share `obs_value`, `obs_flag`, `obs_flag_label`, `conf_status`, and `conf_status_label`, so they join on dimension codes and `time`; a `DS-*` table from either adds `obs_value_text`
-- `eurostat_get_dimension_values` tables carry `code` and `label`: join one to a download on its dimension column (`d.geo = g.code`) to label it
+- `canvas_id` from a staging response; lists each table's `name`, `rowCount`, typed columns, and `expiresAt` (sliding `CANVAS_TTL_MS`, default 24h); fails as `canvas_not_found` or `canvas_disabled`
+- Columns differ by the tool that staged them: `eurostat_query_dataset` writes a code and a `_label` column per dimension, `eurostat_download_dataset` codes only plus `time` — both with the same `obs_*` and `conf_status*` measures, so they join on dimension codes and `time` — and `eurostat_get_dimension_values` writes `code` and `label`
 
 ---
 
 ### `eurostat_dataframe_query` <sub>tool</sub>
 
 - One read-only `SELECT` per call; chained statements, other verbs, and functions that read files or external data are rejected
-- Returns `columns`, `rows`, `rowCount`, and `truncated`, which is true past `CANVAS_DEFAULT_ROW_LIMIT` (default 10,000) rows; 64-bit integers, `COUNT(*)` included, arrive as strings. Fails as `missing_table`, `canvas_not_found`, or `canvas_disabled`
+- Returns `columns`, `rows`, `rowCount`, and `truncated`, true past `CANVAS_DEFAULT_ROW_LIMIT` (default 10,000) rows; 64-bit integers arrive as strings. Fails as `missing_table`, `canvas_not_found`, or `canvas_disabled`
+
+---
+
+### `eurostat_dataframe_drop` <sub>tool</sub>
+
+- `canvas_id` plus `table_name`, exactly as `eurostat_dataframe_describe` lists it; removes that one table and leaves the canvas and its other tables in place. Listed only when `EUROSTAT_DATAFRAME_DROP_ENABLED=true` is set beside the canvas
+- Returns `canvasId`, `tableName`, `dropped`, and `expiresAt`; `dropped` is `false`, with a `notice`, when nothing by that name was staged, so repeating a drop is safe. Fails as `canvas_not_found`, `identifier_reserved`, or `canvas_disabled`
 
 ---
 
 ### `eurostat://dataset/{dataset_code}` <sub>resource</sub>
 
-- Same payload as `eurostat_get_dataset_info`, returned as `application/json`
+- Same payload as `eurostat_get_dataset_info`, returned as `application/json`; a failed read carries the same `reason`, and `retryable` on an outage
 - `dataset_code` comes from `eurostat_search_datasets` or `eurostat_browse_themes`
 
 ## Features
@@ -139,10 +141,10 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 Eurostat-specific:
 
 - The Statistics API (JSON-stat 2.0) for slices, the SDMX 2.1 TSV bulk endpoint for whole datasets at roughly half the bytes, and the catalogue TOC cached in memory for 12 hours
-- The Comext host's `DS-*` collections through the same tools: detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM. The trade flows mix annual and monthly series in one dataset, so filter `freq`; `product`, `reporter` and `partner` carry aggregates (`TOTAL`, `EU27_2020`, `EXT_EU27_2020`) that double-count when summed with their members. The Comext host serves no large collection unfiltered
-- NUTS geo-level filtering (`aggregate` / `country` / `nuts1` / `nuts2` / `nuts3`) on `eurostat_query_dataset` and `eurostat_get_dimension_values`
-- OBS_FLAG (provisional, estimated, and so on) and CONF_STATUS (confidentiality) decoded into separate fields, with the same codes from JSON-stat and the bulk TSV
+- The Comext host's `DS-*` collections through the same tools: detailed trade by CN8, HS, SITC, BEC and CPA, and PRODCOM. They report no period coverage or `obsCount`, and the trade flows mix annual and monthly series in one dataset, so filter `freq`; `product`, `reporter` and `partner` carry aggregates (`TOTAL`, `EU27_2020`, `EXT_EU27_2020`) that double-count when summed with their members. The Comext host serves no large collection unfiltered. PRODCOM values published as text arrive in `valueText` / `obs_value_text` (the unit `KG`), and its `:C` as confidentiality status `C`. A collection on neither host, such as the legacy `DS-056120`, is not disseminated
+- NUTS geo-level filtering (`aggregate` / `country` / `nuts1` / `nuts2` / `nuts3`) on `eurostat_query_dataset` and `eurostat_get_dimension_values`, and OBS_FLAG (provisional, estimated, and so on) and CONF_STATUS (confidentiality) decoded into separate fields, with the same codes from JSON-stat and the bulk TSV
 - Eurostat's too-large-to-serve responses (HTTP-200 async warnings, HTTP 413, SOAP fault 413, SOAP queue tickets) come back as non-retryable `async_response`, `extraction_too_big`, or `async_queued` errors that name the dataset's own dimensions left to filter, not timeouts
+- A Eurostat outage — HTTP 5xx or an unreachable host on all four attempts, about seven seconds of backoff in all — comes back as `upstream_fault` marked `retryable`, with a hint naming the endpoint and saying to retry in a few minutes. HTTP 501 fails on its first attempt, marked not retryable
 - Inline rows are capped by `preview_limit` (at most 500). With `CANVAS_PROVIDER_TYPE=duckdb`, a query match above 5,000 observations, or any bulk download, is staged whole as a SQL table (`canvasId` / `tableName` / `stagedRowCount`) for the dataframe tools, and `canvas_id` stages the next result beside earlier ones for joins — including a dimension's code/label list from `eurostat_get_dimension_values`, which labels a bulk table's codes. An empty download fails as `no_results` without creating or touching a canvas. The `.mcpb` bundle strips the native DuckDB binding, so SQL analytics need the npm, Docker, or from-source install
 
 Agent-friendly output:
@@ -270,15 +272,17 @@ cp .env.example .env
 | `EUROSTAT_TOC_CACHE_TTL_MS` | Catalogue TOC cache lifetime, in ms; the first search or browse call past it refreshes the TOC. | `43200000` (12 h) |
 | `EUROSTAT_BULK_TIMEOUT_MS` | Timeout for one `eurostat_download_dataset` transfer, in ms. | `120000` (2 min) |
 | `EUROSTAT_BULK_MAX_BYTES` | Byte budget for one bulk download, counted on the decoded TSV and enforced while streaming. | `52428800` (50 MiB) |
-| `CANVAS_PROVIDER_TYPE` | `duckdb` enables the dataframe canvas: lists the two dataframe tools and turns on staging. | `none` |
+| `CANVAS_PROVIDER_TYPE` | `duckdb` enables the dataframe canvas: lists `eurostat_dataframe_describe` and `eurostat_dataframe_query` and turns on staging. | `none` |
 | `CANVAS_TTL_MS` | Sliding lifetime of a staged canvas, in ms. | `86400000` (24 h) |
 | `CANVAS_DEFAULT_ROW_LIMIT` | Max rows one `eurostat_dataframe_query` returns before reporting `truncated`. | `10000` |
+| `EUROSTAT_DATAFRAME_DROP_ENABLED` | `true` lists `eurostat_dataframe_drop`, which removes one staged table; needs `CANVAS_PROVIDER_TYPE=duckdb`. Off by default because a drop cannot be undone. | `false` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port. | `3010` |
 | `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. The server declares `stateless`; a set value overrides it. | `stateless` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). The Docker image sets `info`. | `debug` |
 | `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
+| `LOG_TOOL_FAILURE_PAYLOADS` | Log each failed tool call's arguments and result, redacted by key name and capped at `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES` (default `16384`). A secret inside a free-form value is not redacted. | `false` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
 | `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
 
@@ -320,8 +324,8 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 
 | Directory | Purpose |
 |:---|:---|
-| `src/index.ts` | `createApp()` entry point — registers tools and the resource, inits services, gates the dataframe tools on the canvas. |
-| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Six discovery and data tools, plus two canvas-gated dataframe tools. |
+| `src/index.ts` | `createApp()` entry point — registers tools and the resource, inits services, gates the dataframe tools on the canvas and the drop tool on its own flag. |
+| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Six discovery and data tools, plus three canvas-gated dataframe tools, one of them opt-in. |
 | `src/mcp-server/resources` | Resource definitions. Dataset metadata resource. |
 | `src/services/eurostat-catalogue` | Catalogue service — fetches and parses the Eurostat TOC, merges the Comext dataflow list into it, with a TTL-bounded in-memory cache. |
 | `src/services/eurostat-data` | Statistics API service — SDMX metadata parsing with a per-dataset cache, JSON-stat 2.0 decoding, async-response detection, canvas row source. |

package/changelog/0.10.x/0.10.0.md

@@ -0,0 +1,40 @@
+---
+summary: "Pages long dimension-value lists with filter and cursor, rejects filter keys named like API controls, reports upstream outages and partial or stale catalogues, fixes blank filters, time-selection conflicts and canvas recoveries, matches search terms across spacing beside punctuation, and adopts mcp-ts-core 0.13.15."
+breaking: true
+security: false
+---
+
+# 0.10.0 — 2026-10-14
+
+## Added
+
+- **`eurostat_get_dimension_values` takes `filter`, `limit`, and `cursor`** ([#64](https://github.com/cyanheads/eurostat-mcp-server/issues/64)) — `filter` keeps values whose code and label contain every word given (case- and accent-blind, any order), with `matchCount` counting the matches; a page with more after it carries `truncated`, `nextCursor`, and a `notice`. A cursor bound to another `dataset_code`, `dimension`, `geo_level`, or `filter`, or resuming after a code no longer listed, fails as `invalid_cursor`; every binding but `geo_level` is checked before the dimension's structure is fetched. On a deployment with a dataframe canvas, `canvas_id` beside `cursor` fails as `conflicting_params`; without one, `canvas_id` is ignored and the page is served. A filter that matches nothing on a call that staged the list names the staged table.
+- **Partial and stale catalogues are disclosed** ([#63](https://github.com/cyanheads/eurostat-mcp-server/issues/63)) — while the Comext dataflow list is unmerged, `eurostat_search_datasets` and `eurostat_browse_themes` (on `ext_go` and `icts`) carry `comextListMissing` and a `notice`, `no_match` hints name it, and `not_found` on a Comext folder or `DS-*` code says the list could not be loaded. A catalogue a failed TOC refresh could not replace carries `catalogueLoadedAt`, and a search `no_match` or browse `not_found` answered from it names that load time in its hint.
+- **`eurostat_search_datasets` `no_match` names the blocking word** ([#69](https://github.com/cyanheads/eurostat-mcp-server/issues/69)) — for two or more distinct words, each word whose removal alone yields matches is listed with its count (`Without "rates": 7 matches.`), counted in one pass over the catalogue.
+- **Upstream outages fail as retryable `upstream_fault`** ([#71](https://github.com/cyanheads/eurostat-mcp-server/issues/71)) — an HTTP 5xx or an unreachable host that outlasts the retries, on every tool that calls Eurostat, with an outage hint (HTTP 501 is not retryable); the `eurostat://dataset/{dataset_code}` resource fails with the same retryable `upstream_fault`, without a hint. `eurostat_download_dataset`, filtered or not, now retries its SDMX data request on an outage instead of failing on the first attempt, and `eurostat_search_datasets` and `eurostat_browse_themes` fail the same way when no catalogue has loaded yet.
+
+## Changed
+
+- **Breaking: `eurostat_query_dataset` rejects filter keys named like Eurostat API controls** (`lang`, `format`, `geoLevel`, `sinceTimePeriod`, `untilTimePeriod`, `lastTimePeriod`, any case) as `invalid_dimension` ([#62](https://github.com/cyanheads/eurostat-mcp-server/issues/62)). Some such calls used to return data; set the `lang`, `geo_level`, `since_period`, `until_period`, or `last_n_periods` input instead.
+- **Breaking: `eurostat_get_dimension_values` no longer returns `shown` and `cap`** ([#64](https://github.com/cyanheads/eurostat-mcp-server/issues/64)). Long lists are paged within a 64,000-byte budget per response surface with `nextCursor`, instead of being cut at 2,000 values.
+- **`eurostat_search_datasets` matches across spacing beside punctuation** ([#69](https://github.com/cyanheads/eurostat-mcp-server/issues/69)) — `Rev.2` finds `Rev. 2`, and `R&D`, `non-EU`, and `DS-045409` keep their punctuation. Search text is built once per catalogue snapshot.
+- **Eurostat error labels in messages end in one period**, and server log lines no longer carry request URLs; fetches are labelled by endpoint.
+- **`instructions`, tool descriptions, `README.md`, and `docs/design.md`** describe paging, outage and partial-catalogue behavior, and the new rejections.
+- **`CLAUDE.md`/`AGENTS.md`** follow the 0.13.15 template, and the framework anti-pattern checks in `scripts/check-framework-antipatterns.ts` use POSIX character classes.
+- **Framework** — `cyanheads/mcp-ts-core` ^0.13.11 → ^0.13.15: log records carry no request URLs, and `eurostat_dataframe_query` runs on a DuckDB canvas with external access off, with an SQL gate that refuses more functions and file references. Framework skills are synced to 0.13.15.
+
+## Fixed
+
+- **A blank or whitespace-only filter element is unset** ([#61](https://github.com/cyanheads/eurostat-mcp-server/issues/61)) — `[""]` accepts every value and `["", "DE"]` is `["DE"]` on `eurostat_query_dataset` and `eurostat_download_dataset`, in the request, the `geo`/`geo_level` check, `appliedFilters`/`appliedQuery`, and the too-large hint. A blank used to be sent upstream and echoed as applied.
+- **A time filter beside a period input fails as `conflicting_params`** ([#70](https://github.com/cyanheads/eurostat-mcp-server/issues/70)) — `filters.time` or `filters.time_period` (any case) with `since_period`, `until_period`, or `last_n_periods` is refused before any request, and Eurostat's own "cannot be set at the same time" refusal is no longer reported as `invalid_period`.
+- **Declared `canvas_not_found` and `missing_table` recoveries reach callers** ([#68](https://github.com/cyanheads/eurostat-mcp-server/issues/68)) on `eurostat_query_dataset`, `eurostat_download_dataset`, `eurostat_get_dimension_values`, `eurostat_dataframe_describe`, and `eurostat_dataframe_query`, in place of the canvas service's generic hints.
+- **The canvas-off over-cap notice and truncation banner of `eurostat_query_dataset` name only filters and a period range** ([#65](https://github.com/cyanheads/eurostat-mcp-server/issues/65)); they used to route to `eurostat_download_dataset`, which keeps only its preview without a canvas.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.11 → ^0.13.15
+- `pino-pretty` ^13.1.3 → ^13.2.0
+- `zod` ^4.6.5 → ^4.6.6
+- Dev: `@types/node` 26.6.3 → 26.6.5
+- Dev: `ignore` ^7.0.11 → ^7.0.12
+- Bun 1.4.2 → 1.4.3 (`packageManager`, Dockerfile)

package/changelog/0.9.x/0.9.0.md

@@ -0,0 +1,43 @@
+---
+summary: "Opt-in eurostat_dataframe_drop removes one staged table from a canvas, the server moves to mcp-ts-core 0.13.11, and an unwritable CANVAS_TEMP_PATH now fails as a configuration error naming its errno."
+breaking: false
+security: false
+---
+
+# 0.9.0 — 2026-10-03
+
+## Added
+
+- **`eurostat_dataframe_drop`** removes one table from a dataframe canvas, leaving the canvas and its other tables in place, and returns `canvasId`, `tableName`, `dropped`, and `expiresAt`. `dropped: false`, with a `notice`, means nothing by that name was staged, so repeating a drop is safe.
+- **`EUROSTAT_DATAFRAME_DROP_ENABLED`** (default `false`) gates it, since a drop cannot be undone: the tool is listed only with this set to `true` beside `CANVAS_PROVIDER_TYPE=duckdb`, and is otherwise registered disabled, shown on the landing page with the setting or settings that turn it on. A boot test pins that a `.env` file in the working directory sets the gate as the environment does.
+- **The drop tool's errors carry its own recovery** ([#66](https://github.com/cyanheads/eurostat-mcp-server/issues/66)) — `canvas_not_found` and `identifier_reserved` reach the caller with the tool's declared recovery instead of the canvas service's hints, which are worded for staging (stage the data again, choose another table name), and `identifier_reserved` with the tool's own message.
+
+## Changed
+
+- **The server config is parsed in `setup()`**, so a bad `EUROSTAT_*` value fails startup with the framework's configuration banner naming the variable. The first tool call used to parse it, so the server reported ready and then failed every call.
+- **Dockerfile installs in a `deps` stage** on `$BUILDPLATFORM`, cross-installing for the target with `--os`/`--cpu` through `bunfig.toml`'s release-age gate and scanner; `scripts/install-otel.ts` installs the OTel peers and `scripts/prune-musl-packages.ts` drops musl-only packages. `MCP_FORCE_CONSOLE_LOGGING`, which nothing read, is gone.
+- **`server.json` npm entries launch the bin via `npx`** without the `run start:*` arguments, and the `streamable-http` entry fixes `MCP_TRANSPORT_TYPE` to `http`; the bin ignored those arguments, so the HTTP entry started on stdio.
+- **Tool handlers no longer forward `ctx.recoveryFor`**, which the framework now fills (0.13.10); the recovery hints on the wire are unchanged.
+- **Repo and packaging config** — `.gitignore` and `.dockerignore` cover every `.env*` file (the three templates stay tracked) and `.dockerignore` adds the MCP registry token files, CodeQL runs one job per language under `/language:<language>`, `.mcpbignore` excludes `docs/idea.md` and `logs/`, and `package.json` `files` excludes `dist/*.mcpb`.
+- **Docs** — the README documents the drop tool and condenses the per-tool reference, `.env.example` documents `EUROSTAT_DATAFRAME_DROP_ENABLED`, `LOG_TOOL_FAILURE_PAYLOADS`, and the per-signal OTLP endpoints, `CANVAS_TEMP_PATH` is described as a parent directory throughout, and `CLAUDE.md`/`AGENTS.md` follow the 0.13.11 template.
+- **Framework skills and scripts resynced** from mcp-ts-core 0.13.11, adding `scripts/install-otel.ts` and `scripts/prune-musl-packages.ts` and removing the one-shot `scripts/split-changelog.ts`; `lint:packaging` gains the `.mcpb` exclusion, manifest version, Dockerfile build platform, and npm launch shape checks.
+- **mcp-ts-core 0.13.7** — server stack traces (`originalStack`, `causeChain`) no longer reach clients through error `data`. With `OTEL_ENABLED=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` alone exports traces and metrics to `<base>/v1/traces` and `<base>/v1/metrics`, and with no endpoint set nothing is exported (it used to send to `localhost:4318`).
+- **mcp-ts-core 0.13.8** — request context (tenant, operation, `extra` fields) no longer reaches client error `data`, and a tool result that breaks its own output schema fails as `-32603` (was `-32007`). Opt-in OTLP log export (`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`) and failed-call payload logging (`LOG_TOOL_FAILURE_PAYLOADS`, `LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`).
+- **mcp-ts-core 0.13.9** — a JSON-stringified object sent for an object field, or an integer sent for a string field, is repaired before validation, and argument rejections name alias rewrites and dropped keys. Canvas scratch files live in a private directory inside `CANVAS_TEMP_PATH`. MCP SDK 2.1.0 refuses a JSON-RPC batch over 100 messages, and stdin EOF on stdio aborts in-flight requests.
+- **mcp-ts-core 0.13.10** — a declared `recovery` hint reaches the wire on any typed error that carries none of its own, service throws included. Error results carry `data.requestId`, and their `content[]` closes with `request <id>`. `invalid_arguments` refusals log at `notice`. The multi-arch Docker build installs dependencies on the build platform, so Bun no longer runs under QEMU.
+- **mcp-ts-core 0.13.11** — `ctx.log` messages mirrored to the client honor `MCP_LOG_LEVEL` and mask sensitive fields, the log level filter compares RFC 5424 severity, and resource-read logs cap the URI at 1,024 characters. The Docker image drops musl-only bindings, `lint:packaging` enforces the `server.json` npm launch shape above, and `@modelcontextprotocol/server` moves to 2.2.0.
+
+## Fixed
+
+- **An unwritable `CANVAS_TEMP_PATH` fails as `-32008` `ConfigurationError`** (was `-32000` `ServiceUnavailable`), naming its errno in the message and in `data.errno` beside `data.reason: "canvas_unavailable"`. Since mcp-ts-core 0.13.9 the provider fails with that code itself; the server keeps it and adds the errno and the `CANVAS_PROVIDER_TYPE=none` way out, which the framework's message omits.
+- **A cancelled `eurostat_query_dataset` or `eurostat_download_dataset` call stays a cancellation** when it reaches the too-large refusal's dimension lookup, which rethrows the abort instead of swallowing it into a generic narrowing hint.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.6 → ^0.13.11 (`@modelcontextprotocol/server` 2.0.0 → 2.2.0 transitively).
+- `@duckdb/node-api` ^1.5.5-r.5 → ^1.5.6-r.1.
+- Dev: `@biomejs/biome` 2.5.14 → 2.5.15.
+- Dev: `@types/node` 26.6.2 → 26.6.3.
+- Dev: `ignore` ^7.0.9 → ^7.0.11.
+- Dev: `tsc-alias` ^1.9.5 → ^1.9.7.
+- Dev: `vitest` ^5.0.1 → ^5.0.3.

package/dist/config/server-config.d.ts

@@ -11,6 +11,7 @@ declare const ServerConfigSchema: z.ZodObject<{
     tocCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     bulkTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     bulkMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    dataframeDropEnabled: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
 }, z.core.$strip>;
 export declare function getServerConfig(): z.infer<typeof ServerConfigSchema>;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;iBAmDtB,CAAC;AAIH,wBAAgB,eAAe,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAWpE"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;iBAyDtB,CAAC;AAIH,wBAAgB,eAAe,IAAI,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAYpE"}

package/dist/config/server-config.js

@@ -45,6 +45,10 @@ const ServerConfigSchema = z.object({
         .positive()
         .default(52_428_800)
         .describe('Byte budget for one SDMX bulk download, measured on the decoded TSV rather than on the wire. Eurostat sends the body chunked with no Content-Length, so the budget is enforced while streaming and the transfer is aborted the moment it is reached. Defaults to 50 MiB.'),
+    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.'),
 });
 let _config;
 export function getServerConfig() {
@@ -56,6 +60,7 @@ export function getServerConfig() {
         tocCacheTtlMs: 'EUROSTAT_TOC_CACHE_TTL_MS',
         bulkTimeoutMs: 'EUROSTAT_BULK_TIMEOUT_MS',
         bulkMaxBytes: 'EUROSTAT_BULK_MAX_BYTES',
+        dataframeDropEnabled: 'EUROSTAT_DATAFRAME_DROP_ENABLED',
     });
     return _config;
 }

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;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;KACxC,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,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"}

package/dist/index.js

@@ -5,9 +5,11 @@
  */
 import { createApp, disabledTool } from '@cyanheads/mcp-ts-core';
 import { config } 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 { eurostatGetDatasetInfo } from './mcp-server/tools/definitions/eurostat-get-dataset-info.tool.js';
@@ -20,17 +22,51 @@ import { initEurostatCatalogueService } from './services/eurostat-catalogue/euro
 import { initEurostatDataService } from './services/eurostat-data/eurostat-data-service.js';
 /**
  * The dataframe tools address tables on a canvas, so without one they have
- * nothing to talk to. `disabledTool` keeps them off `tools/list` — clients
- * cannot call them — while leaving them visible on the landing page and the
- * server card with the variable that turns them on, so an operator can see the
+ * nothing to talk to. `disabledTool` keeps a gated tool off `tools/list` —
+ * clients cannot call it — while the landing page still renders it with the
+ * reason it is off and the setting that turns it on, so an operator can see the
  * capability exists rather than wondering why the README documents a tool the
- * server does not advertise.
+ * server does not advertise. The drop tool carries a second gate: a drop cannot
+ * be undone, so it stays off until EUROSTAT_DATAFRAME_DROP_ENABLED opts in, and
+ * its hint names every setting still missing.
  */
 const canvasEnabled = config.canvas.providerType !== 'none';
 const CANVAS_OFF = {
     reason: 'This deployment runs without a dataframe canvas, so there are no tables to address.',
     hint: 'CANVAS_PROVIDER_TYPE=duckdb',
 };
+const DROP_OFF_HINT = 'EUROSTAT_DATAFRAME_DROP_ENABLED=true';
+/**
+ * Read before `createApp()` because the drop tool's registration depends on it.
+ * A value that fails to parse is not reported here: `setup()` reads the server
+ * config again inside `createApp()`, which prints the configuration banner and
+ * exits 1 — thrown at this point, the same error would escape as an uncaught
+ * stack trace.
+ */
+function dataframeDropEnabled() {
+    try {
+        return getServerConfig().dataframeDropEnabled;
+    }
+    catch {
+        return false;
+    }
+}
+/** The drop tool, or its disabled card naming every setting it still needs. */
+function dataframeDropTool() {
+    const dropEnabled = dataframeDropEnabled();
+    if (!canvasEnabled) {
+        return disabledTool(eurostatDataframeDrop, {
+            reason: CANVAS_OFF.reason,
+            hint: dropEnabled ? CANVAS_OFF.hint : `${CANVAS_OFF.hint}\n${DROP_OFF_HINT}`,
+        });
+    }
+    return dropEnabled
+        ? eurostatDataframeDrop
+        : disabledTool(eurostatDataframeDrop, {
+            reason: 'Table cleanup is disabled in this deployment, so a staged table leaves only when its canvas expires.',
+            hint: DROP_OFF_HINT,
+        });
+}
 await createApp({
     name: 'eurostat-mcp-server',
     title: 'eurostat-mcp-server',
@@ -49,17 +85,21 @@ await createApp({
         eurostatDownloadDataset,
         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 return only the first 2,000 values of a long list inline. A collection on neither host, such as the legacy DS-056120, is not disseminated.
+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.`,
     landing: { requireAuth: false },
     setup(core) {
+        // Parsed here so a bad value fails startup with the configuration banner, not every call.
+        getServerConfig();
         initEurostatCatalogueService(core.config, core.storage);
         initEurostatDataService(core.config, core.storage);
         initEurostatBulkService(core.config, core.storage);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iEAAiE,CAAC;AAC1G,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,yBAAyB,EAAE,MAAM,oEAAoE,CAAC;AAC/G,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,uBAAuB,EAAE,MAAM,kEAAkE,CAAC;AAC3G,OAAO,EAAE,sBAAsB,EAAE,MAAM,kEAAkE,CAAC;AAC1G,OAAO,EAAE,0BAA0B,EAAE,MAAM,sEAAsE,CAAC;AAClH,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAC;AAC5F,OAAO,EAAE,4BAA4B,EAAE,MAAM,6DAA6D,CAAC;AAC3G,OAAO,EAAE,uBAAuB,EAAE,MAAM,mDAAmD,CAAC;AAE5F;;;;;;;GAOG;AACH,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC;AAC5D,MAAM,UAAU,GAAG;IACjB,MAAM,EAAE,qFAAqF;IAC7F,IAAI,EAAE,6BAA6B;CAC3B,CAAC;AAEX,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,qBAAqB;IAC3B,KAAK,EAAE,qBAAqB;IAC5B;;;;OAIG;IACH,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE;QACL,sBAAsB;QACtB,oBAAoB;QACpB,sBAAsB;QACtB,0BAA0B;QAC1B,oBAAoB;QACpB,uBAAuB;QACvB,aAAa,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,YAAY,CAAC,yBAAyB,EAAE,UAAU,CAAC;QAC/F,aAAa,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,YAAY,CAAC,sBAAsB,EAAE,UAAU,CAAC;KAC1F;IACD,SAAS,EAAE,CAAC,uBAAuB,CAAC;IACpC,OAAO,EAAE,EAAE;IACX,YAAY,EAAE;;;;;iMAKiL;IAC/L,OAAO,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE;IAC/B,KAAK,CAAC,IAAI;QACR,4BAA4B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,uBAAuB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACnD,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

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

@@ -26,15 +26,23 @@ export declare const eurostatBrowseThemes: import("@cyanheads/mcp-ts-core").Tool
 }, z.core.$strip>, readonly [{
     readonly reason: "not_found";
     readonly code: JsonRpcErrorCode.NotFound;
-    readonly when: "The provided theme_code does not exist in the TOC.";
-    readonly recovery: "Call eurostat_browse_themes without theme_code to see valid root themes, then navigate from there.";
+    readonly when: "The provided theme_code does not exist in the TOC — or is a Comext folder (ext_go_detail, prom, comext) or DS-* code while the Comext dataflow list cannot be loaded.";
+    readonly recovery: "Call eurostat_browse_themes without theme_code to see valid root themes, then navigate from there. A Comext folder missing because its list could not be loaded returns once the merge is retried, about once a minute; eurostat_get_dataset_info reads a DS-* code directly.";
 }, {
     readonly reason: "not_a_folder";
     readonly code: JsonRpcErrorCode.ValidationError;
     readonly when: "The provided theme_code identifies a dataset or table entry instead of a folder.";
     readonly recovery: "Pass the code to eurostat_get_dataset_info to inspect it, then eurostat_query_dataset to retrieve data.";
+}, {
+    readonly reason: "upstream_fault";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The server had no catalogue loaded yet, and Eurostat's table of contents answered HTTP 5xx or could not be reached on every retry, which the error marks retryable. Once a catalogue is loaded, a failed refresh serves that copy instead.";
+    readonly recovery: "Retry in a few minutes: the catalogue load failed on Eurostat's side and runs again on the next call.";
 }], {
     readonly itemCount: z.ZodNumber;
     readonly themeCode: z.ZodOptional<z.ZodString>;
+    readonly comextListMissing: z.ZodOptional<z.ZodBoolean>;
+    readonly catalogueLoadedAt: z.ZodOptional<z.ZodString>;
+    readonly notice: z.ZodOptional<z.ZodString>;
 }>;
 //# sourceMappingURL=eurostat-browse-themes.tool.d.ts.map

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;AAGhF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmK/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiO/B,CAAC"}