@aborruso/ckan-mcp-server 0.4.112 → 0.4.114

package/dist/index.js

@@ -1009,26 +1009,58 @@ function truncateText(text, limit = CHARACTER_LIMIT) {
 
 ... [Response truncated at ${limit} characters]`;
 }
+var SHRINKABLE_KEYS = [
+  "results",
+  "records",
+  "rows",
+  "datasets",
+  "resources",
+  "packages",
+  "organizations",
+  "groups",
+  "portals",
+  "tags",
+  "facets",
+  "fields"
+];
 function truncateJson(obj, limit = CHARACTER_LIMIT) {
   let json = JSON.stringify(obj, null, 2);
   if (json.length <= limit) return json;
   json = JSON.stringify(obj);
   if (json.length <= limit) return json;
   const data = structuredClone(obj);
-  const arrayKeys = ["results", "records", "resources", "packages", "organizations", "groups", "tags"];
-  for (const key of arrayKeys) {
+  for (const key of SHRINKABLE_KEYS) {
     if (Array.isArray(data[key]) && data[key].length > 0) {
       const originalCount = data[key].length;
-      while (data[key].length > 1) {
+      data["_truncated"] = true;
+      data["_original_count"] = originalCount;
+      while (data[key].length > 0) {
         data[key].pop();
-        data["_truncated"] = true;
-        data["_original_count"] = originalCount;
         json = JSON.stringify(data);
         if (json.length <= limit) return json;
       }
     }
   }
-  return truncateText(JSON.stringify(data), limit);
+  const explained = JSON.stringify({
+    _truncated: true,
+    _error: `Response exceeded the ${limit} character limit and could not be reduced to fit. Narrow the query or use pagination.`
+  });
+  if (explained.length <= limit) return explained;
+  const bare = JSON.stringify({ _truncated: true });
+  return bare.length <= limit ? bare : "{}";
+}
+function jsonToolResult(obj, limit = CHARACTER_LIMIT) {
+  const text = truncateJson(obj, limit);
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: JSON.parse(text)
+  };
+}
+function cappedStructured(obj, limit = CHARACTER_LIMIT) {
+  return JSON.parse(truncateJson(obj, limit));
+}
+function formatError(message, asJson) {
+  return asJson ? JSON.stringify({ error: message, _error: true }, null, 2) : message;
 }
 function wrapUntrusted(text) {
   const safe = String(text).replace(/```/g, "\u02BC\u02BC\u02BC");
@@ -2016,7 +2048,7 @@ Note: showing top ${sorted.length} only. Use \`response_format: json\` for full
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_package_search") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_package_search"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2136,10 +2168,7 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
           results: top
         };
         if (params.response_format === "json" /* JSON */) {
-          return {
-            content: [{ type: "text", text: truncateText(JSON.stringify(payload, null, 2)) }],
-            structuredContent: payload
-          };
+          return jsonToolResult(payload);
         }
         let markdown = `# Relevant CKAN Datasets
 
@@ -2218,7 +2247,7 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_find_relevant_datasets") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_find_relevant_datasets"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2283,10 +2312,7 @@ Typical workflow: ckan_package_show \u2192 pick a resource with datastore_active
         );
         if (params.response_format === "json" /* JSON */) {
           const compact = compactPackageShow(enrichPackageShowResult(result), params.server_url);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         const markdown = formatPackageShowMarkdown(result, params.server_url);
         return {
@@ -2294,7 +2320,7 @@ Typical workflow: ckan_package_show \u2192 pick a resource with datastore_active
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_package_show") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_package_show"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2395,10 +2421,7 @@ dataset's own resource URLs); set check_source_portal=true to enable it.`,
             format_filter: formatFilter ?? null,
             resources: summary
           };
-          return {
-            content: [{ type: "text", text: truncateText(JSON.stringify(payload, null, 2)) }],
-            structuredContent: payload
-          };
+          return jsonToolResult(payload);
         }
         let markdown = `# Resources: ${result.title || result.name}
 
@@ -2459,7 +2482,7 @@ dataset's own resource URLs); set check_source_portal=true to enable it.`,
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_list_resources") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_list_resources"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2668,10 +2691,7 @@ Typical workflow: ckan_organization_list \u2192 ckan_organization_show (inspect
             }));
             if (params.response_format === "json" /* JSON */) {
               const output = { count: items.length, organizations };
-              return {
-                content: [{ type: "text", text: truncateJson(output) }],
-                structuredContent: output
-              };
+              return jsonToolResult(output);
             }
             let markdown2 = `# CKAN Organizations
 
@@ -2704,10 +2724,7 @@ Note: organization_list returned 500; using package_search facets.
         }
         if (params.response_format === "json" /* JSON */) {
           const compact = compactOrganizationList(result);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         let markdown = `# CKAN Organizations
 
@@ -2746,7 +2763,7 @@ Note: organization_list returned 500; using package_search facets.
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_list") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_organization_list"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2796,10 +2813,7 @@ Typical workflow: ckan_organization_show \u2192 ckan_package_show (inspect a dat
         );
         if (params.response_format === "json" /* JSON */) {
           const compact = compactOrganizationShow(result, params.server_url);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         const markdown = formatOrganizationShowMarkdown(result, params.server_url);
         return {
@@ -2807,7 +2821,7 @@ Typical workflow: ckan_organization_show \u2192 ckan_package_show (inspect a dat
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_show") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_organization_show"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -2873,10 +2887,7 @@ Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get de
               view_url: getOrganizationViewUrl(params.server_url, { name: item.name })
             }))
           };
-          return {
-            content: [{ type: "text", text: truncateText(JSON.stringify(jsonResult, null, 2)) }],
-            structuredContent: jsonResult
-          };
+          return jsonToolResult(jsonResult);
         }
         let markdown = `# CKAN Organization Search Results
 
@@ -2915,7 +2926,7 @@ Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get de
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_organization_search") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_organization_search"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -3127,7 +3138,7 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_datastore_search") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_datastore_search"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -3177,10 +3188,7 @@ Security note: SQL queries are forwarded directly to the CKAN DataStore API. The
         );
         if (params.response_format === "json" /* JSON */) {
           const compact = compactDatastoreResult(result);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         const markdown = formatDatastoreSqlMarkdown(result, params.server_url, params.sql);
         return {
@@ -3188,7 +3196,7 @@ Security note: SQL queries are forwarded directly to the CKAN DataStore API. The
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_datastore_search_sql") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_datastore_search_sql"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -3251,8 +3259,8 @@ Typical workflow: ckan_status_show (verify server is up) \u2192 ckan_package_sea
         ]);
         const markdown = formatStatusMarkdown(result, params.server_url, hvdCount);
         return {
-          content: [{ type: "text", text: addDemoFooter(markdown) }],
-          structuredContent: result
+          content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }],
+          structuredContent: cappedStructured(result)
         };
       } catch (error) {
         return {
@@ -3362,10 +3370,7 @@ Typical workflow: ckan_tag_list \u2192 ckan_package_search with fq="tags:tag_nam
             count: tags.length,
             tags
           };
-          return {
-            content: [{ type: "text", text: truncateText(JSON.stringify(output, null, 2)) }],
-            structuredContent: output
-          };
+          return jsonToolResult(output);
         }
         let markdown = `# CKAN Tags
 
@@ -3397,7 +3402,7 @@ Typical workflow: ckan_tag_list \u2192 ckan_package_search with fq="tags:tag_nam
         return {
           content: [{
             type: "text",
-            text: `Error listing tags: ${error instanceof Error ? error.message : String(error)}`
+            text: formatError(`Error listing tags: ${error instanceof Error ? error.message : String(error)}`, params.response_format === "json" /* JSON */)
           }],
           isError: true
         };
