@aborruso/ckan-mcp-server 0.4.17 → 0.4.19

package/openspec/changes/archive/2026-01-10-add-cloudflare-workers/tasks.md

@@ -1,519 +0,0 @@
-# Tasks: Add Cloudflare Workers Deployment
-
-## Overview
-Implementation broken into 4 phases with small, verifiable steps. Each task includes validation criteria.
-
----
-
-## Phase 1: Environment Setup (Prerequisites)
-
-### Task 1.1: Install Wrangler CLI
-**Description**: Install Cloudflare's official CLI tool globally
-
-**Steps**:
-```bash
-npm install -g wrangler
-wrangler --version
-```
-
-**Validation**:
-- `wrangler --version` shows version >= 3.0.0
-- Command `wrangler` available in PATH
-
-**Duration**: 2 minutes
-
----
-
-### Task 1.2: Create Cloudflare Account
-**Description**: Sign up for free Cloudflare account (if not already registered)
-
-**Steps**:
-1. Visit https://dash.cloudflare.com/sign-up
-2. Create account with email/password
-3. Verify email address
-
-**Validation**:
-- Can log into https://dash.cloudflare.com
-- Workers section visible in dashboard
-
-**Duration**: 5 minutes
-
-**Note**: If you already have a Cloudflare account, skip to Task 1.3
-
----
-
-### Task 1.3: Authenticate Wrangler
-**Description**: Connect local Wrangler CLI to Cloudflare account
-
-**Steps**:
-```bash
-wrangler login
-```
-
-**What happens**:
-- Browser opens with Cloudflare login
-- Click "Allow" to grant Wrangler access
-- Terminal shows "Successfully logged in"
-
-**Validation**:
-```bash
-wrangler whoami
-```
-Shows your Cloudflare account email
-
-**Duration**: 2 minutes
-
----
-
-### Task 1.4: Install Wrangler as Dev Dependency
-**Description**: Add Wrangler to project dependencies for reproducible builds
-
-**Steps**:
-```bash
-npm install --save-dev wrangler
-```
-
-**Validation**:
-- `package.json` devDependencies includes `"wrangler": "^3.x.x"`
-- `node_modules/.bin/wrangler` exists
-
-**Duration**: 1 minute
-
----
-
-## Phase 2: Workers Configuration
-
-### Task 2.1: Create wrangler.toml
-**Description**: Create Cloudflare Workers configuration file
-
-**Steps**:
-Create `wrangler.toml` in project root:
-
-```toml
-name = "ckan-mcp-server"
-main = "dist/worker.js"
-compatibility_date = "2024-01-01"
-
-[build]
-command = "npm run build:worker"
-
-[env.production]
-name = "ckan-mcp-server"
-```
-
-**Validation**:
-- File exists at project root
-- `wrangler.toml` syntax is valid (no errors when running `wrangler dev`)
-
-**Duration**: 2 minutes
-
-**Dependencies**: Task 1.4 complete
-
----
-
-### Task 2.2: Add Build Scripts to package.json
-**Description**: Add npm scripts for building and deploying Workers
-
-**Steps**:
-Add to `package.json` scripts section:
-
-```json
-"build:worker": "node esbuild.worker.js",
-"dev:worker": "wrangler dev",
-"deploy": "npm run build:worker && wrangler deploy"
-```
-
-**Validation**:
-- `npm run build:worker` command recognized (may fail until worker.ts exists)
-- All 3 scripts visible in `npm run`
-
-**Duration**: 2 minutes
-
-**Dependencies**: Task 2.1 complete
-
----
-
-### Task 2.3: Create esbuild.worker.js Configuration
-**Description**: Separate build config for Workers bundle (different from Node.js bundle)
-
-**Steps**:
-Create `esbuild.worker.js`:
-
-```javascript
-import esbuild from 'esbuild';
-
-await esbuild.build({
-  entryPoints: ['src/worker.ts'],
-  bundle: true,
-  outfile: 'dist/worker.js',
-  format: 'esm',
-  platform: 'browser',
-  target: 'es2022',
-  external: [],  // Bundle everything for Workers
-  minify: false,
-  sourcemap: false,
-});
-
-console.log('✓ Workers build complete');
-```
-
-**Validation**:
-- File exists in project root
-- Running `node esbuild.worker.js` shows error about missing `src/worker.ts` (expected at this stage)
-
-**Duration**: 3 minutes
-
-**Dependencies**: Task 2.2 complete
-
----
-
-## Phase 3: Code Implementation
-
-### Task 3.1: Create src/worker.ts Entry Point
-**Description**: Minimal Workers adapter that handles HTTP requests
-
-**Steps**:
-Create `src/worker.ts`:
-
-```typescript
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-
-export default {
-  async fetch(request: Request): Promise<Response> {
-    // Respond to health checks
-    if (request.method === 'GET' && new URL(request.url).pathname === '/health') {
-      return new Response(JSON.stringify({ status: 'ok', version: '0.4.0' }), {
-        headers: { 'Content-Type': 'application/json' }
-      });
-    }
-
-    // TODO: Implement MCP protocol handling
-    return new Response('CKAN MCP Server - Workers Mode', { status: 200 });
-  }
-};
-```
-
-**Validation**:
-- `npm run build:worker` succeeds
-- `dist/worker.js` created
-- File size < 100KB
-
-**Duration**: 5 minutes
-
-**Dependencies**: Task 2.3 complete
-
----
-
-### Task 3.2: Test Local Development Server
-**Description**: Run Workers locally to verify basic setup
-
-**Steps**:
-```bash
-npm run dev:worker
-```
-
-**What happens**:
-- Wrangler starts local server on http://localhost:8787
-- Terminal shows "Ready on http://localhost:8787"
-
-**Validation**:
-```bash
-curl http://localhost:8787/health
-```
-Returns: `{"status":"ok","version":"0.4.0"}`
-
-**Duration**: 2 minutes
-
-**Dependencies**: Task 3.1 complete
-
-**Note**: Keep wrangler dev running for next tasks
-
----
-
-### Task 3.3: Implement MCP Protocol Handler
-**Description**: Full Workers implementation with MCP server integration
-
-**Steps**:
-This is a larger task - update `src/worker.ts` to:
-1. Import MCP server and all tool registrations
-2. Handle POST /mcp endpoint
-3. Process MCP JSON-RPC requests
-4. Return JSON-RPC responses
-
-**Validation**:
-```bash
-# Test with curl (wrangler dev still running)
-curl -X POST http://localhost:8787/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
-Returns list of 7 CKAN tools
-
-**Duration**: 15-20 minutes
-
-**Dependencies**: Task 3.2 complete
-
-**Note**: We'll implement this together step-by-step
-
----
-
-### Task 3.4: Test All MCP Tools Locally
-**Description**: Verify each tool works in Workers environment
-
-**Steps**:
-Test each tool via curl:
-1. `ckan_status_show` - server connectivity
-2. `ckan_package_search` - basic search
-3. `ckan_package_show` - dataset details
-4. `ckan_organization_list` - list orgs
-5. `ckan_organization_show` - org details
-6. `ckan_organization_search` - search orgs
-7. `ckan_datastore_search` - datastore query
-
-**Validation**:
-- All 7 tools return expected responses
-- No HTTP 500 errors
-- Response times < 30 seconds
-
-**Duration**: 10 minutes
-
-**Dependencies**: Task 3.3 complete
-
----
-
-## Phase 4: Deployment and Documentation
-
-### Task 4.1: Deploy to Cloudflare Workers
-**Description**: First deployment to production Workers environment
-
-**Steps**:
-```bash
-npm run deploy
-```
-
-**What happens**:
-- Build runs (`npm run build:worker`)
-- Wrangler uploads to Cloudflare
-- Deployment URL shown: `https://ckan-mcp-server.<account>.workers.dev`
-
-**Validation**:
-```bash
-curl https://ckan-mcp-server.<account>.workers.dev/health
-```
-Returns: `{"status":"ok","version":"0.4.0"}`
-
-**Duration**: 3 minutes
-
-**Dependencies**: Task 3.4 complete, Tasks 1.1-1.3 complete
-
----
-
-### Task 4.2: Test Production Deployment
-**Description**: Verify all tools work in production Workers environment
-
-**Steps**:
-Same as Task 3.4, but using production URL:
-```bash
-curl -X POST https://ckan-mcp-server.<account>.workers.dev/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
-```
-
-Test all 7 tools with real CKAN portals:
-- dati.gov.it
-- demo.ckan.org
-- catalog.data.gov
-
-**Validation**:
-- All tools return correct results
-- HTTPS works (no certificate errors)
-- Global access (test from different network if possible)
-
-**Duration**: 10 minutes
-
-**Dependencies**: Task 4.1 complete
-
----
-
-### Task 4.3: Create Deployment Documentation
-**Description**: Write comprehensive deployment guide for contributors
-
-**Steps**:
-Create `docs/DEPLOYMENT.md` with:
-1. Prerequisites (Cloudflare account, wrangler CLI)
-2. Step-by-step deployment instructions
-3. Environment configuration
-4. Troubleshooting common issues
-5. Monitoring and logs access
-
-**Validation**:
-- File exists at `docs/DEPLOYMENT.md`
-- Includes code examples for all steps
-- Links to Cloudflare documentation
-
-**Duration**: 20 minutes
-
-**Dependencies**: Task 4.2 complete
-
----
-
-### Task 4.4: Update README.md
-**Description**: Add Workers deployment option to main README
-
-**Steps**:
-Add new "Deployment Options" section:
-
-```markdown
-## Deployment Options
-
-### Option 1: Local Installation (stdio mode)
-[existing instructions]
-
-### Option 2: Self-Hosted HTTP Server
-[existing instructions]
-
-### Option 3: Cloudflare Workers ⭐ NEW
-Deploy to Cloudflare's global edge network for public HTTP access.
-
-See [DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed instructions.
-
-**Quick start**:
-```bash
-npm install -g wrangler
-wrangler login
-npm run deploy
-```
-
-Public endpoint: `https://ckan-mcp-server.<account>.workers.dev`
-```
-
-**Validation**:
-- Section added after "Installation"
-- Links to DEPLOYMENT.md work
-- Code examples tested
-
-**Duration**: 10 minutes
-
-**Dependencies**: Task 4.3 complete
-
----
-
-### Task 4.5: Update LOG.md
-**Description**: Document deployment capability in changelog
-
-**Steps**:
-Add entry for today's date:
-
-```markdown
-## 2026-01-10
-
-### Cloudflare Workers Deployment
-- **Production deployment**: Server now available on Cloudflare Workers
-  - Public endpoint: `https://ckan-mcp-server.<account>.workers.dev`
-  - Global edge deployment (low latency worldwide)
-  - Free tier: 100k requests/day
-- **New files**: `src/worker.ts`, `wrangler.toml`, `esbuild.worker.js`
-- **New scripts**: `build:worker`, `dev:worker`, `deploy`
-- **Documentation**: Created DEPLOYMENT.md with step-by-step guide
-- **Testing**: All 7 MCP tools verified in Workers environment
-- **No breaking changes**: stdio and self-hosted HTTP modes still supported
-```
-
-**Validation**:
-- Entry added at top of LOG.md
-- Date is 2026-01-10
-- Includes deployment URL
-
-**Duration**: 3 minutes
-
-**Dependencies**: Task 4.4 complete
-
----
-
-### Task 4.6: Final Validation
-**Description**: End-to-end test with Claude Desktop
-
-**Steps**:
-1. Configure Claude Desktop to use Workers endpoint
-2. Test MCP integration with all tools
-3. Verify response formatting (markdown/json)
-4. Check error handling
-
-**Validation**:
-- Claude Desktop successfully connects to Workers endpoint
-- All tools accessible from Claude interface
-- Responses properly formatted
-- No unexpected errors
-
-**Duration**: 10 minutes
-
-**Dependencies**: All previous tasks complete
-
----
-
-## Total Estimated Time
-
-- **Phase 1**: 10 minutes (setup)
-- **Phase 2**: 7 minutes (configuration)
-- **Phase 3**: 32-37 minutes (implementation)
-- **Phase 4**: 56 minutes (deployment + docs)
-
-**Total**: ~1.5 - 2 hours (excluding breaks and troubleshooting)
-
----
-
-## Dependencies Graph
-
-```
-Phase 1: Setup
-├─ 1.1 Install Wrangler CLI
-├─ 1.2 Create Cloudflare Account (optional)
-├─ 1.3 Authenticate Wrangler (requires 1.2)
-└─ 1.4 Install Wrangler Locally (requires 1.1)
-
-Phase 2: Configuration (requires 1.4)
-├─ 2.1 Create wrangler.toml
-├─ 2.2 Add Build Scripts (requires 2.1)
-└─ 2.3 Create esbuild.worker.js (requires 2.2)
-
-Phase 3: Implementation (requires 2.3)
-├─ 3.1 Create src/worker.ts
-├─ 3.2 Test Local Dev Server (requires 3.1)
-├─ 3.3 Implement MCP Handler (requires 3.2)
-└─ 3.4 Test All Tools (requires 3.3)
-
-Phase 4: Deployment (requires 3.4 + 1.1-1.3)
-├─ 4.1 Deploy to Workers
-├─ 4.2 Test Production (requires 4.1)
-├─ 4.3 Create DEPLOYMENT.md (requires 4.2)
-├─ 4.4 Update README.md (requires 4.3)
-├─ 4.5 Update LOG.md (requires 4.4)
-└─ 4.6 Final Validation (requires 4.5)
-```
-
----
-
-## Parallel Work Opportunities
-
-These tasks can be done in parallel to save time:
-
-- **During Phase 1**: While waiting for Cloudflare account verification (1.2), install Wrangler CLI (1.1)
-- **During Phase 3.2**: While wrangler dev is running, can start writing worker.ts implementation (3.3)
-- **During Phase 4**: Documentation tasks (4.3, 4.4, 4.5) can be drafted while deployment is in progress
-
----
-
-## Rollback Plan
-
-If deployment fails or issues arise:
-
-1. **Workers deployment fails**: Keep using stdio/http modes (no breaking changes)
-2. **Bundle too large**: Analyze with `esbuild --metafile` and remove unused code
-3. **Runtime errors**: Use `wrangler tail` to view live logs and debug
-4. **Rate limit exceeded**: User deploys own Workers instance (fork + deploy)
-
-Each task is reversible - can revert by:
-- Deleting new files (worker.ts, wrangler.toml, esbuild.worker.js)
-- Removing npm scripts from package.json
-- Running `wrangler delete` to remove Workers deployment

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

@@ -1,13 +0,0 @@
-# Change: Add MCP Guided Prompts
-
-## Why
-Users often need guidance to use CKAN tools correctly; guided prompts reduce misuse and speed up discovery workflows.
-
-## What Changes
-- Add a new MCP prompts capability with reusable guided prompts for common tasks.
-- Register prompts in the MCP server so clients can discover and invoke them.
-- Document prompts and examples in README/docs.
-
-## Impact
-- Affected specs: mcp-prompts (new)
-- Affected code: `src/server.ts`, new `src/prompts/*`, docs/README

package/openspec/changes/archive/2026-01-15-add-mcp-prompts/specs/mcp-prompts/spec.md

@@ -1,22 +0,0 @@
-## ADDED 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/changes/archive/2026-01-15-add-mcp-prompts/tasks.md

@@ -1,10 +0,0 @@
-## 1. Implementation
-- [x] Add prompt generators for guided search workflows (theme, organization, format, recent datasets, dataset analysis)
-- [x] Register prompts in MCP server for discovery
-- [x] Update README/docs with prompt usage examples
-
-## 2. Tests
-- [x] Add unit tests for prompt output structure and parameters
-
-## 3. Validation
-- [x] Run `npm test` (optional if CI)

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

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

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

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

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

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

@@ -1,12 +0,0 @@
-## 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/changes/archive/2026-01-19-update-search-parser-config/proposal.md

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