@aborruso/ckan-mcp-server 0.4.11 → 0.4.13

package/openspec/changes/add-ckan-host-allowlist-env/design.md

@@ -0,0 +1,38 @@
+# Design: CKAN Host Allowlist via Environment
+
+## Overview
+Introduce an optional, environment-driven allowlist for CKAN hosts. When configured, all CKAN requests must target hosts in the allowlist. When not configured, behavior remains unchanged.
+
+## Configuration
+- Environment variable: `ALLOWED_CKAN_HOSTS`
+- Format: comma-separated hostnames (e.g., `dati.gov.it,data.gov,catalog.data.gov`)
+- Parsing rules:
+  - Split on commas
+  - Trim whitespace
+  - Lowercase
+  - Drop empty entries
+
+## Enforcement
+- Validate hostnames extracted from:
+  - Tool inputs: `server_url`
+  - Resource URIs: `ckan://{server}/...`
+- Reject requests where the hostname is not in the allowlist.
+- Error message should be explicit: `Host not allowed: <hostname>`.
+
+## Runtime Scope
+- Node.js (stdio/http) and Workers runtimes share the same validation utility.
+- Workers reads env via `env.ALLOWED_CKAN_HOSTS` (wrangler var), Node via `process.env.ALLOWED_CKAN_HOSTS`.
+
+## Integration Points
+- Add a small utility module, e.g. `src/utils/allowlist.ts`:
+  - `parseAllowedHosts(value?: string): Set<string> | null`
+  - `assertAllowedHost(serverUrl: string, allowed: Set<string> | null): void`
+- Call `assertAllowedHost` inside CKAN request flow or immediately in each tool/resource handler before network calls.
+
+## Backwards Compatibility
+- If `ALLOWED_CKAN_HOSTS` is unset or empty, allow all hosts (no behavior change).
+
+## Testing
+- Unit tests for parsing behavior (case, whitespace, empty entries).
+- Unit tests for allow/deny logic with known hostnames and invalid URLs.
+- Tool/resource tests to verify rejection when allowlist is set.

package/openspec/changes/add-ckan-host-allowlist-env/proposal.md

@@ -0,0 +1,16 @@
+# Change: Add allowlist for CKAN hosts via environment
+
+## Why
+Public HTTP/Workers deployments can be abused to proxy requests to arbitrary hosts. A host allowlist provides a simple, configurable barrier without breaking local usage.
+
+## What Changes
+- Add `ALLOWED_CKAN_HOSTS` env var (comma-separated hostnames) to restrict `server_url` targets.
+- Validate `server_url` host against the allowlist for all tools/resources that call CKAN.
+- Document and expose the env var in `wrangler.toml` for Workers deployments.
+
+## Design Reference
+See `openspec/changes/add-ckan-host-allowlist-env/design.md` for configuration, enforcement, and runtime details.
+
+## Impact
+- Affected specs: `cloudflare-deployment`, new `ckan-request-allowlist`
+- Affected code: request validation utilities; Workers/Node configuration handling; tools/resources that accept `server_url` or `ckan://` URIs.

package/openspec/changes/add-ckan-host-allowlist-env/specs/ckan-request-allowlist/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+### Requirement: CKAN host allowlist validation
+The system SHALL validate every CKAN request target against an optional allowlist configured via `ALLOWED_CKAN_HOSTS`.
+
+#### Scenario: Allowed host
+- **WHEN** a tool or resource is called with a `server_url` whose hostname is in `ALLOWED_CKAN_HOSTS`
+- **THEN** the request proceeds as normal
+
+#### Scenario: Disallowed host
+- **WHEN** a tool or resource is called with a `server_url` whose hostname is not in `ALLOWED_CKAN_HOSTS`
+- **THEN** the request is rejected with a clear error indicating the host is not allowed
+
+#### Scenario: Allowlist not set
+- **WHEN** `ALLOWED_CKAN_HOSTS` is unset or empty
+- **THEN** the system accepts any valid `server_url`

package/openspec/changes/add-ckan-host-allowlist-env/specs/cloudflare-deployment/spec.md

@@ -0,0 +1,11 @@
+## ADDED Requirements
+### Requirement: Workers allowlist configuration
+The system SHALL allow configuring an allowlist of CKAN hosts for Workers deployments via environment variable.
+
+#### Scenario: Wrangler allowlist configuration
+- **WHEN** `wrangler.toml` sets `ALLOWED_CKAN_HOSTS` to a comma-separated list of hostnames
+- **THEN** the Workers runtime reads the variable and restricts CKAN requests to those hosts
+
+#### Scenario: Allowlist not set
+- **WHEN** `ALLOWED_CKAN_HOSTS` is unset or empty in the Workers environment
+- **THEN** the Workers runtime allows requests to any CKAN host