@@ -3598,10 +3603,7 @@ Typical workflow: ckan_group_list \u2192 ckan_group_show (inspect one) \u2192 ck
         );
         if (params.response_format === "json" /* JSON */) {
           const compact = compactGroupList(result);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         let markdown = `# CKAN Groups
 
@@ -3640,7 +3642,7 @@ Typical workflow: ckan_group_list \u2192 ckan_group_show (inspect one) \u2192 ck
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_group_list") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_group_list"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -3687,10 +3689,7 @@ Typical workflow: ckan_group_show \u2192 ckan_package_show (inspect a dataset) \
         );
         if (params.response_format === "json" /* JSON */) {
           const compact = compactGroupShow(result);
-          return {
-            content: [{ type: "text", text: truncateJson(compact) }],
-            structuredContent: compact
-          };
+          return jsonToolResult(compact);
         }
         const markdown = formatGroupShowMarkdown(result, params.server_url);
         return {
@@ -3698,7 +3697,7 @@ Typical workflow: ckan_group_show \u2192 ckan_package_show (inspect a dataset) \
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_group_show") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_group_show"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -3759,10 +3758,7 @@ Typical workflow: ckan_group_search \u2192 ckan_group_show (get details) \u2192
               dataset_count: group.count
             }))
           };
-          return {
-            content: [{ type: "text", text: truncateText(JSON.stringify(jsonResult, null, 2)) }],
-            structuredContent: jsonResult
-          };
+          return jsonToolResult(jsonResult);
         }
         let markdown = `# CKAN Group Search Results
 
@@ -3800,7 +3796,7 @@ Typical workflow: ckan_group_search \u2192 ckan_group_show (get details) \u2192
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_group_search") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_group_search"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -4457,25 +4453,31 @@ function registerQualityTools(server) {
         return {
           content: [{
             type: "text",
-            text: `Error: MQA quality metrics are only available for dati.gov.it datasets. Provided server: ${server_url}
+            text: formatError(
+              `Error: MQA quality metrics are only available for dati.gov.it datasets. Provided server: ${server_url}
 
-The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`
-          }]
+The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`,
+              response_format === "json" /* JSON */
+            )
+          }],
+          isError: true
         };
       }
       try {
         const qualityData = await getMqaQuality(server_url, dataset_id);
         const format = response_format || "markdown" /* MARKDOWN */;
-        const output = format === "json" /* JSON */ ? JSON.stringify(qualityData, null, 2) : formatQualityMarkdown(qualityData, dataset_id);
+        const output = format === "json" /* JSON */ ? truncateJson(qualityData) : truncateText(addDemoFooter(formatQualityMarkdown(qualityData, dataset_id)));
         return {
           content: [{
             type: "text",
-            text: addDemoFooter(output)
+            text: output
           }]
         };
       } catch (error) {
+        const message = `Error retrieving quality metrics: ${formatCkanError(error, "ckan_get_mqa_quality")}`;
         return {
-          content: [{ type: "text", text: `Error retrieving quality metrics: ${formatCkanError(error, "ckan_get_mqa_quality")}` }]
+          content: [{ type: "text", text: formatError(message, response_format === "json" /* JSON */) }],
+          isError: true
         };
       }
     }
@@ -4502,25 +4504,31 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
         return {
           content: [{
             type: "text",
-            text: `Error: MQA quality details are only available for dati.gov.it datasets. Provided server: ${server_url}
+            text: formatError(
+              `Error: MQA quality details are only available for dati.gov.it datasets. Provided server: ${server_url}
 
-The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`
-          }]
+The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`,
+              response_format === "json" /* JSON */
+            )
+          }],
+          isError: true
         };
       }
       try {
         const details = await getMqaQualityDetails(server_url, dataset_id);
         const format = response_format || "markdown" /* MARKDOWN */;
-        const output = format === "json" /* JSON */ ? JSON.stringify(details, null, 2) : formatQualityDetailsMarkdown(details, dataset_id);
+        const output = format === "json" /* JSON */ ? truncateJson(details) : truncateText(addDemoFooter(formatQualityDetailsMarkdown(details, dataset_id)));
         return {
           content: [{
             type: "text",
-            text: addDemoFooter(output)
+            text: output
           }]
         };
       } catch (error) {
+        const message = `Error retrieving quality details: ${formatCkanError(error, "ckan_get_mqa_quality_details")}`;
         return {
-          content: [{ type: "text", text: `Error retrieving quality details: ${formatCkanError(error, "ckan_get_mqa_quality_details")}` }]
+          content: [{ type: "text", text: formatError(message, response_format === "json" /* JSON */) }],
+          isError: true
         };
       }
     }
