@aborruso/ckan-mcp-server 0.4.6 → 0.4.7

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.7",
   "description": "MCP server for interacting with CKAN open data portals",
   "main": "dist/index.js",
   "type": "module",