@aborruso/ckan-mcp-server 0.4.72 → 0.4.76

package/LOG.md

@@ -1,5 +1,19 @@
 # LOG
 
+## 2026-03-06 (v0.4.75)
+
+- fix(`ckan_find_portals`): deduplicate portals by hostname, preferring https over http
+- feat: new tool `ckan_find_portals` — discovers CKAN portals from datashades.info registry (~950 portals); filters by country, keyword, min_datasets, language, has_datastore; LLM translates country to English
+
+## 2026-03-06 (v0.4.74)
+
+- fix: use `z.coerce.number()` for all numeric tool parameters — fixes validation errors when MCP clients pass numbers as strings (closes #16)
+
+## 2026-03-05 (v0.4.73)
+
+- feat: `package_show` now includes `api_json_url` for dataset and each resource (direct CKAN API JSON link)
+- fix: `api_json_url` uses portal-specific API path via `getPortalApiPath` instead of hardcoded `/api/3/action`
+
 ## 2026-03-05 (v0.4.72)
 
 - fix: `package_show` JSON now includes `hvd_category`, `applicable_legislation`, `frequency`, `language`, `publisher_name`, `holder_name`

package/dist/index.js

@@ -729,6 +729,8 @@ var formatPackageShowMarkdown = (result, serverUrl) => {
   markdown += `**Server**: ${serverUrl}
 `;
   markdown += `**Link**: ${getDatasetViewUrl(serverUrl, result)}
+`;
+  markdown += `**Full JSON metadata**: ${serverUrl.replace(/\/$/, "")}${getPortalApiPath(serverUrl)}/package_show?id=${result.id}
 
 `;
   markdown += `## Basic Information
@@ -851,6 +853,8 @@ ${result.notes}
         markdown += `- **DataStore**: \u2753 Not reported by portal
 `;
       }
+      markdown += `- **Full JSON metadata**: ${serverUrl.replace(/\/$/, "")}${getPortalApiPath(serverUrl)}/resource_show?id=${resource.id}
+`;
       markdown += "\n";
     }
   }
@@ -923,9 +927,13 @@ function compactPackageShow(result, serverUrl) {
       size: r.size || null,
       datastore_active: r.datastore_active ?? null,
       created: r.created || null,
-      last_modified: r.last_modified || null
+      last_modified: r.last_modified || null,
+      ...serverUrl ? { api_json_url: `${serverUrl.replace(/\/$/, "")}${getPortalApiPath(serverUrl)}/resource_show?id=${r.id}` } : {}
     })),
-    ...serverUrl ? { view_url: getDatasetViewUrl(serverUrl, result) } : {}
+    ...serverUrl ? {
+      view_url: getDatasetViewUrl(serverUrl, result),
+      api_json_url: `${serverUrl.replace(/\/$/, "")}${getPortalApiPath(serverUrl)}/package_show?id=${result.id}`
+    } : {}
   };
 }
 function registerPackageTools(server2) {
@@ -1054,16 +1062,16 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (get full metadat
         server_url: z2.string().url("Must be a valid URL").describe("Base URL of the CKAN server"),
         q: z2.string().optional().default("*:*").describe("Search query in Solr syntax"),
         fq: z2.string().optional().describe(`Filter query in Solr syntax; applied after scoring, does not affect relevance. CKAN extras fields use prefix 'extras_' (e.g. extras_hvd_category). For OR on same field use field:(val1 OR val2), never field:val1 OR field:val2 (silently breaks). Examples: 'organization:comune-palermo', 'res_format:CSV', 'extras_hvd_category:("uri1" OR "uri2")'.`),
-        rows: z2.number().int().min(0).max(1e3).optional().default(10).describe("Number of results to return"),
-        start: z2.number().int().min(0).optional().default(0).describe("Offset for pagination"),
+        rows: z2.coerce.number().int().min(0).max(1e3).optional().default(10).describe("Number of results to return"),
+        start: z2.coerce.number().int().min(0).optional().default(0).describe("Offset for pagination"),
         sort: z2.string().optional().describe("Sort field and direction (e.g., 'metadata_modified desc')"),
         facet_field: z2.array(z2.string()).optional().describe("Fields to facet on"),
-        facet_limit: z2.number().int().min(1).optional().default(50).describe("Maximum facet values per field"),
-        page: z2.number().int().min(1).optional().describe("Page number (1-based); alias for start. Overrides start if provided."),
-        page_size: z2.number().int().min(1).max(1e3).optional().default(10).describe("Results per page when using page (default: 10)"),
+        facet_limit: z2.coerce.number().int().min(1).optional().default(50).describe("Maximum facet values per field"),
+        page: z2.coerce.number().int().min(1).optional().describe("Page number (1-based); alias for start. Overrides start if provided."),
+        page_size: z2.coerce.number().int().min(1).max(1e3).optional().default(10).describe("Results per page when using page (default: 10)"),
         include_drafts: z2.boolean().optional().default(false).describe("Include draft datasets"),
         content_recent: z2.boolean().optional().default(false).describe("Use issued date with fallback to metadata_created for recent content"),
-        content_recent_days: z2.number().int().min(1).optional().default(30).describe("Day window for content_recent (default 30)"),
+        content_recent_days: z2.coerce.number().int().min(1).optional().default(30).describe("Day window for content_recent (default 30)"),
         query_parser: z2.enum(["default", "text"]).optional().describe("Override search parser ('text' forces text:(...) on non-fielded queries)"),
         response_format: ResponseFormatSchema
       }).strict(),
@@ -1304,12 +1312,12 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
       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"),
-        limit: z2.number().int().min(1).max(50).optional().default(10).describe("Number of datasets to return"),
+        limit: z2.coerce.number().int().min(1).max(50).optional().default(10).describe("Number of datasets to return"),
         weights: z2.object({
-          title: z2.number().min(0).optional().describe("Weight for title match (default 4)"),
-          notes: z2.number().min(0).optional().describe("Weight for description match (default 2)"),
-          tags: z2.number().min(0).optional().describe("Weight for tag match (default 3)"),
-          organization: z2.number().min(0).optional().describe("Weight for organization match (default 1)")
+          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)")
         }).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
@@ -1486,8 +1494,8 @@ Returns (JSON format):
   author, maintainer,
   frequency, language, publisher_name, holder_name,
   hvd_category, applicable_legislation,
-  resources (id, name, format, url, size, datastore_active, created, last_modified),
-  view_url
+  resources (id, name, format, url, size, datastore_active, created, last_modified, api_json_url),
+  view_url, api_json_url
 
 Examples:
   - { server_url: "https://dati.gov.it/opendata", id: "dataset-name" }
@@ -1787,8 +1795,8 @@ Typical workflow: ckan_organization_list \u2192 ckan_organization_show (inspect
         server_url: z3.string().url().describe("Base URL of the CKAN server (e.g., https://dati.gov.it/opendata)"),
         all_fields: z3.boolean().optional().default(false).describe("Return full organization objects (true) or just name slugs (false)"),
         sort: z3.string().optional().default("name asc").describe("Sort field and direction (e.g., 'name asc', 'package_count desc')"),
-        limit: z3.number().int().min(0).optional().default(100).describe("Max organizations to return. Use 0 to get only the count via faceting"),
-        offset: z3.number().int().min(0).optional().default(0).describe("Pagination offset"),
+        limit: z3.coerce.number().int().min(0).optional().default(100).describe("Max organizations to return. Use 0 to get only the count via faceting"),
+        offset: z3.coerce.number().int().min(0).optional().default(0).describe("Pagination offset"),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -2293,8 +2301,8 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id
         resource_id: z4.string().min(1).describe("UUID of the DataStore resource (from ckan_package_show resource.id where datastore_active is true)"),
         q: z4.string().optional().describe("Full-text search across all fields"),
         filters: z4.record(z4.any()).optional().describe('Key-value filters for exact matches (e.g., { "regione": "Sicilia", "anno": 2023 })'),
-        limit: z4.number().int().min(0).max(32e3).optional().default(100).describe("Max rows to return (default 100, max 32000); use 0 to get only column names without data"),
-        offset: z4.number().int().min(0).optional().default(0).describe("Pagination offset"),
+        limit: z4.coerce.number().int().min(0).max(32e3).optional().default(100).describe("Max rows to return (default 100, max 32000); use 0 to get only column names without data"),
+        offset: z4.coerce.number().int().min(0).optional().default(0).describe("Pagination offset"),
         fields: z4.array(z4.string()).optional().describe("Specific field names to return; omit to return all fields"),
         sort: z4.string().optional().describe("Sort expression (e.g., 'anno desc', 'nome asc')"),
         distinct: z4.boolean().optional().default(false).describe("Return only distinct rows"),
@@ -4207,6 +4215,132 @@ ${error instanceof Error ? error.message : String(error)}`
   );
 }
 