@@ -4686,7 +4694,7 @@ Typical workflow: ckan_analyze_datasets \u2192 ckan_datastore_search (with known
         }));
         if (params.response_format === "json" /* JSON */) {
           return {
-            content: [{ type: "text", text: truncateText(JSON.stringify({ total: searchResult.count, datasets: analyzed }, null, 2)) }]
+            content: [{ type: "text", text: truncateJson({ total: searchResult.count, datasets: analyzed }) }]
           };
         }
         const markdown = formatAnalyzeDatasetsMarkdown(
@@ -4700,7 +4708,7 @@ Typical workflow: ckan_analyze_datasets \u2192 ckan_datastore_search (with known
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_analyze_datasets") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_analyze_datasets"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -4779,7 +4787,7 @@ Typical workflow: ckan_catalog_stats (understand the portal) \u2192 ckan_package
         );
         if (params.response_format === "json" /* JSON */) {
           return {
-            content: [{ type: "text", text: truncateText(JSON.stringify({ total: result.count, facets: result.facets }, null, 2)) }]
+            content: [{ type: "text", text: truncateJson({ total: result.count, facets: result.facets }) }]
           };
         }
         const markdown = formatCatalogStatsMarkdown(params.server_url, result.count, result.facets);
@@ -4788,7 +4796,7 @@ Typical workflow: ckan_catalog_stats (understand the portal) \u2192 ckan_package
         };
       } catch (error) {
         return {
-          content: [{ type: "text", text: formatCkanError(error, "ckan_catalog_stats") }],
+          content: [{ type: "text", text: formatError(formatCkanError(error, "ckan_catalog_stats"), params.response_format === "json" /* JSON */) }],
           isError: true
         };
       }
@@ -4952,26 +4960,18 @@ Typical workflow: sparql_query (explore schema) \u2192 sparql_query (targeted qu
         const data = await querySparqlEndpoint(params.endpoint_url, limitedQuery);
         if (params.response_format === "json" /* JSON */) {
           const result = formatSparqlJson(data);
-          let text2 = JSON.stringify(result, null, 2);
-          if (text2.length > CHARACTER_LIMIT) {
-            text2 = text2.slice(0, CHARACTER_LIMIT) + "\n/* output truncated */";
-          }
-          return {
-            content: [{ type: "text", text: text2 }],
-            structuredContent: result
-          };
-        }
-        let text = formatSparqlMarkdown(data, params.endpoint_url);
-        if (text.length > CHARACTER_LIMIT) {
-          text = text.slice(0, CHARACTER_LIMIT) + "\n\n_Output truncated._";
+          return jsonToolResult(result);
         }
-        return { content: [{ type: "text", text }] };
+        return {
+          content: [{ type: "text", text: truncateText(formatSparqlMarkdown(data, params.endpoint_url)) }]
+        };
       } catch (error) {
+        const message = `SPARQL query failed:
+${error instanceof Error ? error.message : String(error)}`;
         return {
           content: [{
             type: "text",
-            text: `SPARQL query failed:
-${error instanceof Error ? error.message : String(error)}`
+            text: formatError(message, params.response_format === "json" /* JSON */)
           }],
           isError: true
         };
@@ -5081,8 +5081,8 @@ Typical workflow: ckan_find_portals (discover portal URL) \u2192 ckan_status_sho
         });
         const markdown = formatMarkdown(results, active.length, params.limit);
         return {
-          content: [{ type: "text", text: addDemoFooter(markdown) }],
-          structuredContent: { portals: results.map((p) => ({
+          content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }],
+          structuredContent: cappedStructured({ portals: results.map((p) => ({
             url: p.Href,
             title: p.SiteInfo.site_title,
             country: p.Coordinates.country_name,
@@ -5090,7 +5090,7 @@ Typical workflow: ckan_find_portals (discover portal URL) \u2192 ckan_status_sho
             datasets: p.DatasetsNumber,
             locale: p.SiteInfo.locale_default,
             has_datastore: (p.Plugins || []).includes("datastore")
-          })) }
+          })) })
         };
       } catch (error) {
         return {
@@ -5144,7 +5144,7 @@ function registerDatasetResource(server) {
         const result = await makeCkanRequest(serverUrl, "package_show", {
           id
         });
-        const content = truncateText(JSON.stringify(result, null, 2));
+        const content = truncateJson(result);
         return {
           contents: [
             {
@@ -5188,7 +5188,7 @@ function registerResourceResource(server) {
         const result = await makeCkanRequest(serverUrl, "resource_show", {
           id
         });
-        const content = truncateText(JSON.stringify(result, null, 2));
+        const content = truncateJson(result);
         return {
           contents: [
             {
@@ -5239,7 +5239,7 @@ function registerOrganizationResource(server) {
             include_datasets: false
           }
         );
-        const content = truncateText(JSON.stringify(result, null, 2));
+        const content = truncateJson(result);
         return {
           contents: [
             {
@@ -5298,7 +5298,7 @@ var registerDatasetFilterResource = (server, config) => {
           q: "*:*",
           fq
         });
-        const content = truncateText(JSON.stringify(result, null, 2));
+        const content = truncateJson(result);
         return {
           contents: [
             {