@aborruso/ckan-mcp-server 0.4.125 → 0.4.126

package/LOG.md

@@ -2,6 +2,16 @@
 
 ## 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`.

package/dist/index.js

@@ -4497,7 +4497,55 @@ async function fetchMqaV1(europeanId, links) {
     ...links
   };
 }
-async function getMqaQuality(serverUrl, datasetId) {
+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;
+  }
+  for (const item of urlTests) {
+    const perCode = counts.get(item.metric);
+    if (perCode) item.httpStatus = perCode;
+  }
+}
+async function getMqaQuality(serverUrl, datasetId, opts = {}) {
   const dataset = await makeCkanRequest(
     serverUrl,
     "package_show",
@@ -4534,7 +4582,11 @@ async function getMqaQuality(serverUrl, datasetId) {
     if (!entry || typeof entry !== "object") {
       throw new Error("Unexpected MQA payload: no result");
     }
-    return parseMqaV2(entry, links);
+    const result = parseMqaV2(entry, links);
+    if (opts.httpStatus) {
+      await addHttpStatus(result);
+    }
+    return result;
   }
   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').`
@@ -4545,7 +4597,14 @@ function formatNumber(value) {
 }
 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)}`;
+  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(", ")}`;
+  }
+  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})`);
@@ -4704,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 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)",
+      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"),
@@ -4733,7 +4792,7 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
         };
       }
       try {
-        const details = await getMqaQuality(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 {
@@ -5935,7 +5994,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.125"
+    version: "0.4.126"
   });
 }
 function registerAll(server) {

package/package.json

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