package/openspec/changes/add-ckan-host-allowlist-env/tasks.md

@@ -0,0 +1,12 @@
+## 1. Implementation
+- [ ] Add allowlist parsing utility for `ALLOWED_CKAN_HOSTS` (comma-separated hostnames, case-insensitive, trim whitespace).
+- [ ] Enforce allowlist for all CKAN requests (tools and resource templates) with clear error messaging.
+- [ ] Ensure allowlist applies to both Node and Workers runtimes.
+
+## 2. Configuration
+- [ ] Add `ALLOWED_CKAN_HOSTS` to `wrangler.toml` with example values.
+- [ ] Update docs/README to describe the env var and behavior (optional if required by spec).
+
+## 3. Tests
+- [ ] Add unit tests for allowlist parsing and validation.
+- [ ] Add tool/resource tests verifying rejection for non-allowed hosts when env var is set.

package/openspec/changes/add-escape-text-query/proposal.md

@@ -0,0 +1,12 @@
+# Change: Escape text-field query wrapping in search parser
+
+## Why
+Wrapping arbitrary user input in `text:(...)` without escaping allows query parser errors or unintended semantics when the input contains Solr/Lucene metacharacters (e.g., `"` or `)`).
+
+## What Changes
+- Escape Solr/Lucene special characters before wrapping user input in `text:(...)`.
+- Add tests to confirm escaped output and prevent regressions.
+
+## Impact
+- Affected specs: `ckan-search`
+- Affected code: `src/utils/search.ts`, package search tool behavior, related tests.

package/openspec/changes/add-escape-text-query/specs/ckan-search/spec.md

@@ -0,0 +1,11 @@
+## MODIFIED 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, and SHALL escape Solr/Lucene special characters when wrapping queries in `text:(...)`.
+
+#### 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 with escaped query content
+
+#### Scenario: Request override applies
+- **WHEN** a client explicitly requests the text-field parser
+- **THEN** `ckan_package_search` uses `text:(...)` regardless of portal defaults with escaped query content

package/openspec/changes/add-escape-text-query/tasks.md

@@ -0,0 +1,8 @@
+## 1. Implementation
+- [x] Add a Solr/Lucene escaping helper for text-field queries.
+- [x] Apply escaping when `resolveSearchQuery` forces `text:(...)`.
+- [x] Ensure behavior is unchanged when not forcing the text parser.
+
+## 2. Tests
+- [x] Add unit tests for escaping behavior (quotes, parentheses, backslashes, colons).
+- [x] Add tests to cover `resolveSearchQuery` effectiveQuery output with forced text parser.

package/openspec/changes/archive/2026-01-15-add-mcp-resource-filters/proposal.md

@@ -0,0 +1,13 @@
+# Change: add filtered CKAN dataset resource templates
+
+## Why
+Users need quick, direct access to filtered dataset lists (by theme, publisher, tag, format) without building complex tool queries.
+
+## What Changes
+- Add new MCP resource templates under the existing `ckan://{server}/...` scheme for group, organization, tag, and format dataset filters.
+- Extend resource discovery to list the new templates.
+- Document new resource URIs and examples.
+
+## Impact
+- Affected specs: mcp-resources
+- Affected code: `src/resources/*`, `src/resources/uri.ts`, README/docs

package/openspec/changes/archive/2026-01-15-add-mcp-resource-filters/specs/mcp-resources/spec.md

@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Group Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by group via the URI pattern `ckan://{server}/group/{name}/datasets`.
+
+#### Scenario: Read datasets by group
+- **WHEN** client reads `ckan://dati.gov.it/group/governo/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Organization Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by organization via the URI pattern `ckan://{server}/organization/{name}/datasets`.
+
+#### Scenario: Read datasets by organization
+- **WHEN** client reads `ckan://dati.gov.it/organization/regione-toscana/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Tag Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by tag via the URI pattern `ckan://{server}/tag/{name}/datasets`.
+
+#### Scenario: Read datasets by tag
+- **WHEN** client reads `ckan://dati.gov.it/tag/turismo/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Format Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by resource format via the URI pattern `ckan://{server}/format/{format}/datasets`.
+
+#### Scenario: Read datasets by format
+- **WHEN** client reads `ckan://dati.gov.it/format/csv/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search` filtered by resource format
+
+## MODIFIED Requirements
+
+### Requirement: Resource Discovery
+The system SHALL list available resource templates when client requests resource list, including dataset, resource, organization, and dataset filter templates (group, organization, tag, format).
+
+#### Scenario: List resource templates
+- **WHEN** client calls `resources/listTemplates`
+- **THEN** server returns list of available URI templates with descriptions, including the dataset filter templates

package/openspec/changes/archive/2026-01-15-add-mcp-resource-filters/tasks.md

@@ -0,0 +1,10 @@
+## 1. Implementation
+- [x] Add new resource handlers for group, organization datasets, tag, and format filters under `src/resources/`.
+- [x] Register new resource templates in `src/resources/index.ts`.
+- [x] Update URI parsing/validation to accept the new dataset filter paths.
+- [x] Add tests for each new resource template and error cases.
+- [x] Update README/docs with new `ckan://{server}/...` examples.
+
+## 2. Validation
+- [x] Run `npm test` (or targeted resource tests).
+- [x] Run `openspec validate add-mcp-resource-filters --strict`.

package/openspec/changes/archive/2026-01-19-update-repo-owner-ondata/proposal.md

@@ -0,0 +1,13 @@
+# Change: Move repository ownership to ondata organization
+
+## Why
+The repository is moving from the personal account to the ondata organization. Documentation, badges, and published references must reflect the new canonical URL to avoid confusion and broken links.
+
+## What Changes
+- Update documentation and in-app links to the new repository URL under the ondata organization.
+- Preserve npm package ownership and scope as @aborruso (no npm ownership change).
+- Confirm GitHub Pages and related references align with the new organization ownership.
+
+## Impact
+- Affected specs: repository-metadata, cloudflare-deployment (docs references)
+- Affected code: README.md, docs/*, src/worker.ts, .github/ISSUE_TEMPLATE/config.yml

package/openspec/changes/archive/2026-01-19-update-repo-owner-ondata/specs/repository-metadata/spec.md

@@ -0,0 +1,14 @@
+## ADDED Requirements
+### Requirement: Canonical repository ownership references
+The project documentation and UI MUST reference the canonical repository under the ondata organization once the repository is migrated.
+
+#### Scenario: Repository references updated
+- **WHEN** a user follows documentation or UI links to the repository
+- **THEN** the links point to the ondata organization repository URL
+
+### Requirement: NPM package ownership remains personal
+The project MUST continue to document the npm package under the @aborruso scope unless an explicit npm ownership change is approved.
+
+#### Scenario: npm install instructions unchanged
+- **WHEN** a user follows installation instructions
+- **THEN** the package name remains @aborruso/ckan-mcp-server

package/openspec/changes/archive/2026-01-19-update-repo-owner-ondata/tasks.md

@@ -0,0 +1,12 @@
+## 1. Documentation and Links
+- [x] 1.1 Inventory repo URL references (README, docs, issue templates, web GUI).
+- [x] 1.2 Update GitHub repository links to the ondata org.
+- [x] 1.3 Update any badges and external links that embed the old owner.
+
+## 2. Deployment Guidance
+- [x] 2.1 Update deployment docs that reference the old GitHub repo.
+- [x] 2.2 Validate GitHub Pages URL references where applicable.
+
+## 3. Verification
+- [x] 3.1 Confirm npm scope and publish instructions remain unchanged.
+- [x] 3.2 Run openspec validation and address any issues.

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

@@ -11,9 +11,13 @@ The system SHALL maintain this specification to document dataset insight tools w
 - **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.
+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/specs/ckan-search/spec.md

@@ -0,0 +1,16 @@
+# ckan-search Specification
+
+## Purpose
+TBD - created by archiving change update-search-parser-config. Update Purpose after archive.
+## 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/specs/mcp-prompts/spec.md

@@ -0,0 +1,26 @@
+# mcp-prompts Specification
+
+## Purpose
+TBD - created by archiving change add-mcp-prompts. Update Purpose after archive.
+## Requirements
+### Requirement: Guided prompts are available
+The system SHALL expose a set of guided MCP prompts for common CKAN discovery workflows.
+
+#### Scenario: User requests a guided search prompt
+- **WHEN** a client lists MCP prompts
+- **THEN** the guided prompts are returned with name, description, and parameters
+
+### Requirement: Prompt output includes tool usage instructions
+Each guided prompt SHALL produce instructions that reference the appropriate CKAN tools and parameters.
+
+#### Scenario: Prompt generation for thematic search
+- **WHEN** the user generates a prompt for a specific theme and format
+- **THEN** the output includes the correct tool name and required parameters
+
+### Requirement: Prompt content is localized and consistent
+Guided prompts SHALL use consistent language and parameter naming aligned with CKAN tool schemas.
+
+#### Scenario: Prompt content consistency
+- **WHEN** a prompt is generated
+- **THEN** parameter names match the tool schema (e.g., `server_url`, `q`, `fq`, `rows`)
+

package/openspec/specs/mcp-resources/spec.md

@@ -84,11 +84,37 @@ The system SHALL return resource content as JSON with standard MCP resource resp
 - **THEN** response is truncated to CHARACTER_LIMIT with truncation indicator
 
 ### Requirement: Resource Discovery
-
-The system SHALL list available resource templates when client requests resource list.
+The system SHALL list available resource templates when client requests resource list, including dataset, resource, organization, and dataset filter templates (group, organization, tag, format).
 
 #### Scenario: List resource templates
-
 - **WHEN** client calls `resources/listTemplates`
-- **THEN** server returns list of available URI templates with descriptions
+- **THEN** server returns list of available URI templates with descriptions, including the dataset filter templates
+
+### Requirement: Group Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by group via the URI pattern `ckan://{server}/group/{name}/datasets`.
+
+#### Scenario: Read datasets by group
+- **WHEN** client reads `ckan://dati.gov.it/group/governo/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Organization Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by organization via the URI pattern `ckan://{server}/organization/{name}/datasets`.
+
+#### Scenario: Read datasets by organization
+- **WHEN** client reads `ckan://dati.gov.it/organization/regione-toscana/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Tag Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by tag via the URI pattern `ckan://{server}/tag/{name}/datasets`.
+
+#### Scenario: Read datasets by tag
+- **WHEN** client reads `ckan://dati.gov.it/tag/turismo/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search`
+
+### Requirement: Format Datasets Resource Template
+The system SHALL expose a resource template for accessing CKAN datasets by resource format via the URI pattern `ckan://{server}/format/{format}/datasets`.
+
+#### Scenario: Read datasets by format
+- **WHEN** client reads `ckan://dati.gov.it/format/csv/datasets`
+- **THEN** server returns JSON with the matching datasets from `package_search` filtered by resource format
 

package/openspec/specs/repository-metadata/spec.md

@@ -0,0 +1,19 @@
+# repository-metadata Specification
+
+## Purpose
+TBD - created by archiving change update-repo-owner-ondata. Update Purpose after archive.
+## Requirements
+### Requirement: Canonical repository ownership references
+The project documentation and UI MUST reference the canonical repository under the ondata organization once the repository is migrated.
+
+#### Scenario: Repository references updated
+- **WHEN** a user follows documentation or UI links to the repository
+- **THEN** the links point to the ondata organization repository URL
+
+### Requirement: NPM package ownership remains personal
+The project MUST continue to document the npm package under the @aborruso scope unless an explicit npm ownership change is approved.
+
+#### Scenario: npm install instructions unchanged
+- **WHEN** a user follows installation instructions
+- **THEN** the package name remains @aborruso/ckan-mcp-server
+

package/package.json

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

package/private/commenti-privati.yaml

@@ -0,0 +1,14 @@
+# File YAML per commenti privati su ckan-mcp-server
+# Ogni elemento rappresenta un commento ricevuto
+- autore: Giovanni Pirrotta
+  data: 2026-01-19
+  modalità: telegram
+  testo: >
+    Ciao Andy, se non lo hai già fatto secondo me dovresti contattare AGID. È uno strumento così potente da meritare massima visibilità, non solo per le PA, ma soprattutto per chi oggi fa fatica a trovare dati o a interagire con i portali opendata. Vedo grandissime potenzialità!!
+- autore: Matteo Fortini
+  data: 2026-01-18
+  modalità: call
+  testo: |
+    Ho visto il video, molto interessante, lo proverò e lo racconterò.
+    Ti confesso che quando vedo queste cose mi chiedo se si possa implementare un meccanismo di feedback per ottenere lo stesso risultato con meno risorse. Intendo "come miglioreresti questo sito/API per renderlo più efficiente per queste cose?"
+    In generale a me piacerebbe che la IA pian piano venisse usata per "oliare" le interazioni, adesso la stiamo usando come una schiava per fare le cose scomode