@aborruso/ckan-mcp-server 0.4.123 → 0.4.125

package/EXAMPLES.md

@@ -160,34 +160,18 @@ ckan_get_mqa_quality({
 })
 ```
 
-Returns quality score and detailed metrics from data.europa.eu MQA (Metadata Quality Assurance) system:
-- Overall score (max 405 points)
-- Accessibility (URL status, download availability)
-- Reusability (license, contact point, publisher)
-- Interoperability (format, media type)
-- Findability (keywords, category, spatial/temporal coverage)
+Returns the quality score from the data.europa.eu MQA (Metadata Quality Assessment), [methodology v2](https://data.europa.eu/mqa/methodology):
+- Final score on a 0-7.5 scale and its band (Sufficient < 2.5 ≤ Good < 5 ≤ Excellent)
+- Dataset score, distribution average and data service average
+- The failing metrics with the largest gain on the final score (DCAT-AP property, weight, how many distributions fail it)
 
-**Note**: Only works with dati.gov.it datasets. Uses the `identifier` field (or falls back to `name`) to query the European MQA API.
+`ckan_get_mqa_quality_details` lists every failing metric grouped by FAIR dimension (findability, accessibility, interoperability, reusability).
 
-## USA Examples - data.gov
+**Note**: Only works with dati.gov.it datasets. Uses the `identifier` field (or falls back to `name`) to query the European MQA API. Datasets that data.europa.eu has not re-evaluated with v2 yet are reported with the previous methodology (405-point scale), labelled as such.
 
-### Search government datasets
-```typescript
-ckan_package_search({
-  server_url: "https://catalog.data.gov",
-  q: "climate change",
-  rows: 20
-})
-```
+## USA - data.gov
 
-### 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,152 @@
 # LOG
 
+## 2026-09-23
+
+### v0.4.125 - MQA scores on the new data.europa.eu methodology
+
+Ships #549 (closes #548). For a caller: `ckan_get_mqa_quality` and `ckan_get_mqa_quality_details` report the MQA v2 score (0-7.5, band, failing metrics by gain) instead of printing v2 numbers on the old 405 scale or failing with "identifier not aligned"; datasets not yet re-evaluated get the previous-methodology score, labelled. The MQA tools work again on the Cloudflare Worker. **BREAKING** for JSON consumers of the two MQA tools: compact shape with `methodology`, `metricsVersion`, `score`, `maxScore`.
+
+### MQA tools follow the data.europa.eu methodology v2 (#548)
+
+- data.europa.eu switched the MQA to a new methodology (DCAT-AP 3, weights 1/0.5/0.25, 0-7.5 scale, four FAIR dimensions, no Contextuality, SHACL not scored). The dataset cache now serves only v2 and answers `404 No v2 metrics found` for datasets not yet re-evaluated: on day one, 1,051 of 61,897 dati.gov.it datasets.
+- Both MQA tools were broken: re-evaluated datasets printed `6.5/405` and `Accessibility 2.25/100`, the JSON of a 24-distribution dataset exceeded 50k and came back `{_truncated}`; the others failed with a wrong "identifier not aligned" error.
+- Now: v2 payload parsed directly — `datasetFinal`/7.5 with band, dataset/distribution/data service scores, failing metrics aggregated across distributions ("21 of 24") and ordered by their exact gain on the final score. Checked live: score + sum of gains = 7.5.
+- `result: null` (test not run, e.g. no URL) counts as failing, as it does in the official score; found only on the live payload.
+- No v2 yet → previous-methodology scores from the metrics endpoint, labelled; refused if the graph already carries v2-scale numbers.
+- MQA tools were already broken on the Worker (`The 'cache' field on 'RequestInitializerDict' is not implemented`, axios fetch adapter): the cache call now goes through `safeFetch` like the metrics call. Verified with `wrangler dev` and the Node HTTP server.
+- `DQV of dataset not found` and `No v2 metrics found` now give different errors. JSON output is compact (`methodology`, `metricsVersion`, `maxScore`), never the raw payload. OpenSpec change `update-mqa-methodology-v2`.
+
+## 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.

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,
@@ -1376,6 +1398,14 @@ var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
   "dei",
   "degli",
   "delle",
+  // elided forms: `dell'aria` tokenises to `dell` + `aria`
+  "dell",
+  "nell",
+  "dall",
+  "sull",
+  "all",
+  "coll",
+  "quell",
   "il",
   "lo",
   "la",
@@ -1444,9 +1474,16 @@ var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
   "these",
   "those"
 ]);
+var SOLR_OPERATORS = /* @__PURE__ */ new Set(["AND", "OR", "NOT"]);
 var extractQueryTerms = (query) => {
-  const raw = query.normalize("NFC").match(/[\p{L}\p{N}]+/gu) ?? [];
+  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;
@@ -1454,18 +1491,15 @@ var extractQueryTerms = (query) => {
   }).map((token) => token.toLowerCase());
   return Array.from(new Set(terms));
 };
-var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var termPattern = (term) => new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(term.normalize("NFC"))}(?![\\p{L}\\p{N}])`, "iu");
-var normalizeForMatch = (text) => text.normalize("NFC").toLowerCase().replace(/_/g, " ");
-var textMatchesTerms = (text, terms) => {
-  if (!text || terms.length === 0) return false;
-  const normalized = normalizeForMatch(text);
-  return terms.some((term) => termPattern(term).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 normalized = normalizeForMatch(text);
-  return terms.filter((term) => termPattern(term).test(normalized)).length;
+  const words = wordsOf(text);
+  return terms.filter((term) => words.some((word) => termMatchesWord(term.normalize("NFC"), word))).length;
 };
 var scoreTextField = (text, terms, weight) => {
   const matched = countMatchingTerms(text, terms);
@@ -1483,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 || "";
@@ -1491,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,
@@ -1506,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) => {
@@ -1804,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 {
@@ -2084,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) }]
           };
@@ -2244,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"
@@ -2273,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
@@ -2302,27 +2347,22 @@ Typical workflow: ckan_find_relevant_datasets \u2192 ckan_package_show (inspect
           params.query,
           parserOverride
         );
-        const searchResult = await makeCkanRequest(
-          params.server_url,
-          "package_search",
-          {
-            q: effectiveQuery,
-            rows,
-            start: 0
-          }
-        );
-        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;
@@ -2342,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
         };
@@ -2412,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}
 `;
@@ -3024,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({
@@ -3457,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
         };
@@ -4016,7 +4061,6 @@ Typical workflow: ckan_group_search \u2192 ckan_group_show (get details) \u2192
 
 // src/tools/quality.ts
 import { z as z8 } from "zod";
-import axios2 from "axios";
 var MQA_API_BASE = "https://data.europa.eu/api/mqa/cache/datasets";
 var MQA_METRICS_BASE = "https://data.europa.eu/api/hub/repo/datasets";
 var ALLOWED_MQA_HOSTS = /* @__PURE__ */ new Set(["dati.gov.it", "www.dati.gov.it"]);
@@ -4306,338 +4350,302 @@ function findNonMaxDimensions(scores) {
   });
   return nonMax;
 }
-async function fetchMqaQuality(serverUrl, datasetId) {
-  const dataset = await makeCkanRequest(
-    serverUrl,
-    "package_show",
-    { id: datasetId }
-  );
-  const baseIdentifier = dataset.identifier || dataset.name;
-  const candidates = buildMqaIdCandidates(baseIdentifier);
-  if (candidates.length === 0) {
-    throw new Error("Dataset identifier is empty; cannot query MQA API");
-  }
-  for (const europeanId of candidates) {
-    const mqaUrl = `${MQA_API_BASE}/${europeanId}`;
-    const metricsUrl = `${MQA_METRICS_BASE}/${europeanId}/metrics`;
-    try {
-      const response = await axios2.get(mqaUrl, {
-        timeout: 3e4,
-        headers: {
-          "User-Agent": "CKAN-MCP-Server/1.0"
-        }
-      });
-      let metricsPayload;
-      try {
-        const metricsResponse = await safeFetch(metricsUrl, {
-          headers: {
-            "User-Agent": "CKAN-MCP-Server/1.0"
-          }
-        }, { httpsOnly: true });
-        if (!metricsResponse.ok) {
-          throw new Error(`MQA metrics error: ${metricsResponse.status} ${metricsResponse.statusText}`);
-        }
-        try {
-          metricsPayload = await metricsResponse.json();
-        } catch {
-          metricsPayload = await metricsResponse.text();
-        }
-      } catch (metricsError) {
-        if (metricsError instanceof Error) {
-          throw new Error(`MQA metrics error: ${metricsError.message}`);
-        }
-        throw metricsError;
-      }
-      const scores = extractMetricsScores(metricsPayload);
-      const resultEntry = response.data?.result?.results?.[0];
-      const portalId = resultEntry?.info?.["dataset-id"] || europeanId;
-      const breakdown = {
-        scores,
-        nonMaxDimensions: findNonMaxDimensions(scores),
-        metricsUrl,
-        mqaUrl,
-        portalId
-      };
-      return {
-        mqa: response.data,
-        metrics: metricsPayload,
-        breakdown
-      };
-    } catch (error) {
-      if (axios2.isAxiosError(error)) {
-        if (error.response?.status === 404) {
-          continue;
-        }
-        throw new Error(`MQA API error: ${error.message}`);
-      }
-      throw error;
+var V2_MAX_SCORE = 7.5;
+var V1_MAX_SCORE = 405;
+var V2_DIMENSIONS = ["findability", "accessibility", "interoperability", "reusability"];
+var V1_NOTE = "Not yet re-evaluated with MQA methodology v2: scores come from the previous MQA methodology (405-point scale, five dimensions).";
+var PROPERTY_PREFIXES = [
+  ["http://purl.org/dc/terms/", "dct:"],
+  ["http://www.w3.org/ns/dcat#", "dcat:"],
+  ["http://www.w3.org/ns/adms#", "adms:"],
+  ["http://xmlns.com/foaf/0.1/", "foaf:"],
+  ["http://data.europa.eu/r5r/", "dcatap:"]
+];
+function shortProperty(uri) {
+  for (const [namespace, prefix] of PROPERTY_PREFIXES) {
+    if (uri.startsWith(namespace)) {
+      return prefix + uri.slice(namespace.length);
     }
   }
-  throw new Error(
-    `Quality metrics not found or identifier not aligned on data.europa.eu. Tried: ${candidates.join(", ")}. Check the dataset quality page on data.europa.eu to confirm the identifier (it may include a '~~1' suffix) or verify alignment on dati.gov.it (quality may be marked as 'Non disponibile o identificativo non allineato').`
-  );
+  return uri;
 }
-async function getMqaQuality(serverUrl, datasetId) {
-  const result = await fetchMqaQuality(serverUrl, datasetId);
-  return {
-    mqa: result.mqa,
-    breakdown: result.breakdown
-  };
+function mqaBand(score) {
+  if (score >= 5) return "Excellent";
+  if (score >= 2.5) return "Good";
+  return "Sufficient";
 }
-async function getMqaQualityDetails(serverUrl, datasetId) {
-  const result = await fetchMqaQuality(serverUrl, datasetId);
-  const details = extractMetricDetails(result.metrics, result.breakdown.nonMaxDimensions);
-  return {
-    breakdown: result.breakdown,
-    details
-  };
+function round(value, digits = 3) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
 }
-function findSectionMetric(section, key) {
-  if (!Array.isArray(section)) {
-    return void 0;
-  }
-  for (const item of section) {
-    if (item && typeof item === "object" && key in item) {
-      return item[key];
-    }
+function groupScore(entities) {
+  if (entities.length === 0) {
+    return null;
   }
-  return void 0;
+  const average = entities.reduce((sum, entity) => sum + entity.score, 0) / entities.length;
+  return { count: entities.length, average: round(average) };
 }
-function metricArrayIsAvailable(metric) {
-  if (!Array.isArray(metric)) {
-    return void 0;
+function parseMqaV2(entry, links) {
+  const dataset = entry.dataset;
+  if (!dataset || typeof dataset.score !== "number") {
+    throw new Error("Unexpected MQA payload: missing dataset score");
   }
-  const byName = /* @__PURE__ */ new Map();
-  for (const entry of metric) {
-    if (!entry || typeof entry !== "object") {
-      continue;
-    }
-    const name = entry.name;
-    const percentage = entry.percentage;
-    if (typeof name === "string" && typeof percentage === "number") {
-      byName.set(name.toLowerCase(), percentage);
-    }
-  }
-  if (byName.has("yes")) {
-    return (byName.get("yes") || 0) > 0;
-  }
-  if (byName.size > 0) {
-    for (const [name, percentage] of byName.entries()) {
-      if (name.startsWith("2") && percentage > 0) {
-        return true;
+  const groups = [
+    ["dataset", [dataset]],
+    ["distribution", Array.isArray(entry.distributions) ? entry.distributions : []],
+    ["dataService", Array.isArray(entry.dataServices) ? entry.dataServices : []]
+  ];
+  const groupsPresent = groups.filter(([, entities]) => entities.length > 0).length;
+  const score = typeof entry.datasetFinal === "number" ? entry.datasetFinal : groupsPresent === 1 ? dataset.score : void 0;
+  if (score === void 0) {
+    throw new Error("Unexpected MQA payload: missing final dataset score");
+  }
+  const failing = [];
+  for (const [entity, entities] of groups) {
+    const byMetric = /* @__PURE__ */ new Map();
+    for (const item of entities) {
+      for (const metric of item.metrics ?? []) {
+        if (metric.result === 1) continue;
+        const current = byMetric.get(metric.metric);
+        if (current) {
+          current.failed += 1;
+        } else {
+          byMetric.set(metric.metric, { metric, failed: 1 });
+        }
       }
     }
-    return false;
+    for (const { metric, failed } of byMetric.values()) {
+      failing.push({
+        metric: metric.metric,
+        property: shortProperty(metric.property),
+        dimension: metric.dimension,
+        importance: metric.importance,
+        weight: metric.weight,
+        entity,
+        failed,
+        total: entities.length,
+        // The group average spans all its entities, and the final score averages the groups
+        gain: round(metric.weight * failed / entities.length / groupsPresent, 4)
+      });
+    }
   }
-  return void 0;
+  failing.sort((a, b) => b.gain - a.gain || a.metric.localeCompare(b.metric));
+  return {
+    methodology: "v2",
+    metricsVersion: typeof entry.metricsVersion === "string" ? entry.metricsVersion : "2",
+    score: round(score, 4),
+    maxScore: V2_MAX_SCORE,
+    band: mqaBand(score),
+    dataset: { score: dataset.score, maxScore: V2_MAX_SCORE },
+    distributions: groupScore(groups[1][1]),
+    dataServices: groupScore(groups[2][1]),
+    failing,
+    ...links
+  };
 }
-function metricBoolean(section, key) {
-  const metric = findSectionMetric(section, key);
-  if (typeof metric === "boolean") {
-    return metric;
-  }
-  return void 0;
+var MQA_TIMEOUT_MS = 3e4;
+function fetchMqa(url) {
+  return safeFetch(url, {
+    headers: { "User-Agent": "CKAN-MCP-Server/1.0" },
+    signal: AbortSignal.timeout(MQA_TIMEOUT_MS)
+  }, { httpsOnly: true });
 }
-function metricAvailability(section, availabilityKey, statusKey) {
-  const availabilityMetric = findSectionMetric(section, availabilityKey);
-  const availability = metricArrayIsAvailable(availabilityMetric);
-  if (availability !== void 0) {
-    return { available: availability };
-  }
-  if (statusKey) {
-    const statusMetric = findSectionMetric(section, statusKey);
-    const statusAvailable = metricArrayIsAvailable(statusMetric);
-    if (statusAvailable !== void 0) {
-      return { available: statusAvailable };
+async function fetchMetricsGraph(metricsUrl) {
+  try {
+    const response = await fetchMqa(metricsUrl);
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`);
     }
+    try {
+      return await response.json();
+    } catch {
+      return await response.text();
+    }
+  } catch (error) {
+    throw new Error(`MQA metrics error: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return void 0;
 }
-function normalizeQualityData(data) {
-  const d = data;
-  const mqaData = d?.mqa ?? data;
-  const breakdown = d?.breakdown;
-  const resultEntry = mqaData?.result?.results?.[0];
-  if (!resultEntry || typeof resultEntry !== "object") {
-    return { ...data, breakdown };
+async function fetchMqaV1(europeanId, links) {
+  const metricsUrl = `${MQA_METRICS_BASE}/${europeanId}/metrics`;
+  const notReEvaluated = `Dataset ${europeanId} is on data.europa.eu but not yet re-evaluated with MQA methodology v2, and previous-methodology metrics are not available`;
+  let metrics;
+  try {
+    metrics = await fetchMetricsGraph(metricsUrl);
+  } catch (error) {
+    throw new Error(`${notReEvaluated} (${error instanceof Error ? error.message : String(error)}).`);
+  }
+  const scores = extractMetricsScores(metrics);
+  const looksV1 = scores.contextuality !== void 0 || (scores.total ?? 0) > V2_MAX_SCORE;
+  if (!looksV1) {
+    throw new Error(`${notReEvaluated}. Try again after the next harvest.`);
   }
+  const nonMaxDimensions = findNonMaxDimensions(scores);
   return {
-    id: resultEntry.info?.["dataset-id"],
-    info: { score: resultEntry.info?.score },
-    accessibility: {
-      accessUrl: metricAvailability(resultEntry.accessibility, "accessUrlAvailability", "accessUrlStatusCode"),
-      downloadUrl: metricAvailability(resultEntry.accessibility, "downloadUrlAvailability", "downloadUrlStatusCode")
-    },
-    reusability: {
-      licence: metricAvailability(resultEntry.reusability, "licenceAvailability"),
-      contactPoint: metricBoolean(resultEntry.reusability, "contactPointAvailability") !== void 0 ? { available: metricBoolean(resultEntry.reusability, "contactPointAvailability") } : void 0,
-      publisher: metricBoolean(resultEntry.reusability, "publisherAvailability") !== void 0 ? { available: metricBoolean(resultEntry.reusability, "publisherAvailability") } : void 0
-    },
-    interoperability: {
-      format: metricAvailability(resultEntry.interoperability, "formatAvailability"),
-      mediaType: metricAvailability(resultEntry.interoperability, "mediaTypeAvailability")
+    methodology: "v1",
+    metricsVersion: "1",
+    note: V1_NOTE,
+    score: scores.total ?? null,
+    maxScore: V1_MAX_SCORE,
+    breakdown: {
+      scores,
+      nonMaxDimensions,
+      metricsUrl,
+      mqaUrl: links.mqaUrl,
+      portalId: europeanId
     },
-    findability: {
-      keyword: metricBoolean(resultEntry.findability, "keywordAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "keywordAvailability") } : void 0,
-      category: metricBoolean(resultEntry.findability, "categoryAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "categoryAvailability") } : void 0,
-      spatial: metricBoolean(resultEntry.findability, "spatialAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "spatialAvailability") } : void 0,
-      temporal: metricBoolean(resultEntry.findability, "temporalAvailability") !== void 0 ? { available: metricBoolean(resultEntry.findability, "temporalAvailability") } : void 0
-    },
-    contextuality: {
-      byteSize: metricAvailability(resultEntry.contextuality, "byteSizeAvailability"),
-      rights: metricAvailability(resultEntry.contextuality, "rightsAvailability")
-    },
-    breakdown
+    details: extractMetricDetails(metrics, nonMaxDimensions),
+    ...links
   };
 }
-function formatQualityMarkdown(data, datasetId) {
-  const normalized = normalizeQualityData(data);
-  const lines = [];
-  lines.push(`# Quality Metrics for Dataset: ${datasetId}`);
-  lines.push("");
-  if (normalized.info?.score !== void 0) {
-    lines.push(`**Overall Score**: ${normalized.info.score}/405`);
-    lines.push("");
+async function getMqaQuality(serverUrl, datasetId) {
+  const dataset = await makeCkanRequest(
+    serverUrl,
+    "package_show",
+    { id: datasetId }
+  );
+  const baseIdentifier = dataset.identifier || dataset.name;
+  const candidates = buildMqaIdCandidates(baseIdentifier);
+  if (candidates.length === 0) {
+    throw new Error("Dataset identifier is empty; cannot query MQA API");
   }
-  if (normalized.breakdown?.scores) {
-    lines.push("## Dimension Scores");
-    const scores = normalized.breakdown.scores;
-    const order = [
-      ["accessibility", "Accessibility", DIMENSION_MAX.accessibility],
-      ["findability", "Findability", DIMENSION_MAX.findability],
-      ["interoperability", "Interoperability", DIMENSION_MAX.interoperability],
-      ["reusability", "Reusability", DIMENSION_MAX.reusability],
-      ["contextuality", "Contextuality", DIMENSION_MAX.contextuality]
-    ];
-    for (const [key, label, max] of order) {
-      const value = scores[key];
-      if (typeof value === "number") {
-        const isMax = value >= max;
-        const status = isMax ? "\u2705" : "\u26A0\uFE0F";
-        lines.push(`- ${label}: ${value}/${max} ${status}${isMax ? "" : ` (max ${max})`}`);
-      }
+  for (const europeanId of candidates) {
+    const links = {
+      portalId: europeanId,
+      portalUrl: `https://data.europa.eu/data/datasets/${europeanId}/quality?locale=it`,
+      mqaUrl: `${MQA_API_BASE}/${europeanId}`
+    };
+    let response;
+    try {
+      response = await fetchMqa(links.mqaUrl);
+    } catch (error) {
+      throw new Error(`MQA API error: ${error instanceof Error ? error.message : String(error)}`);
     }
-    if (normalized.breakdown.nonMaxDimensions.length > 0) {
-      lines.push(`- Non-max dimension(s): ${normalized.breakdown.nonMaxDimensions.join(", ")}`);
-    } else if (Object.keys(scores).length > 0) {
-      lines.push("- Non-max dimension(s): none");
+    if (response.status === 404) {
+      if (/no v2 metrics/i.test(await response.text())) {
+        return fetchMqaV1(europeanId, links);
+      }
+      continue;
     }
-    lines.push("");
-  }
-  if (normalized.accessibility) {
-    lines.push("## Accessibility");
-    if (normalized.accessibility.accessUrl !== void 0) {
-      lines.push(`- Access URL: ${normalized.accessibility.accessUrl.available ? "\u2713" : "\u2717"} Available`);
+    if (!response.ok) {
+      throw new Error(`MQA API error: ${response.status} ${response.statusText}`);
     }
-    if (normalized.accessibility.downloadUrl !== void 0) {
-      lines.push(`- Download URL: ${normalized.accessibility.downloadUrl.available ? "\u2713" : "\u2717"} Available`);
+    const payload = await response.json();
+    const entry = payload?.result?.results?.[0];
+    if (!entry || typeof entry !== "object") {
+      throw new Error("Unexpected MQA payload: no result");
     }
-    lines.push("");
+    return parseMqaV2(entry, links);
   }
-  if (normalized.reusability) {
-    lines.push("## Reusability");
-    if (normalized.reusability.licence !== void 0) {
-      lines.push(`- License: ${normalized.reusability.licence.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.reusability.contactPoint !== void 0) {
-      lines.push(`- Contact Point: ${normalized.reusability.contactPoint.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.reusability.publisher !== void 0) {
-      lines.push(`- Publisher: ${normalized.reusability.publisher.available ? "\u2713" : "\u2717"} Available`);
-    }
-    lines.push("");
+  throw new Error(
+    `No MQA record on data.europa.eu for this dataset (identifier may not be aligned). Tried: ${candidates.join(", ")}. Check the dataset quality page on data.europa.eu to confirm the identifier (it may include a '~~1' suffix) or verify alignment on dati.gov.it (quality may be marked as 'Non disponibile o identificativo non allineato').`
+  );
+}
+function formatNumber(value) {
+  return String(round(value, 2));
+}
+function describeFailing(item) {
+  const scope = item.entity === "dataset" ? "dataset" : `${item.failed} of ${item.total} ${item.entity === "distribution" ? "distributions" : "data services"}`;
+  return `\`${item.property}\` (${item.metric}, ${item.importance.toLowerCase()} ${item.weight}) - ${scope}, +${formatNumber(item.gain)}`;
+}
+function pushV2Scores(lines, result) {
+  lines.push(`**Score**: ${formatNumber(result.score)}/${result.maxScore} (${result.band})`);
+  lines.push(`Methodology: MQA v2 (metrics ${result.metricsVersion}). Bands: Sufficient < 2.5 \u2264 Good < 5 \u2264 Excellent.`);
+  lines.push("");
+  lines.push("## Scores");
+  lines.push(`- Dataset: ${formatNumber(result.dataset.score)}/${result.dataset.maxScore}`);
+  if (result.distributions) {
+    lines.push(`- Distributions (${result.distributions.count}): average ${formatNumber(result.distributions.average)}/${result.maxScore}`);
   }
-  if (normalized.interoperability) {
-    lines.push("## Interoperability");
-    if (normalized.interoperability.format !== void 0) {
-      lines.push(`- Format: ${normalized.interoperability.format.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.interoperability.mediaType !== void 0) {
-      lines.push(`- Media Type: ${normalized.interoperability.mediaType.available ? "\u2713" : "\u2717"} Available`);
-    }
-    lines.push("");
+  if (result.dataServices) {
+    lines.push(`- Data services (${result.dataServices.count}): average ${formatNumber(result.dataServices.average)}/${result.maxScore}`);
   }
-  if (normalized.findability) {
-    lines.push("## Findability");
-    if (normalized.findability.keyword !== void 0) {
-      lines.push(`- Keywords: ${normalized.findability.keyword.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.findability.category !== void 0) {
-      lines.push(`- Category: ${normalized.findability.category.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.findability.spatial !== void 0) {
-      lines.push(`- Spatial: ${normalized.findability.spatial.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.findability.temporal !== void 0) {
-      lines.push(`- Temporal: ${normalized.findability.temporal.available ? "\u2713" : "\u2717"} Available`);
-    }
+  lines.push("");
+}
+function pushV1Scores(lines, result) {
+  lines.push(`> ${result.note}`);
+  lines.push("");
+  const scores = result.breakdown.scores;
+  if (typeof scores.total === "number") {
+    lines.push(`**Score**: ${scores.total}/${result.maxScore}`);
     lines.push("");
   }
-  if (normalized.contextuality) {
-    lines.push("## Contextuality");
-    if (normalized.contextuality.byteSize !== void 0) {
-      lines.push(`- Byte Size: ${normalized.contextuality.byteSize.available ? "\u2713" : "\u2717"} Available`);
+  lines.push("## Dimension Scores");
+  for (const dimension of Object.keys(DIMENSION_MAX)) {
+    const value = scores[dimension];
+    if (typeof value !== "number") continue;
+    const max = DIMENSION_MAX[dimension];
+    const isMax = value >= max;
+    lines.push(`- ${DIMENSION_LABELS[dimension]}: ${value}/${max} ${isMax ? "\u2705" : "\u26A0\uFE0F"}`);
+  }
+  lines.push("");
+}
+function pushLinks(lines, result) {
+  lines.push("---");
+  lines.push(`Portal: ${result.portalUrl}`);
+  lines.push(`MQA source: ${result.mqaUrl}`);
+  if (result.methodology === "v1") {
+    lines.push(`Metrics endpoint: ${result.breakdown.metricsUrl}`);
+  }
+}
+var TOP_FIXES = 5;
+function formatQualityMarkdown(result, datasetId) {
+  const lines = [`# Quality Metrics for Dataset: ${datasetId}`, ""];
+  if (result.methodology === "v1") {
+    pushV1Scores(lines, result);
+    if (result.breakdown.nonMaxDimensions.length > 0) {
+      lines.push(`Non-max dimension(s): ${result.breakdown.nonMaxDimensions.join(", ")}. Use ckan_get_mqa_quality_details for the reasons.`);
+      lines.push("");
     }
-    if (normalized.contextuality.rights !== void 0) {
-      lines.push(`- Rights: ${normalized.contextuality.rights.available ? "\u2713" : "\u2717"} Available`);
+  } else {
+    pushV2Scores(lines, result);
+    if (result.failing.length === 0) {
+      lines.push("All evaluated metrics are fulfilled.");
+    } else {
+      lines.push(`## Top fixes (${Math.min(TOP_FIXES, result.failing.length)} of ${result.failing.length} failing metrics, by gain on the final score)`);
+      for (const item of result.failing.slice(0, TOP_FIXES)) {
+        lines.push(`- ${describeFailing(item)}`);
+      }
+      if (result.failing.length > TOP_FIXES) {
+        lines.push("- Use ckan_get_mqa_quality_details for the full list.");
+      }
     }
     lines.push("");
   }
-  lines.push("---");
-  const portalId = normalized.breakdown?.portalId || normalized.id || datasetId;
-  lines.push(`Portal: https://data.europa.eu/data/datasets/${portalId}/quality?locale=it`);
-  lines.push(`MQA source: ${MQA_API_BASE}/${portalId}`);
-  const metricsEndpoint = normalized.breakdown?.metricsUrl || `${MQA_METRICS_BASE}/${portalId}/metrics`;
-  lines.push(`Metrics endpoint: ${metricsEndpoint}`);
-  lines.push(`Tip: Use the metrics endpoint to explain score deductions (e.g., failing measurements such as knownLicence = false).`);
+  pushLinks(lines, result);
   return lines.join("\n");
 }
-function formatQualityDetailsMarkdown(data, datasetId) {
-  const lines = [];
-  const breakdown = data.breakdown;
-  lines.push(`# Quality Details for Dataset: ${datasetId}`);
-  lines.push("");
-  if (typeof breakdown.scores.total === "number") {
-    lines.push(`**Overall Score**: ${breakdown.scores.total}/405`);
-    lines.push("");
-  }
-  if (breakdown.scores) {
-    lines.push("## Dimension Scores");
-    const order = [
-      ["accessibility", DIMENSION_MAX.accessibility],
-      ["findability", DIMENSION_MAX.findability],
-      ["interoperability", DIMENSION_MAX.interoperability],
-      ["reusability", DIMENSION_MAX.reusability],
-      ["contextuality", DIMENSION_MAX.contextuality]
-    ];
-    for (const [key, max] of order) {
-      const value = breakdown.scores[key];
-      if (typeof value === "number") {
-        const status = value >= max ? "\u2705" : "\u26A0\uFE0F";
-        lines.push(`- ${DIMENSION_LABELS[key]}: ${value}/${max} ${status}${value >= max ? "" : ` (max ${max})`}`);
-      }
+function formatQualityDetailsMarkdown(result, datasetId) {
+  const lines = [`# Quality Details for Dataset: ${datasetId}`, ""];
+  if (result.methodology === "v1") {
+    pushV1Scores(lines, result);
+    lines.push("## Non-max Reasons");
+    if (result.breakdown.nonMaxDimensions.length === 0) {
+      lines.push("- All dimensions are at max score.");
+    }
+    for (const dimension of result.breakdown.nonMaxDimensions) {
+      const reasons = result.details.reasons[dimension] || [];
+      lines.push(`- ${DIMENSION_LABELS[dimension]}: ${reasons.length > 0 ? reasons.join("; ") : "no failing flags detected in metrics payload"}`);
     }
     lines.push("");
-  }
-  lines.push("## Non-max Reasons");
-  if (breakdown.nonMaxDimensions.length === 0) {
-    lines.push("- All dimensions are at max score.");
   } else {
-    for (const dimension of breakdown.nonMaxDimensions) {
-      const reasons = data.details.reasons[dimension] || [];
-      if (reasons.length === 0) {
-        lines.push(`- ${DIMENSION_LABELS[dimension]}: no failing flags detected in metrics payload`);
-      } else {
-        lines.push(`- ${DIMENSION_LABELS[dimension]}: ${reasons.join("; ")}`);
+    pushV2Scores(lines, result);
+    if (result.failing.length === 0) {
+      lines.push("All evaluated metrics are fulfilled.");
+      lines.push("");
+    }
+    for (const dimension of V2_DIMENSIONS) {
+      const items = result.failing.filter((item) => item.dimension === dimension);
+      if (items.length === 0) continue;
+      lines.push(`## ${DIMENSION_LABELS[dimension]}`);
+      for (const item of items) {
+        lines.push(`- ${describeFailing(item)}`);
       }
+      lines.push("");
     }
+    lines.push("Gain = increase of the final score if every listed entity fulfilled the metric.");
+    lines.push("");
   }
-  lines.push("");
-  lines.push("---");
-  const portalId = breakdown.portalId || datasetId;
-  lines.push(`Portal: https://data.europa.eu/data/datasets/${portalId}/quality?locale=it`);
-  lines.push(`MQA source: ${MQA_API_BASE}/${portalId}`);
-  lines.push(`Metrics endpoint: ${breakdown.metricsUrl || `${MQA_METRICS_BASE}/${portalId}/metrics`}`);
+  pushLinks(lines, result);
   return lines.join("\n");
 }
 function registerQualityTools(server) {
@@ -4645,7 +4653,7 @@ function registerQualityTools(server) {
     "ckan_get_mqa_quality",
     {
       title: "Get MQA Quality Score",
-      description: "Get MQA (Metadata Quality Assurance) quality metrics for a dataset on dati.gov.it. Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability, contextuality) from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_package_show (get dataset ID) \u2192 ckan_get_mqa_quality \u2192 ckan_get_mqa_quality_details (for non-max dimensions)",
+      description: "Get MQA (Metadata Quality Assessment) quality score for a dataset on dati.gov.it from data.europa.eu. Returns the final score on the 0-7.5 scale of MQA methodology v2 with its band (Sufficient/Good/Excellent), dataset, distribution and data service scores, and the failing metrics with the largest gain. Datasets not yet re-evaluated fall back to the previous methodology (405 scale), labelled as such. Only works with dati.gov.it server. Typical workflow: ckan_package_show (get dataset ID) \u2192 ckan_get_mqa_quality \u2192 ckan_get_mqa_quality_details (full list of failing metrics)",
       inputSchema: z8.object({
         server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
         dataset_id: z8.string().describe("Dataset ID or name"),
@@ -4696,7 +4704,7 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
     "ckan_get_mqa_quality_details",
     {
       title: "Get MQA Quality Details",
-      description: "Get detailed MQA (Metadata Quality Assurance) quality reasons for a dataset on dati.gov.it. Returns dimension scores, non-max reasons, and raw MQA flags from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_get_mqa_quality (get overview scores) \u2192 ckan_get_mqa_quality_details (inspect failing metrics)",
+      description: "Get detailed MQA (Metadata Quality Assessment) quality reasons for a dataset on dati.gov.it. Lists every failing metric grouped by FAIR dimension, with DCAT-AP property, weight, how many distributions fail it and its gain on the final score (methodology v2); previous-methodology datasets get non-max reasons. Only works with dati.gov.it server. Typical workflow: ckan_get_mqa_quality (get overview scores) \u2192 ckan_get_mqa_quality_details (inspect failing metrics)",
       inputSchema: z8.object({
         server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
         dataset_id: z8.string().describe("Dataset ID or name"),
@@ -4725,7 +4733,7 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
         };
       }
       try {
-        const details = await getMqaQualityDetails(server_url, dataset_id);
+        const details = await getMqaQuality(server_url, dataset_id);
         const format = response_format || "markdown" /* MARKDOWN */;
         const output = format === "json" /* JSON */ ? truncateJson(details) : truncateText(addDemoFooter(formatQualityDetailsMarkdown(details, dataset_id)));
         return {
@@ -5192,10 +5200,10 @@ ${error instanceof Error ? error.message : String(error)}`;
 
 // src/tools/portal-discovery.ts
 import { z as z11 } from "zod";
-import axios3 from "axios";
+import axios2 from "axios";
 var DATASHADES_URL = "https://datashades.info/api/portal/list";
 async function fetchPortals() {
-  const resp = await axios3.get(DATASHADES_URL, {
+  const resp = await axios2.get(DATASHADES_URL, {
     timeout: 15e3,
     headers: { "User-Agent": "CKAN-MCP-Server/1.0" }
   });
@@ -5927,7 +5935,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.123"
+    version: "0.4.125"
   });
 }
 function registerAll(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.123",
+  "version": "0.4.125",
   "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",