User asks about data
  |
  +-- Knows the portal URL? ---------> Flow B (Named Portal)
  |
  +-- Mentions a country? -----------> Flow A (Country Search)
  |
  +-- EU / multi-country / France? --> Flow C (European Portal)
  |
  +-- Asks about dataset content? ---> Flow D (Dataset Detail + DataStore)
  |
  +-- Asks about publishers/groups? -> Flow E (Orgs / Groups)
  |
  +-- Asks about data quality? ------> Flow F (Quality)
  |
  +-- Wants best/most relevant? -----> Flow G (Relevance Ranking + Analysis)
  |
  +-- Wants to schema/annotate data? -> Flow H (Ontology & Schema Discovery)

Flows

Flow A — Country Search

Use when: user mentions a country but no specific portal URL.

ckan_find_portals(country=COUNTRY) to discover known CKAN portals
Identify the most authoritative portal (usually national/federal, largest dataset count)
ckan_status_show to verify it is reachable
- If it fails: tell the user explicitly — e.g. "The national portal (X) is unreachable or not a valid CKAN instance. Trying alternative portals..." — then try the next portals from the list
- If ckan_find_portals returns no national portal: tell the user — e.g. "No national CKAN portal was found for this country. Searching available regional/local portals..."
ckan_package_search(q="TERM_NATIVE OR TERM_EN") on the first reachable portal

If all CKAN portals return 0 results and the country is European: fall back to data.europa.eu using the two-step approach (see references/europa-api.md):

Step 1: find catalogues for the country

curl "https://data.europa.eu/api/hub/search/search?q=&filter=catalogue&facetOperator=AND&facetGroupOperator=AND&facets=%7B%22superCatalog%22%3A%5B%5D%2C%22country%22%3A%5B%22xx%22%5D%7D&limit=20"

Step 2: search datasets by catalog ID(s) found in step 1

curl "https://data.europa.eu/api/hub/search/search?q=QUERY&filter=dataset&facetOperator=AND&facetGroupOperator=AND&facets=%7B%22superCatalog%22%3A%5B%5D%2C%22catalog%22%3A%5B%22catalog-id%22%5D%7D&limit=10"

If step 1 returns 0 catalogues, try the direct country filter on datasets as fallback. Country code must be lowercase (e.g. "pt", "fr", "it").

Always summarize which portal was actually used and why (national CKAN / regional CKAN / data.europa.eu fallback)

Example: "What data on pollution is available in Canada?"
-> ckan_find_portals(country="Canada")
-> ckan_status_show(server_url="https://open.canada.ca/data")
-> ckan_package_search(server_url=..., q="pollution OR air quality")

Example: national portal unreachable
-> ckan_find_portals(country="Argentina")
-> ckan_status_show(national_portal) -> FAIL
-> [tell user] "The national portal (X) is unreachable. Trying available regional portals..."
-> ckan_status_show(next_portal) -> OK
-> ckan_package_search(server_url=next_portal, ...)
-> [tell user] "Results found on the Buenos Aires Province portal (not the national portal)."

Example: no national CKAN portal, European country, 0 results on regional portals
-> ckan_find_portals(country="Portugal") -> 3 regional portals, no national
-> ckan_package_search on all 3 -> 0 results
-> [tell user] "No results on Portuguese CKAN portals. Searching data.europa.eu..."
-> Bash: curl "...?q=acidentes+rodoviarios&filter=dataset&facets=%7B%22country%22%3A%5B%22pt%22%5D%7D&limit=10"
-> 157 results found on data.europa.eu
-> [tell user] "Found 157 datasets on data.europa.eu (country filter: PT)."

Flow B — Named Portal

Use when: user provides a specific portal URL or a well-known portal name.

ckan_status_show to verify the portal
(optional) ckan_catalog_stats — call this when the user wants a general overview of the portal (total datasets, organizations, tags, formats) before searching, or when they ask "what's on this portal?" / "how big is it?"
ckan_package_search(q="TERM_NATIVE OR TERM_EN")
If >100 results, guide refinement with fq filters or a narrower query

