@aborruso/ckan-mcp-server 0.4.124 → 0.4.126

package/EXAMPLES.md

@@ -160,14 +160,14 @@ 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)
-
-**Note**: Only works with dati.gov.it datasets. Uses the `identifier` field (or falls back to `name`) to query the European MQA API.
+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)
+
+`ckan_get_mqa_quality_details` lists every failing metric grouped by FAIR dimension (findability, accessibility, interoperability, reusability).
+
+**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.
 
 ## USA - data.gov
 

package/LOG.md

@@ -1,5 +1,31 @@
 # LOG
 
+## 2026-09-23
+
+### v0.4.126 - why MQA URL tests fail
+
+Ships #552. For a caller: `ckan_get_mqa_quality_details` now says why URL tests fail (`HTTP test: 1100 timeout ×21, no status recorded ×3`). For the project: `npm run smoke` checks the MQA tool live against data.europa.eu, so a format change there fails the release gate.
+
+### MQA: smoke gate and HTTP status of failing URL tests
+
+- `npm run smoke` gains a live MQA case (Roma `czrm-…-2023`: `methodology` v2, `maxScore` 7.5, 0 ≤ `score` ≤ 7.5) and a generic `field_max`. v0.4.124 shipped broken MQA tools with green tests because the tests read stored fixtures; the gate now asks data.europa.eu. Negative check: expecting `v1` fails the case.
+- `ckan_get_mqa_quality_details` says why URL tests fail: `HTTP test: 1100 timeout ×21, no status recorded ×3`. Codes come from the metrics graph (`http:statusCodeValue` in v2, `dqv:value` in v1; ≥1000 are piveau's own, 1100 = timeout), latest per distribution, 2xx excluded. Fetched only by the details tool and only when a URL test fails (the graph is ~570 KB); best effort, a failed fetch leaves the details intact.
+- Bug caught by the tests: boolean result nodes share the metric id, and `Number(false)` read as status code 0.
+
+### 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

package/dist/index.js

@@ -4061,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"]);
@@ -4351,338 +4350,361 @@ 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")
+    methodology: "v1",
+    metricsVersion: "1",
+    note: V1_NOTE,
+    score: scores.total ?? null,
+    maxScore: V1_MAX_SCORE,
+    breakdown: {
+      scores,
+      nonMaxDimensions,
+      metricsUrl,
+      mqaUrl: links.mqaUrl,
+      portalId: europeanId
     },
-    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")
-    },
-    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("");
+var STATUS_METRICS = /* @__PURE__ */ new Set(["accessUrlStatusCode", "downloadUrlStatusCode"]);
+var HTTP_STATUS_CODE = "http://www.w3.org/2011/http#statusCodeValue";
+function extractStatusCodes(metricsData) {
+  const latest = /* @__PURE__ */ new Map();
+  const graph = decodeMetricsPayload(metricsData)?.["@graph"];
+  for (const node of Array.isArray(graph) ? graph : []) {
+    if (!node || typeof node !== "object") continue;
+    const record = node;
+    const metricRef = record["dqv:isMeasurementOf"];
+    const metricId = typeof metricRef === "string" ? metricRef : metricRef?.["@id"];
+    if (typeof metricId !== "string") continue;
+    const metric = metricKeyFromId(metricId);
+    if (!STATUS_METRICS.has(metric)) continue;
+    const raw = record[HTTP_STATUS_CODE] !== void 0 ? Number(record[HTTP_STATUS_CODE]) : parseMetricValue(record["dqv:value"]);
+    if (typeof raw !== "number" || !Number.isInteger(raw)) continue;
+    const code = raw;
+    const target = record["dqv:computedOn"]?.["@id"];
+    const time = String(record["prov:generatedAtTime"]?.["@value"] ?? "");
+    const key = `${metric} ${typeof target === "string" ? target : ""}`;
+    const current = latest.get(key);
+    if (current && current.time > time) continue;
+    const description = typeof record["dct:description"] === "string" ? record["dct:description"] : "";
+    const label = code >= 1e3 ? `${code} ${/timeout/i.test(description) ? "timeout" : "connection error"}` : String(code);
+    latest.set(key, { metric, code, label, time });
+  }
+  const counts = /* @__PURE__ */ new Map();
+  for (const { metric, code, label } of latest.values()) {
+    if (code >= 200 && code < 300) continue;
+    const perMetric = counts.get(metric) ?? {};
+    perMetric[label] = (perMetric[label] ?? 0) + 1;
+    counts.set(metric, perMetric);
+  }
+  return counts;
+}
+async function addHttpStatus(result) {
+  const urlTests = result.failing.filter((item) => item.entity === "distribution" && STATUS_METRICS.has(item.metric));
+  if (urlTests.length === 0) return;
+  let counts;
+  try {
+    counts = extractStatusCodes(await fetchMetricsGraph(`${MQA_METRICS_BASE}/${result.portalId}/metrics`));
+  } catch {
+    return;
   }
-  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})`}`);
-      }
-    }
-    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");
-    }
-    lines.push("");
+  for (const item of urlTests) {
+    const perCode = counts.get(item.metric);
+    if (perCode) item.httpStatus = perCode;
   }
-  if (normalized.accessibility) {
-    lines.push("## Accessibility");
-    if (normalized.accessibility.accessUrl !== void 0) {
-      lines.push(`- Access URL: ${normalized.accessibility.accessUrl.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.accessibility.downloadUrl !== void 0) {
-      lines.push(`- Download URL: ${normalized.accessibility.downloadUrl.available ? "\u2713" : "\u2717"} Available`);
-    }
-    lines.push("");
+}
+async function getMqaQuality(serverUrl, datasetId, opts = {}) {
+  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.reusability) {
-    lines.push("## Reusability");
-    if (normalized.reusability.licence !== void 0) {
-      lines.push(`- License: ${normalized.reusability.licence.available ? "\u2713" : "\u2717"} Available`);
+  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.reusability.contactPoint !== void 0) {
-      lines.push(`- Contact Point: ${normalized.reusability.contactPoint.available ? "\u2713" : "\u2717"} Available`);
+    if (response.status === 404) {
+      if (/no v2 metrics/i.test(await response.text())) {
+        return fetchMqaV1(europeanId, links);
+      }
+      continue;
     }
-    if (normalized.reusability.publisher !== void 0) {
-      lines.push(`- Publisher: ${normalized.reusability.publisher.available ? "\u2713" : "\u2717"} Available`);
+    if (!response.ok) {
+      throw new Error(`MQA API error: ${response.status} ${response.statusText}`);
     }
-    lines.push("");
-  }
-  if (normalized.interoperability) {
-    lines.push("## Interoperability");
-    if (normalized.interoperability.format !== void 0) {
-      lines.push(`- Format: ${normalized.interoperability.format.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");
     }
-    if (normalized.interoperability.mediaType !== void 0) {
-      lines.push(`- Media Type: ${normalized.interoperability.mediaType.available ? "\u2713" : "\u2717"} Available`);
+    const result = parseMqaV2(entry, links);
+    if (opts.httpStatus) {
+      await addHttpStatus(result);
     }
-    lines.push("");
+    return result;
   }
-  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("");
+  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"}`;
+  let http = "";
+  if (item.httpStatus) {
+    const codes = Object.entries(item.httpStatus).sort((a, b) => b[1] - a[1]).map(([code, n]) => `${code} \xD7${n}`);
+    const unexplained = item.failed - Object.values(item.httpStatus).reduce((sum, n) => sum + n, 0);
+    if (unexplained > 0) codes.push(`no status recorded \xD7${unexplained}`);
+    http = `; HTTP test: ${codes.join(", ")}`;
   }
-  if (normalized.contextuality) {
-    lines.push("## Contextuality");
-    if (normalized.contextuality.byteSize !== void 0) {
-      lines.push(`- Byte Size: ${normalized.contextuality.byteSize.available ? "\u2713" : "\u2717"} Available`);
-    }
-    if (normalized.contextuality.rights !== void 0) {
-      lines.push(`- Rights: ${normalized.contextuality.rights.available ? "\u2713" : "\u2717"} Available`);
-    }
-    lines.push("");
+  return `\`${item.property}\` (${item.metric}, ${item.importance.toLowerCase()} ${item.weight}) - ${scope}, +${formatNumber(item.gain)}${http}`;
+}
+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}`);
   }
-  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).`);
-  return lines.join("\n");
+  if (result.dataServices) {
+    lines.push(`- Data services (${result.dataServices.count}): average ${formatNumber(result.dataServices.average)}/${result.maxScore}`);
+  }
+  lines.push("");
 }
-function formatQualityDetailsMarkdown(data, datasetId) {
-  const lines = [];
-  const breakdown = data.breakdown;
-  lines.push(`# Quality Details for Dataset: ${datasetId}`);
+function pushV1Scores(lines, result) {
+  lines.push(`> ${result.note}`);
   lines.push("");
-  if (typeof breakdown.scores.total === "number") {
-    lines.push(`**Overall Score**: ${breakdown.scores.total}/405`);
+  const scores = result.breakdown.scores;
+  if (typeof scores.total === "number") {
+    lines.push(`**Score**: ${scores.total}/${result.maxScore}`);
     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})`}`);
+  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("");
+    }
+  } 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("## Non-max Reasons");
-  if (breakdown.nonMaxDimensions.length === 0) {
-    lines.push("- All dimensions are at max score.");
+  pushLinks(lines, result);
+  return lines.join("\n");
+}
+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("");
   } 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) {
@@ -4690,7 +4712,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"),
@@ -4741,7 +4763,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, plus the HTTP status of failing URL tests (e.g. 1100 timeout, 404) (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"),
@@ -4770,7 +4792,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, { httpStatus: true });
         const format = response_format || "markdown" /* MARKDOWN */;
         const output = format === "json" /* JSON */ ? truncateJson(details) : truncateText(addDemoFooter(formatQualityDetailsMarkdown(details, dataset_id)));
         return {
@@ -5237,10 +5259,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" }
   });
@@ -5972,7 +5994,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.124"
+    version: "0.4.126"
   });
 }
 function registerAll(server) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.124",
+  "version": "0.4.126",
   "mcpName": "io.github.aborruso/ckan-mcp-server",
   "description": "MCP server for interacting with CKAN open data portals",
   "repository": {