@aborruso/ckan-mcp-server 0.3.2 → 0.4.1

package/openspec/changes/add-cloudflare-workers/proposal.md

@@ -0,0 +1,183 @@
+# Proposal: Add Cloudflare Workers Deployment
+
+## Change ID
+`add-cloudflare-workers`
+
+## Summary
+Enable deployment of CKAN MCP Server to Cloudflare Workers platform, providing global HTTP access to the server without requiring local installation.
+
+## Motivation
+
+### Problem
+Currently, CKAN MCP Server can only run:
+- Locally via stdio mode (Claude Desktop integration)
+- Self-hosted via HTTP mode (requires Node.js runtime, port management, server maintenance)
+
+This limits accessibility for users who want to use the server remotely without managing infrastructure.
+
+### Solution
+Deploy to Cloudflare Workers - a serverless platform ideal for this use case:
+- **Stateless architecture**: Server makes no persistent state (only API calls to CKAN)
+- **Read-only operations**: All tools are GET-only, perfect for edge deployment
+- **Lightweight**: Small bundle size (~50KB), fast cold starts
+- **Free tier**: 100k requests/day sufficient for typical usage
+- **Global edge**: Low latency worldwide
+- **Zero maintenance**: No server management required
+
+### Alternatives Considered
+- **Railway** ($5/month credit): Overkill for stateless app, requires VM management
+- **Fly.io** (3 free VMs): More infrastructure than needed
+- **Render** (free tier): Spin-down after inactivity causes poor UX for MCP clients
+
+## Goals
+
+### Primary
+- [ ] Deploy server to Cloudflare Workers
+- [ ] Preserve all existing functionality (7 MCP tools, 3 resource templates)
+- [ ] Provide public HTTPS endpoint: `https://ckan-mcp-server.<account>.workers.dev`
+- [ ] Maintain stdio and self-hosted HTTP modes (no breaking changes)
+
+### Secondary
+- [ ] Document deployment process for contributors
+- [ ] Add deployment scripts to package.json
+- [ ] Test with multiple CKAN portals (dati.gov.it, data.gov, demo.ckan.org)
+
+### Non-Goals
+- Authentication/authorization (public read-only access is acceptable)
+- Custom domain setup (workers.dev subdomain is sufficient)
+- Rate limiting beyond Cloudflare's default (100k req/day is adequate)
+- WebSocket support (MCP over HTTP uses SSE, which Workers supports)
+
+## Impact Analysis
+
+### Code Changes
+- **New files**:
+  - `src/worker.ts` (~80-100 lines): Workers entry point
+  - `wrangler.toml` (~15 lines): Cloudflare configuration
+  - `docs/DEPLOYMENT.md` (~100 lines): Deployment guide
+- **Modified files**:
+  - `package.json`: Add wrangler scripts and devDependency
+  - `esbuild.config.js`: Add Workers build target (or create separate config)
+  - `README.md`: Add deployment section
+  - `LOG.md`: Document deployment capability
+
+### Build System
+- Add `wrangler` CLI as devDependency
+- Create separate esbuild config for Workers (different entry point, output format)
+- Workers build: `src/worker.ts` → `dist/worker.js` (ESM format, bundled)
+- Existing builds unchanged (stdio/http modes still work)
+
+### Testing
+- Manual testing required: Deploy to workers.dev and test all 7 tools
+- Integration tests already cover tool functionality
+- No new automated tests needed (same MCP server logic)
+
+### Documentation
+- New `docs/DEPLOYMENT.md`: Step-by-step deployment guide
+- Update `README.md`: Add "Deployment" section with 3 options (local, self-hosted, Cloudflare)
+- Update `docs/future-ideas.md`: Move item from backlog to implemented
+
+### Dependencies
+- **New devDependency**: `wrangler` (Cloudflare CLI)
+- **No new runtime dependencies**: Workers runtime provides fetch/Request/Response APIs
+
+## User Experience
+
+### Before
+Users must:
+1. Install Node.js and npm
+2. Clone repository or install via npm
+3. Run server locally (stdio or HTTP mode)
+4. Configure Claude Desktop with local path
+
+### After (Option 3)
+Users can:
+1. Use public endpoint directly: `https://ckan-mcp-server.<account>.workers.dev`
+2. Configure Claude Desktop with HTTP URL (no local installation)
+3. Access from any MCP client supporting HTTP transport
+
+**Benefit**: Zero installation for end users who just want to query CKAN portals.
+
+### For Contributors
+Contributors can:
+1. Fork repository
+2. Run `npm run deploy` (after Cloudflare account setup)
+3. Get personal Workers deployment for testing
+
+## Risks and Mitigations
+
+### Risk: API Rate Limits
+- **Issue**: Cloudflare free tier limits to 100k req/day
+- **Likelihood**: Low (typical usage << 100k/day)
+- **Mitigation**: Document rate limits; users can deploy own Workers instance
+
+### Risk: Workers Runtime Compatibility
+- **Issue**: Node.js APIs may not work in Workers environment
+- **Likelihood**: Low (server uses standard fetch/HTTP APIs)
+- **Mitigation**: Test thoroughly; Workers supports most standard Web APIs
+
+### Risk: Bundle Size Limits
+- **Issue**: Workers free tier limits script size to 1MB
+- **Likelihood**: Very low (current bundle ~50KB)
+- **Mitigation**: Bundle analysis, treeshaking with esbuild
+
+### Risk: Cold Start Latency
+- **Issue**: First request after idle period may be slower
+- **Likelihood**: Medium (Workers spin down after inactivity)
+- **Mitigation**: Document expected latency; acceptable for MCP use case
+
+## Success Criteria
+
+### Must Have
+- [ ] Server deploys successfully to Cloudflare Workers
+- [ ] All 7 MCP tools work identically to local/self-hosted modes
+- [ ] Public HTTPS endpoint accessible from Claude Desktop
+- [ ] Response times < 5 seconds for typical CKAN queries
+- [ ] Documentation complete (DEPLOYMENT.md with screenshots)
+
+### Nice to Have
+- [ ] Deployment CI/CD via GitHub Actions
+- [ ] Monitoring/analytics dashboard
+- [ ] Multiple environment support (dev, staging, prod)
+
+## Timeline Estimate
+
+**Total**: 4-6 hours of focused work (spread over multiple sessions for user learning)
+
+### Phase 1: Setup and Configuration (1-2 hours)
+- Install wrangler CLI
+- Create Cloudflare account (free)
+- Initialize Workers project
+- Configure wrangler.toml
+
+### Phase 2: Code Adaptation (1-2 hours)
+- Create src/worker.ts adapter
+- Update build configuration
+- Test local build with `wrangler dev`
+
+### Phase 3: Deployment and Testing (1 hour)
+- Deploy to workers.dev
+- Test all 7 tools with curl/Claude Desktop
+- Verify with multiple CKAN portals
+
+### Phase 4: Documentation (1 hour)
+- Write DEPLOYMENT.md
+- Update README.md
+- Add LOG.md entry
+
+## Open Questions
+
+1. **Cloudflare Account**: Do you already have a Cloudflare account, or do we need to create one?
+2. **Workers Subdomain**: Are you okay with `ckan-mcp-server.<account>.workers.dev`, or do you want a custom workers.dev name?
+3. **Public Access**: Are you comfortable with the endpoint being publicly accessible (read-only, no auth)?
+4. **Environment Variables**: Do we need any configurable settings (e.g., default CKAN server, rate limits)?
+
+## Next Steps
+
+1. User reviews and approves this proposal
+2. User answers open questions
+3. Create `tasks.md` with ordered, step-by-step work items
+4. Create `design.md` with architectural details
+5. Create spec delta in `specs/cloudflare-deployment/spec.md`
+6. Validate proposal with `openspec validate add-cloudflare-workers --strict`
+7. Begin implementation in `openspec:apply` phase (only after approval)

