@aborruso/ckan-mcp-server 0.4.128 → 0.4.129

package/LOG.md

@@ -1,7 +1,17 @@
 # LOG
 
+## 2026-10-06
+
+### v0.4.129
+
+Ships #558 (by @paoValle, closes #31): error messages now tell the caller what to try next where they said nothing. A timeout, DNS failure or network error gets "Portal unreachable. Retry later, or call `ckan_status_show`" (noting its answer can be cached up to an hour), on both Node and Workers; 5xx errors point at `ckan_status_show` too; a 404 on `ckan_group_show` suggests `ckan_group_list`/`ckan_group_search`. A request refused by the SSRF guard keeps the guard's own message instead of a retry hint. Released the same day as the merge, by explicit exception to the release cadence rule. Tests 587 passed, smoke 17/17.
+
 ## 2026-09-28
 
+### Advisory GHSA-279h-fmcr-4rwv published
+
+Reported by @manus-pi, accepted and published as Medium (CVSS 5.8): affected `<= 0.4.127`, patched `0.4.128`. CVE requested, not yet assigned. v0.4.128 is live on npm (with provenance), the MCP Registry and the Worker. `SECURITY.md` table updated; GHSA-x32r-mh7g-q2rf got CVE-2026-92146 in the meantime.
+
 ### v0.4.128
 
 Ships #556: every redirect hop in `makeCkanRequest` is re-validated (GHSA-279h-fmcr-4rwv), on both the Node/axios and Workers/fetch paths. Smoke 17/17.

package/dist/index.js

@@ -476,7 +476,36 @@ var CkanApiError = class extends Error {
     this.serverUrl = serverUrl;
   }
 };
+var CkanTransportError = class extends Error {
+  /** The portal the request went to, as the caller wrote it. */
+  serverUrl;
+  constructor(message, serverUrl) {
+    super(message);
+    this.name = "CkanTransportError";
+    this.serverUrl = serverUrl;
+  }
+};
+var SsrfGuardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SsrfGuardError";
+  }
+};
+function unwrapSsrfGuardError(axiosError) {
+  if (axiosError.cause instanceof SsrfGuardError) return axiosError.cause;
+  const redirected = axiosError.cause?.cause;
+  return redirected instanceof SsrfGuardError ? redirected : null;
+}
 function formatCkanError(error, _toolName) {
+  if (error instanceof CkanTransportError) {
+    const migration2 = error.serverUrl ? getPortalMigration(error.serverUrl) : null;
+    if (migration2) {
+      return `${error.message}
+\u2192 ${migration2.notice} See ${migration2.docs_url}`;
+    }
+    return `${error.message}
+\u2192 Portal unreachable. Retry later, or call \`ckan_status_show\` to check portal health (its answer can come from the cache for up to an hour).`;
+  }
   if (!(error instanceof CkanApiError)) {
     return error instanceof Error ? error.message : String(error);
   }
@@ -496,6 +525,8 @@ function formatCkanError(error, _toolName) {
       hint = "\u2192 Use `ckan_package_search` to find a valid dataset name or ID.";
     } else if (action === "organization_show") {
       hint = "\u2192 Use `ckan_organization_list` or `ckan_organization_search` to discover valid organization names.";
+    } else if (action === "group_show") {
+      hint = "\u2192 Use `ckan_group_list` or `ckan_group_search` to discover valid group names.";
     }
   } else if (status === 400) {
     if (action === "datastore_search_sql") {
@@ -506,9 +537,9 @@ function formatCkanError(error, _toolName) {
   } else if (status === 409 || status === 422) {
     hint = "\u2192 Portal rejected the request \u2014 parameters may conflict; simplify filters and retry.";
   } else if (status === 503 || status === 502 || status === 504) {
-    hint = "\u2192 Portal temporarily unavailable \u2014 retry in a few seconds.";
+    hint = "\u2192 Portal temporarily unavailable \u2014 retry in a few seconds, or call `ckan_status_show` to check portal health (cached up to an hour).";
   } else if (status === 500) {
-    hint = "\u2192 Portal internal error \u2014 try a different portal or retry later.";
+    hint = "\u2192 Portal internal error \u2014 try a different portal or retry later, and call `ckan_status_show` to check portal health (cached up to an hour).";
   } else if (status === void 0) {
     hint = "\u2192 The portal may not support this action, or the endpoint is unavailable.";
   }
@@ -721,10 +752,10 @@ function validateServerUrl(serverUrl) {
   try {
     parsed = new URL(serverUrl);
   } catch {
-    throw new Error(`Invalid URL: ${serverUrl}`);
+    throw new SsrfGuardError(`Invalid URL: ${serverUrl}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`Disallowed protocol "${parsed.protocol}". Only http and https are allowed.`);
+    throw new SsrfGuardError(`Disallowed protocol "${parsed.protocol}". Only http and https are allowed.`);
   }
   const hostname = parsed.hostname.toLowerCase();
   const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
@@ -733,18 +764,18 @@ function validateServerUrl(serverUrl) {
     "ip6-loopback"
   ]);
   if (BLOCKED_HOSTNAMES.has(hostname)) {
-    throw new Error(`Access to "${hostname}" is not allowed.`);
+    throw new SsrfGuardError(`Access to "${hostname}" is not allowed.`);
   }
   if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname) && isBlockedIp(hostname)) {
-    throw new Error(`Access to private/internal IP addresses is not allowed.`);
+    throw new SsrfGuardError(`Access to private/internal IP addresses is not allowed.`);
   }
   if (hostname.startsWith("[") && isBlockedIp(hostname.slice(1, -1))) {
-    throw new Error(`Access to private/internal IPv6 addresses is not allowed.`);
+    throw new SsrfGuardError(`Access to private/internal IPv6 addresses is not allowed.`);
   }
   const rawAllowed = typeof process !== "undefined" ? process.env.CKAN_ALLOWED_DOMAINS ?? "" : "";
   const allowedDomains = rawAllowed.split(",").map((s) => s.trim()).filter(Boolean);
   if (allowedDomains.length > 0 && !allowedDomains.includes(hostname)) {
-    throw new Error(`Domain "${hostname}" is not in the allowed list (CKAN_ALLOWED_DOMAINS).`);
+    throw new SsrfGuardError(`Domain "${hostname}" is not in the allowed list (CKAN_ALLOWED_DOMAINS).`);
   }
 }
 function assertHttpAllowlistConfigured() {
@@ -776,7 +807,7 @@ function createSsrfSafeLookup(dnsModule) {
       const list = Array.isArray(addresses) ? addresses : [addresses];
       for (const a of list) {
         if (isBlockedIp(a.address)) {
-          callback(new Error(
+          callback(new SsrfGuardError(
             `Access to private/internal IP addresses is not allowed ("${hostname}" resolves to ${a.address}).`
           ));
           return;
@@ -844,11 +875,11 @@ async function assertHostnameResolvesSafe(hostname) {
   try {
     addresses = await lookup(hostname);
   } catch {
-    throw new Error(`Cannot resolve "${hostname}" for SSRF validation (failing closed).`);
+    throw new SsrfGuardError(`Cannot resolve "${hostname}" for SSRF validation (failing closed).`);
   }
   for (const a of addresses) {
     if (isBlockedIp(a.address)) {
-      throw new Error(
+      throw new SsrfGuardError(
         `Access to private/internal IP addresses is not allowed ("${hostname}" resolves to ${a.address}).`
       );
     }
@@ -994,6 +1025,14 @@ async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
             "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
           }
         }, { maxHops: 5 });
+      } catch (error) {
+        if (controller.signal.aborted) {
+          throw new CkanTransportError(`Request timeout connecting to ${serverUrl}`, serverUrl);
+        }
+        if (error instanceof TypeError) {
+          throw new CkanTransportError(`Network error: ${error.message}`, serverUrl);
+        }
+        throw error;
       } finally {
         clearTimeout(timeoutId);
       }
@@ -1048,17 +1087,19 @@ async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
     if (error instanceof CkanApiError) throw error;
     if (axios.isAxiosError(error)) {
       const axiosError = error;
+      const guardError = unwrapSsrfGuardError(axiosError);
+      if (guardError) throw guardError;
       if (axiosError.response) {
         const status = axiosError.response.status;
         const data = axiosError.response.data;
         const errorMsg = data?.error?.message || data?.error || "Unknown error";
         throw new CkanApiError(`CKAN API error (${status}): ${errorMsg}`, status, action, serverUrl);
       } else if (axiosError.code === "ECONNABORTED") {
-        throw new Error(`Request timeout connecting to ${serverUrl}`);
+        throw new CkanTransportError(`Request timeout connecting to ${serverUrl}`, serverUrl);
       } else if (axiosError.code === "ENOTFOUND") {
-        throw new Error(`Server not found: ${serverUrl}`);
+        throw new CkanTransportError(`Server not found: ${serverUrl}`, serverUrl);
       } else {
-        throw new Error(`Network error: ${axiosError.message}`);
+        throw new CkanTransportError(`Network error: ${axiosError.message}`, serverUrl);
       }
     }
     throw error;
@@ -6048,7 +6089,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.128"
+    version: "0.4.129"
   });
 }
 function registerAll(server) {

package/package.json

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