Example: "Find transport data on data.gov.uk"
-> ckan_status_show(server_url="https://data.gov.uk")
-> ckan_package_search(server_url="https://data.gov.uk", q="transport OR transportation")

Flow C — European Portal

Use when: user mentions EU-wide data, multi-country comparison, OR France (data.gouv.fr is NOT CKAN — always redirect to data.europa.eu).

IMPORTANT — tool choice:

ckan_package_search does NOT work on data.europa.eu (returns 404) — never use it here
For text search: use Bash with the REST API https://data.europa.eu/api/hub/search/search
For precise/structured queries: use sparql_query(endpoint="https://data.europa.eu/sparql")

Query language — EU-wide vs country-specific:

EU-wide (no country filter): use English terms only — multilingual queries overweight countries with more native-language datasets (e.g. IT dominates with Italian terms)
Country-specific (with catalogue filter): use native language terms for that country

See references/europa-api.md for full API patterns.

REST API known limitations:

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

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

Recommended country search — two-step via catalogue:

Find catalogues for the country: filter=catalogue&facets={"superCatalog":[],"country":["xx"]}
Search datasets by catalog ID: filter=dataset&facets={"superCatalog":[],"catalog":["catalog-id"]} This is more reliable than the direct country facet on datasets, which returns 0 for some countries (e.g. Denmark, Germany, Poland). If step 1 returns 0 catalogues, fall back to direct country filter on datasets.

Multi-country via catalogue — run one query per country: When querying multiple countries via their catalogues, do NOT mix catalogue IDs in a single query with a combined multilingual query string — it returns 0 results. Run one query per country, using native language terms for each:

DE → GovData catalogue + German terms
PL → dane.gov.pl catalogue + Polish terms Then merge and present results together.

Publisher catalog URL: Each dataset result contains a catalog.id field (e.g. "eige", "dane-gov-pl"). Use it to build a direct link to all datasets from that publisher on data.europa.eu:

https://data.europa.eu/data/datasets?locale=en&catalog={catalog.id}

Always include this link when showing results from data.europa.eu — it lets the user browse all datasets from the same publisher without extra queries.

Example: dataset with catalog.id = "eige"
→ Publisher page: https://data.europa.eu/data/datasets?locale=en&catalog=eige

Example: "Find environmental data for Italy and Spain"
-> Bash: curl "https://data.europa.eu/api/hub/search/search?q=environment&filter=dataset&facetOperator=OR&facets=%7B%22country%22%3A%5B%22it%22%2C%22es%22%5D%7D&limit=10"

Example: "French open data on energy"
-> NOTE: data.gouv.fr is NOT CKAN
-> Bash: curl "https://data.europa.eu/api/hub/search/search?q=energy&filter=dataset&facets=%7B%22country%22%3A%5B%22fr%22%5D%7D&limit=10"

Flow D — Dataset Detail + DataStore

Use when: user asks about the content of a specific dataset or wants to query tabular data.

