@aborruso/ckan-mcp-server 0.4.33 → 0.4.36

package/LOG.md

@@ -2,6 +2,33 @@
 
 ## 2026-02-01
 
+### Release v0.4.36
+
+- Fix: align server and worker reported version with package version
+- Fix: update worker health tool count
+- Files: `src/server.ts`, `src/worker.ts`
+
+### Unreleased
+
+- None
+
+### Release v0.4.35
+
+- Tests: adjust MQA metrics details fixture to include scoring entries
+- Files: `tests/integration/quality.test.ts`
+
+### Release v0.4.34
+
+- MQA: add detailed quality reasons tool with metrics flag parsing
+- MQA: add guidance note to use metrics endpoint for score deductions
+- Tests: cover detailed MQA reasons output and guidance note
+- Docs: list `ckan_get_mqa_quality_details` tool
+- Files: `src/tools/quality.ts`, `tests/integration/quality.test.ts`, `README.md`, `docs/architecture-flow.md`
+
+### Unreleased
+
+- None
+
 ### Release v0.4.33
 
 - Docs: clarify natural language date-field mapping for package search and document `content_recent` usage with example

package/README.md

@@ -260,6 +260,7 @@ See [Claude web guide](docs/guide/claude/claude_web.md)
 ### Quality Metrics
 
 - **ckan_get_mqa_quality**: Get MQA quality score and metrics for dati.gov.it datasets (accessibility, reusability, interoperability, findability)
+- **ckan_get_mqa_quality_details**: Get detailed MQA quality reasons and failing flags for dati.gov.it datasets
 
 ### Utilities
 

package/dist/index.js

@@ -2458,6 +2458,47 @@ var DIMENSION_MAX = {
   reusability: 75,
   contextuality: 20
 };