package/openspec/changes/add-cloudflare-workers/specs/cloudflare-deployment/spec.md

@@ -0,0 +1,389 @@
+# cloudflare-deployment Specification
+
+## Purpose
+Enable deployment of CKAN MCP Server to Cloudflare Workers platform, providing global HTTP access without local installation or server management.
+
+## ADDED 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
+
+---
+
+## Related Specifications
+
+- **mcp-resources**: Resource templates must work in Workers runtime
+- **documentation-language**: Deployment docs must be in English
+
+---
+
+## Implementation Notes
+
+### HTTP Client Migration
+- Replace `axios` with `fetch()` in `src/utils/http.ts`
+- Use `AbortController` for timeout (same 30s limit)
+- Maintain identical error handling behavior
+
+### Build System
+- Add `esbuild.worker.js` for Workers-specific build
+- Keep existing `esbuild.config.js` for Node.js build
+- Add npm scripts: `build:worker`, `dev:worker`, `deploy`
+
+### Testing Approach
+- Manual testing with `wrangler dev` and curl
+- Production testing after deployment
+- Claude Desktop integration test
+- Existing test suite validates tool logic (no new tests needed)
+
+### Deployment Process
+1. User creates Cloudflare account (free)
+2. User installs wrangler CLI
+3. User authenticates: `wrangler login`
+4. User builds: `npm run build:worker`
+5. User deploys: `wrangler deploy`
+6. User gets endpoint: `https://ckan-mcp-server.<account>.workers.dev`
+
+### Bundle Size Optimization
+- Remove `axios` dependency (save ~15KB)
+- Use esbuild tree-shaking
+- Minify Workers bundle
+- Target: < 50KB (well below 1MB limit)
+
+### Future Enhancements
+- Add Workers KV caching (documented in future-ideas.md)
+- Support custom domains (documented in future-ideas.md)
+- Add API key authentication via Workers secrets (documented in future-ideas.md)