@aborruso/ckan-mcp-server 0.4.4 → 0.4.6

package/openspec/changes/add-ckan-analyze-dataset-structure/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_analyze_dataset_structure tool
+
+## Why
+Users need quick schema and quality signals without manual inspection.
+
+## What Changes
+- Add MCP tool `ckan_analyze_dataset_structure` for schema summaries.
+- Use resource schema or DataStore fields for columns and types.
+- Compute null-rate stats when DataStore is available.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/datastore.ts` and resource utilities
+
+## Open Questions
+- Default `sample_size` for null-rate analysis?
+- How to select resource when only dataset id is provided?

package/openspec/changes/add-ckan-analyze-dataset-structure/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Analyze dataset structure
+The system SHALL provide a `ckan_analyze_dataset_structure` tool that accepts `server_url`, a `resource_id` or `dataset_id`, and optional `sample_size`, returning column names and types; when a DataStore is available it MUST compute per-column null rates from a sampled query.
+
+#### Scenario: Schema summary with null rates
+- **WHEN** the tool is invoked for a DataStore-enabled resource
+- **THEN** the system returns columns, types, and null-rate statistics

package/openspec/changes/add-ckan-analyze-dataset-structure/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Resolve resource selection (resource_id or dataset)
+- [ ] 1.3 Compute schema summary + null rates
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-analyze-dataset-updates/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_analyze_dataset_updates tool
+
+## Why
+Users need quick insight on dataset freshness and update cadence.
+
+## What Changes
+- Add MCP tool `ckan_analyze_dataset_updates` for dataset freshness analysis.
+- Combine `metadata_modified` and resource `last_modified` to estimate cadence.
+- Flag stale datasets based on a configurable threshold.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/package.ts` and `src/tools/datastore.ts`
+
+## Open Questions
+- Default `stale_days` threshold?
+- How to handle resources without `last_modified`?

package/openspec/changes/add-ckan-analyze-dataset-updates/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Analyze dataset updates
+The system SHALL provide a `ckan_analyze_dataset_updates` tool that accepts `server_url`, `dataset_id`, and optional `stale_days`, and returns update cadence based on `metadata_modified` and resource `last_modified`, including a `stale` flag when the most recent update exceeds the threshold.
+
+#### Scenario: Update cadence and stale flag
+- **WHEN** the tool is invoked with a dataset id and stale threshold
+- **THEN** the system returns last update timestamps, cadence summary, and a stale flag

package/openspec/changes/add-ckan-analyze-dataset-updates/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Compute update cadence from metadata/resource dates
+- [ ] 1.3 Add stale detection output
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-audit-tool/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_audit tool
+
+## Why
+Operators need an automated probe to detect datastore/SQL/alias support and capture portal quirks.
+
+## What Changes
+- Add MCP tool `ckan_audit` to probe CKAN API capabilities.
+- Detect DataStore availability, SQL endpoint, and datastore id alias support.
+- Return suggested overrides for portal configuration.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/status.ts` or new insights module
+
+## Open Questions
+- Should audit run only read-only GET probes?
+- Which overrides format to return (JSON block vs markdown list)?

package/openspec/changes/add-ckan-audit-tool/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Audit CKAN portal capabilities
+The system SHALL provide a `ckan_audit` tool that accepts `server_url` and returns detected capabilities for DataStore, SQL endpoint availability, and datastore id alias support, plus suggested portal override values.
+
+#### Scenario: Capability probe
+- **WHEN** the tool probes a CKAN portal
+- **THEN** the response includes datastore availability, SQL support, alias support, and recommended overrides

package/openspec/changes/add-ckan-audit-tool/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Probe datastore_search and datastore_search_sql
+- [ ] 1.3 Detect datastore id alias support
+- [ ] 1.4 Return override suggestions
+- [ ] 1.5 Add fixtures + tests

package/openspec/changes/add-ckan-dataset-insights/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_dataset_insights tool
+
+## Why
+Users want a single call that returns ranked datasets plus freshness and structure insights.
+
+## What Changes
+- Add MCP tool `ckan_dataset_insights` as a wrapper.
+- Combine outputs from `ckan_find_relevant_datasets`, `ckan_analyze_dataset_updates`, and `ckan_analyze_dataset_structure`.
+- Provide compact summary per dataset.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: new insights module orchestrating existing tools
+
+## Open Questions
+- Default number of datasets to enrich?
+- Should structure analysis be optional for non-DataStore resources?

package/openspec/changes/add-ckan-dataset-insights/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Dataset insights wrapper
+The system SHALL provide a `ckan_dataset_insights` tool that accepts `server_url`, `query`, `limit`, and optional analysis parameters, and returns per-dataset summaries combining relevance scores, update cadence, and structure metrics.
+
+#### Scenario: Combined insights output
+- **WHEN** the tool is invoked with a query and limit
+- **THEN** the system returns the top N datasets with combined relevance, update, and structure insights

package/openspec/changes/add-ckan-dataset-insights/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Orchestrate find/update/structure analyses
+- [ ] 1.3 Define merged output format
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-find-relevant-datasets/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_find_relevant_datasets tool
+
+## Why
+Ranked discovery helps surface the best datasets for a query without manual sorting.
+
+## What Changes
+- Add MCP tool `ckan_find_relevant_datasets` wrapping `package_search`.
+- Score results using weighted fields (title, notes, tags, organization).
+- Return top N datasets with score breakdown.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/package.ts` (or new insights module)
+
+## Open Questions
+- Default weights for title/notes/tags/organization?
+- Default `limit` when omitted?