+var DIMENSION_LABELS = {
+  accessibility: "Accessibility",
+  findability: "Findability",
+  interoperability: "Interoperability",
+  reusability: "Reusability",
+  contextuality: "Contextuality"
+};
+var METRIC_DEFINITIONS = {
+  accessUrlAvailability: { dimension: "accessibility", reason: "accessUrlAvailability=false" },
+  downloadUrlAvailability: { dimension: "accessibility", reason: "downloadUrlAvailability=false" },
+  accessUrlStatusCode: { dimension: "accessibility", expectsStatusCode: true },
+  downloadUrlStatusCode: { dimension: "accessibility", expectsStatusCode: true },
+  keywordAvailability: { dimension: "findability", reason: "keywordAvailability=false" },
+  categoryAvailability: { dimension: "findability", reason: "categoryAvailability=false" },
+  spatialAvailability: { dimension: "findability", reason: "spatialAvailability=false" },
+  temporalAvailability: { dimension: "findability", reason: "temporalAvailability=false" },
+  dcatApCompliance: { dimension: "interoperability", reason: "dcatApCompliance=false" },
+  formatAvailability: { dimension: "interoperability", reason: "formatAvailability=false" },
+  mediaTypeAvailability: { dimension: "interoperability", reason: "mediaTypeAvailability=false" },
+  formatMediaTypeVocabularyAlignment: { dimension: "interoperability", reason: "formatMediaTypeVocabularyAlignment=false" },
+  formatMediaTypeMachineInterpretable: {
+    dimension: "interoperability",
+    reason: "formatMediaTypeMachineInterpretable=false"
+  },
+  accessRightsAvailability: { dimension: "reusability", reason: "accessRightsAvailability=false" },
+  accessRightsVocabularyAlignment: {
+    dimension: "reusability",
+    reason: "accessRightsVocabularyAlignment=false"
+  },
+  licenceAvailability: { dimension: "reusability", reason: "licenceAvailability=false" },
+  knownLicence: {
+    dimension: "reusability",
+    reason: "knownLicence=false (licence not aligned to controlled vocabulary)"
+  },
+  contactPointAvailability: { dimension: "reusability", reason: "contactPointAvailability=false" },
+  publisherAvailability: { dimension: "reusability", reason: "publisherAvailability=false" },
+  byteSizeAvailability: { dimension: "contextuality", reason: "byteSizeAvailability=false" },
+  rightsAvailability: { dimension: "contextuality", reason: "rightsAvailability=false" },
+  dateModifiedAvailability: { dimension: "contextuality", reason: "dateModifiedAvailability=false" },
+  dateIssuedAvailability: { dimension: "contextuality", reason: "dateIssuedAvailability=false" }
+};
 function parseScoreValue(value) {
   if (!value || typeof value !== "object") {
     return void 0;
@@ -2472,6 +2513,44 @@ function parseScoreValue(value) {
   }
   return void 0;
 }
+function parseMetricValue(value) {
+  if (!value || typeof value !== "object") {
+    if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+      return value;
+    }
+    return void 0;
+  }
+  const raw = value["@value"];
+  if (typeof raw === "boolean") {
+    return raw;
+  }
+  if (typeof raw === "number") {
+    return raw;
+  }
+  if (typeof raw === "string") {
+    const lower = raw.toLowerCase();
+    if (lower === "true" || lower === "false") {
+      return lower === "true";
+    }
+    const numeric = Number(raw);
+    if (Number.isFinite(numeric)) {
+      return numeric;
+    }
+    return raw;
+  }
+  return void 0;
+}
+function metricKeyFromId(metricId) {
+  const hashIndex = metricId.lastIndexOf("#");
+  if (hashIndex >= 0 && hashIndex < metricId.length - 1) {
+    return metricId.slice(hashIndex + 1);
+  }
+  const slashIndex = metricId.lastIndexOf("/");
+  if (slashIndex >= 0 && slashIndex < metricId.length - 1) {
+    return metricId.slice(slashIndex + 1);
+  }
+  return metricId;
+}
 function decodeMetricsPayload(payload) {
   if (payload && typeof payload === "object" && "@graph" in payload) {
     return payload;
@@ -2544,6 +2623,86 @@ function extractMetricsScores(metricsData) {
   }
   return scores;
 }
+function extractMetricDetails(metricsData, nonMaxDimensions) {
+  const parsed = decodeMetricsPayload(metricsData);
+  if (!parsed || typeof parsed !== "object") {
+    return { flags: [], reasons: {} };
+  }
+  const graph = parsed["@graph"];
+  if (!Array.isArray(graph)) {
+    return { flags: [], reasons: {} };
+  }
+  const flagsMap = /* @__PURE__ */ new Map();
+  for (const node of graph) {
+    if (!node || typeof node !== "object") {
+      continue;
+    }
+    const metricRef = node["dqv:isMeasurementOf"];
+    if (!metricRef) {
+      continue;
+    }
+    const metricId = typeof metricRef === "string" ? metricRef : metricRef["@id"];
+    if (typeof metricId !== "string") {
+      continue;
+    }
+    const metricKey = metricKeyFromId(metricId);
+    const definition = METRIC_DEFINITIONS[metricKey];
+    if (!definition) {
+      continue;
+    }
+    const value = parseMetricValue(node["dqv:value"]);
+    if (value === void 0) {
+      continue;
+    }
+    const entry = flagsMap.get(metricKey);
+    if (entry) {
+      entry.values.add(value);
+      continue;
+    }
+    flagsMap.set(metricKey, {
+      metricId,
+      metricKey,
+      dimension: definition.dimension,
+      values: /* @__PURE__ */ new Set([value])
+    });
+  }
+  const reasons = {};
+  const reasonSets = /* @__PURE__ */ new Map();
+  for (const dimension of nonMaxDimensions) {
+    reasonSets.set(dimension, /* @__PURE__ */ new Set());
+  }
+  for (const entry of flagsMap.values()) {
+    const definition = METRIC_DEFINITIONS[entry.metricKey];
+    if (!definition) {
+      continue;
+    }
+    const reasonSet = reasonSets.get(entry.dimension);
+    if (!reasonSet) {
+      continue;
+    }
+    for (const value of entry.values) {
+      if (typeof value === "boolean" && value === false) {
+        reasonSet.add(definition.reason || `${entry.metricKey}=false`);
+        continue;
+      }
+      if (definition.expectsStatusCode && typeof value === "number" && value !== 200) {
+        reasonSet.add(`${entry.metricKey}=${value}`);
+      }
+    }
+  }
+  for (const [dimension, set] of reasonSets.entries()) {
+    if (set.size > 0) {
+      reasons[dimension] = Array.from(set.values());
+    }
+  }
+  const flags = Array.from(flagsMap.values()).map((entry) => ({
+    metricId: entry.metricId,
+    metricKey: entry.metricKey,
+    dimension: entry.dimension,
+    values: Array.from(entry.values)
+  }));
+  return { flags, reasons };
+}
 function findNonMaxDimensions(scores) {
   const nonMax = [];
   Object.keys(DIMENSION_MAX).forEach((dimension) => {
@@ -2554,7 +2713,7 @@ function findNonMaxDimensions(scores) {
   });
   return nonMax;
 }
-async function getMqaQuality(serverUrl, datasetId) {
+async function fetchMqaQuality(serverUrl, datasetId) {
   const dataset = await makeCkanRequest(
     serverUrl,
     "package_show",
@@ -2608,6 +2767,7 @@ async function getMqaQuality(serverUrl, datasetId) {
       };
       return {
         mqa: response.data,
+        metrics: metricsPayload,
         breakdown
       };
     } catch (error) {
@@ -2624,6 +2784,21 @@ async function getMqaQuality(serverUrl, datasetId) {
     `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').`
   );
 }
+async function getMqaQuality(serverUrl, datasetId) {
+  const result = await fetchMqaQuality(serverUrl, datasetId);
+  return {
+    mqa: result.mqa,
+    breakdown: result.breakdown
+  };
+}
+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 findSectionMetric(section, key) {
   if (!Array.isArray(section)) {
     return void 0;
@@ -2818,7 +2993,57 @@ function formatQualityMarkdown(data, datasetId) {
   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}`);
-  lines.push(`Metrics endpoint: ${normalized.breakdown?.metricsUrl || `${MQA_METRICS_BASE}/${portalId}/metrics`}`);
+  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");
+}
+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})`}`);
+      }
+    }
+    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("; ")}`);
+      }
+    }
+  }
+  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`}`);
   return lines.join("\n");
 }
 function registerQualityTools(server2) {
@@ -2862,6 +3087,46 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
       }
     }
   );
+  server2.tool(
+    "ckan_get_mqa_quality_details",
+    "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.",
+    {
+      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"),
+      response_format: ResponseFormatSchema.optional()
+    },
+    async ({ server_url, dataset_id, response_format }) => {
+      if (!isValidMqaServer(server_url)) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error: MQA quality details are only available for dati.gov.it datasets. Provided server: ${server_url}
+
+The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`
+          }]
+        };
+      }
+      try {
+        const details = await getMqaQualityDetails(server_url, dataset_id);
+        const format = response_format || "markdown" /* MARKDOWN */;
+        const output = format === "json" /* JSON */ ? JSON.stringify(details, null, 2) : formatQualityDetailsMarkdown(details, dataset_id);
+        return {
+          content: [{
+            type: "text",
+            text: output
+          }]
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{
+            type: "text",
+            text: `Error retrieving quality details: ${errorMessage}`
+          }]
+        };
+      }
+    }
+  );
 }
 
 // src/resources/dataset.ts
@@ -3403,7 +3668,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.33"
+    version: "0.4.36"
   });
 }
 function registerAll(server2) {