fix(skill): correct europa.eu SPARQL and CKAN API documentation

- CKAN endpoint exists at /api/hub/search/ckan/ (not /api/3/action/)
- ckan_package_search MCP tool cannot use it (wrong path suffix)
- fq=country:XX returns 0 on CKAN endpoint (country nested in org)
- SPARQL country filter via skos:exactMatch does not work (blank nodes)
- Replace broken SPARQL examples with tested ones (theme, file type)
- REST API via Bash is the only reliable country-filtered method

Author: aborruso

skills/ckan-mcp/SKILL.md

@@ -89,11 +89,15 @@ See [references/europa-api.md](references/europa-api.md) for full API patterns.
 - `country=XX` filter is not strict — results may include nearby countries (e.g. BE, CH when filtering FR)
 - Many datasets lack English titles → use `lang=XX` matching the target country
 - Filter results post-fetch by `country.id` to remove off-target countries
-- Prefer `sparql_query` when exact country filtering is required
 
-**When to use REST vs SPARQL**:
-- REST (`Bash` + curl): fast broad discovery, when approximate results are acceptable
-- SPARQL (`sparql_query`): exact country filter, date ranges, thematic filtering
+**SPARQL limitations on data.europa.eu**:
+- The endpoint is reachable and returns results for generic queries
+- Country filtering via `dct:spatial` + `skos:exactMatch` does **NOT** work — spatial values are blank nodes, not URIs
+- Do not use `sparql_query` for country-filtered searches on this portal
+- `sparql_query` is only useful for schema exploration or generic graph queries
+
+**Default tool: always REST API via Bash**:
+- REST is the only reliable method for country-filtered searches on data.europa.eu
 
 ```
 Example: "Trova dati ambientali per Italia e Spagna"
@@ -103,9 +107,6 @@ Example: "Dati aperti francesi sull'energia"
 -> NOTE: data.gouv.fr is NOT CKAN
 -> Bash: curl "https://data.europa.eu/api/hub/search/search?q=energie+energy&country=FR&lang=fr&limit=10"
 -> Filter post-fetch: keep only items where country.id == "fr"
-
-Example: "Dataset recenti sull'ambiente dal portale europeo" (precise)
--> sparql_query(query="...", endpoint="https://data.europa.eu/sparql")
 ```
 
 ### Flow D — Dataset Detail + DataStore

skills/ckan-mcp/references/europa-api.md

@@ -84,35 +84,41 @@ curl "https://data.europa.eu/api/hub/search/search?q=*&facets=country&limit=0"
 
 ## CKAN-Compatible API
 
-data.europa.eu also exposes a CKAN-compatible endpoint:
+A CKAN-compatible endpoint exists at:
 
 ```
-POST https://data.europa.eu/ckan/api/3/action/package_search
+GET https://data.europa.eu/api/hub/search/ckan/package_search
+GET https://data.europa.eu/api/hub/search/ckan/package_show?id=DATASET_ID
 ```
 
-Use via MCP tool:
+**Cannot be used via `ckan_package_search` MCP tool** — the tool appends `/api/3/action/package_search` which does not exist on this portal (returns 404).
 
-```
-ckan_package_search(
-  server_url="https://data.europa.eu/ckan",
-  q="environment",
-  fq="country:IT"
-)
+**Country filtering does not work** — `fq=country:FR` returns 0 results. Country info is nested inside `organization.country` in the response, not a top-level filterable field.
+
+To use this endpoint, call it directly via Bash:
+
+```bash
+curl "https://data.europa.eu/api/hub/search/ckan/package_search?q=water+quality&rows=10"
 ```
 
+For country-filtered searches, use the REST API instead (see above).
+
 ## SPARQL Endpoint
 
 For structured linked-data queries using RDF/DCAT vocabulary.
 
 ```
 Endpoint: https://data.europa.eu/sparql
 Method: POST
-Content-Type: application/x-www-form-urlencoded
-Body: query=SELECT...&format=application/sparql-results+json
 ```
 
 Use via MCP tool: `sparql_query(query="...", endpoint="https://data.europa.eu/sparql")`
 
+**SPARQL limitations**:
+- Country filtering via `dct:spatial` + `skos:exactMatch` does **NOT** work — spatial values on datasets are blank nodes, not country URIs
+- For country-filtered searches, use the REST API via Bash (the only reliable method)
+- SPARQL is useful for: theme filtering, file type filtering, specific dataset/distribution lookup
+
 ### Common Prefixes
 
 ```sparql
@@ -124,35 +130,48 @@ PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
 PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>
 ```
 
-### Example Queries
+### Example Queries (tested and working)
 
 ```sparql
--- Datasets about environment from Italy, English titles
-SELECT ?dataset ?title ?issued WHERE {
-  ?dataset a dcat:Dataset ;
-           dct:title ?title ;
-           dct:issued ?issued ;
-           dct:spatial ?spatial .
-  ?spatial skos:exactMatch <http://publications.europa.eu/resource/authority/country/ITA> .
-  FILTER(LANG(?title) = "en")
-  FILTER(CONTAINS(LCASE(STR(?title)), "environment"))
+-- Datasets by EU theme (Environment), with publisher and keywords
+SELECT DISTINCT ?datasetURI ?datasetTitle ?publisher (GROUP_CONCAT(?keyword; SEPARATOR = " | ") AS ?keywords)
+WHERE {
+  ?datasetURI a dcat:Dataset;
+    dct:publisher/rdfs:label|dct:publisher/skos:prefLabel ?publisher;
+    dcat:theme <http://publications.europa.eu/resource/authority/data-theme/ENVI>;
+    dcat:keyword ?keyword;
+    dct:title ?datasetTitle.
+  FILTER(LANG(?datasetTitle)= "" || LANG(?datasetTitle) = "en").
+  FILTER (LANG(?publisher) = "" || LANG(?publisher) = "en").
+}
+ORDER BY ?datasetURI
+LIMIT 10
+```
+
+```sparql
+-- Distributions of a specific file type (e.g. XML)
+SELECT DISTINCT ?datasetURI ?accessURL ?OPLabel
+WHERE {
+  ?datasetURI a dcat:Dataset;
+    dcat:distribution ?distributionURI.
+  ?distributionURI dcat:accessURL ?accessURL;
+    dct:format ?OPFileType. FILTER(?OPFileType=<http://publications.europa.eu/resource/authority/file-type/XML>)
+  ?OPFileType skos:prefLabel ?OPLabel. FILTER(LANGMATCHES(LANG(?OPLabel),"en"))
 }
-ORDER BY DESC(?issued)
+ORDER BY ?datasetURI
 LIMIT 10
 ```
 
+### What does NOT work in SPARQL
+
 ```sparql
--- Count datasets per country for a topic
-SELECT ?country (COUNT(?dataset) AS ?count) WHERE {
+-- BROKEN: country filter via skos:exactMatch — returns 0 results
+-- dct:spatial on datasets uses blank nodes, not country URIs
+SELECT ?dataset ?title WHERE {
   ?dataset a dcat:Dataset ;
-           dct:title ?title ;
            dct:spatial ?spatial .
-  ?spatial skos:exactMatch ?country .
-  FILTER(CONTAINS(LCASE(STR(?title)), "climate"))
+  ?spatial skos:exactMatch <http://publications.europa.eu/resource/authority/country/ITA> .
 }
-GROUP BY ?country
-ORDER BY DESC(?count)
-LIMIT 20
 ```
 
 ## EU Data Themes