@aborruso/ckan-mcp-server 0.4.14 → 0.4.15

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,36 @@
 # LOG
 
+## 2026-01-23
+
+### 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;
+  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.15"
   });
 }
 function registerAll(server2) {
@@ -2619,6 +2759,7 @@ function registerAll(server2) {
   registerStatusTools(server2);
   registerTagTools(server2);
   registerGroupTools(server2);
+  registerQualityTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }

package/openspec/changes/add-mqa-quality-tool/proposal.md

@@ -0,0 +1,21 @@
+# Change: Add MQA Quality Score Tool for dati.gov.it
+
+## Why
+Datasets on dati.gov.it display quality scores (Eccellente, Buono, etc.) calculated by data.europa.eu's MQA (Metadata Quality Assurance) system. Currently there's no way to access these quality metrics through the MCP server, limiting users' ability to evaluate dataset quality programmatically.
+
+## What Changes
+- Add `ckan_get_mqa_quality` tool for retrieving quality metrics from data.europa.eu
+- Tool works only with dati.gov.it server (validated at runtime)
+- Fetches dataset identifier from CKAN, then queries MQA API
+- Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability)
+- Supports both markdown and JSON output formats
+
+## Impact
+- Affected specs: New capability `ckan-quality`
+- Affected code:
+  - New file: `src/tools/quality.ts` (tool handler)
+  - New file: `tests/integration/quality.test.ts` (tests with mocked responses)
+  - New file: `tests/fixtures/responses/mqa-quality.json` (mock data)
+  - Modified: `src/server.ts` (register new tool)
+  - Modified: `README.md` (document new tool)
+  - Modified: `EXAMPLES.md` (add usage examples)

package/openspec/changes/add-mqa-quality-tool/specs/ckan-quality/spec.md

@@ -0,0 +1,71 @@
+## ADDED Requirements
+
+### Requirement: MQA Quality Score Retrieval
+The system SHALL provide a tool to retrieve MQA (Metadata Quality Assurance) quality metrics from data.europa.eu for datasets published on dati.gov.it.
+
+#### Scenario: Successful quality score retrieval
+- **GIVEN** a valid dataset ID from dati.gov.it
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL fetch identifier field from CKAN package_show
+- **AND** system SHALL query data.europa.eu MQA API
+- **AND** system SHALL return quality score and detailed metrics (accessibility, reusability, interoperability, findability)
+
+#### Scenario: Identifier fallback to name
+- **GIVEN** a dataset with empty identifier field
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL use the name field as fallback identifier for MQA API query
+
+#### Scenario: Dataset not found
+- **GIVEN** an invalid or non-existent dataset ID
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL return clear error message indicating dataset not found
+
+#### Scenario: MQA API unavailable
+- **GIVEN** data.europa.eu MQA API is unavailable or returns error
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL return clear error message indicating MQA service unavailability
+
+### Requirement: Server Validation
+The system SHALL restrict MQA quality queries to dati.gov.it server only.
+
+#### Scenario: Valid dati.gov.it server
+- **GIVEN** server_url is "https://www.dati.gov.it/opendata" or "https://dati.gov.it/opendata"
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL proceed with MQA query
+
+#### Scenario: Invalid server URL
+- **GIVEN** server_url is not dati.gov.it (e.g., "https://catalog.data.gov")
+- **WHEN** user requests quality metrics
+- **THEN** system SHALL reject request with error message explaining MQA is only available for dati.gov.it
+
+### Requirement: Output Formats
+The system SHALL support both markdown and JSON output formats for quality metrics.
+
+#### Scenario: Markdown format (default)
+- **GIVEN** user does not specify response_format or specifies "markdown"
+- **WHEN** quality metrics are retrieved
+- **THEN** system SHALL return human-readable markdown with:
+  - Overall quality score
+  - Breakdown by dimension (accessibility, reusability, interoperability, findability)
+  - Key findings and recommendations
+
+#### Scenario: JSON format
+- **GIVEN** user specifies response_format as "json"
+- **WHEN** quality metrics are retrieved
+- **THEN** system SHALL return complete MQA API response as structured JSON
+
+### Requirement: Tool Parameters
+The system SHALL accept the following parameters for the MQA quality tool:
+- server_url (required): Base URL of dati.gov.it portal
+- dataset_id (required): Dataset ID or name
+- response_format (optional): "markdown" (default) or "json"
+
+#### Scenario: Minimal parameters
+- **GIVEN** user provides only server_url and dataset_id
+- **WHEN** tool is invoked
+- **THEN** system SHALL use default markdown format
+
+#### Scenario: All parameters specified
+- **GIVEN** user provides server_url, dataset_id, and response_format
+- **WHEN** tool is invoked
+- **THEN** system SHALL use specified format for output

package/openspec/changes/add-mqa-quality-tool/tasks.md

@@ -0,0 +1,29 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [x] 1.1 Create `src/tools/quality.ts` with `ckan_get_mqa_quality` tool handler
+- [x] 1.2 Implement server URL validation (dati.gov.it only)
+- [x] 1.3 Add CKAN package_show call to extract identifier field
+- [x] 1.4 Add MQA API client (https://data.europa.eu/api/mqa/cache/datasets/{id})
+- [x] 1.5 Implement markdown and JSON formatters for quality metrics
+- [x] 1.6 Register tool in `src/server.ts`
+
+## 2. Testing
+- [x] 2.1 Create mock fixtures for CKAN package_show response
+- [x] 2.2 Create mock fixtures for MQA API response
+- [x] 2.3 Write integration tests for successful quality retrieval
+- [x] 2.4 Write tests for error scenarios (invalid server, dataset not found, MQA API unavailable)
+- [x] 2.5 Write tests for fallback from identifier to name field
+- [x] 2.6 Verify test coverage matches project standards
+
+## 3. Documentation
+- [x] 3.1 Add tool description to README.md
+- [x] 3.2 Add usage examples to EXAMPLES.md
+- [x] 3.3 Document server restriction (dati.gov.it only)
+- [x] 3.4 Document quality metrics structure (score, accessibility, reusability, interoperability, findability)
+
+## 4. Validation
+- [x] 4.1 Run full test suite (npm test) - 212 tests passing
+- [x] 4.2 Test manually with real dati.gov.it dataset
+- [x] 4.3 Verify error handling for non-dati.gov.it servers
+- [x] 4.4 Build project successfully (npm run build)

package/package.json

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