@aborruso/ckan-mcp-server 0.4.14 → 0.4.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/EXAMPLES.md +18 -0
- package/LOG.md +42 -0
- package/README.md +7 -3
- package/dist/index.js +160 -19
- package/dist/worker.js +40 -37
- package/openspec/changes/add-mqa-quality-tool/proposal.md +21 -0
- package/openspec/changes/add-mqa-quality-tool/specs/ckan-quality/spec.md +71 -0
- package/openspec/changes/add-mqa-quality-tool/tasks.md +29 -0
- package/package.json +1 -1
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Change: Add MQA Quality Score Tool for dati.gov.it
|
|
2
|
+
|
|
3
|
+
## Why
|
|
4
|
+
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.
|
|
5
|
+
|
|
6
|
+
## What Changes
|
|
7
|
+
- Add `ckan_get_mqa_quality` tool for retrieving quality metrics from data.europa.eu
|
|
8
|
+
- Tool works only with dati.gov.it server (validated at runtime)
|
|
9
|
+
- Fetches dataset identifier from CKAN, then queries MQA API
|
|
10
|
+
- Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability)
|
|
11
|
+
- Supports both markdown and JSON output formats
|
|
12
|
+
|
|
13
|
+
## Impact
|
|
14
|
+
- Affected specs: New capability `ckan-quality`
|
|
15
|
+
- Affected code:
|
|
16
|
+
- New file: `src/tools/quality.ts` (tool handler)
|
|
17
|
+
- New file: `tests/integration/quality.test.ts` (tests with mocked responses)
|
|
18
|
+
- New file: `tests/fixtures/responses/mqa-quality.json` (mock data)
|
|
19
|
+
- Modified: `src/server.ts` (register new tool)
|
|
20
|
+
- Modified: `README.md` (document new tool)
|
|
21
|
+
- Modified: `EXAMPLES.md` (add usage examples)
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
## ADDED Requirements
|
|
2
|
+
|
|
3
|
+
### Requirement: MQA Quality Score Retrieval
|
|
4
|
+
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.
|
|
5
|
+
|
|
6
|
+
#### Scenario: Successful quality score retrieval
|
|
7
|
+
- **GIVEN** a valid dataset ID from dati.gov.it
|
|
8
|
+
- **WHEN** user requests quality metrics
|
|
9
|
+
- **THEN** system SHALL fetch identifier field from CKAN package_show
|
|
10
|
+
- **AND** system SHALL query data.europa.eu MQA API
|
|
11
|
+
- **AND** system SHALL return quality score and detailed metrics (accessibility, reusability, interoperability, findability)
|
|
12
|
+
|
|
13
|
+
#### Scenario: Identifier fallback to name
|
|
14
|
+
- **GIVEN** a dataset with empty identifier field
|
|
15
|
+
- **WHEN** user requests quality metrics
|
|
16
|
+
- **THEN** system SHALL use the name field as fallback identifier for MQA API query
|
|
17
|
+
|
|
18
|
+
#### Scenario: Dataset not found
|
|
19
|
+
- **GIVEN** an invalid or non-existent dataset ID
|
|
20
|
+
- **WHEN** user requests quality metrics
|
|
21
|
+
- **THEN** system SHALL return clear error message indicating dataset not found
|
|
22
|
+
|
|
23
|
+
#### Scenario: MQA API unavailable
|
|
24
|
+
- **GIVEN** data.europa.eu MQA API is unavailable or returns error
|
|
25
|
+
- **WHEN** user requests quality metrics
|
|
26
|
+
- **THEN** system SHALL return clear error message indicating MQA service unavailability
|
|
27
|
+
|
|
28
|
+
### Requirement: Server Validation
|
|
29
|
+
The system SHALL restrict MQA quality queries to dati.gov.it server only.
|
|
30
|
+
|
|
31
|
+
#### Scenario: Valid dati.gov.it server
|
|
32
|
+
- **GIVEN** server_url is "https://www.dati.gov.it/opendata" or "https://dati.gov.it/opendata"
|
|
33
|
+
- **WHEN** user requests quality metrics
|
|
34
|
+
- **THEN** system SHALL proceed with MQA query
|
|
35
|
+
|
|
36
|
+
#### Scenario: Invalid server URL
|
|
37
|
+
- **GIVEN** server_url is not dati.gov.it (e.g., "https://catalog.data.gov")
|
|
38
|
+
- **WHEN** user requests quality metrics
|
|
39
|
+
- **THEN** system SHALL reject request with error message explaining MQA is only available for dati.gov.it
|
|
40
|
+
|
|
41
|
+
### Requirement: Output Formats
|
|
42
|
+
The system SHALL support both markdown and JSON output formats for quality metrics.
|
|
43
|
+
|
|
44
|
+
#### Scenario: Markdown format (default)
|
|
45
|
+
- **GIVEN** user does not specify response_format or specifies "markdown"
|
|
46
|
+
- **WHEN** quality metrics are retrieved
|
|
47
|
+
- **THEN** system SHALL return human-readable markdown with:
|
|
48
|
+
- Overall quality score
|
|
49
|
+
- Breakdown by dimension (accessibility, reusability, interoperability, findability)
|
|
50
|
+
- Key findings and recommendations
|
|
51
|
+
|
|
52
|
+
#### Scenario: JSON format
|
|
53
|
+
- **GIVEN** user specifies response_format as "json"
|
|
54
|
+
- **WHEN** quality metrics are retrieved
|
|
55
|
+
- **THEN** system SHALL return complete MQA API response as structured JSON
|
|
56
|
+
|
|
57
|
+
### Requirement: Tool Parameters
|
|
58
|
+
The system SHALL accept the following parameters for the MQA quality tool:
|
|
59
|
+
- server_url (required): Base URL of dati.gov.it portal
|
|
60
|
+
- dataset_id (required): Dataset ID or name
|
|
61
|
+
- response_format (optional): "markdown" (default) or "json"
|
|
62
|
+
|
|
63
|
+
#### Scenario: Minimal parameters
|
|
64
|
+
- **GIVEN** user provides only server_url and dataset_id
|
|
65
|
+
- **WHEN** tool is invoked
|
|
66
|
+
- **THEN** system SHALL use default markdown format
|
|
67
|
+
|
|
68
|
+
#### Scenario: All parameters specified
|
|
69
|
+
- **GIVEN** user provides server_url, dataset_id, and response_format
|
|
70
|
+
- **WHEN** tool is invoked
|
|
71
|
+
- **THEN** system SHALL use specified format for output
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Implementation Tasks
|
|
2
|
+
|
|
3
|
+
## 1. Core Implementation
|
|
4
|
+
- [x] 1.1 Create `src/tools/quality.ts` with `ckan_get_mqa_quality` tool handler
|
|
5
|
+
- [x] 1.2 Implement server URL validation (dati.gov.it only)
|
|
6
|
+
- [x] 1.3 Add CKAN package_show call to extract identifier field
|
|
7
|
+
- [x] 1.4 Add MQA API client (https://data.europa.eu/api/mqa/cache/datasets/{id})
|
|
8
|
+
- [x] 1.5 Implement markdown and JSON formatters for quality metrics
|
|
9
|
+
- [x] 1.6 Register tool in `src/server.ts`
|
|
10
|
+
|
|
11
|
+
## 2. Testing
|
|
12
|
+
- [x] 2.1 Create mock fixtures for CKAN package_show response
|
|
13
|
+
- [x] 2.2 Create mock fixtures for MQA API response
|
|
14
|
+
- [x] 2.3 Write integration tests for successful quality retrieval
|
|
15
|
+
- [x] 2.4 Write tests for error scenarios (invalid server, dataset not found, MQA API unavailable)
|
|
16
|
+
- [x] 2.5 Write tests for fallback from identifier to name field
|
|
17
|
+
- [x] 2.6 Verify test coverage matches project standards
|
|
18
|
+
|
|
19
|
+
## 3. Documentation
|
|
20
|
+
- [x] 3.1 Add tool description to README.md
|
|
21
|
+
- [x] 3.2 Add usage examples to EXAMPLES.md
|
|
22
|
+
- [x] 3.3 Document server restriction (dati.gov.it only)
|
|
23
|
+
- [x] 3.4 Document quality metrics structure (score, accessibility, reusability, interoperability, findability)
|
|
24
|
+
|
|
25
|
+
## 4. Validation
|
|
26
|
+
- [x] 4.1 Run full test suite (npm test) - 212 tests passing
|
|
27
|
+
- [x] 4.2 Test manually with real dati.gov.it dataset
|
|
28
|
+
- [x] 4.3 Verify error handling for non-dati.gov.it servers
|
|
29
|
+
- [x] 4.4 Build project successfully (npm run build)
|