@aborruso/ckan-mcp-server 0.4.6 → 0.4.8

package/openspec/changes/update-search-parser-config/proposal.md

@@ -0,0 +1,13 @@
+# Change: Update CKAN search parser handling per portal
+
+## Why
+Some CKAN portals (notably dati.gov.it) use a default edismax parser with restrictive `mm` settings that breaks long OR queries. For those portals, the Lucene standard parser on the `text` field yields correct results.
+
+## What Changes
+- Add per-portal search configuration to `src/portals.json` to force `text:(...)` queries where needed.
+- Add an optional tool override to force the text-field parser regardless of portal defaults.
+- Update tool documentation to describe the behavior and override.
+
+## Impact
+- Affected specs: `ckan-insights`, new `ckan-search` capability
+- Affected code: `src/portals.json`, `src/tools/package.ts`, `src/utils/*` (if new helper is added)

package/openspec/changes/update-search-parser-config/specs/ckan-insights/spec.md

@@ -0,0 +1,11 @@
+## MODIFIED Requirements
+### Requirement: Find relevant datasets
+The system SHALL provide a `ckan_find_relevant_datasets` tool that accepts `server_url`, `query`, `limit`, optional weights for title, notes, tags, and organization, and an optional search parser override, and returns the top N datasets ranked by score with a per-field score breakdown.
+
+#### Scenario: Ranked results returned
+- **WHEN** the tool is invoked with a query and limit
+- **THEN** the system uses `package_search` results to return the top N datasets with numeric scores and field contributions
+
+#### Scenario: Search parser override applied
+- **WHEN** the tool is invoked with a search parser override
+- **THEN** the system applies the override to the underlying `package_search` query

package/openspec/changes/update-search-parser-config/specs/ckan-search/spec.md

@@ -0,0 +1,11 @@
+## ADDED Requirements
+### Requirement: Package search parser override
+The system SHALL support a per-portal default and a per-request override to force package search queries through the `text` field when needed.
+
+#### Scenario: Portal default applies
+- **WHEN** a portal is configured to force the text-field parser
+- **THEN** `ckan_package_search` uses `text:(...)` for non-fielded queries by default
+
+#### Scenario: Request override applies
+- **WHEN** a client explicitly requests the text-field parser
+- **THEN** `ckan_package_search` uses `text:(...)` regardless of portal defaults

package/openspec/changes/update-search-parser-config/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [x] 1.1 Add per-portal search config for forcing text-field parser
+- [x] 1.2 Add tool override input and apply parser selection in package search
+- [x] 1.3 Apply same override logic in find-relevant datasets
+- [x] 1.4 Update tool docs and examples
+- [x] 1.5 Add/adjust tests if present for query handling

package/openspec/project.md

@@ -22,24 +22,25 @@ Exposes MCP tools for:
 
 ### Code Style
 - TypeScript strict mode enabled
-- Single-file architecture (src/index.ts)
-- Utility functions for reusable operations (makeCkanRequest, truncateText, formatDate, formatBytes)
+- Modular tool files in `src/tools/*`
+- Utility functions for reusable operations (makeCkanRequest, truncateText, formatDate)
 - Zod schemas for strict input validation (reject extra parameters)
 - Italian locale for date formatting (it-IT)
 - Markdown output optimized for human readability; JSON available for programmatic use
 
 ### Architecture Patterns
-- **Single-file MCP server** - all logic in src/index.ts
-- **Tool-based architecture** - 7 registered MCP tools for CKAN operations
-- **Dual transport modes**:
+- **Modular MCP server** - registration in `src/server.ts`
+- **Tool-based architecture** - 13 registered MCP tools for CKAN operations
+- **Multiple transport modes**:
   - stdio (default) - for local MCP client integration
   - HTTP - for remote access via POST /mcp endpoint
+  - Cloudflare Workers - `/mcp` endpoint in `src/worker.ts`
 - **Read-only operations** - no data modification on CKAN
 - **No caching** - fresh API calls for each request
 - **Error handling** - HTTP errors, timeouts, server validation
 
 ### Testing Strategy
-- **No automated tests currently** (consider adding for critical tools)
+- **Automated tests** with Vitest (integration fixtures)
 - Manual testing:
   - stdio mode: direct integration testing with Claude Desktop
   - HTTP mode: curl-based testing against localhost endpoint
@@ -67,6 +68,7 @@ Exposes MCP tools for:
 - Output truncated to 50000 characters max (hardcoded)
 - Dates formatted in Italian locale
 - File sizes in human-readable format
+- `server_url` for Italy uses `https://dati.gov.it/opendata`
 
 ## Important Constraints
 
@@ -91,7 +93,7 @@ Exposes MCP tools for:
 
 ### CKAN Portals
 Major supported portals:
-- 🇮🇹 https://dati.gov.it (Italia)
+- 🇮🇹 https://dati.gov.it/opendata (Italia)
 - 🇺🇸 https://catalog.data.gov (United States)
 - 🇨🇦 https://open.canada.ca/data (Canada)
 - 🇬🇧 https://data.gov.uk (United Kingdom)

package/openspec/specs/ckan-insights/spec.md

@@ -2,7 +2,6 @@
 
 ## Purpose
 Describe dataset insight tools (relevance, freshness, structure) once implemented.
-
 ## Requirements
 ### Requirement: Insights capability reserved
 The system SHALL maintain this specification to document dataset insight tools when they are added.
@@ -10,3 +9,11 @@ The system SHALL maintain this specification to document dataset insight tools w
 #### Scenario: Insight tools documented
 - **WHEN** new insight tools are implemented
 - **THEN** their requirements are captured in this specification
+
+### Requirement: Find relevant datasets
+The system SHALL provide a `ckan_find_relevant_datasets` tool that accepts `server_url`, `query`, `limit`, and optional weights for title, notes, tags, and organization, and returns the top N datasets ranked by score with a per-field score breakdown.
+
+#### Scenario: Ranked results returned
+- **WHEN** the tool is invoked with a query and limit
+- **THEN** the system uses `package_search` results to return the top N datasets with numeric scores and field contributions
+

package/package.json

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

package/web-gui/PRD.md

@@ -0,0 +1,158 @@
+# CKAN Open Data Explorer
+
+**Versione**: 1.0
+**Data**: 25 luglio 2024
+
+---
+
+## 1. Introduzione
+
+"CKAN Open Data Explorer" è un'applicazione web frontend progettata per facilitare l'interazione con portali Open Data basati su CKAN, sfruttando un'interfaccia di chat in linguaggio naturale potenziata dall'API Gemini. L'obiettivo principale è rendere l'esplorazione dei dataset e delle risorse Open Data più accessibile e intuitiva per gli utenti, eliminando la necessità di navigare direttamente le interfacce complesse dei portali CKAN o di formulare query API specifiche.
+
+---
+
+## 2. Obiettivi del Prodotto
+
+- **Semplificare l'accesso ai dati**: Permettere agli utenti di trovare e comprendere i dataset Open Data utilizzando domande e comandi in linguaggio naturale
+- **Migliorare l'esperienza utente**: Fornire un'interfaccia conversazionale fluida e reattiva che guida l'utente attraverso il processo di ricerca dati
+- **Abilitare l'interazione tool-driven**: Utilizzare il modello Gemini per orchestrare chiamate a un server MCP (Microservice Controller Proxy) che a sua volta interagisce con i portali CKAN
+- **Gestire errori comuni**: Fornire feedback chiari e gestibili per errori di connessione al server MCP o problemi di quota dell'API Gemini
+- **Configurabilità**: Consentire agli utenti di configurare l'endpoint del server MCP per adattarsi a diversi ambienti o istanze
+
+---
+
+## 3. Utenti Target / Personas
+
+- **Ricercatori e Analisti Dati (Principianti)**: Cercano dati specifici ma non hanno familiarità con le API CKAN o la navigazione approfondita dei portali
+- **Giornalisti o Cittadini Curiosi**: Vogliono esplorare i dati pubblici per storie o interessi personali senza barriere tecniche
+- **Sviluppatori (per testing)**: Potrebbero usarlo per testare il funzionamento del server MCP o per esplorare la capacità di Gemini di interpretare le richieste utente e tradurle in chiamate a tool
+
+---
+
+## 4. Funzionalità
+
+### 4.1 Interfaccia di Chat in Linguaggio Naturale
+
+**Input Messaggi**:
+- Campo di testo per l'utente per digitare domande e comandi
+- Supporta l'invio tramite tasto Invio o un pulsante dedicato
+
+**Display Messaggi**:
+- Messaggi dell'utente visualizzati con sfondo grigio chiaro e testo nero
+- Messaggi dell'assistente visualizzati con sfondo bianco
+- Supporto per il rendering Markdown (tramite react-markdown e remark-gfm)
+- Icone chiare (User, Bot) per distinguere il mittente
+
+**Comportamenti**:
+- Scroll automatico verso il basso per mostrare l'ultimo messaggio
+- Messaggio di benvenuto iniziale per guidare l'utente
+- Suggerimenti di query iniziali per aiutare gli utenti a iniziare
+
+### 4.2 Integrazione con Gemini API per NLU e Tool Calling
+
+- **Orchestrazione Gemini**: L'API Gemini (gemini-3-pro-preview) viene utilizzata per comprendere le intenzioni dell'utente e decidere quali tool dell'MCP chiamare
+- **System Instruction**: Istruzione di sistema personalizzata che guida Gemini a comportarsi come "esperto assistente Open Data specializzato in portali CKAN" con regole rigide per l'utilizzo dei tool e la gestione degli errori CKAN
+- **Tool Calling**: Gemini identifica e formatta le chiamate ai tool (search_datasets, get_dataset) basandosi sul inputSchema fornito dal server MCP
+- **Ciclo di Tool Execution**: L'applicazione gestisce un ciclo di esecuzione dei tool, inviando le risposte dei tool a Gemini per ulteriori elaborazioni e generazioni di risposte in linguaggio naturale
+- **Visualizzazione Tool in Uso**: Durante l'esecuzione di un tool, viene visualizzato un messaggio "Utilizzo tool: [nome_tool]" con icona di caricamento e parametri JSON della chiamata tool (con break-all per adattamento a tutti i dispositivi)
+
+### 4.3 Integrazione con MCP (Microservice Controller Proxy)
+
+- **Endpoint Configurable**: L'URL del server MCP è configurabile tramite interfaccia utente dedicata (sezione "Impostazioni")
+- **Salute del Server**: Indicatore di stato che mostra se il server MCP è online, offline o in fase di verifica (CheckCircle2, XCircle, RefreshCw)
+- **Fallback Tool Definitions**: Se il server MCP non è raggiungibile, l'applicazione usa definizioni di tool di fallback per mantenere funzionalità minima
+- **Chiamate JSON-RPC**: Il servizio mcp.ts gestisce le chiamate JSON-RPC per listare i tool (tools/list) e chiamare i tool specifici (tools/call)
+- **Gestione CORS**: Include logica di fallback utilizzando proxy corsproxy.io se la richiesta diretta fallisce
+- **Output Tool**: L'output JSON dei tool viene parsato e visualizzato nella chat, con rendering specifico per DatasetCard
+
+### 4.4 Visualizzazione Dati (DatasetCard)
+
+- **Card Dettagli Dataset**: Quando Gemini restituisce risultati di dataset, questi vengono visualizzati come DatasetCard con informazioni chiave: titolo, descrizione, data di creazione, autore, licenza, tag e elenco di risorse (con link esterni)
+- **Formattazione**: Date formattate in modo leggibile, link alle risorse chiaramente distinguibili
+- **Troncamento**: Viene mostrato un numero limitato di risorse con messaggio "Mostrati i primi X risultati" se ce ne sono di più
+
+### 4.5 Gestione Errori e Feedback Utente
+
+**Errori Gemini API**:
+- Gestione specifica degli errori di quota (RESOURCE_EXHAUSTED, codice 429)
+- Banner di avviso (AlertTriangle) in caso di quota esaurita
+- Istruzione per selezionare chiave API da progetto a pagamento con link alla documentazione di fatturazione
+- Pulsante per aprire il selettore di chiavi API (se window.aistudio.openSelectKey disponibile)
+
+**Errori MCP**:
+- Messaggi di errore chiari se il server MCP non è raggiungibile o se una chiamata tool fallisce (es. Status 404)
+- Incoraggiamento a controllare l'URL dell'MCP nelle impostazioni
+
+**Stati di Caricamento**:
+- Indicatore "Gemini sta elaborando..." al centro dello schermo quando l'API Gemini è attiva ma non sta chiamando un tool
+- Indicatore "Utilizzo tool: [nome_tool]" quando un tool MCP è in esecuzione
+- Pulsante di invio disabilitato durante il caricamento, se l'input è vuoto, o se l'MCP è offline
+
+### 4.6 Configurabilità
+
+- **Sezione Impostazioni**: Icona Settings apre un pannello dove l'utente può visualizzare e modificare l'endpoint del server MCP e la propria API key di Gemini
+- **Salvataggio Endpoint**: Pulsante Applica salva il nuovo endpoint e verifica immediatamente la connettività MCP
+- **Gestione API Key**: L'utente inserisce la propria API key di Gemini tramite interfaccia dedicata (campo di input protetto). La chiave viene salvata nel browser storage (localStorage) e rimane disponibile per le sessioni successive
+
+---
+
+## 5. Requisiti Tecnici
+
+### Frontend
+
+- **Framework**: React 19 (tramite react/)
+- **Linguaggio**: TypeScript
+- **Styling**: Tailwind CSS (con plugin typography) per design moderno e responsivo
+- **Icone**: Lucide React (lucide-react) per interfaccia visivamente accattivante
+- **Rendering Markdown**: react-markdown con remark-gfm per rendering robusto del testo generato da Gemini
+- **Gestione Moduli**: Utilizzo di importmap in index.html per caricamento diretto dei moduli ES6
+
+### Backend (Implicito)
+
+- **Gemini API**: Comunicazione con gemini-3-pro-preview tramite @google/genai SDK
+- **MCP Server**: Interazione con un server MCP (es. ckan-mcp-server.andy-pr.workers.dev/mcp) che espone API JSON-RPC
+- **API Key Management**: L'API key di Gemini è inserita dall'utente tramite l'interfaccia di impostazioni. La chiave viene salvata in localStorage e recuperata in ogni sessione. Supporta anche process.env.API_KEY come fallback per ambienti di sviluppo. Include meccanismo per interagire con window.aistudio.openSelectKey() per selezione di chiave API a pagamento
+- **Error Handling**: Gestione robusta di errori HTTP, errori JSON-RPC e errori specifici dell'API Gemini
+
+---
+
+## 6. Requisiti Non Funzionali
+
+### Performance
+
+- Caricamento rapido dell'interfaccia utente
+- Risposte della chat ottimizzate per la velocità, minimizzando la latenza delle chiamate API
+- Scroll fluido della chat, anche con molti messaggi
+
+### Usabilità (UX)
+
+- Interfaccia intuitiva e facile da usare per utenti di tutti i livelli tecnici
+- Feedback visivo chiaro per stati di caricamento, errori e successo delle operazioni
+- Messaggi di errore comprensibili e azioni suggerite
+
+### Reattività
+
+L'applicazione deve essere completamente responsiva e funzionare bene su desktop, tablet e dispositivi mobili
+
+### Accessibilità (A11Y)
+
+- Utilizzo di elementi HTML semantici
+- Contrasto colori adeguato
+- Navigazione da tastiera e supporto per lettori di schermo (da verificare e migliorare)
+
+### Compatibilità Cross-browser
+
+Funzionalità e aspetto devono essere coerenti sui principali browser moderni (Chrome, Firefox, Safari, Edge)
+
+### Sicurezza
+
+- La chiave API di Gemini è gestita tramite variabili d'ambiente e non esposta nel codice sorgente lato client
+- Il CORS proxy è usato come fallback, ma si raccomanda che il server MCP gestisca il CORS direttamente per maggiore sicurezza
+
+### Internazionalizzazione
+
+Attualmente l'interfaccia è interamente in italiano
+
+### Offline Functionality
+
+L'applicazione richiede una connessione internet attiva sia per l'API Gemini che per il server MCP, quindi non supporta la funzionalità offline