@aborruso/ckan-mcp-server 0.4.120 → 0.4.121

package/LOG.md

@@ -2,6 +2,53 @@
 
 ## 2026-09-05
 
+### v0.4.121 - clearer 404 on datastore_search_sql
+
+Patch release for the fix in #532: a 404 on `datastore_search_sql` now says the portal does not expose the SQL endpoint, instead of sending the caller to `ckan_package_show` for a resource_id that was already valid. Also ships the telemetry pipeline fixes and the DEPLOYMENT.md/CLAUDE.md realignment from earlier today.
+
+### DEPLOYMENT.md and CLAUDE.md realigned with the actual deployment
+
+Six things the deployment guide got wrong, all verified against the live system:
+
+- tool count stuck at 7; `/health` reports 20 tools, 7 resources, 6 prompts on v0.4.120
+- bundle "~400KB" in two places, while the doc's own sample output said 541 KiB; rebuilt: 533 KB
+- the free tier presented as the configuration in use. Workers Observability keeps 7 days of telemetry on this account (measured: events at 7 days back, none at 8), which is the paid retention — the free-tier request and CPU limits are not the ones this deployment operates under
+- `demo.ckan.org` in three curl examples, which CLAUDE.md forbids for tests
+- the release workflow told you to commit and push straight to `main`, in both files. Now branch, PR, squash-merge, then tag on the merged commit
+- a stale `Co-Authored-By` line in the sample commit
+
+Also corrected the troubleshooting entry calling CPU-limit errors "rare": 22 in the first four days of September against 11 in all of August. Left flagged as unexplained.
+
+Left alone on purpose: archived OpenSpec proposals, historical LOG entries, and `demo.ckan.org` where it appears as an example for end users (README, EXAMPLES, SKILL) rather than as a test target.
+
+### 404 on datastore_search_sql: hint sent callers round a loop
+
+A 404 on `datastore_search_sql` fell into the generic `datastore_search` branch of
+`formatCkanError`, which answers "get a valid resource_id first: call `ckan_package_show`".
+On a portal that does not expose SQL the resource_id is fine and `ckan_package_show`
+hands back the same one, so a client following the hint retries into the same 404.
+
+SQL access is optional in CKAN and widely disabled: `datastore_search_sql?sql=SELECT 1`
+returns 404 on Toronto's portal and 200 on dati.comune.messina.it, while
+`datastore_search` answers 200 on both. A bad table name comes back as a 400, not a 404,
+so a 404 on that action means the endpoint itself is missing. The hint now says so and
+points at `ckan_datastore_search`.
+
+Verified e2e: Toronto returns the new hint; Messina counts 202.906 rows in a single SQL
+call. 498 tests pass, one added.
+
+### Telemetry pipeline: cross-worker contamination, missing outcome, unattributable errors
+
+A usage review of `worker_events_flat.jsonl` surfaced three defects in the measurement itself, all confirmed against the live Observability API:
+
+- The query filtered only on `$metadata.type = cf-worker`, with no `service` filter, so events from `opensdmx-mcp` (another Worker on the same account) were archived here: 7 out of 31 events in a 48h probe, 589 `sdmx_*` records in the May-July history. Added `$metadata.service = ckan-mcp-server` (env override `CF_SCRIPT_NAME`); the probe then returned 24/24 ckan events. The existing records cannot be cleaned: retention is 3 days.
+- `$workers.outcome` disappeared from the API on 2026-07-12 (the object now carries `spanId`/`traceId` instead). Not a regression of ours: the archiver's only refactor is 7e78b32, March. The replacement was already there and unused: `src/worker.ts` logs its own `status` per call, plus `cache_hit`, `duration_ms` and `limit`, and the archiver was throwing all four away. `resolve_outcome()` now reads `$workers.outcome`, then `source.status`, then `$metadata.level`, and writes `unknown` rather than assuming `ok`. On a 47-event live sample it resolved every record (40 ok, 7 error, no unknown), CPU-limit crashes included. July-September stays null and cannot be backfilled: retention is 3 days.
+- `worker_daily_stats.sh` had been writing `ok:0, errors:0` on every row since that date. It now derives the error flag from `error IS NOT NULL OR outcome IN (...)`, which stays valid across the schema change. March figures are unchanged; August and September are populated again (2026-09-03: 240 calls, 220 ok, 20 errors).
+
+Flat schema gains `script_version`, `request_id`, `trigger`, `cache_hit`, `duration_ms`, `limit`. Without the first, a CPU-limit event cannot be tied to a release, and those events carry no `tool` or `server` either; they now do carry the version, so September's 22 CPU errors in 4 days (against 11 in the whole of August) become attributable from here on, not retroactively. `cache_hit` and `limit` answer the two questions this review could only guess at: cache fragmentation from URL spelling, and page size on the long datastore loops. Older records are padded to the same field set on rewrite.
+
+Usage, excluding March (evaluation traffic: 2.953 calls, 242 portals) and the sdmx events: ~470-1.450 calls a month, median 13,5 a day, very spiky. `ckan_datastore_search` leads (1.142 since June), and on 2026-08-24 a single client generated 392 calls with 6 distinct queries paging Toronto's datastore. Callers spell the same portal in three or four ways (`dati.gov.it/opendata`, `www.` variant, trailing slash; `open.canada.ca` in three forms), which fragments the cache key.
+
 ### v0.4.120 - SSRF hardening release + dependency audit
 
 Releases PR #531 (env-proxy refusal, multicast/reserved/site-local ranges, see 2026-09-04 entry). Also:

package/dist/index.js

@@ -496,7 +496,9 @@ function formatCkanError(error, _toolName) {
   const { status, action, message } = error;
   let hint = "";
   if (status === 404) {
-    if (action.startsWith("datastore_search")) {
+    if (action === "datastore_search_sql") {
+      hint = "\u2192 This portal does not expose the SQL endpoint (optional in CKAN, often disabled). Use `ckan_datastore_search` with `filters`/`sort` instead; the resource_id is probably fine.";
+    } else if (action.startsWith("datastore_search")) {
       hint = "\u2192 Get a valid resource_id first: call `ckan_package_show` on a dataset, then pick a resource where `datastore_active` is true.";
     } else if (action === "package_show") {
       hint = "\u2192 Use `ckan_package_search` to find a valid dataset name or ID.";
@@ -5800,7 +5802,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.120"
+    version: "0.4.121"
   });
 }
 function registerAll(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.120",
+  "version": "0.4.121",
   "mcpName": "io.github.aborruso/ckan-mcp-server",
   "description": "MCP server for interacting with CKAN open data portals",
   "repository": {