CKAN MCP Server

Find Relevant CKAN Datasets

ckan_find_relevant_datasets

Read-onlyIdempotent

Finds relevant CKAN datasets without manual filtering. Ranks results by weighted matches in titles, tags, descriptions, and publishers.

Instructions

Find and rank datasets by relevance to a query using weighted fields.

Use this instead of ckan_package_search when you want relevance-ranked results with explicit scoring across title, notes, tags, and organization fields. Use ckan_package_search instead when you need Solr filter syntax, facets, or pagination.

Uses package_search for discovery and applies a local scoring model.

Args:

server_url (string): Base URL of CKAN server (e.g., "https://dati.gov.it/opendata")
query (string): Natural language or keyword query (e.g., "mobilità urbana", "air quality")
limit (number): Number of datasets to return (default: 10)
weights (object): Field weights for scoring — higher weight = more influence on rank Default: title=4, tags=3, notes=2, organization=1, holder=4, publisher=2, coverage=4 coverage: bonus for datasets the portal returned with every query term required (Solr mm=100%); these are fetched first, the rest fills in when they are fewer than limit Note on holder vs organization: on federated catalogs (e.g. dati.gov.it), organization is the harvesting catalog (e.g. Regione Puglia), while holder (DCAT-AP_IT dct:rightsHolder) is the actual data owner (e.g. Comune di Lecce). Queries like "datasets from a specific Comune" match holder correctly; matching only organization misses datasets harvested via aggregators. publisher (dct:publisher) is scored separately at lower weight as it can contain technical roles ("Redazione OD") rather than the institutional owner.
query_parser ('default' | 'text'): Override search parser behavior
response_format ('markdown' | 'json'): Output format

Returns: Ranked datasets with relevance scores and per-field score breakdowns

Examples:

{ server_url: "https://dati.gov.it/opendata", query: "mobilità" }
{ server_url: "...", query: "trasporti", limit: 5, weights: { title: 5, notes: 2 } }
{ server_url: "...", query: "defibrillatori Comune di Lecce", weights: { holder: 5 } }

Typical workflow: ckan_find_relevant_datasets → ckan_package_show (inspect top results) → ckan_datastore_search (query data)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Number of datasets to return
`query`	Yes	Natural language or keyword query to match against dataset title, notes, tags, organization, holder and publisher
`weights`	No	Per-field scoring weights; unspecified fields use defaults
`server_url`	Yes	Base URL of the CKAN server (e.g., https://dati.gov.it/opendata)
`query_parser`	No	Override search parser ('text' forces text:(...) on non-fielded queries)
`response_format`	No	Output format: 'markdown' for human-readable or 'json' for machine-readable	markdown

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.4.124Sep 8, 2026

addedInput schema / properties / weights / properties / coverage

Added value: +{
+  "description": "Bonus for datasets the portal returned with every query term required (default 4)",
+  "minimum": 0,
+  "type": "number"
+}

First observedv0.4.108Jun 30, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds valuable behavioral detail beyond that: it uses package_search for discovery, applies a local scoring model, fetches coverage-matched datasets first, and fills remaining slots when they are fewer than the limit. The detailed explanation of holder vs organization on federated catalogs is particularly useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: purpose, routing guidance, parameter semantics, return value summary, examples, and workflow. The most important scoping and alternative-selection information is front-loaded, with detailed parameter nuance placed later where it belongs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, including six parameters and a nested weights object, the description is complete enough for an agent to call it correctly. It explains return values, provides realistic examples, documents the default weight behavior, and clarifies domain-specific edge cases like federated catalogs. The absence of an output schema is adequately compensated by the return-value summary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Even though schema coverage is 100%, the description adds meaning that the schema alone does not provide, such as default weights for every scoring field, the semantic difference between holder, organization, and publisher, and how the coverage bonus behaves. The query_parser and response_format parameters are also contextualized in the examples and return description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: find and rank datasets by relevance to a query using weighted fields. It clearly distinguishes itself from ckan_package_search by naming the scoring and ranking behavior, which lets an agent understand exactly what this tool adds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool instead of ckan_package_search, and also explains when to switch back to ckan_package_search for Solr syntax, facets, or pagination. The typical workflow sentence adds further routing context by showing how this tool fits with ckan_package_show and ckan_datastore_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Find Relevant CKAN Datasets

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools