@aborruso/ckan-mcp-server 0.4.99 → 0.4.105

package/dist/index.js

@@ -262,7 +262,257 @@ function requiresMultilingualNormalization(serverUrl) {
   return portal?.normalize === "multilingual";
 }
 
+// src/utils/cache.ts
+var TTL_METADATA = /* @__PURE__ */ new Set([
+  "package_search",
+  "package_show",
+  "current_package_list_with_resources",
+  "resource_show",
+  "organization_show",
+  "organization_list",
+  "organization_search",
+  "group_show",
+  "group_list",
+  "group_search",
+  "tag_list",
+  "tag_show",
+  "tag_search"
+]);
+var TTL_STATUS = /* @__PURE__ */ new Set(["status_show", "site_read"]);
+var TTL_DATASTORE = /* @__PURE__ */ new Set(["datastore_search", "datastore_search_sql"]);
+function getTtlForAction(action, fallback) {
+  if (TTL_METADATA.has(action)) return 300;
+  if (TTL_STATUS.has(action)) return 3600;
+  if (TTL_DATASTORE.has(action)) return 60;
+  return fallback;
+}
+function readEnv(name) {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  const value = process.env[name];
+  return value === void 0 || value === "" ? void 0 : value;
+}
+function getCacheConfig() {
+  const enabledRaw = readEnv("CKAN_CACHE_ENABLED");
+  const isTest = readEnv("VITEST") === "true";
+  const enabled = enabledRaw !== void 0 ? enabledRaw !== "false" : !isTest;
+  const ttlDefault = Number(readEnv("CKAN_CACHE_TTL_DEFAULT")) || 300;
+  const maxEntries = Number(readEnv("CKAN_CACHE_MAX_ENTRIES")) || 500;
+  const maxEntryBytes = Number(readEnv("CKAN_CACHE_MAX_ENTRY_BYTES")) || 1024 * 1024;
+  return { enabled, ttlDefault, maxEntries, maxEntryBytes };
+}
+function canonicalizeParams(params) {
+  const keys = Object.keys(params).sort();
+  const pairs = [];
+  for (const key of keys) {
+    const value = params[key];
+    if (value === void 0 || value === null) continue;
+    const serialized = typeof value === "object" ? JSON.stringify(value) : String(value);
+    pairs.push(`${key}=${serialized}`);
+  }
+  return pairs.join("&");
+}
+async function sha1Hex(input) {
+  const data = new TextEncoder().encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-1", data);
+  const bytes = new Uint8Array(hashBuffer);
+  let hex = "";
+  for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+async function buildCacheKey(serverUrl, action, params) {
+  const raw = `${serverUrl}|${action}|${canonicalizeParams(params)}`;
+  return sha1Hex(raw);
+}
+var MemoryLruCache = class {
+  constructor(maxEntries) {
+    this.maxEntries = maxEntries;
+  }
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  async set(key, value, ttlSeconds) {
+    if (ttlSeconds <= 0) return;
+    if (this.store.has(key)) this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1e3 });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next().value;
+      if (oldest === void 0) break;
+      this.store.delete(oldest);
+    }
+  }
+  clear() {
+    this.store.clear();
+  }
+  size() {
+    return this.store.size;
+  }
+};
+var WorkersCacheApi = class {
+  origin = "https://ckan-mcp-cache.internal";
+  async get(key) {
+    try {
+      const response = await caches.default.match(`${this.origin}/${key}`);
+      if (!response) return void 0;
+      return await response.json();
+    } catch {
+      return void 0;
+    }
+  }
+  async set(key, value, ttlSeconds) {
+    if (ttlSeconds <= 0) return;
+    try {
+      const body = JSON.stringify(value);
+      const response = new Response(body, {
+        headers: {
+          "Content-Type": "application/json",
+          "Cache-Control": `public, s-maxage=${ttlSeconds}`
+        }
+      });
+      await caches.default.put(`${this.origin}/${key}`, response);
+    } catch {
+    }
+  }
+};
+var sharedCache = null;
+function getCache() {
+  if (sharedCache) return sharedCache;
+  const hasWorkersCaches = typeof caches !== "undefined" && typeof caches.default !== "undefined";
+  const isNode = typeof process !== "undefined" && !!process.versions?.node;
+  if (hasWorkersCaches && !isNode) {
+    sharedCache = new WorkersCacheApi();
+  } else {
+    sharedCache = new MemoryLruCache(getCacheConfig().maxEntries);
+  }
+  return sharedCache;
+}
+
+// src/utils/rate-limiter.ts
+var RateLimitError = class extends Error {
+  constructor(hostname, waitMs) {
+    super(
+      `Rate limit exceeded for ${hostname}: would need to wait ${Math.round(waitMs)}ms`
+    );
+    this.name = "RateLimitError";
+  }
+};
+var MAX_BUCKETS = 200;
+function readEnv2(name) {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  const v = process.env[name];
+  return v === void 0 || v === "" ? void 0 : v;
+}
+function getRateLimitConfig() {
+  const enabledRaw = readEnv2("CKAN_RATE_LIMIT_ENABLED");
+  const isTest = readEnv2("VITEST") === "true";
+  const enabled = enabledRaw !== void 0 ? enabledRaw !== "false" : !isTest;
+  return {
+    enabled,
+    rps: Number(readEnv2("CKAN_RATE_LIMIT_RPS")) || 5,
+    burst: Number(readEnv2("CKAN_RATE_LIMIT_BURST")) || 10,
+    maxWaitMs: Number(readEnv2("CKAN_RATE_LIMIT_MAX_WAIT_MS")) || 5e3
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var UpstreamRateLimiter = class {
+  constructor(config) {
+    this.config = config;
+  }
+  buckets = /* @__PURE__ */ new Map();
+  async acquire(hostname) {
+    const { rps, burst, maxWaitMs } = this.config;
+    if (!this.buckets.has(hostname)) {
+      if (this.buckets.size >= MAX_BUCKETS) {
+        const oldest = this.buckets.keys().next().value;
+        if (oldest !== void 0) this.buckets.delete(oldest);
+      }
+      this.buckets.set(hostname, { tokens: burst, lastRefill: Date.now() });
+    }
+    let waited = 0;
+    while (true) {
+      const bucket = this.buckets.get(hostname);
+      const now = Date.now();
+      const elapsed = now - bucket.lastRefill;
+      bucket.tokens = Math.min(burst, bucket.tokens + elapsed / 1e3 * rps);
+      bucket.lastRefill = now;
+      if (bucket.tokens >= 1) {
+        bucket.tokens -= 1;
+        return;
+      }
+      const waitNeeded = (1 - bucket.tokens) / rps * 1e3;
+      if (waited + waitNeeded > maxWaitMs) {
+        throw new RateLimitError(hostname, waited + waitNeeded);
+      }
+      await sleep(waitNeeded);
+      waited += waitNeeded;
+    }
+  }
+  clear() {
+    this.buckets.clear();
+  }
+};
+var sharedLimiter = null;
+function getRateLimiter() {
+  if (!sharedLimiter) {
+    sharedLimiter = new UpstreamRateLimiter(getRateLimitConfig());
+  }
+  return sharedLimiter;
+}
+
 // src/utils/http.ts
+var CkanApiError = class extends Error {
+  status;
+  action;
+  constructor(message, status, action) {
+    super(message);
+    this.name = "CkanApiError";
+    this.status = status;
+    this.action = action;
+  }
+};
+function formatCkanError(error, _toolName) {
+  if (!(error instanceof CkanApiError)) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  const { status, action, message } = error;
+  let hint = "";
+  if (status === 404) {
+    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.";
+    } else if (action === "organization_show") {
+      hint = "\u2192 Use `ckan_organization_list` or `ckan_organization_search` to discover valid organization names.";
+    }
+  } else if (status === 400) {
+    if (action === "datastore_search_sql") {
+      hint = "\u2192 Invalid SQL syntax or unknown column \u2014 check column names with `ckan_datastore_search` before writing SQL.";
+    } else if (action.startsWith("datastore_search")) {
+      hint = "\u2192 Bad request \u2014 likely an invalid field name or filter syntax; check column names with a `SELECT *` query first.";
+    }
+  } 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.";
+  } else if (status === 500) {
+    hint = "\u2192 Portal internal error \u2014 try a different portal or retry later.";
+  } else if (status === void 0) {
+    hint = "\u2192 The portal may not support this action, or the endpoint is unavailable.";
+  }
+  return hint ? `${message}
+${hint}` : message;
+}
+var _lastCacheHit = null;
 var loadZlib = /* @__PURE__ */ (() => {
   let cached = null;
   return async () => {
@@ -437,8 +687,32 @@ function validateServerUrl(serverUrl) {
       throw new Error(`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).`);
+  }
+}
+function auditLog(serverUrl, action, params, cacheHit) {
+  if (typeof process === "undefined" || !process.versions?.node) return;
+  const entry = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    server: serverUrl,
+    action,
+    cache_hit: cacheHit
+  };
+  if (params.q !== void 0) entry.q = params.q;
+  if (params.fq !== void 0) entry.fq = params.fq;
+  if (params.sql !== void 0) entry.sql = String(params.sql).slice(0, 200);
+  if (params.id !== void 0) entry.id = params.id;
+  if (params.rows !== void 0) entry.rows = params.rows;
+  if (params.limit !== void 0) entry.limit = params.limit;
+  try {
+    process.stderr.write(JSON.stringify(entry) + "\n");
+  } catch {
+  }
 }
-async function makeCkanRequest(serverUrl, action, params = {}) {
+async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
   const isNode = typeof process !== "undefined" && !!process.versions?.node;
   validateServerUrl(serverUrl);
   let resolvedServerUrl = serverUrl;
@@ -453,6 +727,26 @@ async function makeCkanRequest(serverUrl, action, params = {}) {
   const baseUrl = resolvedServerUrl.replace(/\/$/, "");
   const apiPath = getPortalApiPath(resolvedServerUrl);
   const url = `${baseUrl}${apiPath}/${action}`;
+  const cacheConfig = getCacheConfig();
+  const cacheEnabled = cacheConfig.enabled && opts.cache !== false;
+  const ttl = getTtlForAction(action, cacheConfig.ttlDefault);
+  const cache = cacheEnabled && ttl > 0 ? getCache() : null;
+  const cacheKey = cache ? await buildCacheKey(resolvedServerUrl, action, params) : "";
+  if (cache) {
+    const cached = await cache.get(cacheKey);
+    if (cached !== void 0) {
+      _lastCacheHit = true;
+      auditLog(serverUrl, action, params, true);
+      return cached;
+    }
+  }
+  _lastCacheHit = false;
+  const rateLimitConfig = getRateLimitConfig();
+  const rateLimitEnabled = rateLimitConfig.enabled && opts.rateLimit !== false;
+  if (rateLimitEnabled) {
+    const hostname = new URL(resolvedServerUrl).hostname;
+    await getRateLimiter().acquire(hostname);
+  }
   try {
     let decodedData;
     if (isNode) {
@@ -501,7 +795,7 @@ async function makeCkanRequest(serverUrl, action, params = {}) {
         clearTimeout(timeoutId);
       }
       if (!response.ok) {
-        throw new Error(`CKAN API error (${response.status}): ${response.statusText}`);
+        throw new CkanApiError(`CKAN API error (${response.status}): ${response.statusText}`, response.status, action);
       }
       const buffer = await response.arrayBuffer();
       const headers = {};
@@ -511,20 +805,34 @@ async function makeCkanRequest(serverUrl, action, params = {}) {
       decodedData = await decodePossiblyCompressed(buffer, headers);
     }
     if (decodedData && decodedData.success === true) {
-      return decodedData.result;
+      const result = decodedData.result;
+      if (cache) {
+        try {
+          const serialized = JSON.stringify(result);
+          if (serialized.length <= cacheConfig.maxEntryBytes) {
+            await cache.set(cacheKey, result, ttl);
+          }
+        } catch {
+        }
+      }
+      auditLog(serverUrl, action, params, false);
+      return result;
     } else {
-      throw new Error(
-        `CKAN API returned success=false: ${JSON.stringify(decodedData)}`
+      throw new CkanApiError(
+        `CKAN API returned success=false: ${JSON.stringify(decodedData)}`,
+        void 0,
+        action
       );
     }
   } catch (error) {
+    if (error instanceof CkanApiError) throw error;
     if (axios.isAxiosError(error)) {
       const axiosError = error;
       if (axiosError.response) {
         const status = axiosError.response.status;
         const data = axiosError.response.data;
         const errorMsg = data?.error?.message || data?.error || "Unknown error";
-        throw new Error(`CKAN API error (${status}): ${errorMsg}`);
+        throw new CkanApiError(`CKAN API error (${status}): ${errorMsg}`, status, action);
       } else if (axiosError.code === "ECONNABORTED") {
         throw new Error(`Request timeout connecting to ${serverUrl}`);
       } else if (axiosError.code === "ENOTFOUND") {
@@ -604,6 +912,25 @@ function addDemoFooter(text) {
 }
 
 // src/utils/url-generator.ts
+var UUID_RE = /\/resource\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i;
+function extractSourcePortal(resourceUrl, serverUrl) {
+  if (!resourceUrl) return null;
+  let rParsed;
+  let sParsed;
+  try {
+    rParsed = new URL(resourceUrl);
+    sParsed = new URL(serverUrl);
+  } catch {
+    return null;
+  }
+  if (rParsed.hostname === sParsed.hostname) return null;
+  const match = rParsed.pathname.match(UUID_RE);
+  if (!match) return null;
+  return {
+    portalUrl: `${rParsed.protocol}//${rParsed.host}`,
+    resourceId: match[1]
+  };
+}
 function getDatasetViewUrl(serverUrl, pkg) {
   const cleanServerUrl = normalizePortalUrl(serverUrl);
   const portal = getPortalConfig(serverUrl);
@@ -708,7 +1035,9 @@ var DEFAULT_RELEVANCE_WEIGHTS = {
   title: 4,
   notes: 2,
   tags: 3,
-  organization: 1
+  organization: 1,
+  holder: 4,
+  publisher: 2
 };
 var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
   "a",
@@ -767,16 +1096,31 @@ var textMatchesTerms = (text, terms) => {
 var scoreTextField = (text, terms, weight) => {
   return textMatchesTerms(text, terms) ? weight : 0;
 };
+var readDcatExtra = (dataset, key) => {
+  const extras = Array.isArray(dataset.extras) ? dataset.extras : [];
+  for (const e of extras) {
+    if (e && typeof e === "object" && e.key === key) {
+      const value = e.value;
+      if (typeof value === "string" && value.length > 0) return value;
+    }
+  }
+  const rootValue = dataset[key];
+  return typeof rootValue === "string" ? rootValue : "";
+};
 var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS) => {
   const terms = extractQueryTerms(query);
   const titleText = dataset.title || dataset.name || "";
   const notesText = dataset.notes || "";
   const orgText = dataset.organization?.title || dataset.organization?.name || dataset.owner_org || "";
+  const holderText = readDcatExtra(dataset, "holder_name");
+  const publisherText = readDcatExtra(dataset, "publisher_name");
   const breakdown = {
     title: scoreTextField(titleText, terms, weights.title),
     notes: scoreTextField(notesText, terms, weights.notes),
     tags: 0,
     organization: scoreTextField(orgText, terms, weights.organization),
+    holder: scoreTextField(holderText, terms, weights.holder),
+    publisher: scoreTextField(publisherText, terms, weights.publisher),
     total: 0
   };
   if (Array.isArray(dataset.tags) && dataset.tags.length > 0 && terms.length > 0) {
@@ -786,7 +1130,7 @@ var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS
     });
     breakdown.tags = tagMatch ? weights.tags : 0;
   }
-  breakdown.total = breakdown.title + breakdown.notes + breakdown.tags + breakdown.organization;
+  breakdown.total = breakdown.title + breakdown.notes + breakdown.tags + breakdown.organization + breakdown.holder + breakdown.publisher;
   return { total: breakdown.total, breakdown, terms };
 };
 var parseAccessServices = (resource) => {
@@ -1478,10 +1822,7 @@ Note: showing top ${sorted.length} only. Use \`response_format: json\` for full
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error searching packages: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_package_search") }],
           isError: true
         };
       }
@@ -1504,7 +1845,13 @@ Args:
   - query (string): Natural language or keyword query (e.g., "mobilit\xE0 urbana", "air quality")
   - limit (number): Number of datasets to return (default: 10)
   - weights (object): Field weights for scoring \u2014 higher weight = more influence on rank
-    Default: title=4, tags=3, notes=2, organization=1
+    Default: title=4, tags=3, notes=2, organization=1, holder=4, publisher=2
+    Note on holder vs organization: on federated catalogs (e.g. dati.gov.it), \`organization\`
+    is the harvesting catalog (e.g. Regione Puglia), while \`holder\` (DCAT-AP_IT dct:rightsHolder)
+    is the actual data owner (e.g. Comune di Lecce). Queries like "datasets from a specific Comune"
+    match \`holder\` correctly; matching only \`organization\` misses datasets harvested via
+    aggregators. \`publisher\` (dct:publisher) is scored separately at lower weight as it can
+    contain technical roles ("Redazione OD") rather than the institutional owner.
   - query_parser ('default' | 'text'): Override search parser behavior
   - response_format ('markdown' | 'json'): Output format
 
@@ -1514,17 +1861,20 @@ Returns:
 Examples:
   - { server_url: "https://dati.gov.it/opendata", query: "mobilit\xE0" }
   - { server_url: "...", query: "trasporti", limit: 5, weights: { title: 5, notes: 2 } }
+  - { server_url: "...", query: "defibrillatori Comune di Lecce", weights: { holder: 5 } }
 
 Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect top results) \u2192 ckan_datastore_search (query data)`,
       inputSchema: z2.object({
         server_url: z2.string().url().describe("Base URL of the CKAN server (e.g., https://dati.gov.it/opendata)"),
-        query: z2.string().min(2).describe("Natural language or keyword query to match against dataset title, notes, tags, and organization"),
+        query: z2.string().min(2).describe("Natural language or keyword query to match against dataset title, notes, tags, organization, holder and publisher"),
         limit: z2.coerce.number().int().min(1).max(50).optional().default(10).describe("Number of datasets to return"),
         weights: z2.object({
           title: z2.coerce.number().min(0).optional().describe("Weight for title match (default 4)"),
           notes: z2.coerce.number().min(0).optional().describe("Weight for description match (default 2)"),
           tags: z2.coerce.number().min(0).optional().describe("Weight for tag match (default 3)"),
-          organization: z2.coerce.number().min(0).optional().describe("Weight for organization match (default 1)")
+          organization: z2.coerce.number().min(0).optional().describe("Weight for organization (CKAN catalog / harvester) match (default 1)"),
+          holder: z2.coerce.number().min(0).optional().describe("Weight for holder_name match \u2014 DCAT-AP_IT dct:rightsHolder, the actual data owner (default 4)"),
+          publisher: z2.coerce.number().min(0).optional().describe("Weight for publisher_name match \u2014 DCAT-AP_IT dct:publisher (default 2)")
         }).optional().describe("Per-field scoring weights; unspecified fields use defaults"),
         query_parser: z2.enum(["default", "text"]).optional().describe("Override search parser ('text' forces text:(...) on non-fielded queries)"),
         response_format: ResponseFormatSchema
@@ -1621,6 +1971,10 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
         markdown += `- **Tags**: ${weights.tags}
 `;
         markdown += `- **Organization**: ${weights.organization}
+`;
+        markdown += `- **Holder**: ${weights.holder}
+`;
+        markdown += `- **Publisher**: ${weights.publisher}
 
 `;
         if (top.length === 0) {
@@ -1655,6 +2009,10 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
             markdown += `- Tags: ${dataset.breakdown.tags}
 `;
             markdown += `- Organization: ${dataset.breakdown.organization}
+`;
+            markdown += `- Holder: ${dataset.breakdown.holder}
+`;
+            markdown += `- Publisher: ${dataset.breakdown.publisher}
 `;
             markdown += `- Total: ${dataset.breakdown.total}
 
@@ -1666,10 +2024,7 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error ranking datasets: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_find_relevant_datasets") }],
           isError: true
         };
       }
@@ -1745,15 +2100,20 @@ Typical workflow: ckan_package_show \u2192 pick a resource with datastore_active
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error fetching package: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_package_show") }],
           isError: true
         };
       }
     }
   );
+  async function checkSourceDatastore(portalUrl, resourceId) {
+    try {
+      await makeCkanRequest(portalUrl, "datastore_search", { resource_id: resourceId, limit: 0 }, { cache: false });
+      return true;
+    } catch {
+      return false;
+    }
+  }
   server.registerTool(
     "ckan_list_resources",
     {
@@ -1776,11 +2136,17 @@ Examples:
   - { server_url: "https://dati.gov.it/opendata", id: "dataset-name" }
   - { server_url: "...", id: "dataset-name", format_filter: "CSV" }
 
-Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess available files) \u2192 ckan_datastore_search (for resources with DataStore=true)`,
+Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess available files) \u2192 ckan_datastore_search (for resources with DataStore=true)
+
+When a resource has DataStore=false but its download URL belongs to a different (source) portal,
+the tool automatically probes the source portal for DataStore availability and reports
+source_datastore_active and source_portal_url so you can query the data there instead.
+Set check_source_portal=false to skip these extra HTTP calls.`,
       inputSchema: z2.object({
         server_url: z2.string().url().describe("Base URL of the CKAN server"),
         id: z2.string().min(1).describe("Dataset ID or name"),
         format_filter: z2.string().optional().describe("Filter resources by format, case-insensitive (e.g., 'CSV', 'json', 'XLSX')"),
+        check_source_portal: z2.boolean().optional().describe("When true (default), probes the source portal for DataStore availability when a resource URL points to a different CKAN instance"),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -1799,6 +2165,7 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
         );
         const resources = Array.isArray(result.resources) ? result.resources : [];
         const formatFilter = params.format_filter?.toUpperCase();
+        const doSourceCheck = params.check_source_portal !== false;
         const summary = resources.filter((r) => !formatFilter || (r.format || "").toUpperCase() === formatFilter).map((r) => {
           const effectiveUrl = resolveDownloadUrl(r);
           return {
@@ -1810,6 +2177,18 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
             url: effectiveUrl
           };
         });
+        if (doSourceCheck) {
+          await Promise.all(
+            summary.map(async (item, idx) => {
+              if (item.datastore_active) return;
+              const extracted = extractSourcePortal(item.url, params.server_url);
+              if (!extracted) return;
+              const active = await checkSourceDatastore(extracted.portalUrl, extracted.resourceId);
+              summary[idx].source_datastore_active = active;
+              summary[idx].source_portal_url = active ? extracted.portalUrl : null;
+            })
+          );
+        }
         if (params.response_format === "json" /* JSON */) {
           const payload = {
             dataset_id: result.id,
@@ -1864,6 +2243,16 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
 `;
             for (const r of dsResources) {
               markdown += `- **${r.name}** (${r.format}): \`${r.id}\`
+`;
+            }
+          }
+          const sourceResources = summary.filter((r) => r.source_datastore_active && r.source_portal_url);
+          if (sourceResources.length > 0) {
+            markdown += `
+**Available on source portal** (use \`ckan_datastore_search\` with the source portal URL):
+`;
+            for (const r of sourceResources) {
+              markdown += `- **${r.name}** (${r.format}): \`${r.id}\` on ${r.source_portal_url}
 `;
             }
           }
@@ -1873,10 +2262,7 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error listing resources: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_list_resources") }],
           isError: true
         };
       }
@@ -2055,8 +2441,7 @@ Typical workflow: ckan_organization_list \u2192 ckan_organization_show (inspect
             }
           );
         } catch (error) {
-          const message = error instanceof Error ? error.message : String(error);
-          if (message.includes("CKAN API error (500)")) {
+          if (error instanceof CkanApiError && error.status === 500) {
             const searchResult = await makeCkanRequest(
               params.server_url,
               "package_search",
@@ -2164,10 +2549,7 @@ Note: organization_list returned 500; using package_search facets.
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error listing organizations: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_list") }],
           isError: true
         };
       }
@@ -2228,10 +2610,7 @@ Typical workflow: ckan_organization_show \u2192 ckan_package_show (inspect a dat
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error fetching organization: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_show") }],
           isError: true
         };
       }
@@ -2339,10 +2718,7 @@ Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get de
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error searching organizations: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_search") }],
           isError: true
         };
       }
@@ -2554,10 +2930,7 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error querying DataStore: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_datastore_search") }],
           isError: true
         };
       }
@@ -2618,10 +2991,7 @@ Security note: SQL queries are forwarded directly to the CKAN DataStore API. The
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error querying DataStore SQL: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_datastore_search_sql") }],
           isError: true
         };
       }
@@ -3073,10 +3443,7 @@ Typical workflow: ckan_group_list \u2192 ckan_group_show (inspect one) \u2192 ck
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error listing groups: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_group_list") }],
           isError: true
         };
       }
@@ -3134,10 +3501,7 @@ Typical workflow: ckan_group_show \u2192 ckan_package_show (inspect a dataset) \
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error fetching group: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_group_show") }],
           isError: true
         };
       }
@@ -3239,10 +3603,7 @@ Typical workflow: ckan_group_search \u2192 ckan_group_show (get details) \u2192
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error searching groups: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_group_search") }],
           isError: true
         };
       }
@@ -3911,12 +4272,8 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
           }]
         };
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
         return {
-          content: [{
-            type: "text",
-            text: `Error retrieving quality metrics: ${errorMessage}`
-          }]
+          content: [{ type: "text", text: `Error retrieving quality metrics: ${formatCkanError(error, "ckan_get_mqa_quality")}` }]
         };
       }
     }
@@ -3960,12 +4317,8 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
           }]
         };
       } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
         return {
-          content: [{
-            type: "text",
-            text: `Error retrieving quality details: ${errorMessage}`
-          }]
+          content: [{ type: "text", text: `Error retrieving quality details: ${formatCkanError(error, "ckan_get_mqa_quality_details")}` }]
         };
       }
     }
@@ -4145,10 +4498,7 @@ Typical workflow: ckan_analyze_datasets \u2192 ckan_datastore_search (with known
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error analyzing datasets: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_analyze_datasets") }],
           isError: true
         };
       }
@@ -4236,10 +4586,7 @@ Typical workflow: ckan_catalog_stats (understand the portal) \u2192 ckan_package
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Error retrieving catalog stats: ${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: formatCkanError(error, "ckan_catalog_stats") }],
           isError: true
         };
       }
@@ -4544,11 +4891,8 @@ Typical workflow: ckan_find_portals (discover portal URL) \u2192 ckan_status_sho
         };
       } catch (error) {
         return {
-          content: [{
-            type: "text",
-            text: `Could not fetch portal list from datashades.info:
-${error instanceof Error ? error.message : String(error)}`
-          }],
+          content: [{ type: "text", text: `Could not fetch portal list from datashades.info:
+${formatCkanError(error, "ckan_find_portals")}` }],
           isError: true
         };
       }
@@ -5170,7 +5514,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.99"
+    version: "0.4.105"
   });
 }
 function registerAll(server) {