@aborruso/ckan-mcp-server 0.4.32 → 0.4.35

package/AGENTS.md

@@ -45,6 +45,13 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 
 **Single test**: `npm test -- tests/unit/http.test.ts` | `npm test -- -t "testName"`
 
+## Local MCP Client Build Test
+
+Before deploying, you can test the current dev build by pointing your MCP client at the Node entrypoint in `dist/`:
+
+1. Build: `npm run build`
+2. Example absolute path: `/home/aborruso/git/idee/ckan-mcp-server/dist/index.js` (adjust to your local checkout)
+
 ## GitHub CLI Notes
 
 When creating issues with multi-line bodies, avoid literal `\n` in `--body`. Use a here-doc

package/LOG.md

@@ -2,6 +2,32 @@
 
 ## 2026-02-01
 
+### Release v0.4.35
+
+- Tests: adjust MQA metrics details fixture to include scoring entries
+- Files: `tests/integration/quality.test.ts`
+
+### Unreleased
+
+- None
+
+### 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
+- Files: `src/tools/package.ts`, `src/server.ts`, `src/worker.ts`, `package.json`, `package-lock.json`
+
 ### Release v0.4.32
 
 - Workers: align browser-like headers for fetch path to avoid 403 on dati.gov.it

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

@@ -142,12 +142,49 @@ function asBuffer(data) {
   }
   return void 0;
 }
+function asArrayBuffer(data) {
+  if (!data) {
+    return void 0;
+  }
+  if (data instanceof ArrayBuffer) {
+    return data;
+  }
+  if (ArrayBuffer.isView(data)) {
+    return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+  }
+  return void 0;
+}
+async function decodeArrayBufferText(buffer, encoding) {
+  if (encoding && typeof DecompressionStream !== "undefined") {
+    try {
+      const stream = new DecompressionStream(
+        encoding.includes("br") ? "br" : encoding.includes("deflate") ? "deflate" : "gzip"
+      );
+      const decompressed = await new Response(
+        new Blob([buffer]).stream().pipeThrough(stream)
+      ).arrayBuffer();
+      return new TextDecoder("utf-8").decode(decompressed).trim();
+    } catch {
+    }
+  }
+  return new TextDecoder("utf-8").decode(buffer).trim();
+}
 async function decodePossiblyCompressed(data, headers) {
   if (data === null || data === void 0) {
     return data;
   }
-  if (typeof data === "object" && !asBuffer(data)) {
-    return data;
+  const arrayBuffer = asArrayBuffer(data);
+  if (arrayBuffer && typeof Buffer === "undefined") {
+    const encoding2 = getHeaderValue(headers, "content-encoding");
+    const text2 = await decodeArrayBufferText(arrayBuffer, encoding2);
+    if (!text2) {
+      return text2;
+    }
+    try {
+      return JSON.parse(text2);
+    } catch {
+      return text2;
+    }
   }
   if (typeof data === "string") {
     try {
@@ -158,6 +195,9 @@ async function decodePossiblyCompressed(data, headers) {
   }
   const buffer = asBuffer(data);
   if (!buffer) {
+    if (typeof data === "object") {
+      return data;
+    }
     return data;
   }
   const encoding = getHeaderValue(headers, "content-encoding");
@@ -241,7 +281,18 @@ async function makeCkanRequest(serverUrl, action, params = {}) {
         method: "GET",
         headers: {
           Accept: "application/json, text/plain, */*",
-          "Accept-Language": "en-US,en;q=0.9,it;q=0.8"
+          "Accept-Language": "en-US,en;q=0.9,it;q=0.8",
+          "Accept-Encoding": "gzip, deflate, br",
+          Connection: "keep-alive",
+          Referer: `${baseUrl}/`,
+          "Sec-Fetch-Site": "same-origin",
+          "Sec-Fetch-Mode": "navigate",
+          "Sec-Fetch-Dest": "document",
+          "Upgrade-Insecure-Requests": "1",
+          "Sec-CH-UA": '"Chromium";v="120", "Not?A_Brand";v="24", "Google Chrome";v="120"',
+          "Sec-CH-UA-Mobile": "?0",
+          "Sec-CH-UA-Platform": '"Linux"',
+          "User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
         }
       });
       if (!response.ok) {
@@ -668,6 +719,11 @@ Important - Date field semantics:
   - metadata_modified: CKAN record update timestamp (publish time on source portals,
     harvest time on aggregators; use for "updated/modified in last X")
 
+Natural language mapping (important for tool callers):
+  - "created"/"published" -> prefer issued; fallback to metadata_created
+  - "updated"/"modified" -> prefer modified; fallback to metadata_modified
+  - For "recent in last X", consider using content_recent (issued with metadata_created fallback)
+
 Content-recent helper:
   - content_recent: if true, rewrites the query to use issued with a fallback to
     metadata_created when issued is missing.
@@ -743,6 +799,7 @@ Examples:
   - Date range: { q: "metadata_modified:[2024-01-01T00:00:00Z TO 2024-12-31T23:59:59Z]" }
   - Date math: { q: "metadata_modified:[NOW-6MONTHS TO *]" }
   - Date math (auto-converted): { q: "modified:[NOW-30DAYS TO NOW]" }
+  - Recent content (issued w/ fallback): { q: "*:*", content_recent: true, content_recent_days: 180 }
   - Field exists: { q: "organization:* AND num_resources:[1 TO *]" }
   - Boosting: { q: "title:climate^2 OR notes:climate" }
   - Filter org: { fq: "organization:regione-siciliana" }
@@ -2401,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;
@@ -2415,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;
@@ -2487,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) => {
@@ -2497,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",
@@ -2551,6 +2767,7 @@ async function getMqaQuality(serverUrl, datasetId) {
       };
       return {
         mqa: response.data,
+        metrics: metricsPayload,
         breakdown
       };
     } catch (error) {
@@ -2567,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;
@@ -2761,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) {
@@ -2805,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
@@ -3346,7 +3668,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.27"
+    version: "0.4.33"
   });
 }
 function registerAll(server2) {