@aborruso/ckan-mcp-server 0.4.17 → 0.4.18

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

@@ -1,12 +0,0 @@
-## 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

@@ -1,12 +0,0 @@
-# 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

@@ -1,11 +0,0 @@
-## 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

@@ -1,8 +0,0 @@
-## 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/add-mqa-quality-tool/proposal.md

@@ -1,21 +0,0 @@
-# Change: Add MQA Quality Score Tool for dati.gov.it
-
-## Why
-Datasets on dati.gov.it display quality scores (Eccellente, Buono, etc.) calculated by data.europa.eu's MQA (Metadata Quality Assurance) system. Currently there's no way to access these quality metrics through the MCP server, limiting users' ability to evaluate dataset quality programmatically.
-
-## What Changes
-- Add `ckan_get_mqa_quality` tool for retrieving quality metrics from data.europa.eu
-- Tool works only with dati.gov.it server (validated at runtime)
-- Fetches dataset identifier from CKAN, then queries MQA API
-- Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability)
-- Supports both markdown and JSON output formats
-
-## Impact
-- Affected specs: New capability `ckan-quality`
-- Affected code:
-  - New file: `src/tools/quality.ts` (tool handler)
-  - New file: `tests/integration/quality.test.ts` (tests with mocked responses)
-  - New file: `tests/fixtures/responses/mqa-quality.json` (mock data)
-  - Modified: `src/server.ts` (register new tool)
-  - Modified: `README.md` (document new tool)
-  - Modified: `EXAMPLES.md` (add usage examples)

package/openspec/changes/add-mqa-quality-tool/specs/ckan-quality/spec.md

@@ -1,71 +0,0 @@
-## ADDED Requirements
-
-### Requirement: MQA Quality Score Retrieval
-The system SHALL provide a tool to retrieve MQA (Metadata Quality Assurance) quality metrics from data.europa.eu for datasets published on dati.gov.it.
-
-#### Scenario: Successful quality score retrieval
-- **GIVEN** a valid dataset ID from dati.gov.it
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL fetch identifier field from CKAN package_show
-- **AND** system SHALL query data.europa.eu MQA API
-- **AND** system SHALL return quality score and detailed metrics (accessibility, reusability, interoperability, findability)
-
-#### Scenario: Identifier fallback to name
-- **GIVEN** a dataset with empty identifier field
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL use the name field as fallback identifier for MQA API query
-
-#### Scenario: Dataset not found
-- **GIVEN** an invalid or non-existent dataset ID
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL return clear error message indicating dataset not found
-
-#### Scenario: MQA API unavailable
-- **GIVEN** data.europa.eu MQA API is unavailable or returns error
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL return clear error message indicating MQA service unavailability
-
-### Requirement: Server Validation
-The system SHALL restrict MQA quality queries to dati.gov.it server only.
-
-#### Scenario: Valid dati.gov.it server
-- **GIVEN** server_url is "https://www.dati.gov.it/opendata" or "https://dati.gov.it/opendata"
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL proceed with MQA query
-
-#### Scenario: Invalid server URL
-- **GIVEN** server_url is not dati.gov.it (e.g., "https://catalog.data.gov")
-- **WHEN** user requests quality metrics
-- **THEN** system SHALL reject request with error message explaining MQA is only available for dati.gov.it
-
-### Requirement: Output Formats
-The system SHALL support both markdown and JSON output formats for quality metrics.
-
-#### Scenario: Markdown format (default)
-- **GIVEN** user does not specify response_format or specifies "markdown"
-- **WHEN** quality metrics are retrieved
-- **THEN** system SHALL return human-readable markdown with:
-  - Overall quality score
-  - Breakdown by dimension (accessibility, reusability, interoperability, findability)
-  - Key findings and recommendations
-
-#### Scenario: JSON format
-- **GIVEN** user specifies response_format as "json"
-- **WHEN** quality metrics are retrieved
-- **THEN** system SHALL return complete MQA API response as structured JSON
-
-### Requirement: Tool Parameters
-The system SHALL accept the following parameters for the MQA quality tool:
-- server_url (required): Base URL of dati.gov.it portal
-- dataset_id (required): Dataset ID or name
-- response_format (optional): "markdown" (default) or "json"
-
-#### Scenario: Minimal parameters
-- **GIVEN** user provides only server_url and dataset_id
-- **WHEN** tool is invoked
-- **THEN** system SHALL use default markdown format
-
-#### Scenario: All parameters specified
-- **GIVEN** user provides server_url, dataset_id, and response_format
-- **WHEN** tool is invoked
-- **THEN** system SHALL use specified format for output

package/openspec/changes/add-mqa-quality-tool/tasks.md

@@ -1,29 +0,0 @@
-# Implementation Tasks
-
-## 1. Core Implementation
-- [x] 1.1 Create `src/tools/quality.ts` with `ckan_get_mqa_quality` tool handler
-- [x] 1.2 Implement server URL validation (dati.gov.it only)
-- [x] 1.3 Add CKAN package_show call to extract identifier field
-- [x] 1.4 Add MQA API client (https://data.europa.eu/api/mqa/cache/datasets/{id})
-- [x] 1.5 Implement markdown and JSON formatters for quality metrics
-- [x] 1.6 Register tool in `src/server.ts`
-
-## 2. Testing
-- [x] 2.1 Create mock fixtures for CKAN package_show response
-- [x] 2.2 Create mock fixtures for MQA API response
-- [x] 2.3 Write integration tests for successful quality retrieval
-- [x] 2.4 Write tests for error scenarios (invalid server, dataset not found, MQA API unavailable)
-- [x] 2.5 Write tests for fallback from identifier to name field
-- [x] 2.6 Verify test coverage matches project standards
-
-## 3. Documentation
-- [x] 3.1 Add tool description to README.md
-- [x] 3.2 Add usage examples to EXAMPLES.md
-- [x] 3.3 Document server restriction (dati.gov.it only)
-- [x] 3.4 Document quality metrics structure (score, accessibility, reusability, interoperability, findability)
-
-## 4. Validation
-- [x] 4.1 Run full test suite (npm test) - 212 tests passing
-- [x] 4.2 Test manually with real dati.gov.it dataset
-- [x] 4.3 Verify error handling for non-dati.gov.it servers
-- [x] 4.4 Build project successfully (npm run build)

package/openspec/changes/archive/2026-01-08-add-mcp-resources/design.md

@@ -1,115 +0,0 @@
-# Design: MCP Resource Templates
-
-## Context
-
-MCP protocol supports two primitives:
-- **Tools**: Functions that perform actions (current implementation)
-- **Resources**: Data that can be read directly (to be added)
-
-The `@modelcontextprotocol/sdk` provides `server.registerResourceTemplate()` for dynamic resources with URI templates.
-
-## Goals / Non-Goals
-
-### Goals
-- Expose CKAN data as MCP resources using `ckan://` URI scheme
-- Support dataset, resource, and organization access
-- Reuse existing `makeCkanRequest()` for CKAN API calls
-- Maintain consistency with tool output formats
-
-### Non-Goals
-- Write operations (resources are read-only by design)
-- Caching implementation (defer to future enhancement)
-- Authentication support (public endpoints only, same as tools)
-- Real-time subscriptions (defer to future enhancement)
-
-## Decisions
-
-### URI Scheme Design
-
-**Decision**: Use `ckan://{server}/type/{id}` pattern
-
-```
-ckan://dati.gov.it/dataset/vaccini-covid
-ckan://data.gov/resource/abc-123
-ckan://demo.ckan.org/organization/sample-org
-```
-
-**Rationale**:
-- Server in hostname position enables multi-server support
-- Type in path makes intent clear
-- ID as final segment matches REST conventions
-
-**Alternatives considered**:
-1. `ckan://dataset/{server}/{id}` - rejected: server as path segment is unusual
-2. `ckan+https://{server}/...` - rejected: overly complex
-3. Query parameters `ckan://data?server=...&id=...` - rejected: less readable
-
-### Module Structure
-
-**Decision**: Create `src/resources/` directory with one file per resource type
-
-```
-src/resources/
-├── index.ts          # Export registerAllResources()
-├── dataset.ts        # ckan://{server}/dataset/{id}
-├── resource.ts       # ckan://{server}/resource/{id}
-└── organization.ts   # ckan://{server}/organization/{name}
-```
-
-**Rationale**: Mirrors existing `src/tools/` structure for consistency.
-
-### URI Parsing
-
-**Decision**: Extract server from URI hostname, type and ID from path
-
-```typescript
-function parseResourceUri(uri: URL): { server: string; type: string; id: string } {
-  const server = uri.hostname;
-  const [, type, id] = uri.pathname.split('/');
-  return { server: `https://${server}`, type, id };
-}
-```
-
-**Rationale**: Simple parsing, assumes HTTPS (most CKAN servers use it).
-
-### Response Format
-
-**Decision**: Return JSON by default (no markdown option for resources)
-
-**Rationale**:
-- Resources are meant for programmatic access
-- LLMs can interpret JSON directly
-- Keeps implementation simple
-- Tools still support markdown for interactive use
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| SDK API changes | Pin SDK version, test before updates |
-| URI parsing edge cases | Validate URIs before processing |
-| Large responses | Apply existing `CHARACTER_LIMIT` truncation |
-| Server unreachable | Same error handling as tools |
-
-## Migration Plan
-
-1. Add resources alongside existing tools (no breaking changes)
-2. Resources are additive - tools remain fully functional
-3. No migration needed for existing users
-
-## Implementation Sequence
-
-1. Create `src/resources/` directory structure
-2. Implement URI parsing utility
-3. Implement dataset resource template
-4. Implement resource resource template
-5. Implement organization resource template
-6. Register resources in `src/index.ts`
-7. Add tests for resource handlers
-8. Update documentation
-
-## Open Questions
-
-1. Should resources support `response_format` parameter like tools?
-2. Should we add `ckan://{server}/search?q=...` for search results as resource?
-3. How to handle CKAN servers that require `www.` prefix (e.g., dati.gov.it)?

package/openspec/changes/archive/2026-01-08-add-mcp-resources/proposal.md

@@ -1,52 +0,0 @@
-# Change: Add MCP Resource Templates
-
-## Why
-
-MCP has two primitives for exposing data: **Tools** (functions) and **Resources** (data). Currently we only expose tools. Adding resources enables:
-
-1. Direct data access without tool calls
-2. Native caching and subscription support
-3. Better LLM context injection
-4. Alignment with MCP best practices (see Data.gov MCP server pattern)
-
-## What Changes
-
-- Add MCP Resource Templates using RFC 6570 URI syntax
-- Implement `ckan://` URI scheme for dataset and resource access
-- Create new module `src/resources/` for resource handlers
-- Register resources alongside existing tools
-
-**New URI templates**:
-- `ckan://{server}/dataset/{id}` - Dataset metadata
-- `ckan://{server}/resource/{id}` - Resource metadata and download URL
-- `ckan://{server}/organization/{name}` - Organization details
-
-## Impact
-
-- Affected specs: New capability `mcp-resources`
-- Affected code:
-  - `src/index.ts` - import and register resources
-  - `src/resources/` - new directory with resource handlers
-  - `src/utils/http.ts` - may need minor adjustments
-- No breaking changes to existing tools
-- Dependencies: No new dependencies required
-
-## Benefits
-
-| Aspect | Current (Tools) | With Resources |
-|--------|-----------------|----------------|
-| Data access | Tool call required | Direct read |
-| Caching | Manual | MCP native |
-| Subscriptions | Not supported | Supported |
-| Context loading | Via tool results | Direct injection |
-
-## Risks
-
-- **URI parsing complexity**: Need to handle `ckan://` scheme correctly
-- **Error handling**: Different pattern than tools
-- **Testing**: New test patterns needed for resources
-
-## References
-
-- [MCP Resources Specification](https://modelcontextprotocol.io/specification/2025-11-25)
-- [Data.gov MCP Server](https://skywork.ai/skypage/en/unlocking-government-data-mcp-server/1980445961155629056) - uses `datagov://` scheme

package/openspec/changes/archive/2026-01-08-add-mcp-resources/specs/mcp-resources/spec.md

@@ -1,92 +0,0 @@
-# MCP Resources Capability
-
-## ADDED Requirements
-
-### Requirement: Dataset Resource Template
-
-The system SHALL expose a resource template for accessing CKAN dataset metadata via the URI pattern `ckan://{server}/dataset/{id}`.
-
-#### Scenario: Read dataset metadata successfully
-
-- **WHEN** client reads `ckan://dati.gov.it/dataset/vaccini-covid`
-- **THEN** server returns JSON with complete dataset metadata including title, description, resources, organization, tags
-
-#### Scenario: Dataset not found
-
-- **WHEN** client reads `ckan://demo.ckan.org/dataset/nonexistent-id`
-- **THEN** server returns error indicating dataset not found
-
-#### Scenario: Server unreachable
-
-- **WHEN** client reads `ckan://invalid-server.example/dataset/test`
-- **THEN** server returns error indicating server unreachable
-
-### Requirement: Resource Resource Template
-
-The system SHALL expose a resource template for accessing CKAN resource metadata via the URI pattern `ckan://{server}/resource/{id}`.
-
-#### Scenario: Read resource metadata successfully
-
-- **WHEN** client reads `ckan://dati.gov.it/resource/abc-123-def`
-- **THEN** server returns JSON with resource metadata including name, format, URL, size, and download link
-
-#### Scenario: Resource not found
-
-- **WHEN** client reads `ckan://demo.ckan.org/resource/invalid-id`
-- **THEN** server returns error indicating resource not found
-
-### Requirement: Organization Resource Template
-
-The system SHALL expose a resource template for accessing CKAN organization metadata via the URI pattern `ckan://{server}/organization/{name}`.
-
-#### Scenario: Read organization metadata successfully
-
-- **WHEN** client reads `ckan://dati.gov.it/organization/regione-toscana`
-- **THEN** server returns JSON with organization metadata including title, description, and dataset count
-
-#### Scenario: Organization not found
-
-- **WHEN** client reads `ckan://demo.ckan.org/organization/nonexistent-org`
-- **THEN** server returns error indicating organization not found
-
-### Requirement: URI Scheme Parsing
-
-The system SHALL parse `ckan://` URIs extracting server hostname and path components.
-
-#### Scenario: Parse standard URI
-
-- **WHEN** URI is `ckan://dati.gov.it/dataset/test-id`
-- **THEN** server extracts: server=`https://dati.gov.it`, type=`dataset`, id=`test-id`
-
-#### Scenario: Parse URI with www prefix
-
-- **WHEN** URI is `ckan://www.dati.gov.it/dataset/test-id`
-- **THEN** server extracts: server=`https://www.dati.gov.it`, type=`dataset`, id=`test-id`
-
-#### Scenario: Reject malformed URI
-
-- **WHEN** URI is `ckan://invalid` (missing path)
-- **THEN** server returns validation error
-
-### Requirement: Resource Response Format
-
-The system SHALL return resource content as JSON with standard MCP resource response structure.
-
-#### Scenario: JSON response structure
-
-- **WHEN** client reads any valid resource URI
-- **THEN** response contains `contents` array with `uri`, `mimeType` (application/json), and `text` (JSON string)
-
-#### Scenario: Large response truncation
-
-- **WHEN** resource content exceeds CHARACTER_LIMIT
-- **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.
-
-#### Scenario: List resource templates
-
-- **WHEN** client calls `resources/listTemplates`
-- **THEN** server returns list of available URI templates with descriptions

package/openspec/changes/archive/2026-01-08-add-mcp-resources/tasks.md

@@ -1,56 +0,0 @@
-# Tasks: Add MCP Resource Templates
-
-## 1. Setup
-
-- [x] 1.1 Create `src/resources/` directory
-- [x] 1.2 Create `src/resources/index.ts` with `registerAllResources()` export
-
-## 2. URI Utilities
-
-- [x] 2.1 Create URI parsing function for `ckan://` scheme
-- [x] 2.2 Add validation for malformed URIs
-- [x] 2.3 Handle edge cases (www prefix, trailing slashes)
-
-## 3. Dataset Resource
-
-- [x] 3.1 Create `src/resources/dataset.ts`
-- [x] 3.2 Register template `ckan://{server}/dataset/{id}`
-- [x] 3.3 Implement handler using `makeCkanRequest('package_show')`
-- [x] 3.4 Return JSON response with dataset metadata
-
-## 4. Resource Resource
-
-- [x] 4.1 Create `src/resources/resource.ts`
-- [x] 4.2 Register template `ckan://{server}/resource/{id}`
-- [x] 4.3 Implement handler using `makeCkanRequest('resource_show')`
-- [x] 4.4 Include download URL in response
-
-## 5. Organization Resource
-
-- [x] 5.1 Create `src/resources/organization.ts`
-- [x] 5.2 Register template `ckan://{server}/organization/{name}`
-- [x] 5.3 Implement handler using `makeCkanRequest('organization_show')`
-- [x] 5.4 Return JSON response with organization metadata
-
-## 6. Integration
-
-- [x] 6.1 Import `registerAllResources` in `src/index.ts`
-- [x] 6.2 Call `registerAllResources(server)` after tool registration
-- [x] 6.3 Build and verify no compilation errors
-
-## 7. Testing
-
-- [x] 7.1 Create `tests/integration/resources.test.ts`
-- [x] 7.2 Add tests for dataset resource template
-- [x] 7.3 Add tests for resource resource template
-- [x] 7.4 Add tests for organization resource template
-- [x] 7.5 Add tests for URI parsing edge cases
-- [x] 7.6 Add tests for error handling (invalid URI, server errors)
-- [x] 7.7 Run full test suite, ensure 100% pass
-
-## 8. Documentation
-
-- [x] 8.1 Update README.md with resource templates section
-- [x] 8.2 Update CLAUDE.md architecture section
-- [x] 8.3 Add examples to EXAMPLES.md (deferred - basic examples in README)
-- [x] 8.4 Update LOG.md with changes