+// src/tools/portal-discovery.ts
+import { z as z11 } from "zod";
+import axios3 from "axios";
+var DATASHADES_URL = "https://datashades.info/api/portal/list";
+async function fetchPortals() {
+  const resp = await axios3.get(DATASHADES_URL, {
+    timeout: 15e3,
+    headers: { "User-Agent": "CKAN-MCP-Server/1.0" }
+  });
+  return resp.data.portals;
+}
+function deduplicateByHostname(portals) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const p of portals) {
+    try {
+      const hostname = new URL(p.Href).hostname;
+      const existing = seen.get(hostname);
+      if (!existing || p.Href.startsWith("https://")) {
+        seen.set(hostname, p);
+      }
+    } catch {
+    }
+  }
+  return Array.from(seen.values());
+}
+function filterPortals(portals, params) {
+  const filtered = portals.filter((p) => p.status === "active" && p.Href).filter((p) => !params.country || p.Coordinates.country_name.toLowerCase().includes(params.country.toLowerCase())).filter((p) => !params.query || p.SiteInfo.site_title.toLowerCase().includes(params.query.toLowerCase())).filter((p) => params.min_datasets === void 0 || p.DatasetsNumber >= params.min_datasets).filter((p) => !params.language || p.SiteInfo.locale_default.toLowerCase().startsWith(params.language.toLowerCase())).filter((p) => !params.has_datastore || (p.Plugins || []).includes("datastore"));
+  return deduplicateByHostname(filtered).sort((a, b) => b.DatasetsNumber - a.DatasetsNumber).slice(0, params.limit);
+}
+function formatMarkdown(portals, total, limit) {
+  if (portals.length === 0) return "No CKAN portals found matching the given filters.";
+  const rows = portals.map(
+    (p) => `| [${p.SiteInfo.site_title || p.Href}](${p.Href}) | ${p.Coordinates.country_name} | ${p.Version} | ${p.DatasetsNumber.toLocaleString()} | ${p.SiteInfo.locale_default} | ${(p.Plugins || []).includes("datastore") ? "\u2705" : "\u274C"} |`
+  ).join("\n");
+  return `# CKAN Portals
+
+**Source**: [datashades.info](https://datashades.info/portals) \u2014 live registry of ${total} active portals
+**Showing**: ${portals.length} of ${total} (filtered, sorted by dataset count)
+
+| Portal | Country | CKAN | Datasets | Locale | DataStore |
+|--------|---------|------|----------|--------|-----------|
+${rows}
+
+---
+\u{1F4A1} Use the portal URL as \`server_url\` in any CKAN tool.`;
+}
+function registerPortalDiscoveryTools(server2) {
+  server2.registerTool(
+    "ckan_find_portals",
+    {
+      title: "Find CKAN Portals",
+      description: `Search the live datashades.info registry of ~950 CKAN portals worldwide.
+
+Use this tool to discover which CKAN portals exist for a country, language, or topic
+before querying them with other CKAN tools.
+
+**IMPORTANT \u2014 country parameter**: always pass country name in English.
+If the user writes in another language (e.g. "Italia", "Espa\xF1a", "Brasil"),
+translate to English ("Italy", "Spain", "Brazil") before calling this tool.
+
+Args:
+  - country (string): Country name in English (e.g. "Italy", "Brazil", "France")
+  - query (string): Keyword to match against portal title (e.g. "transport", "health")
+  - min_datasets (number): Minimum number of datasets (e.g. 100)
+  - language (string): Portal default locale code (e.g. "it", "en", "pt_BR", "fr")
+  - has_datastore (boolean): If true, return only portals with DataStore enabled (supports SQL queries)
+  - limit (number): Max results to return (default 10, max 50)
+
+Returns:
+  Ranked list of matching portals with URL, country, CKAN version, dataset count, and DataStore status.
+
+Typical workflow: ckan_find_portals (discover portal URL) \u2192 ckan_status_show (verify) \u2192 ckan_package_search (search datasets)`,
+      inputSchema: z11.object({
+        country: z11.string().optional().describe("Country name in English (e.g. 'Italy', 'Brazil'). Translate from any language before passing."),
+        query: z11.string().optional().describe("Keyword matched against portal title (case-insensitive)"),
+        min_datasets: z11.coerce.number().int().min(0).optional().describe("Minimum number of datasets"),
+        language: z11.string().optional().describe("Portal default locale code (e.g. 'it', 'en', 'pt_BR')"),
+        has_datastore: z11.boolean().optional().describe("If true, return only portals with DataStore plugin (required for SQL queries)"),
+        limit: z11.coerce.number().int().min(1).max(50).optional().default(10).describe("Max results (default 10, max 50)")
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const all = await fetchPortals();
+        const active = all.filter((p) => p.status === "active");
+        const results = filterPortals(all, {
+          country: params.country,
+          query: params.query,
+          min_datasets: params.min_datasets,
+          language: params.language,
+          has_datastore: params.has_datastore,
+          limit: params.limit
+        });
+        const markdown = formatMarkdown(results, active.length, params.limit);
+        return {
+          content: [{ type: "text", text: addDemoFooter(markdown) }],
+          structuredContent: { portals: results.map((p) => ({
+            url: p.Href,
+            title: p.SiteInfo.site_title,
+            country: p.Coordinates.country_name,
+            version: p.Version,
+            datasets: p.DatasetsNumber,
+            locale: p.SiteInfo.locale_default,
+            has_datastore: (p.Plugins || []).includes("datastore")
+          })) }
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Could not fetch portal list from datashades.info:
+${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/resources/dataset.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -4476,7 +4610,7 @@ function registerAllResources(server2) {
 }
 
 // src/prompts/theme.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 
 // src/prompts/types.ts
 var createTextPrompt = (text) => ({
@@ -4537,9 +4671,9 @@ var registerThemePrompt = (server2) => {
       title: "Search datasets by theme",
       description: "Guided prompt to discover a theme and search datasets under it.",
       argsSchema: {
-        server_url: z11.string().url().describe("Base URL of the CKAN server"),
-        theme: z11.string().min(1).describe("Theme or group name to search"),
-        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z12.string().url().describe("Base URL of the CKAN server"),
+        theme: z12.string().min(1).describe("Theme or group name to search"),
+        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
@@ -4547,7 +4681,7 @@ var registerThemePrompt = (server2) => {
 };
 
 // src/prompts/organization.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var ORGANIZATION_PROMPT_NAME = "ckan-search-by-organization";
 var buildOrganizationPromptText = (serverUrl, organization, rows) => `# Guided search: datasets by organization
 
@@ -4582,9 +4716,9 @@ var registerOrganizationPrompt = (server2) => {
       title: "Search datasets by organization",
       description: "Guided prompt to find a publisher and list its datasets.",
       argsSchema: {
-        server_url: z12.string().url().describe("Base URL of the CKAN server"),
-        organization: z12.string().min(1).describe("Organization name or keyword"),
-        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z13.string().url().describe("Base URL of the CKAN server"),
+        organization: z13.string().min(1).describe("Organization name or keyword"),
+        rows: z13.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
@@ -4592,7 +4726,7 @@ var registerOrganizationPrompt = (server2) => {
 };
 
 // src/prompts/format.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var FORMAT_PROMPT_NAME = "ckan-search-by-format";
 var buildFormatPromptText = (serverUrl, format, rows) => `# Guided search: datasets by resource format
 
@@ -4616,9 +4750,9 @@ var registerFormatPrompt = (server2) => {
       title: "Search datasets by resource format",
       description: "Guided prompt to find datasets with a given resource format.",
       argsSchema: {
-        server_url: z13.string().url().describe("Base URL of the CKAN server"),
-        format: z13.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
-        rows: z13.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z14.string().url().describe("Base URL of the CKAN server"),
+        format: z14.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
+        rows: z14.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
@@ -4626,7 +4760,7 @@ var registerFormatPrompt = (server2) => {
 };
 
 // src/prompts/recent.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var RECENT_PROMPT_NAME = "ckan-recent-datasets";
 var buildRecentPromptText = (serverUrl, rows) => `# Guided search: recent datasets
 
@@ -4674,8 +4808,8 @@ var registerRecentPrompt = (server2) => {
       title: "Find recently updated datasets",
       description: "Guided prompt to list recently updated datasets on a CKAN portal.",
       argsSchema: {
-        server_url: z14.string().url().describe("Base URL of the CKAN server"),
-        rows: z14.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z15.string().url().describe("Base URL of the CKAN server"),
+        rows: z15.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
@@ -4683,7 +4817,7 @@ var registerRecentPrompt = (server2) => {
 };
 
 // src/prompts/dataset-analysis.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var DATASET_ANALYSIS_PROMPT_NAME = "ckan-analyze-dataset";
 var buildDatasetAnalysisPromptText = (serverUrl, id) => `# Guided analysis: dataset
 
@@ -4725,8 +4859,8 @@ var registerDatasetAnalysisPrompt = (server2) => {
       title: "Analyze a dataset",
       description: "Guided prompt to inspect dataset metadata and explore DataStore tables.",
       argsSchema: {
-        server_url: z15.string().url().describe("Base URL of the CKAN server"),
-        id: z15.string().min(1).describe("Dataset id or name (CKAN package id)")
+        server_url: z16.string().url().describe("Base URL of the CKAN server"),
+        id: z16.string().min(1).describe("Dataset id or name (CKAN package id)")
       }
     },
     async ({ server_url, id }) => createTextPrompt(buildDatasetAnalysisPromptText(server_url, id))
@@ -4734,7 +4868,7 @@ var registerDatasetAnalysisPrompt = (server2) => {
 };
 
 // src/prompts/hvd.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var HVD_PROMPT_NAME = "ckan-search-hvd";
 var buildHvdPromptText = (serverUrl, rows, categoryField) => {
   if (!categoryField) {
@@ -4796,8 +4930,8 @@ var registerHvdPrompt = (server2) => {
       title: "Search High-Value Datasets (HVD)",
       description: "Guided prompt to find High-Value Datasets (HVD) on a CKAN portal. Automatically uses the correct filter field from portal configuration.",
       argsSchema: {
-        server_url: z16.string().url().describe("Base URL of the CKAN server"),
-        rows: z16.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z17.string().url().describe("Base URL of the CKAN server"),
+        rows: z17.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => {
@@ -4821,7 +4955,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.72"
+    version: "0.4.76"
   });
 }
 function registerAll(server2) {
@@ -4835,6 +4969,7 @@ function registerAll(server2) {
   registerAnalyzeTools(server2);
   registerCatalogStatsTools(server2);
   registerSparqlTools(server2);
+  registerPortalDiscoveryTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }