@aborruso/ckan-mcp-server 0.4.33 → 0.4.35

package/LOG.md

@@ -2,6 +2,27 @@
 
 ## 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

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

package/dist/worker.js

@@ -627,7 +627,7 @@ Returns:
 `,i+=`| Group | Datasets |
 `,i+=`|-------|----------|
 `;for(let a of o)i+=`| ${a.display_name||a.name} | ${a.count} |
-`}return{content:[{type:"text",text:J(i)}]}}catch(r){return{content:[{type:"text",text:`Error searching groups: ${r instanceof Error?r.message:String(r)}`}],isError:!0}}})}var Av="https://data.europa.eu/api/mqa/cache/datasets",Nv="https://data.europa.eu/api/hub/repo/datasets",AO=[/^https?:\/\/(www\.)?dati\.gov\.it/i];function NO(t){return AO.some(e=>e.test(t))}function IO(t){return t.trim().replace(/:/g,"-").replace(/\./g,"-").replace(/-+/g,"-").toLowerCase()}function CO(t){let e=IO(t);if(!e)return[];let r=[e];return e.includes("~~")||r.push(`${e}~~1`,`${e}~~2`),r}var ln={accessibility:100,findability:100,interoperability:110,reusability:75,contextuality:20};function jO(t){if(!t||typeof t!="object")return;let e=t["@value"];if(typeof e=="number")return e;if(typeof e=="string"){let r=Number(e);return Number.isFinite(r)?r:void 0}}function MO(t){if(t&&typeof t=="object"&&"@graph"in t)return t;if(typeof t=="string")try{return JSON.parse(t)}catch{return}if(t instanceof ArrayBuffer)try{let e=new TextDecoder().decode(new Uint8Array(t));return JSON.parse(e)}catch{return}if(ArrayBuffer.isView(t))try{let e=t,r=new TextDecoder().decode(new Uint8Array(e.buffer,e.byteOffset,e.byteLength));return JSON.parse(r)}catch{return}return t}function ZO(t){let e={},r=MO(t);if(!r||typeof r!="object")return e;let n=r["@graph"];if(!Array.isArray(n))return e;for(let o of n){if(!o||typeof o!="object")continue;let s=o["dqv:isMeasurementOf"];if(!s)continue;let i=typeof s=="string"?s:s["@id"];if(typeof i!="string")continue;let a=jO(o["dqv:value"]);a!==void 0&&(i.endsWith("#accessibilityScoring")?e.accessibility=a:i.endsWith("#findabilityScoring")?e.findability=a:i.endsWith("#interoperabilityScoring")?e.interoperability=a:i.endsWith("#reusabilityScoring")?e.reusability=a:i.endsWith("#contextualityScoring")?e.contextuality=a:i.endsWith("#scoring")&&(e.total=a))}return e}function DO(t){let e=[];return Object.keys(ln).forEach(r=>{let n=t[r];typeof n=="number"&&n<ln[r]&&e.push(r)}),e}async function qO(t,e){let r=await ne(t,"package_show",{id:e}),n=r.identifier||r.name,o=CO(n);if(o.length===0)throw new Error("Dataset identifier is empty; cannot query MQA API");for(let s of o){let i=`${Av}/${s}`,a=`${Nv}/${s}/metrics`;try{let c=await Sr.get(i,{timeout:3e4,headers:{"User-Agent":"CKAN-MCP-Server/1.0"}}),u;try{let p=await fetch(a,{headers:{"User-Agent":"CKAN-MCP-Server/1.0"}});if(!p.ok)throw new Error(`MQA metrics error: ${p.status} ${p.statusText}`);try{u=await p.json()}catch{u=await p.text()}}catch(p){throw p instanceof Error?new Error(`MQA metrics error: ${p.message}`):p}let l=ZO(u),h=c.data?.result?.results?.[0]?.info?.["dataset-id"]||s,f={scores:l,nonMaxDimensions:DO(l),metricsUrl:a,mqaUrl:i,portalId:h};return{mqa:c.data,breakdown:f}}catch(c){if(Sr.isAxiosError(c)){if(c.response?.status===404)continue;throw new Error(`MQA API error: ${c.message}`)}throw c}}throw new Error(`Quality metrics not found or identifier not aligned on data.europa.eu. Tried: ${o.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 jp(t,e){if(Array.isArray(t)){for(let r of t)if(r&&typeof r=="object"&&e in r)return r[e]}}function Ov(t){if(!Array.isArray(t))return;let e=new Map;for(let r of t){if(!r||typeof r!="object")continue;let n=r.name,o=r.percentage;typeof n=="string"&&typeof o=="number"&&e.set(n.toLowerCase(),o)}if(e.has("yes"))return(e.get("yes")||0)>0;if(e.size>0){for(let[r,n]of e.entries())if(r.startsWith("2")&&n>0)return!0;return!1}}function dt(t,e){let r=jp(t,e);if(typeof r=="boolean")return r}function un(t,e,r){let n=jp(t,e),o=Ov(n);if(o!==void 0)return{available:o};if(r){let s=jp(t,r),i=Ov(s);if(i!==void 0)return{available:i}}}function LO(t){let e=t?.mqa??t,r=t?.breakdown,n=e?.result?.results?.[0];return!n||typeof n!="object"?{...t,breakdown:r}:{id:n.info?.["dataset-id"],info:{score:n.info?.score},accessibility:{accessUrl:un(n.accessibility,"accessUrlAvailability","accessUrlStatusCode"),downloadUrl:un(n.accessibility,"downloadUrlAvailability","downloadUrlStatusCode")},reusability:{licence:un(n.reusability,"licenceAvailability"),contactPoint:dt(n.reusability,"contactPointAvailability")!==void 0?{available:dt(n.reusability,"contactPointAvailability")}:void 0,publisher:dt(n.reusability,"publisherAvailability")!==void 0?{available:dt(n.reusability,"publisherAvailability")}:void 0},interoperability:{format:un(n.interoperability,"formatAvailability"),mediaType:un(n.interoperability,"mediaTypeAvailability")},findability:{keyword:dt(n.findability,"keywordAvailability")!==void 0?{available:dt(n.findability,"keywordAvailability")}:void 0,category:dt(n.findability,"categoryAvailability")!==void 0?{available:dt(n.findability,"categoryAvailability")}:void 0,spatial:dt(n.findability,"spatialAvailability")!==void 0?{available:dt(n.findability,"spatialAvailability")}:void 0,temporal:dt(n.findability,"temporalAvailability")!==void 0?{available:dt(n.findability,"temporalAvailability")}:void 0},contextuality:{byteSize:un(n.contextuality,"byteSizeAvailability"),rights:un(n.contextuality,"rightsAvailability")},breakdown:r}}function UO(t,e){let r=LO(t),n=[];if(n.push(`# Quality Metrics for Dataset: ${e}`),n.push(""),r.info?.score!==void 0&&(n.push(`**Overall Score**: ${r.info.score}/405`),n.push("")),r.breakdown?.scores){n.push("## Dimension Scores");let s=r.breakdown.scores,i=[["accessibility","Accessibility",ln.accessibility],["findability","Findability",ln.findability],["interoperability","Interoperability",ln.interoperability],["reusability","Reusability",ln.reusability],["contextuality","Contextuality",ln.contextuality]];for(let[a,c,u]of i){let l=s[a];if(typeof l=="number"){let d=l>=u,h=d?"\u2705":"\u26A0\uFE0F";n.push(`- ${c}: ${l}/${u} ${h}${d?"":` (max ${u})`}`)}}r.breakdown.nonMaxDimensions.length>0?n.push(`- Non-max dimension(s): ${r.breakdown.nonMaxDimensions.join(", ")}`):Object.keys(s).length>0&&n.push("- Non-max dimension(s): none"),n.push("")}r.accessibility&&(n.push("## Accessibility"),r.accessibility.accessUrl!==void 0&&n.push(`- Access URL: ${r.accessibility.accessUrl.available?"\u2713":"\u2717"} Available`),r.accessibility.downloadUrl!==void 0&&n.push(`- Download URL: ${r.accessibility.downloadUrl.available?"\u2713":"\u2717"} Available`),n.push("")),r.reusability&&(n.push("## Reusability"),r.reusability.licence!==void 0&&n.push(`- License: ${r.reusability.licence.available?"\u2713":"\u2717"} Available`),r.reusability.contactPoint!==void 0&&n.push(`- Contact Point: ${r.reusability.contactPoint.available?"\u2713":"\u2717"} Available`),r.reusability.publisher!==void 0&&n.push(`- Publisher: ${r.reusability.publisher.available?"\u2713":"\u2717"} Available`),n.push("")),r.interoperability&&(n.push("## Interoperability"),r.interoperability.format!==void 0&&n.push(`- Format: ${r.interoperability.format.available?"\u2713":"\u2717"} Available`),r.interoperability.mediaType!==void 0&&n.push(`- Media Type: ${r.interoperability.mediaType.available?"\u2713":"\u2717"} Available`),n.push("")),r.findability&&(n.push("## Findability"),r.findability.keyword!==void 0&&n.push(`- Keywords: ${r.findability.keyword.available?"\u2713":"\u2717"} Available`),r.findability.category!==void 0&&n.push(`- Category: ${r.findability.category.available?"\u2713":"\u2717"} Available`),r.findability.spatial!==void 0&&n.push(`- Spatial: ${r.findability.spatial.available?"\u2713":"\u2717"} Available`),r.findability.temporal!==void 0&&n.push(`- Temporal: ${r.findability.temporal.available?"\u2713":"\u2717"} Available`),n.push("")),r.contextuality&&(n.push("## Contextuality"),r.contextuality.byteSize!==void 0&&n.push(`- Byte Size: ${r.contextuality.byteSize.available?"\u2713":"\u2717"} Available`),r.contextuality.rights!==void 0&&n.push(`- Rights: ${r.contextuality.rights.available?"\u2713":"\u2717"} Available`),n.push("")),n.push("---");let o=r.breakdown?.portalId||r.id||e;return n.push(`Portal: https://data.europa.eu/data/datasets/${o}/quality?locale=it`),n.push(`MQA source: ${Av}/${o}`),n.push(`Metrics endpoint: ${r.breakdown?.metricsUrl||`${Nv}/${o}/metrics`}`),n.join(`
+`}return{content:[{type:"text",text:J(i)}]}}catch(r){return{content:[{type:"text",text:`Error searching groups: ${r instanceof Error?r.message:String(r)}`}],isError:!0}}})}var Av="https://data.europa.eu/api/mqa/cache/datasets",Nv="https://data.europa.eu/api/hub/repo/datasets",AO=[/^https?:\/\/(www\.)?dati\.gov\.it/i];function NO(t){return AO.some(e=>e.test(t))}function IO(t){return t.trim().replace(/:/g,"-").replace(/\./g,"-").replace(/-+/g,"-").toLowerCase()}function CO(t){let e=IO(t);if(!e)return[];let r=[e];return e.includes("~~")||r.push(`${e}~~1`,`${e}~~2`),r}var ln={accessibility:100,findability:100,interoperability:110,reusability:75,contextuality:20};function jO(t){if(!t||typeof t!="object")return;let e=t["@value"];if(typeof e=="number")return e;if(typeof e=="string"){let r=Number(e);return Number.isFinite(r)?r:void 0}}function MO(t){if(t&&typeof t=="object"&&"@graph"in t)return t;if(typeof t=="string")try{return JSON.parse(t)}catch{return}if(t instanceof ArrayBuffer)try{let e=new TextDecoder().decode(new Uint8Array(t));return JSON.parse(e)}catch{return}if(ArrayBuffer.isView(t))try{let e=t,r=new TextDecoder().decode(new Uint8Array(e.buffer,e.byteOffset,e.byteLength));return JSON.parse(r)}catch{return}return t}function ZO(t){let e={},r=MO(t);if(!r||typeof r!="object")return e;let n=r["@graph"];if(!Array.isArray(n))return e;for(let o of n){if(!o||typeof o!="object")continue;let s=o["dqv:isMeasurementOf"];if(!s)continue;let i=typeof s=="string"?s:s["@id"];if(typeof i!="string")continue;let a=jO(o["dqv:value"]);a!==void 0&&(i.endsWith("#accessibilityScoring")?e.accessibility=a:i.endsWith("#findabilityScoring")?e.findability=a:i.endsWith("#interoperabilityScoring")?e.interoperability=a:i.endsWith("#reusabilityScoring")?e.reusability=a:i.endsWith("#contextualityScoring")?e.contextuality=a:i.endsWith("#scoring")&&(e.total=a))}return e}function DO(t){let e=[];return Object.keys(ln).forEach(r=>{let n=t[r];typeof n=="number"&&n<ln[r]&&e.push(r)}),e}async function qO(t,e){let r=await ne(t,"package_show",{id:e}),n=r.identifier||r.name,o=CO(n);if(o.length===0)throw new Error("Dataset identifier is empty; cannot query MQA API");for(let s of o){let i=`${Av}/${s}`,a=`${Nv}/${s}/metrics`;try{let c=await Sr.get(i,{timeout:3e4,headers:{"User-Agent":"CKAN-MCP-Server/1.0"}}),u;try{let p=await fetch(a,{headers:{"User-Agent":"CKAN-MCP-Server/1.0"}});if(!p.ok)throw new Error(`MQA metrics error: ${p.status} ${p.statusText}`);try{u=await p.json()}catch{u=await p.text()}}catch(p){throw p instanceof Error?new Error(`MQA metrics error: ${p.message}`):p}let l=ZO(u),h=c.data?.result?.results?.[0]?.info?.["dataset-id"]||s,f={scores:l,nonMaxDimensions:DO(l),metricsUrl:a,mqaUrl:i,portalId:h};return{mqa:c.data,breakdown:f}}catch(c){if(Sr.isAxiosError(c)){if(c.response?.status===404)continue;throw new Error(`MQA API error: ${c.message}`)}throw c}}throw new Error(`Quality metrics not found or identifier not aligned on data.europa.eu. Tried: ${o.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 jp(t,e){if(Array.isArray(t)){for(let r of t)if(r&&typeof r=="object"&&e in r)return r[e]}}function Ov(t){if(!Array.isArray(t))return;let e=new Map;for(let r of t){if(!r||typeof r!="object")continue;let n=r.name,o=r.percentage;typeof n=="string"&&typeof o=="number"&&e.set(n.toLowerCase(),o)}if(e.has("yes"))return(e.get("yes")||0)>0;if(e.size>0){for(let[r,n]of e.entries())if(r.startsWith("2")&&n>0)return!0;return!1}}function dt(t,e){let r=jp(t,e);if(typeof r=="boolean")return r}function un(t,e,r){let n=jp(t,e),o=Ov(n);if(o!==void 0)return{available:o};if(r){let s=jp(t,r),i=Ov(s);if(i!==void 0)return{available:i}}}function LO(t){let e=t?.mqa??t,r=t?.breakdown,n=e?.result?.results?.[0];return!n||typeof n!="object"?{...t,breakdown:r}:{id:n.info?.["dataset-id"],info:{score:n.info?.score},accessibility:{accessUrl:un(n.accessibility,"accessUrlAvailability","accessUrlStatusCode"),downloadUrl:un(n.accessibility,"downloadUrlAvailability","downloadUrlStatusCode")},reusability:{licence:un(n.reusability,"licenceAvailability"),contactPoint:dt(n.reusability,"contactPointAvailability")!==void 0?{available:dt(n.reusability,"contactPointAvailability")}:void 0,publisher:dt(n.reusability,"publisherAvailability")!==void 0?{available:dt(n.reusability,"publisherAvailability")}:void 0},interoperability:{format:un(n.interoperability,"formatAvailability"),mediaType:un(n.interoperability,"mediaTypeAvailability")},findability:{keyword:dt(n.findability,"keywordAvailability")!==void 0?{available:dt(n.findability,"keywordAvailability")}:void 0,category:dt(n.findability,"categoryAvailability")!==void 0?{available:dt(n.findability,"categoryAvailability")}:void 0,spatial:dt(n.findability,"spatialAvailability")!==void 0?{available:dt(n.findability,"spatialAvailability")}:void 0,temporal:dt(n.findability,"temporalAvailability")!==void 0?{available:dt(n.findability,"temporalAvailability")}:void 0},contextuality:{byteSize:un(n.contextuality,"byteSizeAvailability"),rights:un(n.contextuality,"rightsAvailability")},breakdown:r}}function UO(t,e){let r=LO(t),n=[];if(n.push(`# Quality Metrics for Dataset: ${e}`),n.push(""),r.info?.score!==void 0&&(n.push(`**Overall Score**: ${r.info.score}/405`),n.push("")),r.breakdown?.scores){n.push("## Dimension Scores");let i=r.breakdown.scores,a=[["accessibility","Accessibility",ln.accessibility],["findability","Findability",ln.findability],["interoperability","Interoperability",ln.interoperability],["reusability","Reusability",ln.reusability],["contextuality","Contextuality",ln.contextuality]];for(let[c,u,l]of a){let d=i[c];if(typeof d=="number"){let h=d>=l,f=h?"\u2705":"\u26A0\uFE0F";n.push(`- ${u}: ${d}/${l} ${f}${h?"":` (max ${l})`}`)}}r.breakdown.nonMaxDimensions.length>0?n.push(`- Non-max dimension(s): ${r.breakdown.nonMaxDimensions.join(", ")}`):Object.keys(i).length>0&&n.push("- Non-max dimension(s): none"),n.push("")}r.accessibility&&(n.push("## Accessibility"),r.accessibility.accessUrl!==void 0&&n.push(`- Access URL: ${r.accessibility.accessUrl.available?"\u2713":"\u2717"} Available`),r.accessibility.downloadUrl!==void 0&&n.push(`- Download URL: ${r.accessibility.downloadUrl.available?"\u2713":"\u2717"} Available`),n.push("")),r.reusability&&(n.push("## Reusability"),r.reusability.licence!==void 0&&n.push(`- License: ${r.reusability.licence.available?"\u2713":"\u2717"} Available`),r.reusability.contactPoint!==void 0&&n.push(`- Contact Point: ${r.reusability.contactPoint.available?"\u2713":"\u2717"} Available`),r.reusability.publisher!==void 0&&n.push(`- Publisher: ${r.reusability.publisher.available?"\u2713":"\u2717"} Available`),n.push("")),r.interoperability&&(n.push("## Interoperability"),r.interoperability.format!==void 0&&n.push(`- Format: ${r.interoperability.format.available?"\u2713":"\u2717"} Available`),r.interoperability.mediaType!==void 0&&n.push(`- Media Type: ${r.interoperability.mediaType.available?"\u2713":"\u2717"} Available`),n.push("")),r.findability&&(n.push("## Findability"),r.findability.keyword!==void 0&&n.push(`- Keywords: ${r.findability.keyword.available?"\u2713":"\u2717"} Available`),r.findability.category!==void 0&&n.push(`- Category: ${r.findability.category.available?"\u2713":"\u2717"} Available`),r.findability.spatial!==void 0&&n.push(`- Spatial: ${r.findability.spatial.available?"\u2713":"\u2717"} Available`),r.findability.temporal!==void 0&&n.push(`- Temporal: ${r.findability.temporal.available?"\u2713":"\u2717"} Available`),n.push("")),r.contextuality&&(n.push("## Contextuality"),r.contextuality.byteSize!==void 0&&n.push(`- Byte Size: ${r.contextuality.byteSize.available?"\u2713":"\u2717"} Available`),r.contextuality.rights!==void 0&&n.push(`- Rights: ${r.contextuality.rights.available?"\u2713":"\u2717"} Available`),n.push("")),n.push("---");let o=r.breakdown?.portalId||r.id||e;n.push(`Portal: https://data.europa.eu/data/datasets/${o}/quality?locale=it`),n.push(`MQA source: ${Av}/${o}`);let s=r.breakdown?.metricsUrl||`${Nv}/${o}/metrics`;return n.push(`Metrics endpoint: ${s}`),n.push("Tip: Use the metrics endpoint to explain score deductions (e.g., failing measurements such as knownLicence = false)."),n.join(`
 `)}function Iv(t){t.tool("ckan_get_mqa_quality","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.",{server_url:$.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),dataset_id:$.string().describe("Dataset ID or name"),response_format:ke.optional()},async({server_url:e,dataset_id:r,response_format:n})=>{if(!NO(e))return{content:[{type:"text",text:`Error: MQA quality metrics are only available for dati.gov.it datasets. Provided server: ${e}
 
 The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and only evaluates datasets from Italian open data portal.`}]};try{let o=await qO(e,r);return{content:[{type:"text",text:(n||"markdown")==="json"?JSON.stringify(o,null,2):UO(o,r)}]}}catch(o){return{content:[{type:"text",text:`Error retrieving quality metrics: ${o instanceof Error?o.message:String(o)}`}]}}})}function kr(t){let e=t.hostname;if(!e)throw new Error("Invalid ckan:// URI: missing server hostname");let r=t.pathname.split("/").filter(a=>a.length>0);if(r.length<2)throw new Error(`Invalid ckan:// URI: expected /{type}/{id}, got ${t.pathname}`);let[n,...o]=r,s=o.join("/");if(!n||!s)throw new Error("Invalid ckan:// URI: missing type or id");return{server:Sa(e)||`https://${e}`,type:n,id:s}}function Cv(t){t.registerResource("ckan-dataset",new Ct("ckan://{server}/dataset/{id}",{list:void 0}),{title:"CKAN Dataset",description:"Access dataset metadata from any CKAN server. URI format: ckan://{server}/dataset/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=kr(e),o=r.id,s=await ne(n,"package_show",{id:o}),i=J(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching dataset: ${o}`}]}}})}function jv(t){t.registerResource("ckan-resource",new Ct("ckan://{server}/resource/{id}",{list:void 0}),{title:"CKAN Resource",description:"Access resource metadata and download URL from any CKAN server. URI format: ckan://{server}/resource/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=kr(e),o=r.id,s=await ne(n,"resource_show",{id:o}),i=J(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching resource: ${o}`}]}}})}function Mv(t){t.registerResource("ckan-organization",new Ct("ckan://{server}/organization/{name}",{list:void 0}),{title:"CKAN Organization",description:"Access organization metadata from any CKAN server. URI format: ckan://{server}/organization/{name}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=kr(e),o=r.name,s=await ne(n,"organization_show",{id:o,include_datasets:!1}),i=J(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching organization: ${o}`}]}}})}var za=t=>t.replace(/["\\]/g,"\\$&"),FO=t=>{let e=t.trim(),r=[e],n=e.toUpperCase();return n!==e&&r.push(n),`(${["res_format","distribution_format"].flatMap(i=>r.map(a=>`${i}:"${za(a)}"`)).join(" OR ")})`},Ta=(t,e)=>{t.registerResource(e.name,new Ct(e.template,{list:void 0}),{title:e.title,description:e.description,mimeType:"application/json"},async(r,n)=>{try{let{server:o}=kr(r),s=e.buildFq(n),i=await ne(o,"package_search",{q:"*:*",fq:s}),a=J(JSON.stringify(i,null,2));return{contents:[{uri:r.href,mimeType:"application/json",text:a}]}}catch(o){let s=o instanceof Error?o.message:String(o);return{contents:[{uri:r.href,mimeType:"text/plain",text:`Error fetching datasets: ${s}`}]}}})};function Zv(t){Ta(t,{name:"ckan-group-datasets",template:"ckan://{server}/group/{name}/datasets",title:"CKAN Group Datasets",description:"List datasets in a CKAN group (theme). URI format: ckan://{server}/group/{name}/datasets",buildFq:e=>`groups:"${za(e.name)}"`})}function Dv(t){Ta(t,{name:"ckan-organization-datasets",template:"ckan://{server}/organization/{name}/datasets",title:"CKAN Organization Datasets",description:"List datasets for a CKAN organization. URI format: ckan://{server}/organization/{name}/datasets",buildFq:e=>`organization:"${za(e.name)}"`})}function qv(t){Ta(t,{name:"ckan-tag-datasets",template:"ckan://{server}/tag/{name}/datasets",title:"CKAN Tag Datasets",description:"List datasets matching a CKAN tag. URI format: ckan://{server}/tag/{name}/datasets",buildFq:e=>`tags:"${za(e.name)}"`})}function Lv(t){Ta(t,{name:"ckan-format-datasets",template:"ckan://{server}/format/{format}/datasets",title:"CKAN Format Datasets",description:"List datasets by resource format. URI format: ckan://{server}/format/{format}/datasets",buildFq:e=>FO(e.format)})}function Uv(t){Cv(t),jv(t),Mv(t),Zv(t),Dv(t),qv(t),Lv(t)}var Zt=t=>({messages:[{role:"user",content:{type:"text",text:t}}]});var VO="ckan-search-by-theme",HO=(t,e,r)=>`# Guided search: datasets by theme

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "description": "MCP server for interacting with CKAN open data portals",
   "main": "dist/index.js",
   "type": "module",