package/openspec/changes/add-ckan-find-relevant-datasets/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### 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/openspec/changes/add-ckan-find-relevant-datasets/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Implement weighted scoring + ranking
+- [ ] 1.3 Define markdown/json output shape
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

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

@@ -0,0 +1,12 @@
+# ckan-insights Specification
+
+## 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.
+
+#### Scenario: Insight tools documented
+- **WHEN** new insight tools are implemented
+- **THEN** their requirements are captured in this specification

package/openspec/specs/cloudflare-deployment/spec.md

@@ -0,0 +1,344 @@
+# cloudflare-deployment Specification
+
+## Purpose
+TBD - created by archiving change add-cloudflare-workers. Update Purpose after archive.
+## Requirements
+### Requirement: Workers Entry Point
+
+The system SHALL provide a Cloudflare Workers-compatible entry point that handles HTTP requests using the Workers fetch API.
+
+#### Scenario: Health check endpoint
+
+- **WHEN** client sends `GET /health` to Workers endpoint
+- **THEN** server returns JSON with status, version, tool count, and resource count
+
+#### Scenario: MCP protocol endpoint
+
+- **WHEN** client sends `POST /mcp` with JSON-RPC request to Workers endpoint
+- **THEN** server processes MCP request and returns JSON-RPC response
+
+#### Scenario: Invalid route
+
+- **WHEN** client requests any path other than `/health` or `/mcp`
+- **THEN** server returns 404 Not Found
+
+#### Scenario: Invalid method on MCP endpoint
+
+- **WHEN** client sends non-POST request to `/mcp`
+- **THEN** server returns 404 Not Found
+
+---
+
+### Requirement: MCP Server Integration
+
+The system SHALL initialize MCP server instance on each Workers invocation and register all tools and resources.
+
+#### Scenario: Server initialization
+
+- **WHEN** Workers receives MCP request
+- **THEN** server creates MCP Server instance with name "ckan-mcp-server" and version "0.4.0"
+
+#### Scenario: Tool registration
+
+- **WHEN** Workers initializes MCP server
+- **THEN** server registers all 7 CKAN tools (package_search, package_show, organization_list, organization_show, organization_search, datastore_search, status_show)
+
+#### Scenario: Resource registration
+
+- **WHEN** Workers initializes MCP server
+- **THEN** server registers all 3 resource templates (dataset, resource, organization)
+
+#### Scenario: Tools list request
+
+- **WHEN** client calls `tools/list` method via Workers endpoint
+- **THEN** response includes all 7 registered CKAN tools with descriptions
+
+---
+
+### Requirement: Web Standards HTTP Client
+
+The system SHALL use native Web Fetch API for CKAN API requests instead of Node.js-specific libraries.
+
+#### Scenario: CKAN API request with fetch
+
+- **WHEN** tool calls `makeCkanRequest()` in Workers runtime
+- **THEN** client uses native `fetch()` with 30-second timeout
+
+#### Scenario: Query parameter encoding
+
+- **WHEN** CKAN request includes parameters (e.g., `q`, `rows`, `start`)
+- **THEN** client encodes parameters in URL using `URLSearchParams`
+
+#### Scenario: Request timeout
+
+- **WHEN** CKAN API takes longer than 30 seconds
+- **THEN** client aborts request using `AbortController` and returns timeout error
+
+#### Scenario: HTTP error handling
+
+- **WHEN** CKAN API returns HTTP error status (4xx, 5xx)
+- **THEN** client throws error with status code and message
+
+#### Scenario: CKAN API validation
+
+- **WHEN** CKAN API returns 200 OK but `success: false`
+- **THEN** client throws error with CKAN error message
+
+---
+
+### Requirement: Workers Build Configuration
+
+The system SHALL provide separate build configuration for Workers deployment targeting browser platform with ESM format.
+
+#### Scenario: Workers build script
+
+- **WHEN** user runs `npm run build:worker`
+- **THEN** esbuild compiles `src/worker.ts` to `dist/worker.js` in ESM format
+
+#### Scenario: Bundle all dependencies
+
+- **WHEN** esbuild builds Workers bundle
+- **THEN** all dependencies are bundled (no external modules)
+
+#### Scenario: Platform targeting
+
+- **WHEN** esbuild builds Workers bundle
+- **THEN** platform is set to `browser` and target is `es2022`
+
+#### Scenario: Output format
+
+- **WHEN** Workers build completes
+- **THEN** output is ESM format (not CommonJS)
+
+#### Scenario: Bundle size validation
+
+- **WHEN** Workers build completes
+- **THEN** bundle size is less than 1MB (Workers script size limit)
+
+---
+
+### Requirement: Wrangler Configuration
+
+The system SHALL provide Wrangler configuration file for Workers deployment and local development.
+
+#### Scenario: Wrangler configuration file
+
+- **WHEN** project contains `wrangler.toml` in root directory
+- **THEN** configuration specifies name, main entry point, and compatibility date
+
+#### Scenario: Build command
+
+- **WHEN** `wrangler deploy` or `wrangler dev` runs
+- **THEN** Wrangler executes `npm run build:worker` before deployment
+
+#### Scenario: Local development server
+
+- **WHEN** user runs `npm run dev:worker`
+- **THEN** Wrangler starts local Workers server on http://localhost:8787
+
+---
+
+### Requirement: Workers Deployment
+
+The system SHALL deploy to Cloudflare Workers and provide public HTTPS endpoint.
+
+#### Scenario: Deploy to Workers
+
+- **WHEN** user runs `npm run deploy`
+- **THEN** Wrangler builds and uploads worker to Cloudflare
+
+#### Scenario: Public endpoint
+
+- **WHEN** deployment succeeds
+- **THEN** Workers script is accessible at `https://ckan-mcp-server.<account>.workers.dev`
+
+#### Scenario: HTTPS support
+
+- **WHEN** client accesses Workers endpoint
+- **THEN** connection uses HTTPS with valid certificate
+
+---
+
+### Requirement: Tool Functionality Preservation
+
+The system SHALL maintain identical functionality for all CKAN tools in Workers runtime compared to Node.js runtime.
+
+#### Scenario: Package search in Workers
+
+- **WHEN** client calls `ckan_package_search` via Workers endpoint
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Datastore query in Workers
+
+- **WHEN** client calls `ckan_datastore_search` via Workers endpoint
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Resource template in Workers
+
+- **WHEN** client reads `ckan://{server}/dataset/{id}` via Workers
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Error handling in Workers
+
+- **WHEN** CKAN API is unreachable in Workers runtime
+- **THEN** error response matches Node.js runtime error format
+
+---
+
+### Requirement: Response Format Compatibility
+
+The system SHALL support both markdown and JSON output formats in Workers runtime.
+
+#### Scenario: Markdown format
+
+- **WHEN** client requests tool with `response_format: "markdown"`
+- **THEN** Workers returns formatted markdown text
+
+#### Scenario: JSON format
+
+- **WHEN** client requests tool with `response_format: "json"`
+- **THEN** Workers returns raw JSON data
+
+#### Scenario: Character limit
+
+- **WHEN** response exceeds CHARACTER_LIMIT (50000 characters)
+- **THEN** Workers truncates response identically to Node.js runtime
+
+---
+
+### Requirement: Error Handling
+
+The system SHALL handle Workers-specific errors gracefully with JSON-RPC error responses.
+
+#### Scenario: Malformed JSON-RPC request
+
+- **WHEN** client sends invalid JSON to `/mcp` endpoint
+- **THEN** Workers returns JSON-RPC error with code -32700 (Parse error)
+
+#### Scenario: Internal worker error
+
+- **WHEN** worker encounters unexpected exception
+- **THEN** Workers returns JSON-RPC error with code -32603 (Internal error)
+
+#### Scenario: Method not found
+
+- **WHEN** client calls non-existent MCP method
+- **THEN** Workers returns JSON-RPC error with code -32601 (Method not found)
+
+---
+
+### Requirement: CORS Support
+
+The system SHALL include CORS headers to enable browser-based MCP clients.
+
+#### Scenario: CORS headers on success
+
+- **WHEN** Workers returns successful response
+- **THEN** response includes `Access-Control-Allow-Origin: *` header
+
+#### Scenario: CORS headers on error
+
+- **WHEN** Workers returns error response
+- **THEN** response includes `Access-Control-Allow-Origin: *` header
+
+#### Scenario: Preflight request
+
+- **WHEN** browser sends OPTIONS request for CORS preflight
+- **THEN** Workers returns allowed methods and headers
+
+---
+
+### Requirement: Deployment Documentation
+
+The system SHALL provide comprehensive documentation for deploying to Cloudflare Workers.
+
+#### Scenario: Deployment guide
+
+- **WHEN** contributor wants to deploy Workers instance
+- **THEN** `docs/DEPLOYMENT.md` provides step-by-step instructions
+
+#### Scenario: Prerequisites documentation
+
+- **WHEN** contributor reads DEPLOYMENT.md
+- **THEN** document lists all prerequisites (Cloudflare account, wrangler CLI)
+
+#### Scenario: Troubleshooting guide
+
+- **WHEN** deployment fails
+- **THEN** DEPLOYMENT.md includes common errors and solutions
+
+#### Scenario: README update
+
+- **WHEN** user reads README.md
+- **THEN** deployment options section includes Cloudflare Workers option
+
+---
+
+### Requirement: Backwards Compatibility
+
+The system SHALL maintain all existing deployment modes (stdio, self-hosted HTTP) without breaking changes.
+
+#### Scenario: Stdio mode unchanged
+
+- **WHEN** user runs `npm start` after Workers implementation
+- **THEN** stdio transport works identically to pre-Workers version
+
+#### Scenario: Self-hosted HTTP mode unchanged
+
+- **WHEN** user runs `TRANSPORT=http PORT=3000 npm start` after Workers implementation
+- **THEN** HTTP server works identically to pre-Workers version
+
+#### Scenario: Existing tests pass
+
+- **WHEN** user runs `npm test` after Workers implementation
+- **THEN** all 113 existing tests pass without modification
+
+#### Scenario: Node.js bundle unchanged
+
+- **WHEN** user runs `npm run build` after Workers implementation
+- **THEN** Node.js bundle (`dist/index.js`) is unchanged
+
+---
+
+### Requirement: Development Workflow
+
+The system SHALL support efficient local development and testing of Workers deployment.
+
+#### Scenario: Local Workers testing
+
+- **WHEN** developer runs `npm run dev:worker`
+- **THEN** wrangler starts local server with hot reload
+
+#### Scenario: Quick iteration
+
+- **WHEN** developer modifies `src/worker.ts`
+- **THEN** wrangler automatically rebuilds and reloads
+
+#### Scenario: curl testing
+
+- **WHEN** developer sends curl request to local Workers
+- **THEN** response matches expected MCP protocol format
+
+---
+
+### Requirement: Monitoring and Debugging
+
+The system SHALL provide access to Workers logs and metrics for troubleshooting.
+
+#### Scenario: Real-time logs
+
+- **WHEN** developer runs `wrangler tail`
+- **THEN** console.log output from worker appears in terminal
+
+#### Scenario: Error logs
+
+- **WHEN** worker throws exception
+- **THEN** stack trace appears in `wrangler tail` output
+
+#### Scenario: Cloudflare dashboard
+
+- **WHEN** user accesses Cloudflare Workers dashboard
+- **THEN** metrics show request count, error rate, and CPU time
+
+---
+

package/package.json

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