@aborruso/ckan-mcp-server 0.4.122 → 0.4.124

package/EXAMPLES.md

@@ -169,25 +169,9 @@ Returns quality score and detailed metrics from data.europa.eu MQA (Metadata Qua
 
 **Note**: Only works with dati.gov.it datasets. Uses the `identifier` field (or falls back to `name`) to query the European MQA API.
 
-## USA Examples - data.gov
+## USA - data.gov
 
-### Search government datasets
-```typescript
-ckan_package_search({
-  server_url: "https://catalog.data.gov",
-  q: "climate change",
-  rows: 20
-})
-```
-
-### Datasets by tag
-```typescript
-ckan_package_search({
-  server_url: "https://catalog.data.gov",
-  q: "tags:health",
-  rows: 20
-})
-```
+`catalog.data.gov` stopped being a CKAN portal in 2025: Data.gov now serves its catalog through a different API (`api.gsa.gov/technology/datagov/v4`, key required, not CKAN-compatible). A call to it returns an error that says so. See [#540](https://github.com/ondata/ckan-mcp-server/issues/540).
 
 ## CKAN Demo Examples
 

package/LOG.md

@@ -1,7 +1,193 @@
 # LOG
 
+## 2026-09-06
+
+### v0.4.124 - search that answers the question that was asked
+
+Ships #542, #543, #544 and #545. For a caller: a query naming a place or an organisation
+now returns that place's datasets instead of any dataset on the topic; `catalog.data.gov`
+says where its data went instead of failing with "Unknown error"; `OR`, `AND` and `NOT`
+are treated as operators rather than words to score.
+
+### Two gate cases for the strict pass, and one that was passing for free
+
+The `mm=100%` pass added in #544 was verified by hand, so nothing stopped it from
+regressing. Two cases now cover it: a boolean query must skip the strict pass
+(`all_terms_results: null`), and a query no dataset satisfies in full must still be
+answered by the fill pass (`all_terms_results: 0`, results returned).
+
+Checking that they fail on the defects they name — which is the point of this file —
+found that the second one did not. It asserted `total_results` and `all_terms_results`
+but never that any result came back, so a build where the strict pass emptied the answer
+passed it. `returned_min` was added: a tool can report thousands of matches and hand back
+an empty list, and those are different claims. Both cases now fail on the broken build and
+pass on the fixed one.
+
+Also added `field_equals`, an exact check on any payload field, and `field_min`, a floor.
+The split came from review: pinning the Milano case at exactly 327 matching datasets broke
+the file's own rule that thresholds survive catalog drift, so counts that track the catalog
+are floors now, while `null` and `0` stay equalities — they are behaviours, not counts.
+`field_equals` also requires the field to be present, or a response that stopped emitting
+`all_terms_results` would read as an explicit null and pass.
+
+16 cases, 16 passing.
+
+### #539: the window is the lever, not the score
+
+The issue proposed IDF for the tie at 9.7 on `defibrillatori Comune di Lecce`. Prototyped
+on the real 50 candidates the tool fetches, IDF alone makes it worse — the Lecce dataset
+drops out of the top three, since `lecce` is rarer than `comune` in that set and the
+"patrocini" datasets carry it in every field. Two other things do the work, and both are
+smaller than a ranking model:
+
+- `mm=100%`. It is on CKAN's `VALID_SOLR_PARAMETERS` and works on every portal tried
+  (dati.gov.it, Milano, Toronto, Zurigo); with a wrapped query it is ignored without error.
+  It asks Solr for datasets carrying every term, matched with Solr's own stemming across
+  `qf`, and changes the candidate window itself: the Lecce query returns exactly one
+  dataset; `qualità dell'aria Milano`, whose default top 50 contained no Milan dataset at
+  all, returns the Comune di Milano reports first; `incidenti stradali Palermo` returns 20,
+  all Palermo. The strict pass runs first and the default pass fills in when it is short;
+  strict candidates earn a `coverage` bonus (weight 4) shown in the breakdown.
+- light stemming in the local matcher: `defibrillatore` in the tag and `defibrillatori` in
+  the query were strangers to the whole-word regex, and that tag score was the whole
+  difference. One final vowel stripped from words of five letters or more, whole-word
+  comparison kept. Elided articles (`dell'aria` → `dell`) join the stopwords.
+
+Native dati.gov.it API against the MCP server, same text:
+
+| query | native API, top 3 | MCP `find_relevant_datasets`, top 3 |
+|---|---|---|
+| defibrillatori Comune di Lecce | Mussolente, Desio, Lecce (679) | **Lecce 14.4**, then patrocini 9.7 |
+| qualità dell'aria Milano | Marche, Campania, Sicilia (2401) | three Comune di Milano reports (327 with every term) |
+| incidenti stradali Palermo | Lombardia, Palermo, Lombardia (320) | three Comune di Palermo datasets (20 with every term) |
+| aria OR acqua (Milano) | 0 — dismax swallows the OR | 87, sent as `text:(aria OR acqua)` |
+
+Cost: one extra call per ranked search, the strict pass; the default pass still runs so
+`total_results` keeps its meaning, as a `rows=0` count when the strict pass already filled
+the limit. Boolean and fielded queries make one call, as before. A portal that rejects
+`mm` falls back to the default pass alone. The gate asserts terms and margin now (`terms_equal`, `margin_min`): Lecce leads
+by ≥ 2 with terms `[defibrillatori, comune, lecce]`, and the Milano case requires a Comune
+di Milano report first. 550 tests, 14/14 smoke. OpenSpec change `rank-on-full-coverage`.
+
+### catalog.data.gov has not been CKAN since 2025; we said otherwise in twelve places
+
+Checking the two configured portals that answered nothing yesterday. `dati.arpae.it` is
+still CKAN and still at the same address, just down most of the time — site-wide 500s,
+not ours to fix (#541). `catalog.data.gov` is a different story: Data.gov replaced its
+CKAN catalog with a Flask/OpenSearch application in 2025 and the CKAN-compatible
+endpoints — `catalog-old.data.gov`, the `api.gsa.gov/…/v3` gateway — now all redirect to
+the new host, which answers 404 to any CKAN request. The replacement API (`…/v4/search`)
+needs a key, paginates with a cursor and, per GSA, will not support CKAN filter syntax.
+47 calls reached it through the public deployment since April and got
+`CKAN API error (404): Unknown error`, while README, EXAMPLES, CLAUDE.md, the skill and a
+tool description all listed it as a working CKAN portal (#540).
+
+Fixed the part that is ours: `portals.json` entries can carry a `migrated` block, the
+`catalog-data-gov` entry is kept and marked so the hint keeps firing, `CkanApiError` now
+carries the portal URL, and `formatCkanError` returns the migration notice for such a
+portal whatever the status — no status-based hint can be right for it. `ckan_status_show`
+routes its error through the formatter too. Every document that presented it as CKAN now
+says the opposite; the skill's country table says "NOT CKAN since 2025", which is what
+stops an LLM client from trying. A v4 adapter is a separate proposal.
+
+The gate gained a case that calls the live portal and expects the notice; 13/13.
+OpenSpec change `mark-migrated-portals` on `ckan-error-hints`. 542 tests, 6 added.
+
+Left alone: `docs/DECISIONS.md` still describes the parser probe replaced in #534 and says
+configured portals skip it. Stale independently of this change; flagged, not touched.
+
 ## 2026-09-05
 
+### A release gate that asserts which dataset comes back
+
+Three releases went out today, two of them to repair the one before. The verification in
+between was a sequence of commands rebuilt from memory each time, so it covered something
+different on each pass — and what it always covered was result counts. v0.4.122 shipped
+with counts verified and the ranking broken, because "22 results" and "the right dataset
+first" are different claims and only the second is what a caller asked for.
+
+`npm run smoke` is that check as a command. Twelve known-answer cases from real telemetry
+in `tests/smoke/cases.json`, each asserting which dataset must come back and carrying the
+regression it guards; the runner starts the built server over HTTP, calls each tool the
+way a client does, and exits non-zero on the first failure.
+
+Checked against the defects it claims to catch: reintroducing the v0.4.121 wrapping rule
+fails 4 of 12, and removing the parser probe from `ckan_find_relevant_datasets` — the
+v0.4.122 regression — fails the case requiring the two search tools to agree. Wired into
+the release workflow in `CLAUDE.md` (step 2, before the tag) and the checklist in
+`docs/DEPLOYMENT.md`.
+
+Two things the gate needed on the way:
+
+- the JSON format never exposed the query that actually ran, while Markdown has always
+  shown it. `effective_query` now appears in `ckan_package_search` JSON output when the
+  server rewrote the query, and is absent when it did not.
+- relevance scores summed unrounded fractions, printing totals like `8.299999999999999`.
+
+Known and not fixed: the ranking model weights every query term equally, so on
+`defibrillatori Comune di Lecce` three datasets tie at 9.7 and the right one leads on
+Solr order rather than on score. Making the `tags` field proportional like the others was
+tried and reverted — it promotes "Elenco patrocini Comune di Lecce", whose tags carry two
+of the three terms against the defibrillator dataset's one. The fix is term specificity,
+a design change, not a patch.
+
+### v0.4.123 - relevance scoring and shared parser probe
+
+Ships #536: field scoring by share of matched terms, Italian stopwords with acronyms preserved, Unicode-aware term matching, a wider candidate window, the parser probe shared with `ckan_find_relevant_datasets`, and accent-safe filters in `ckan_organization_search` and `ckan_tag_list`. `openspec/specs/ckan-search/spec.md` rewritten around the query-building path.
+
+### Relevance scoring: three defects that only became visible once search worked
+
+Testing v0.4.122 through an MCP client, not curl, showed `ckan_find_relevant_datasets`
+answering its own documented example badly. `defibrillatori Comune di Lecce` on
+dati.gov.it used to return the catalog's only Lecce dataset — because the search
+returned exactly one result. With recall restored it returns 679, and the top three
+became Trento, Martina Franca and Desio while the Lecce dataset fell out of the window.
+
+The wrapping fix did not cause this; it removed the cover. Three defects, all older:
+
+- `scoreTextField` awarded the **whole** field weight when **any** query term matched.
+  "Comune di Martina Franca" and "Comune di Lecce" both scored a full holder match, so
+  the right dataset could not outrank the wrong ones. It now scores the share of terms
+  the field carries.
+- the stopword list was English-only, so `di` counted as a term: "Provincia Autonoma
+  **di** Trento" earned a full holder match on a query asking for Lecce. Italian
+  stopwords added.
+- `\b` is ASCII-only in JavaScript, so a term ending in an accented letter never found
+  its word boundary: `mobilità` scored 0 against "mobilità urbana", `qualità` against
+  "qualità dell'aria". On a catalog that is mostly not in English this silently sank
+  every accented query. Replaced with Unicode lookarounds.
+
+Looking for more of the same family turned up three more, all cases of a local filter
+running over a truncated or wrongly-normalised set:
+
+- `ckan_find_relevant_datasets` never called the parser probe. `portals.json` used to
+  cover it; removing `force_text_field` left it sending boolean queries to the parser that
+  ignores them. On dati.comune.milano.it `aria OR acqua` returned 0 there against 87 from
+  `ckan_package_search`. Same probe now applies to both.
+- `ckan_organization_search` builds a Solr wildcard, which bypasses the analysis chain, so
+  the pattern must be pre-normalised the way CKAN builds a name slug. It lowercased but did
+  not fold accents: `città` returned 0 while `citta` matched 135 datasets.
+- `ckan_tag_list` applied `tag_query` after faceting, with `facet.limit` set to the
+  caller's `limit`. On dati.gov.it 53 tags contain "citta" and none is in the top 100, so
+  the filter answered "no tags" while they existed. The facet is now widened when a filter
+  is given.
+
+`openspec/specs/ckan-search/spec.md` described the parser as a property of
+`ckan_package_search` alone, which is what let the second caller go unnoticed — and after
+yesterday it was also wrong, still describing the per-portal default that was removed.
+Rewritten as a property of the query-building path, naming every tool that shares it.
+
+Also raised the candidate window to at least 50: the local ranking only sees what Solr
+returns first, and `limit: 3` shrank it to 15 — enough when a search returned a handful
+of results, not enough now.
+
+`defibrillatori Comune di Lecce` puts the Lecce dataset first again. 532 tests, 5 added.
+
+How it was missed: yesterday's verification checked result **counts** through
+`ckan_package_search`, never the ranked output of `ckan_find_relevant_datasets` — the
+third most used tool in the telemetry, and the second caller of `resolveSearchQuery`.
+Counting results proves recall, not usefulness.
+
 ### v0.4.122 - Solr parser fix
 
 Ships #534: the `text:(...)` wrapper is reserved for the queries dismax cannot serve, the escaping preserves unary operators and balanced grouping, and the parser probe measures two terms taken from the catalog on every portal. `force_text_field` is gone from `portals.json`.

package/dist/index.js

@@ -80,7 +80,11 @@ var portals_default = {
       api_url: "https://catalog.data.gov",
       api_url_aliases: [
         "http://catalog.data.gov"
-      ]
+      ],
+      migrated: {
+        notice: "catalog.data.gov stopped being a CKAN portal in 2025. Data.gov now serves its catalog through a different API (api.gsa.gov/technology/datagov/v4, key required, not CKAN-compatible), which this server does not speak.",
+        docs_url: "https://resources.data.gov/catalog-api/"
+      }
     },
     {
       id: "open-canada",
@@ -193,6 +197,14 @@ function getPortalConfig(serverUrl) {
   });
   return portal || null;
 }
+function getPortalMigration(serverUrl) {
+  const hostname = extractHostname(serverUrl);
+  if (!hostname) return null;
+  const portal = portals_default.portals.find(
+    (p) => [p.api_url, ...p.api_url_aliases || []].some((url) => extractHostname(url) === hostname)
+  );
+  return portal?.migrated ?? null;
+}
 function getPortalSearchConfig(serverUrl) {
   const portal = getPortalConfig(serverUrl);
   const defaults = portals_default.defaults?.search || {};
@@ -454,18 +466,26 @@ function getRateLimiter() {
 var CkanApiError = class extends Error {
   status;
   action;
-  constructor(message, status, action) {
+  /** The portal the request went to, as the caller wrote it: lets the hint know its origin. */
+  serverUrl;
+  constructor(message, status, action, serverUrl) {
     super(message);
     this.name = "CkanApiError";
     this.status = status;
     this.action = action;
+    this.serverUrl = serverUrl;
   }
 };
 function formatCkanError(error, _toolName) {
   if (!(error instanceof CkanApiError)) {
     return error instanceof Error ? error.message : String(error);
   }
-  const { status, action, message } = error;
+  const { status, action, message, serverUrl } = error;
+  const migration = serverUrl ? getPortalMigration(serverUrl) : null;
+  if (migration) {
+    return `${message}
+\u2192 ${migration.notice} See ${migration.docs_url}`;
+  }
   let hint = "";
   if (status === 404) {
     if (action === "datastore_search_sql") {
@@ -972,15 +992,15 @@ async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
         clearTimeout(timeoutId);
       }
       if (!response.ok) {
-        throw new CkanApiError(`CKAN API error (${response.status}): ${response.statusText}`, response.status, action);
+        throw new CkanApiError(`CKAN API error (${response.status}): ${response.statusText}`, response.status, action, serverUrl);
       }
       const declaredLength = Number(response.headers.get("content-length"));
       if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
-        throw new CkanApiError(`Response too large (${declaredLength} bytes)`, void 0, action);
+        throw new CkanApiError(`Response too large (${declaredLength} bytes)`, void 0, action, serverUrl);
       }
       const buffer = await response.arrayBuffer();
       if (buffer.byteLength > MAX_RESPONSE_BYTES) {
-        throw new CkanApiError(`Response too large (${buffer.byteLength} bytes)`, void 0, action);
+        throw new CkanApiError(`Response too large (${buffer.byteLength} bytes)`, void 0, action, serverUrl);
       }
       const headers = {};
       response.headers.forEach((headerValue, headerKey) => {
@@ -1014,7 +1034,8 @@ async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
       throw new CkanApiError(
         `CKAN API returned success=false for action "${action}".`,
         void 0,
-        action
+        action,
+        serverUrl
       );
     }
   } catch (error) {
@@ -1025,7 +1046,7 @@ async function makeCkanRequest(serverUrl, action, params = {}, opts = {}) {
         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);
+        throw new CkanApiError(`CKAN API error (${status}): ${errorMsg}`, status, action, serverUrl);
       } else if (axiosError.code === "ECONNABORTED") {
         throw new Error(`Request timeout connecting to ${serverUrl}`);
       } else if (axiosError.code === "ENOTFOUND") {
@@ -1359,6 +1380,7 @@ async function probePortalParser(serverUrl) {
   return needsText;
 }
 var DEFAULT_RELEVANCE_WEIGHTS = {
+  coverage: 4,
   title: 4,
   notes: 2,
   tags: 3,
@@ -1367,6 +1389,49 @@ var DEFAULT_RELEVANCE_WEIGHTS = {
   publisher: 2
 };
 var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
+  // Italian: without these, `defibrillatori Comune di Lecce` scored a full holder
+  // match against "Provincia Autonoma di Trento" on the strength of "di" alone.
+  "di",
+  "del",
+  "dello",
+  "della",
+  "dei",
+  "degli",
+  "delle",
+  // elided forms: `dell'aria` tokenises to `dell` + `aria`
+  "dell",
+  "nell",
+  "dall",
+  "sull",
+  "all",
+  "coll",
+  "quell",
+  "il",
+  "lo",
+  "la",
+  "i",
+  "gli",
+  "le",
+  "un",
+  "uno",
+  "una",
+  "e",
+  "ed",
+  "per",
+  "con",
+  "su",
+  "da",
+  "dal",
+  "dalla",
+  "nel",
+  "nella",
+  "al",
+  "alla",
+  "che",
+  "non",
+  "come",
+  "dove",
+  "sono",
   "a",
   "an",
   "the",
@@ -1409,19 +1474,37 @@ var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
   "these",
   "those"
 ]);
+var SOLR_OPERATORS = /* @__PURE__ */ new Set(["AND", "OR", "NOT"]);
 var extractQueryTerms = (query) => {
-  const matches = query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
-  const terms = matches.filter((term) => term.length > 1 && !QUERY_STOPWORDS.has(term));
+  const normalized = query.normalize("NFC");
+  const raw = normalized.match(/[\p{L}\p{N}]+/gu) ?? [];
+  const quoted = /* @__PURE__ */ new Set();
+  for (const m of normalized.matchAll(/"((?:[^"\\]|\\.)*)"/g)) {
+    for (const t of m[1].match(/[\p{L}\p{N}]+/gu) ?? []) quoted.add(t);
+  }
+  const terms = raw.filter((token) => {
+    if (SOLR_OPERATORS.has(token) && !quoted.has(token)) return false;
+    const term = token.toLowerCase();
+    if (term.length <= 1) return false;
+    if (!QUERY_STOPWORDS.has(term)) return true;
+    return token.length > 1 && token === token.toUpperCase() && token !== term;
+  }).map((token) => token.toLowerCase());
   return Array.from(new Set(terms));
 };
-var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var textMatchesTerms = (text, terms) => {
-  if (!text || terms.length === 0) return false;
-  const normalized = text.toLowerCase().replace(/_/g, " ");
-  return terms.some((term) => new RegExp(`\\b${escapeRegExp(term)}\\b`, "i").test(normalized));
+var FINAL_VOWEL = /[aeiouàèéìòù]$/u;
+var stemTerm = (word) => word.length >= 5 ? word.replace(FINAL_VOWEL, "") : word;
+var wordsOf = (text) => text.normalize("NFC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+var termMatchesWord = (term, word) => word === term || term.length >= 5 && word.length >= 5 && stemTerm(word) === stemTerm(term);
+var textMatchesTerms = (text, terms) => countMatchingTerms(text, terms) > 0;
+var countMatchingTerms = (text, terms) => {
+  if (!text || terms.length === 0) return 0;
+  const words = wordsOf(text);
+  return terms.filter((term) => words.some((word) => termMatchesWord(term.normalize("NFC"), word))).length;
 };
 var scoreTextField = (text, terms, weight) => {
-  return textMatchesTerms(text, terms) ? weight : 0;
+  const matched = countMatchingTerms(text, terms);
+  if (matched === 0) return 0;
+  return Math.round(weight * matched / terms.length * 10) / 10;
 };
 var readDcatExtra = (dataset, key) => {
   const extras = Array.isArray(dataset.extras) ? dataset.extras : [];
@@ -1434,7 +1517,7 @@ var readDcatExtra = (dataset, key) => {
   const rootValue = dataset[key];
   return typeof rootValue === "string" ? rootValue : "";
 };
-var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS) => {
+var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS, fullCoverage = false) => {
   const terms = extractQueryTerms(query);
   const titleText = dataset.title || dataset.name || "";
   const notesText = dataset.notes || "";
@@ -1442,6 +1525,7 @@ var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS
   const holderText = readDcatExtra(dataset, "holder_name");
   const publisherText = readDcatExtra(dataset, "publisher_name");
   const breakdown = {
+    coverage: fullCoverage ? weights.coverage : 0,
     title: scoreTextField(titleText, terms, weights.title),
     notes: scoreTextField(notesText, terms, weights.notes),
     tags: 0,
@@ -1457,7 +1541,9 @@ 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.holder + breakdown.publisher;
+  breakdown.total = Math.round(
+    (breakdown.coverage + breakdown.title + breakdown.notes + breakdown.tags + breakdown.organization + breakdown.holder + breakdown.publisher) * 10
+  ) / 10;
   return { total: breakdown.total, breakdown, terms };
 };
 var parseAccessServices = (resource) => {
@@ -1755,9 +1841,10 @@ function normalizePackage(pkg) {
   }
   return pkg;
 }
-function compactSearchResult(result, serverUrl) {
+function compactSearchResult(result, serverUrl, effectiveQuery) {
   return {
     count: result.count,
+    ...effectiveQuery ? { effective_query: effectiveQuery } : {},
     results: (result.results || []).map((rawPkg) => {
       const pkg = serverUrl && requiresMultilingualNormalization(serverUrl) ? normalizePackage(rawPkg) : rawPkg;
       return {
@@ -2035,7 +2122,11 @@ Typical workflow: ckan_status_show (check locale) \u2192 ckan_package_search (qu
           }
         }
         if (params.response_format === "json" /* JSON */) {
-          const compact = compactSearchResult(result, params.server_url);
+          const compact = compactSearchResult(
+            result,
+            params.server_url,
+            effectiveQuery !== params.q ? effectiveQuery : void 0
+          );
           return {
             content: [{ type: "text", text: truncateJson(compact) }]
           };
@@ -2195,7 +2286,9 @@ 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, holder=4, publisher=2
+    Default: title=4, tags=3, notes=2, organization=1, holder=4, publisher=2, coverage=4
+    coverage: bonus for datasets the portal returned with every query term required
+    (Solr mm=100%); these are fetched first, the rest fills in when they are fewer than limit
     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"
@@ -2224,7 +2317,8 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
           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 (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)")
+          publisher: z2.coerce.number().min(0).optional().describe("Weight for publisher_name match \u2014 DCAT-AP_IT dct:publisher (default 2)"),
+          coverage: z2.coerce.number().min(0).optional().describe("Bonus for datasets the portal returned with every query term required (default 4)")
         }).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
@@ -2242,33 +2336,33 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
           ...DEFAULT_RELEVANCE_WEIGHTS,
           ...params.weights ?? {}
         };
-        const rows = Math.min(Math.max(params.limit * 5, params.limit), 100);
+        const rows = Math.min(Math.max(params.limit * 5, 50), 100);
+        let parserOverride = params.query_parser;
+        if (!parserOverride && mayNeedTextWrapping(params.query)) {
+          const needsText = await probePortalParser(params.server_url);
+          if (needsText) parserOverride = "text";
+        }
         const { effectiveQuery } = resolveSearchQuery(
           params.server_url,
           params.query,
-          params.query_parser
-        );
-        const searchResult = await makeCkanRequest(
-          params.server_url,
-          "package_search",
-          {
-            q: effectiveQuery,
-            rows,
-            start: 0
-          }
+          parserOverride
         );
-        const scored = (searchResult.results || []).map((dataset) => {
-          const { total, breakdown } = scoreDatasetRelevance(
-            params.query,
-            dataset,
-            weights
-          );
-          return {
-            dataset,
-            score: total,
-            breakdown
-          };
-        });
+        const strictEligible = !effectiveQuery.includes(":") && !hasExplicitBooleanOperator(params.query);
+        const fetchCandidates = (extra) => makeCkanRequest(params.server_url, "package_search", { q: effectiveQuery, rows, start: 0, ...extra });
+        const strictResult = strictEligible ? await fetchCandidates({ mm: "100%" }).catch(() => null) : null;
+        const strictHits = strictResult?.results ?? [];
+        const fillResult = await fetchCandidates(strictHits.length >= params.limit ? { rows: 0 } : {});
+        const seen = new Set(strictHits.map((d) => d.id));
+        const fillHits = (fillResult?.results ?? []).filter((d) => !seen.has(d.id));
+        const scoreOne = (dataset, fullCoverage) => {
+          const { total, breakdown } = scoreDatasetRelevance(params.query, dataset, weights, fullCoverage);
+          return { dataset, score: total, breakdown };
+        };
+        const scored = [
+          ...strictHits.map((d) => scoreOne(d, true)),
+          ...fillHits.map((d) => scoreOne(d, false))
+        ];
+        const searchResult = fillResult;
         scored.sort((a, b) => b.score - a.score);
         const top = scored.slice(0, params.limit).map((item) => {
           const dataset = item.dataset;
@@ -2288,6 +2382,7 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
           terms: extractQueryTerms(params.query),
           weights,
           total_results: searchResult.count ?? 0,
+          all_terms_results: strictResult ? strictResult.count ?? 0 : null,
           returned: top.length,
           results: top
         };
@@ -2358,6 +2453,8 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
             markdown += `- Organization: ${dataset.breakdown.organization}
 `;
             markdown += `- Holder: ${dataset.breakdown.holder}
+`;
+            markdown += `- Coverage (every term, per the portal): ${dataset.breakdown.coverage}
 `;
             markdown += `- Publisher: ${dataset.breakdown.publisher}
 `;
@@ -2970,7 +3067,7 @@ Returns:
 
 Examples:
   - { server_url: "https://www.dati.gov.it/opendata", pattern: "toscana" }
-  - { server_url: "https://catalog.data.gov", pattern: "health" }
+  - { server_url: "https://open.canada.ca/data", pattern: "health" }
 
 Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get details) \u2192 ckan_package_search with fq="organization:name"`,
       inputSchema: z3.object({
@@ -2987,7 +3084,7 @@ Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get de
     },
     async (params) => {
       try {
-        const query = `organization:*${params.pattern.toLowerCase()}*`;
+        const query = `organization:*${stripAccents(params.pattern.toLowerCase())}*`;
         const result = await makeCkanRequest(
           params.server_url,
           "package_search",
@@ -3403,11 +3500,13 @@ Typical workflow: ckan_status_show (verify server is up) \u2192 ckan_package_sea
           structuredContent: cappedStructured(result)
         };
       } catch (error) {
+        const migrated = error instanceof CkanApiError && error.serverUrl && getPortalMigration(error.serverUrl);
+        const detail = formatCkanError(error, "ckan_status_show");
         return {
           content: [{
             type: "text",
-            text: `Server appears to be offline or not a valid CKAN instance:
-${error instanceof Error ? error.message : String(error)}`
+            text: migrated ? detail : `Server appears to be offline or not a valid CKAN instance:
+${detail}`
           }],
           isError: true
         };
@@ -3491,7 +3590,13 @@ Typical workflow: ckan_tag_list \u2192 ckan_package_search with fq="tags:tag_nam
           q: params.q,
           rows: 0,
           "facet.field": JSON.stringify(["tags"]),
-          "facet.limit": params.limit
+          // The filter runs on whatever the facet returned, so with a tag_query the
+          // facet has to be wider than the caller's limit: on dati.gov.it 53 tags
+          // contain "citta" and none is in the top 100, so asking for 100 answered
+          // "no tags" while they existed. CKAN rejects Solr's own `facet.contains`
+          // ("Invalid search parameters"), so the filtering cannot move server-side;
+          // this window is the compromise, and WIDE_FACET below is the escape hatch.
+          "facet.limit": params.tag_query ? Math.max(params.limit * 20, 500) : params.limit
         };
         if (params.fq) apiParams.fq = params.fq;
         const result = await makeCkanRequest(
@@ -3501,8 +3606,18 @@ Typical workflow: ckan_tag_list \u2192 ckan_package_search with fq="tags:tag_nam
         );
         let tags = normalizeTagFacets(result);
         if (params.tag_query) {
-          const needle = params.tag_query.toLowerCase();
-          tags = tags.filter((tag) => tag.name.toLowerCase().includes(needle));
+          const needle = stripAccents(params.tag_query.toLowerCase());
+          const matching = (candidates) => candidates.filter((tag) => stripAccents(tag.name.toLowerCase()).includes(needle));
+          tags = matching(tags);
+          if (tags.length < params.limit) {
+            const wide = await makeCkanRequest(
+              params.server_url,
+              "package_search",
+              { ...apiParams, "facet.limit": -1 }
+            );
+            tags = matching(normalizeTagFacets(wide));
+          }
+          tags = tags.sort((a, b) => b.count - a.count).slice(0, params.limit);
         }
         tags = tags.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)).slice(0, params.limit);
         if (params.response_format === "json" /* JSON */) {
@@ -5857,7 +5972,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.122"
+    version: "0.4.124"
   });
 }
 function registerAll(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.122",
+  "version": "0.4.124",
   "mcpName": "io.github.aborruso/ckan-mcp-server",
   "description": "MCP server for interacting with CKAN open data portals",
   "repository": {
@@ -28,7 +28,8 @@
     "pack:dxt": "rm -rf dxt-staging && mkdir -p dxt-staging/server && npm run build:dxt && echo '{\"type\":\"commonjs\"}' > dxt-staging/server/package.json && mkdir -p dxt-staging/server/node_modules && cp -r node_modules/undici dxt-staging/server/node_modules/ && cp manifest.json icon.png dxt-staging/ && dxt pack dxt-staging ckan-mcp-server.dxt && rm -rf dxt-staging",
     "pack:skill": "mkdir -p tmp && cd skills && zip -r ../tmp/ckan-mcp.skill ckan-mcp/ && cd ..",
     "prepack": "cp README.md .readme-full.md && cp .readme-npm.md README.md",
-    "postpack": "mv .readme-full.md README.md"
+    "postpack": "mv .readme-full.md README.md",
+    "smoke": "npm run build && node scripts/smoke.mjs"
   },
   "keywords": [
     "mcp",