ckan_package_show(id=DATASET_ID) — full metadata
ckan_list_resources(dataset_id=DATASET_ID) — list files/resources
Check datastore_active: true on resources
If DataStore is available:
- ckan_datastore_search(resource_id=..., limit=0) — discover columns
- ckan_datastore_search(resource_id=..., q=..., limit=100) — query data
If no DataStore — check source portal first (harvested datasets): Many national/regional aggregators (e.g. dati.gov.it) harvest datasets from municipal or regional portals but do not replicate the DataStore. The resource download URLs often contain the source portal domain, dataset ID, and resource ID.
- Inspect resource URLs: if the domain differs from server_url, extract the source portal URL (e.g. https://dati.comune.milano.it)
- Extract the dataset ID and resource ID from the URL path
- Call ckan_list_resources(server_url=SOURCE_PORTAL, id=SOURCE_DATASET_ID) to check if DataStore is active there
- If yes, use ckan_datastore_search(server_url=SOURCE_PORTAL, resource_id=SOURCE_RESOURCE_ID, ...)
- Tell the user that data is being queried from the source portal, not the aggregator
If still no DataStore: analyze the resource URL directly with DuckDB (works for CSV, JSON, Parquet over HTTP):
```
duckdb -c "COPY (DESCRIBE SELECT * FROM read_csv('URL')) TO '/dev/stdout' (FORMAT JSON)"
duckdb -c "COPY (SUMMARIZE SELECT * FROM read_csv('URL')) TO '/dev/stdout' (FORMAT JSON)"
duckdb -c "COPY (SELECT * FROM read_csv('URL') USING SAMPLE 10) TO '/dev/stdout' (FORMAT JSON)"
```
For non-CSV formats use read_json('URL') or read_parquet('URL'). If the resource is not directly queryable (HTML, PDF, zip), provide the download URL and tell the user they need to open it locally.

Example: "Show me the data in dataset clima-2024"
-> ckan_package_show(server_url=..., id="clima-2024")
-> ckan_list_resources(server_url=..., dataset_id="clima-2024")
-> [if datastore_active] ckan_datastore_search(resource_id=..., limit=0)
-> ckan_datastore_search(resource_id=..., q="...", limit=100)

Example: dataset harvested from source portal, no DataStore on aggregator
-> ckan_list_resources(server_url="https://dati.gov.it/opendata", id="dataset-xyz")
-> datastore_active: No — resource URL: https://dati.comune.milano.it/dataset/abc/resource/def/download/...
-> [extract] source_portal="https://dati.comune.milano.it", dataset_id="abc", resource_id="def"
-> ckan_list_resources(server_url="https://dati.comune.milano.it", id="abc")
-> datastore_active: Yes → ckan_datastore_search(server_url="https://dati.comune.milano.it", resource_id="def", limit=0)
-> [tell user] "DataStore not available on dati.gov.it — querying source portal dati.comune.milano.it directly."

Flow E — Organizations and Groups

Use when: user asks about publishers, organizations, thematic categories, or groups.

# Discover publishers
ckan_organization_list(server_url=...)

# Find a specific publisher
ckan_organization_search(server_url=..., query="ministry")

# Show publisher + their datasets
ckan_organization_show(server_url=..., id="org-name")

# Thematic categories
ckan_group_list(server_url=...)
ckan_group_search(server_url=..., query="environment")
ckan_group_show(server_url=..., id="group-name")

Flow F — Data Quality

Use when: user asks about data quality, MQA score, or metadata completeness.

Portal scope: MQA tools currently work only with dati.gov.it. Do not use them on any other portal — they will return an error or no result.

ckan_get_mqa_quality(dataset_id=..., server_url=...) — overall score
ckan_get_mqa_quality_details(dataset_id=..., server_url=...) — dimension breakdown

Example: "What is the metadata quality of this dataset?"
-> ckan_get_mqa_quality(server_url=..., dataset_id="...")
-> ckan_get_mqa_quality_details(server_url=..., dataset_id="...")

Flow G — Relevance Ranking + Analysis

Use when: user wants the "most relevant" or "best" datasets for a topic, or wants to compare and analyze multiple datasets together.

ckan_package_search ranks by Solr score, which is good for broad discovery but does not re-rank by field importance. Use ckan_find_relevant_datasets when the user wants results prioritized by how well the title, tags, and description match their query — not just keyword hits. Use ckan_analyze_datasets when the user wants a structured comparison of several datasets (e.g., coverage, formats, publishers).

Example: "Find the most relevant datasets on air pollution in Italy"
-> ckan_find_relevant_datasets(server_url="https://www.dati.gov.it/opendata",
                               query="air pollution OR inquinamento aria")

Example: "Compare these three traffic datasets"
-> ckan_analyze_datasets(server_url=..., dataset_ids=[...])

When to prefer over ckan_package_search:

User says "most relevant", "best match", "top results"
ckan_package_search returns many loosely-matched results and you need to surface the closest ones
User wants a comparison or summary across multiple datasets

Flow H — Ontology & Schema Discovery

Use when: the user wants to define a schema for a dataset, find existing standards for their domain, discover controlled vocabularies, or map dataset fields to semantic terms (DCAT, GeoSPARQL, Schema.org, SSN, Data Cube, etc.).

This is relevant when the user:

asks "which ontology should I use for X?"
wants to make their data interoperable or linked-data ready
needs field names aligned with existing W3C/OGC/EU standards
asks "is there a vocabulary for X?"

Tool: query the Open Knowledge Graphs API via Bash with curl.

# Search ontologies for a domain
curl -s "https://api.openknowledgegraphs.com/ontologies?q=TOPIC&limit=5" | jq .

# Narrow to a category (Government & Public Sector, Geospatial, Environment & Agriculture, ...)
curl -s "https://api.openknowledgegraphs.com/ontologies?q=TOPIC&category=CATEGORY&limit=5" | jq .

# Search across all types (ontologies + software)
curl -s "https://api.openknowledgegraphs.com/search?q=TOPIC&limit=5" | jq .

See references/open-knowledge-graphs.md for the full API reference and a complete end-to-end example (air quality sensor dataset → SSN/SOSA ontology → field mapping).

Example: "I have a CSV with sensor readings — what schema should I use?"
-> curl "https://api.openknowledgegraphs.com/ontologies?q=sensor+observation+measurement&limit=5"
-> top result: SSN/SOSA (W3C) — score 0.69
-> follow homepage: https://www.w3.org/TR/vocab-ssn/
-> map CSV columns to sosa:Observation, sosa:Sensor, sosa:resultTime, sosa:hasResult

Example: "Which vocabulary covers open government datasets?"
-> curl "https://api.openknowledgegraphs.com/ontologies?q=open+data+government&limit=5"
-> results: DCAT, NIEMOpen, Core Organization Ontology
-> recommend DCAT (W3C) for dataset metadata, schema.org for web publishing

Key Rules

Query Construction

Always check the portal's locale before searching: call ckan_status_show and read the Portal Locale field (locale_default). Translate query terms to that language. Searching in English on a non-English portal returns 0 results.
- it / it_IT → Italian only
- uk_UA → Ukrainian (Cyrillic) only
- de_DE → German only
- en / en_US / en_GB → English only
- fr_FR → French only
- Exception: multilingual portals (data.europa.eu, open.canada.ca) → use EN + native terms joined with OR
Example (multilingual): q="environment OR ambiente OR environnement"
Example (monolingual IT): q="qualità aria" — no English needed

Geographic qualifiers are never OR-joined: city/region/country names go in fq or AND-ed in q, never in the OR pool.

# Correct — topic bilingue, place as filter
q="qualità aria OR air quality"  fq="organization:comune-di-milano"

# Wrong — OR-joining a place name explodes results with off-topic datasets
q="qualità aria OR air quality OR Milano"

Use Solr fq for hard filters: fq="organization:regione-toscana"
Wildcard for broad match: q="trasport*" (matches trasporto, trasporti, transport...)
Use ckan_tag_list to discover available tags on a portal before building tag-based filters — then use fq="tags:TAG" to narrow results precisely.

Long OR queries — parser issue: some portals use a restrictive default parser that silently breaks multi-term OR queries (returns 0 results). If a complex OR query returns 0, retry with query_parser: "text":

ckan_package_search(server_url=..., q="hotel OR alberghi OR ospitalita", query_parser="text")

fq OR syntax — critical: OR on the same field must use field:(val1 OR val2), NOT field:val1 OR field:val2 (the latter silently returns the entire catalog).

# Correct
fq: "res_format:(CSV OR JSON)"
fq: "organization:(comune-palermo OR comune-roma)"

# Wrong — silently ignored, returns entire catalog
fq: "res_format:CSV OR res_format:JSON"

Portal Verification

Call ckan_status_show before searching any portal not previously confirmed
If it fails, call ckan_find_portals to find the correct URL

Country-to-Portal Mapping

Country/Scope	Portal	Note
Italy	dati.gov.it	Primary
France	data.europa.eu	data.gouv.fr is NOT CKAN
USA	catalog.data.gov
Canada	open.canada.ca/data
UK	data.gov.uk
EU / multi-country	data.europa.eu	Default for cross-border

Date Semantics

User says	Field to use
"recent", "latest" (ambiguous)	`content_recent: true` or sort `metadata_modified desc`
"published after DATE"	`fq="issued:[DATE TO *]"`
"added to portal after DATE"	`fq="metadata_created:[DATE TO *]"`

Result Volume

100 results: guide user to refine — add fq filter, format, org, date range
0 results: broaden query, remove filters, try synonyms, try different portal

Data Integrity

Never invent dataset names, IDs, URLs, or statistics
Report only what MCP tools return
If DataStore is absent on an aggregator portal, always check the source portal first (see Flow D step 5) before falling back to direct download

Tool Quick Reference

Tool	Purpose
`ckan_find_portals`	Find known CKAN portals by country
`ckan_status_show`	Verify portal reachability and version
`ckan_package_search`	Search datasets (Solr syntax)
`ckan_package_show`	Full dataset metadata
`ckan_list_resources`	List files/resources in a dataset
`ckan_find_relevant_datasets`	Smart relevance-ranked search
`ckan_analyze_datasets`	Analyze and compare datasets
`ckan_catalog_stats`	Portal-level statistics
`ckan_datastore_search`	Query tabular data by filters
`ckan_datastore_search_sql`	SQL on tabular DataStore data
`ckan_organization_list`	List all publishers
`ckan_organization_show`	Publisher details + their datasets
`ckan_organization_search`	Find publishers by name pattern
`ckan_group_list`	List thematic groups/categories
`ckan_group_show`	Group details + datasets
`ckan_group_search`	Find groups by name pattern
`ckan_tag_list`	List available tags on a portal
`ckan_get_mqa_quality`	MQA overall quality score
`ckan_get_mqa_quality_details`	MQA dimension-by-dimension breakdown
`sparql_query`	SPARQL on data.europa.eu and dati.gov.it

SPARQL via curl

When using sparql_query is not enough or you need to debug a query directly, use curl.

GET vs POST: the tool picks the HTTP method from portals.json when the endpoint is known. lod.dati.gov.it/sparql is configured as GET. All other endpoints default to POST, with automatic fallback to GET on 403/405.

Critical: lod.dati.gov.it/sparql requires GET method and a browser-like User-Agent — without the correct User-Agent the endpoint returns 403.

# dati.gov.it — GET method, User-Agent required
curl -s -G "https://lod.dati.gov.it/sparql" \
  --data-urlencode "query=SELECT ?dataset ?title WHERE {
    ?dataset a <http://www.w3.org/ns/dcat#Dataset> ;
             <http://purl.org/dc/terms/title> ?title .
    FILTER(CONTAINS(LCASE(STR(?title)), \"popolazione\"))
  } LIMIT 10" \
  -H "Accept: application/sparql-results+json" \
  -H "User-Agent: Mozilla/5.0 (compatible; CKAN-MCP-Server/1.0)"

# data.europa.eu — POST with raw SPARQL body (Content-Type: application/sparql-query)
curl -s -X POST "https://data.europa.eu/sparql" \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: application/sparql-results+json" \
  --data-raw "SELECT ?s WHERE { ?s a <http://www.w3.org/ns/dcat#Dataset> } LIMIT 5"

Reference Files

references/europa-api.md — Read this for any query involving data.europa.eu: REST API patterns, country filtering, SPARQL examples, EU data themes and country codes.
references/tools.md — Full ckanapi CLI equivalents for every MCP tool, with jq formatting patterns and DuckDB analysis examples. Read this when you need to replicate or extend tool behavior via Bash, or when the user needs to explore CSV resources directly.
references/hvd.md — High Value Datasets (EU Regulation 2023/138): API filters, the 6 thematic categories and sub-categories, country breakdowns, and HVD on national CKAN portals. Read this when the user asks about HVD or "dati ad alto valore".
references/open-knowledge-graphs.md — Open Knowledge Graphs API: semantic search over 1,800+ ontologies, vocabularies, and taxonomies. Read this when the user wants to find existing schemas for a dataset, discover controlled vocabularies, adopt W3C/OGC standards (DCAT, SSN, GeoSPARQL...), or map dataset fields to semantic terms.

ckan-mcp

CKAN MCP Skill

Security

Decision Tree