@aborruso/ckan-mcp-server 0.4.125 → 0.4.127

package/LOG.md

@@ -1,7 +1,31 @@
 # LOG
 
+## 2026-09-24
+
+### v0.4.127
+
+Ships #554: `dct:temporal` coverage in `ckan_package_show` (markdown + JSON, every period, `start_equals_issued` flag) and `CKAN_ALLOWED_DOMAINS` declared optional in `server.json` for the MCP Registry. Smoke 17/17.
+
+### `ckan_package_show`: temporal coverage (dct:temporal)
+
+New `readTemporalCoverage()` reads `dct:temporal` in both shapes dati.gov.it uses: root `temporal_coverage` (JSON string, e.g. Comune di Coriano) and extras `temporal_start`/`temporal_end`/`temporal_coverage` (Regione Toscana, 12,426 datasets). Rendered as **Temporal Coverage (dct:temporal)** in markdown and `temporal_coverage: [{start, end, start_equals_issued}]` in JSON, every period kept; before, JSON had nothing and markdown only the extras case. `start_equals_issued` is a factual flag for start = issued with no end: a full scan of the 17,860 datasets with `temporal_start` found a third like that, and on the origin portals (dati.toscana.it, opendata.maggioli.cloud, opendata.uniba.it, all dcatapit) `temporal_coverage` is empty in the CKAN API while their RDF export emits `dct:temporal` with `startDate` = `dct:issued`. So it is an export artefact, not a publisher entry. INPS, MIT, LaMMA weather runs and Camera di Commercio Marche carry real spans.
+
+### server.json: declare `CKAN_ALLOWED_DOMAINS` as optional
+
+Claude Desktop's configure dialog asked for six env vars, `CKAN_ALLOWED_DOMAINS` marked required, inferred from the README HTTP table. The registry package is stdio, where the allowlist is optional. `server.json` now declares the one variable explicitly (`isRequired: false`, placeholder). Takes effect on the next registry publish.
+
 ## 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

@@ -1517,6 +1517,42 @@ var readDcatExtra = (dataset, key) => {
   const rootValue = dataset[key];
   return typeof rootValue === "string" ? rootValue : "";
 };
+var readExtra = (dataset, key) => {
+  const extras = Array.isArray(dataset.extras) ? dataset.extras : [];
+  for (const e of extras) {
+    if (e && typeof e === "object" && e.key === key) {
+      return e.value;
+    }
+  }
+  return void 0;
+};
+var toPeriod = (item) => {
+  if (!item || typeof item !== "object") return null;
+  const { temporal_start, temporal_end } = item;
+  const start = typeof temporal_start === "string" && temporal_start ? temporal_start : null;
+  const end = typeof temporal_end === "string" && temporal_end ? temporal_end : null;
+  return start || end ? { start, end } : null;
+};
+var parseTemporalCoverage = (raw) => {
+  let value = raw;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return [];
+    }
+  }
+  const items = Array.isArray(value) ? value : [value];
+  return items.map(toPeriod).filter((p) => p !== null);
+};
+var readTemporalCoverage = (dataset) => {
+  const fromRoot = parseTemporalCoverage(dataset.temporal_coverage);
+  if (fromRoot.length > 0) return fromRoot;
+  const fromExtra = parseTemporalCoverage(readExtra(dataset, "temporal_coverage"));
+  if (fromExtra.length > 0) return fromExtra;
+  return parseTemporalCoverage({ temporal_start: readExtra(dataset, "temporal_start"), temporal_end: readExtra(dataset, "temporal_end") });
+};
+var startEqualsIssued = (period, issued) => period.end === null && typeof issued === "string" && period.start !== null && period.start.slice(0, 10) === issued.slice(0, 10);
 var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS, fullCoverage = false) => {
   const terms = extractQueryTerms(query);
   const titleText = dataset.title || dataset.name || "";
@@ -1655,6 +1691,15 @@ var formatPackageShowMarkdown = (result, serverUrl) => {
   const accessRights = dcatField("access_rights");
   if (accessRights) markdown += `- **Access Rights (dct:accessRights)**: ${sanitizeInline(accessRights)}
 `;
+  const periods = readTemporalCoverage(result);
+  if (periods.length > 0) {
+    const spans = periods.map((p) => {
+      const span = `${p.start ? formatDate(p.start) : "?"} \u2192 ${p.end ? formatDate(p.end) : "open"}`;
+      return startEqualsIssued(p, result.issued) ? `${span} (start equals issued, no end)` : span;
+    });
+    markdown += `- **Temporal Coverage (dct:temporal)**: ${sanitizeInline(spans.join("; "))}
+`;
+  }
   markdown += `
 `;
   if (result.organization) {
@@ -1888,6 +1933,7 @@ function compactPackageShow(result, serverUrl) {
     holder_name: result.holder_name || null,
     hvd_category: result.hvd_category || null,
     applicable_legislation: result.applicable_legislation || null,
+    temporal_coverage: readTemporalCoverage(result).map((p) => ({ ...p, start_equals_issued: startEqualsIssued(p, result.issued) })),
     resources: (result.resources || []).map((r) => ({
       id: r.id,
       name: r.name || null,
@@ -2500,6 +2546,8 @@ Returns (JSON format):
   author, maintainer,
   frequency, language, publisher_name, holder_name,
   hvd_category, applicable_legislation,
+  temporal_coverage (array of {start, end, start_equals_issued} from dct:temporal; empty if absent;
+    start_equals_issued=true when start = issued and no end: on dcatapit portals an export default, not a data period),
   resources (id, name, format, url, size, datastore_active, created, last_modified, api_json_url),
   view_url, api_json_url
 
@@ -4497,7 +4545,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 +4630,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 +4645,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 +4811,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 +4840,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 +6042,7 @@ var registerAllPrompts = (server) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.125"
+    version: "0.4.127"
   });
 }
 function registerAll(server) {

package/package.json

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