@aborruso/ckan-mcp-server 0.4.14 → 0.4.16

package/EXAMPLES.md

@@ -151,6 +151,24 @@ ckan_package_search({
 })
 ```
 
+### Get MQA quality metrics for a dataset
+```typescript
+ckan_get_mqa_quality({
+  server_url: "https://www.dati.gov.it/opendata",
+  dataset_id: "332be8b7-89b9-4dfe-a252-7fccd3efda76",
+  response_format: "markdown"
+})
+```
+
+Returns quality score and detailed metrics from data.europa.eu MQA (Metadata Quality Assurance) system:
+- Overall score (max 405 points)
+- Accessibility (URL status, download availability)
+- Reusability (license, contact point, publisher)
+- Interoperability (format, media type)
+- Findability (keywords, category, spatial/temporal coverage)
+
+**Note**: Only works with dati.gov.it datasets. Uses the `identifier` field (or falls back to `name`) to query the European MQA API.
+
 ## USA Examples - data.gov
 
 ### Search government datasets

package/LOG.md

@@ -1,5 +1,47 @@
 # LOG
 
+## 2026-01-23
+
+### MQA Quality Metrics - Fix identifier format
+
+- **Bug fix**: Identifier transformation for data.europa.eu API compatibility
+- **Issue**: CKAN identifiers with colon separator (e.g., `c_f158:224c373e...`) were not recognized by MQA API
+- **Root cause**: data.europa.eu uses hyphen-separated identifiers (`c_f158-224c373e...`)
+- **Solution**: Replace colons with hyphens before API call: `.replace(/:/g, '-')`
+- **Impact**: MQA quality metrics now work for all dati.gov.it datasets, including municipal portals
+- **Example**: Messina air quality dataset now returns score 405/560 (Eccellente)
+- **File modified**: `src/tools/quality.ts` (line 41)
+- **Deployed**: Cloudflare Workers v0.4.16
+
+### MQA Quality Metrics Tool
+
+- **Feature**: Added `ckan_get_mqa_quality` tool for retrieving quality metrics from data.europa.eu MQA API
+- **Scope**: Only works with dati.gov.it datasets (server validation enforced)
+- **Data source**: Queries https://data.europa.eu/api/mqa/cache/datasets/{identifier}
+- **Identifier logic**: Uses `identifier` field from CKAN metadata, falls back to `name` if identifier is empty
+- **Metrics returned**:
+  - Overall score (max 405 points)
+  - Accessibility (URL status, download availability)
+  - Reusability (license, contact point, publisher)
+  - Interoperability (format, media type)
+  - Findability (keywords, category, spatial/temporal coverage)
+- **Output formats**: Markdown (default, human-readable) or JSON (structured data)
+- **Error handling**: Dataset not found, MQA API unavailable, invalid server URL
+- **Tests**: +11 integration tests (212 total, all passing)
+  - Server validation (www/non-www dati.gov.it URLs)
+  - Quality retrieval with identifier
+  - Fallback to name field
+  - Error scenarios (404, network errors)
+  - Markdown formatting (complete/partial data, availability indicators)
+- **Documentation**: README.md (new Quality Metrics section), EXAMPLES.md (usage example with expected metrics)
+- **Files**:
+  - `src/tools/quality.ts` (new, 194 lines)
+  - `src/server.ts` (register quality tools)
+  - `tests/integration/quality.test.ts` (new, 11 tests)
+  - `tests/fixtures/responses/mqa-quality-success.json` (new)
+  - `tests/fixtures/responses/package-show-{with,without}-identifier.json` (new)
+- **OpenSpec**: Proposal in `openspec/changes/add-mqa-quality-tool/` (4 requirements, 11 scenarios)
+
 ## 2026-01-22
 
 ### Date Query Auto-Conversion (v0.4.14)

package/README.md

@@ -17,7 +17,7 @@ MCP (Model Context Protocol) server for interacting with CKAN-based open data po
 - ⚡ Pagination and faceting support
 - 📄 MCP Resource Templates for direct data access
 - 🧭 Guided MCP prompts for common workflows
-- 🧪 Test suite with 191 tests (100% passing)
+- 🧪 Test suite with 212 tests (100% passing)
 
 ---
 
@@ -45,7 +45,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (191 tests)
+# Run tests (212 tests)
 npm test
 ```
 
@@ -209,6 +209,10 @@ These guides are based on a public demo server, which has a limit of 100,000 cal
 - **ckan_group_show**: Show group details
 - **ckan_group_search**: Search groups by name
 
+### Quality Metrics
+
+- **ckan_get_mqa_quality**: Get MQA quality score and metrics for dati.gov.it datasets (accessibility, reusability, interoperability, findability)
+
 ### Utilities
 
 - **ckan_status_show**: Verify server status
@@ -566,7 +570,7 @@ ckan-mcp-server/
 │   └── transport/
 │       ├── stdio.ts        # Stdio transport
 │       └── http.ts         # HTTP transport
-├── tests/                  # Test suite (191 tests)
+├── tests/                  # Test suite (212 tests)
 ├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md

package/dist/index.js

@@ -2101,6 +2101,146 @@ Returns:
   );
 }
 
+// src/tools/quality.ts
+import { z as z8 } from "zod";
+import axios2 from "axios";
+var MQA_API_BASE = "https://data.europa.eu/api/mqa/cache/datasets";
+var ALLOWED_SERVER_PATTERNS = [
+  /^https?:\/\/(www\.)?dati\.gov\.it/i
+];
+function isValidMqaServer(serverUrl) {
+  return ALLOWED_SERVER_PATTERNS.some((pattern) => pattern.test(serverUrl));
+}
+async function getMqaQuality(serverUrl, datasetId) {
+  const dataset = await makeCkanRequest(
+    serverUrl,
+    "package_show",
+    { id: datasetId }
+  );
+  const europeanId = (dataset.identifier || dataset.name).replace(/:/g, "-");
+  const mqaUrl = `${MQA_API_BASE}/${europeanId}`;
+  try {
+    const response = await axios2.get(mqaUrl, {
+      timeout: 3e4,
+      headers: {
+        "User-Agent": "CKAN-MCP-Server/1.0"
+      }
+    });
+    return response.data;
+  } catch (error) {
+    if (axios2.isAxiosError(error)) {
+      if (error.response?.status === 404) {
+        throw new Error(`Quality metrics not found for dataset '${europeanId}' on data.europa.eu`);
+      }
+      throw new Error(`MQA API error: ${error.message}`);
+    }
+    throw error;
+  }
+}
+function formatQualityMarkdown(data, datasetId) {
+  const lines = [];
+  lines.push(`# Quality Metrics for Dataset: ${datasetId}`);
+  lines.push("");
+  if (data.info?.score !== void 0) {
+    lines.push(`**Overall Score**: ${data.info.score}/405`);
+    lines.push("");
+  }
+  if (data.accessibility) {
+    lines.push("## Accessibility");
+    if (data.accessibility.accessUrl !== void 0) {
+      lines.push(`- Access URL: ${data.accessibility.accessUrl.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.accessibility.downloadUrl !== void 0) {
+      lines.push(`- Download URL: ${data.accessibility.downloadUrl.available ? "\u2713" : "\u2717"} Available`);
+    }
+    lines.push("");
+  }
+  if (data.reusability) {
+    lines.push("## Reusability");
+    if (data.reusability.licence !== void 0) {
+      lines.push(`- License: ${data.reusability.licence.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.reusability.contactPoint !== void 0) {
+      lines.push(`- Contact Point: ${data.reusability.contactPoint.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.reusability.publisher !== void 0) {
+      lines.push(`- Publisher: ${data.reusability.publisher.available ? "\u2713" : "\u2717"} Available`);
+    }
+    lines.push("");
+  }
+  if (data.interoperability) {
+    lines.push("## Interoperability");
+    if (data.interoperability.format !== void 0) {
+      lines.push(`- Format: ${data.interoperability.format.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.interoperability.mediaType !== void 0) {
+      lines.push(`- Media Type: ${data.interoperability.mediaType.available ? "\u2713" : "\u2717"} Available`);
+    }
+    lines.push("");
+  }
+  if (data.findability) {
+    lines.push("## Findability");
+    if (data.findability.keyword !== void 0) {
+      lines.push(`- Keywords: ${data.findability.keyword.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.findability.category !== void 0) {
+      lines.push(`- Category: ${data.findability.category.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.findability.spatial !== void 0) {
+      lines.push(`- Spatial: ${data.findability.spatial.available ? "\u2713" : "\u2717"} Available`);
+    }
+    if (data.findability.temporal !== void 0) {
+      lines.push(`- Temporal: ${data.findability.temporal.available ? "\u2713" : "\u2717"} Available`);
+    }
+    lines.push("");
+  }
+  lines.push("---");
+  lines.push(`Source: ${MQA_API_BASE}/${data.id || datasetId}`);
+  return lines.join("\n");
+}
+function registerQualityTools(server2) {
+  server2.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) 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 metrics 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 qualityData = await getMqaQuality(server_url, dataset_id);
+        const format = response_format || "markdown" /* MARKDOWN */;
+        const output = format === "json" /* JSON */ ? JSON.stringify(qualityData, null, 2) : formatQualityMarkdown(qualityData, 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 metrics: ${errorMessage}`
+          }]
+        };
+      }
+    }
+  );
+}
+
 // src/resources/dataset.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -2370,7 +2510,7 @@ function registerAllResources(server2) {
 }
 
 // src/prompts/theme.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // src/prompts/types.ts
 var createTextPrompt = (text) => ({
@@ -2427,9 +2567,9 @@ var registerThemePrompt = (server2) => {
       title: "Search datasets by theme",
       description: "Guided prompt to discover a theme and search datasets under it.",
       argsSchema: {
-        server_url: z8.string().url().describe("Base URL of the CKAN server"),
-        theme: z8.string().min(1).describe("Theme or group name to search"),
-        rows: z8.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z9.string().url().describe("Base URL of the CKAN server"),
+        theme: z9.string().min(1).describe("Theme or group name to search"),
+        rows: z9.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
@@ -2437,7 +2577,7 @@ var registerThemePrompt = (server2) => {
 };
 
 // src/prompts/organization.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var ORGANIZATION_PROMPT_NAME = "ckan-search-by-organization";
 var buildOrganizationPromptText = (serverUrl, organization, rows) => `# Guided search: datasets by organization
 
@@ -2468,9 +2608,9 @@ var registerOrganizationPrompt = (server2) => {
       title: "Search datasets by organization",
       description: "Guided prompt to find a publisher and list its datasets.",
       argsSchema: {
-        server_url: z9.string().url().describe("Base URL of the CKAN server"),
-        organization: z9.string().min(1).describe("Organization name or keyword"),
-        rows: z9.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z10.string().url().describe("Base URL of the CKAN server"),
+        organization: z10.string().min(1).describe("Organization name or keyword"),
+        rows: z10.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
@@ -2478,7 +2618,7 @@ var registerOrganizationPrompt = (server2) => {
 };
 
 // src/prompts/format.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var FORMAT_PROMPT_NAME = "ckan-search-by-format";
 var buildFormatPromptText = (serverUrl, format, rows) => `# Guided search: datasets by resource format
 
@@ -2499,9 +2639,9 @@ var registerFormatPrompt = (server2) => {
       title: "Search datasets by resource format",
       description: "Guided prompt to find datasets with a given resource format.",
       argsSchema: {
-        server_url: z10.string().url().describe("Base URL of the CKAN server"),
-        format: z10.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
-        rows: z10.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z11.string().url().describe("Base URL of the CKAN server"),
+        format: z11.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
+        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
@@ -2509,7 +2649,7 @@ var registerFormatPrompt = (server2) => {
 };
 
 // src/prompts/recent.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var RECENT_PROMPT_NAME = "ckan-recent-datasets";
 var buildRecentPromptText = (serverUrl, rows) => `# Guided search: recent datasets
 
@@ -2537,8 +2677,8 @@ var registerRecentPrompt = (server2) => {
       title: "Find recently updated datasets",
       description: "Guided prompt to list recently updated datasets on a CKAN portal.",
       argsSchema: {
-        server_url: z11.string().url().describe("Base URL of the CKAN server"),
-        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z12.string().url().describe("Base URL of the CKAN server"),
+        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
@@ -2546,7 +2686,7 @@ var registerRecentPrompt = (server2) => {
 };
 
 // src/prompts/dataset-analysis.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var DATASET_ANALYSIS_PROMPT_NAME = "ckan-analyze-dataset";
 var buildDatasetAnalysisPromptText = (serverUrl, id) => `# Guided analysis: dataset
 
@@ -2588,8 +2728,8 @@ var registerDatasetAnalysisPrompt = (server2) => {
       title: "Analyze a dataset",
       description: "Guided prompt to inspect dataset metadata and explore DataStore tables.",
       argsSchema: {
-        server_url: z12.string().url().describe("Base URL of the CKAN server"),
-        id: z12.string().min(1).describe("Dataset id or name (CKAN package id)")
+        server_url: z13.string().url().describe("Base URL of the CKAN server"),
+        id: z13.string().min(1).describe("Dataset id or name (CKAN package id)")
       }
     },
     async ({ server_url, id }) => createTextPrompt(buildDatasetAnalysisPromptText(server_url, id))
@@ -2609,7 +2749,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.13"
+    version: "0.4.16"
   });
 }
 function registerAll(server2) {
@@ -2619,6 +2759,7 @@ function registerAll(server2) {
   registerStatusTools(server2);
   registerTagTools(server2);
   registerGroupTools(server2);
+  registerQualityTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }