@aborruso/ckan-mcp-server 0.4.9 → 0.4.10

package/.devin/wiki.json

@@ -0,0 +1,273 @@
+{
+  "repo_notes": [
+    {
+      "content": ""
+    }
+  ],
+  "pages": [
+    {
+      "title": "Overview",
+      "purpose": "Introduce the CKAN MCP Server system, explaining its purpose as a Model Context Protocol server that enables AI agents to interact with 500+ CKAN open data portals worldwide through natural language and structured queries",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Key Features",
+      "purpose": "Highlight the main capabilities: 15+ CKAN tools, dual runtime support, MCP Resource Templates, and global edge deployment",
+      "parent": "Overview",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Architecture Overview",
+      "purpose": "Provide a high-level architectural diagram showing the two-tier system: MCP Server Core and CKAN Portals, plus the dual deployment model",
+      "parent": "Overview",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Getting Started",
+      "purpose": "Guide users through the fastest path to using the system based on their needs and technical expertise",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Claude Desktop Setup",
+      "purpose": "Configure Claude Desktop to use the MCP server via stdio (local) or HTTP (remote/Workers) transport modes",
+      "parent": "Getting Started",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Installation Options",
+      "purpose": "Compare the three deployment options: npm global install, Cloudflare Workers, and self-hosted HTTP server",
+      "parent": "Getting Started",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Architecture",
+      "purpose": "Deep dive into the system architecture, component relationships, and design decisions",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "System Components",
+      "purpose": "Explain the modular architecture: entry points, transport layer, server core, tool handlers, resource templates, and utilities",
+      "parent": "Architecture",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "MCP Server Core",
+      "purpose": "Explain the MCP server implementation: tool registration system, request routing, Zod validation, and error handling",
+      "parent": "Architecture",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Transport Layer",
+      "purpose": "Document the three transport modes: stdio (12 lines), HTTP (27 lines), and Cloudflare Workers WebStandardStreamable, explaining how the same tools run across different runtimes",
+      "parent": "Architecture",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Tool Layer",
+      "purpose": "Describe the tool implementation pattern: Zod schemas, handler functions, makeCkanRequest abstraction, and output formatting (1,465+ lines of business logic)",
+      "parent": "Architecture",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Dual Runtime Design",
+      "purpose": "Explain how the same codebase runs on Node.js and Cloudflare Workers V8 isolates, including build targets, bundle sizes, and runtime differences",
+      "parent": "Architecture",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "User Guides",
+      "purpose": "Practical guides for end users interacting with CKAN data through the system",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Querying CKAN Data",
+      "purpose": "Guide to common CKAN queries: searching datasets, exploring organizations, querying DataStore, using facets, and understanding Solr syntax",
+      "parent": "User Guides",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Advanced Search Techniques",
+      "purpose": "Document Solr query syntax: fuzzy search (~N), proximity search (\"phrase\"~N), boosting (^N), range queries, date math, wildcards, and boolean operators",
+      "parent": "User Guides",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "DataStore Queries",
+      "purpose": "Explain DataStore functionality: basic key-value filtering, SQL queries, field selection, sorting, pagination, and the 32,000 record limit",
+      "parent": "User Guides",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Working with Organizations",
+      "purpose": "Guide to organization tools: listing with package counts, searching by pattern, retrieving details, and understanding organizational hierarchies",
+      "parent": "User Guides",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Tool Reference",
+      "purpose": "Complete reference documentation for all 15+ MCP tools with parameters, return types, and usage examples",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Dataset Tools",
+      "purpose": "Document ckan_package_search, ckan_find_relevant_datasets, ckan_package_show, ckan_package_list with detailed parameter descriptions and examples",
+      "parent": "Tool Reference",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Organization Tools",
+      "purpose": "Document ckan_organization_list, ckan_organization_show, ckan_organization_search with sorting, pagination, and filtering options",
+      "parent": "Tool Reference",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "DataStore Tools",
+      "purpose": "Document ckan_datastore_search and ckan_datastore_search_sql with filtering syntax, SQL query examples, and limit constraints",
+      "parent": "Tool Reference",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Metadata Tools",
+      "purpose": "Document ckan_tag_list, ckan_group_list, ckan_group_show, ckan_group_search, and ckan_status_show for portal exploration",
+      "parent": "Tool Reference",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "MCP Resource Templates",
+      "purpose": "Explain the ckan:// URI scheme for accessing datasets, resources, and organizations via MCP Resource Templates",
+      "parent": "Tool Reference",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Developer Guide",
+      "purpose": "Guide for developers who want to modify, extend, or contribute to the codebase",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Project Structure",
+      "purpose": "Document the codebase organization: src/ structure, tool modules (1,465+ lines), utilities (138+ lines), resources (50+ lines), and test organization (2,340 lines)",
+      "parent": "Developer Guide",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Adding New Tools",
+      "purpose": "Step-by-step guide to implementing a new MCP tool: defining Zod schemas, creating handlers, using makeCkanRequest, formatting outputs, and registering with the server",
+      "parent": "Developer Guide",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    },
+    {
+      "title": "Utility Functions",
+      "purpose": "Document the utility layer: makeCkanRequest (51 lines, 98.59% coverage), formatting functions (37 lines, 98% coverage), query resolution, and URL generation",
+      "parent": "Developer Guide",
+      "page_notes": [
+        {
+          "content": ""
+        }
+      ]
+    }
+  ]
+}

package/AGENTS.md

@@ -33,173 +33,68 @@ Keep this managed block so 'openspec update' can refresh the instructions.
 
 - No `.cursor/rules`, `.cursorrules`, or `.github/copilot-instructions.md` found
 
-## Core Commands
+## Commands
 
-Install deps:
+**Install**: `npm install`
 
-```bash
-npm install
-```
+**Build**: `npm run build` | `npm run build:tsc` | `npm run build:worker`
 
-Build (node bundle):
-
-```bash
-npm run build
-```
+**Run**: `npm start` | `npm run dev` | `npm run watch` | `npm run dev:worker` | `npm run deploy`
 
-Build (worker bundle):
+**Test**: `npm test` | `npm run test:watch` | `npm run test:coverage`
 
-```bash
-npm run build:worker
-```
+**Single test**: `npm test -- tests/unit/http.test.ts` | `npm test -- -t "testName"`
 
-TypeScript build (tsc):
+## TypeScript Style
 
-```bash
-npm run build:tsc
-```
+Use strict typing, avoid `any` unless from CKAN payloads. Prefer explicit return types, `type` aliases, ESM imports with `.js` extensions. Keep `noUnusedLocals` and `noUnusedParameters` clean.
 
-Start server (stdio or HTTP via env):
+## Import Conventions
 
-```bash
-npm start
-```
+Use `import type` for type-only imports. Group by kind: external, internal, types. Double quotes, relative paths.
 
-Dev build + run:
+## Naming
 
-```bash
-npm run dev
-```
+`camelCase` vars/functions, `PascalCase` types/classes, `UPPER_SNAKE_CASE` constants. Tool names match MCP tool ids.
 
-Watch build:
+## Error Handling
 
-```bash
-npm run watch
-```
+Wrap tool handlers in `try/catch`. Return `{ isError: true }` for MCP errors. Include context, map HTTP errors to readable messages, preserve cause when rethrowing.
 
-Cloudflare dev:
+## Tool Responses
 
-```bash
-npm run dev:worker
-```
+Use `ResponseFormat` for markdown vs JSON. `truncateText` for large payloads. Pretty-print JSON, include `structuredContent` for JSON mode.
 
-Deploy worker:
+## Testing Guidelines
 
-```bash
-npm run deploy
-```
+Vitest with `globals: true`. Place tests in `tests/unit` or `tests/integration`. AAA pattern, mock via fixtures in `tests/fixtures`, descriptive names.
 
-## Tests
+## Configuration
 
-Run all tests:
+Node `>=18`. Worker build in `wrangler.toml`. Vitest coverage thresholds enforced.
 
-```bash
-npm test
-```
+## Change Hygiene
 
-Watch tests:
+Minimal focused diffs. No unrelated refactors. Update tests for behavior changes. Avoid editing `dist/`.
 
-```bash
-npm run test:watch
-```
+## Project Layout
 
-Coverage:
+`src/index.ts` entry, `src/server.ts` wiring, `src/tools/` handlers, `src/utils/` helpers, `src/resources/` templates, `src/transport/` stdio/HTTP. `tests/unit/` utilities, `tests/integration/` behavior, `tests/fixtures/` mocks.
 
-```bash
-npm run test:coverage
-```
+## CSV Data Exploration
 
-Run a single file:
+For exploring CSV resources from datasets, use duckdb CLI (already installed) with direct HTTP URL:
 
 ```bash
-npm test -- tests/unit/http.test.ts
+duckdb -jsonlines -c "DESCRIBE SELECT * FROM read_csv('http://url/file.csv')"
+duckdb -jsonlines -c "SUMMARIZE SELECT * FROM read_csv('http://url/file.csv')"
+duckdb -jsonlines -c "SELECT * FROM read_csv('http://url/file.csv') USING SAMPLE 10"
 ```
 
-Run a single test name:
-
-```bash
-npm test -- -t "makeCkanRequest"
-```
+Use direct resource URLs (http/https), not GitHub view/blob URLs. The `-jsonlines` parameter outputs in JSONL format, easier for AI to parse.
 
-Run single file with Vitest directly:
+For random sampling, use `USING SAMPLE N` syntax (where N is the number of rows):
 
 ```bash
-npx vitest tests/unit/http.test.ts
+duckdb -jsonlines -c "SELECT * FROM read_csv('http://url/file.csv') USING SAMPLE 10"
 ```
-
-## Lint and Format
-
-- No ESLint or Prettier config detected
-- Do not add new formatters unless requested
-- Keep formatting consistent with existing files
-
-## Project Layout
-
-- `src/index.ts` entry point
-- `src/server.ts` server wiring
-- `src/tools/` MCP tool handlers
-- `src/utils/` helpers (http, formatting, search)
-- `src/resources/` MCP resource templates
-- `src/transport/` stdio + HTTP
-- `tests/unit/` utilities
-- `tests/integration/` tool behavior
-- `tests/fixtures/` mocked CKAN API responses
-
-## TypeScript Style
-
-- Use strict typing (`tsconfig.json` has `strict: true`)
-- Avoid `any` unless unavoidable or from CKAN payloads
-- Prefer explicit return types for exported functions
-- Use `type` aliases for structured objects
-- Keep `noUnusedLocals` and `noUnusedParameters` clean
-- ESM imports with `.js` extensions for local modules
-
-## Import Conventions
-
-- Use `import type` for type-only imports
-- Group imports by kind: external, internal, types
-- Use double quotes for strings
-- Keep import paths relative and short
-
-## Naming
-
-- `camelCase` for vars/functions
-- `PascalCase` for types/classes
-- `UPPER_SNAKE_CASE` for constants
-- Tool names match MCP tool id strings
-
-## Error Handling
-
-- Wrap tool handlers in `try/catch`
-- Return `{ isError: true }` for MCP errors
-- Include user-facing error text with context
-- For HTTP errors, map to readable messages
-- Preserve error cause when rethrowing
-
-## Tool Responses
-
-- Use `ResponseFormat` for markdown vs JSON
-- Use `truncateText` for large payloads
-- Keep JSON output pretty-printed
-- Include `structuredContent` for JSON mode
-
-## Testing Guidelines
-
-- Tests use Vitest and `globals: true`
-- Place new tests in `tests/unit` or `tests/integration`
-- Follow AAA pattern: Arrange, Act, Assert
-- Mock CKAN API via fixtures under `tests/fixtures`
-- Name tests descriptively with expected behavior
-
-## Configuration Notes
-
-- Node engine: `>=18`
-- Worker build command set in `wrangler.toml`
-- Vitest coverage thresholds enforced in `vitest.config.ts`
-
-## Change Hygiene
-
-- Keep diffs minimal and focused
-- Avoid unrelated refactors
-- Update tests for behavior changes
-- Avoid editing `dist/` (generated)

package/CLAUDE.md

@@ -378,3 +378,21 @@ When releasing a new version:
 7. **Deploy to Cloudflare** (if code changed): `npm run deploy`
 
 See `docs/DEPLOYMENT.md` for detailed Cloudflare deployment instructions.
+
+## CSV Data Exploration
+
+For exploring CSV resources from datasets, use duckdb CLI (already installed) with direct HTTP URL:
+
+```bash
+duckdb -jsonlines -c "DESCRIBE SELECT * FROM read_csv('http://url/file.csv')"
+duckdb -jsonlines -c "SUMMARIZE SELECT * FROM read_csv('http://url/file.csv')"
+duckdb -jsonlines -c "SELECT * FROM read_csv('http://url/file.csv') USING SAMPLE 10"
+```
+
+Use direct resource URLs (http/https), not GitHub view/blob URLs. The `-jsonlines` parameter outputs in JSONL format, easier for AI to parse.
+
+For random sampling, use `USING SAMPLE N` syntax (where N is the number of rows):
+
+```bash
+duckdb -jsonlines -c "SELECT * FROM read_csv('http://url/file.csv') USING SAMPLE 10"
+```

package/LOG.md

@@ -1,5 +1,13 @@
 # LOG
 
+## 2026-01-15
+
+### Version 0.4.10 - Guided MCP prompts
+- **Feature**: Added 5 guided MCP prompts (theme, organization, format, recent datasets, dataset analysis)
+- **Docs**: README and new `docs/prompts.md` updated with usage examples
+- **Tests**: Added prompt unit tests; total now 184 tests (all passing)
+- **Files**: New `src/prompts/*`, updates in `src/server.ts`, `src/worker.ts`, README.md
+
 ## 2026-01-11
 
 ### Version 0.4.9 - Security, Testing & Documentation

package/README.md

@@ -1,6 +1,8 @@
-# CKAN MCP Server
-
 [![npm version](https://img.shields.io/npm/v/@aborruso/ckan-mcp-server)](https://www.npmjs.com/package/@aborruso/ckan-mcp-server)
+[![GitHub](https://img.shields.io/badge/github-aborruso%2Fckan--mcp--server-blue?logo=github)](https://github.com/aborruso/ckan-mcp-server)
+[![deepwiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aborruso/ckan-mcp-server)
+
+# CKAN MCP Server
 
 MCP (Model Context Protocol) server for interacting with CKAN-based open data portals.
 
@@ -14,7 +16,14 @@ MCP (Model Context Protocol) server for interacting with CKAN-based open data po
 - 🎨 Output in Markdown or JSON format
 - ⚡ Pagination and faceting support
 - 📄 MCP Resource Templates for direct data access
-- 🧪 Test suite with 179 tests (100% passing)
+- 🧭 Guided MCP prompts for common workflows
+- 🧪 Test suite with 184 tests (100% passing)
+
+---
+
+👉 If you want to dive deeper, the [**AI-generated DeepWiki**](https://deepwiki.com/aborruso/ckan-mcp-server) is very well done.
+
+---
 
 ## Installation
 
@@ -36,7 +45,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (179 tests)
+# Run tests (184 tests)
 npm test
 ```
 
@@ -202,6 +211,29 @@ ckan://demo.ckan.org/resource/abc-123
 ckan://data.gov/organization/sample-org
 ```
 
+## Guided Prompts
+
+Prompt templates that guide users through common CKAN workflows:
+
+- **ckan-search-by-theme**: Find a theme/group and list datasets under it
+- **ckan-search-by-organization**: Discover an organization and list its datasets
+- **ckan-search-by-format**: Find datasets by resource format (CSV/JSON/etc.)
+- **ckan-recent-datasets**: List recently updated datasets
+- **ckan-analyze-dataset**: Inspect dataset metadata and explore DataStore resources
+
+Example (retrieve a prompt by name with args):
+
+```json
+{
+  "name": "ckan-search-by-theme",
+  "arguments": {
+    "server_url": "https://www.dati.gov.it/opendata",
+    "theme": "ambiente",
+    "rows": 10
+  }
+}
+```
+
 ## Usage Examples
 
 ### Search datasets on dati.gov.it (natural language: "search for population datasets")
@@ -497,10 +529,17 @@ ckan-mcp-server/
 │   │   ├── dataset.ts
 │   │   ├── resource.ts
 │   │   └── organization.ts
+│   ├── prompts/            # MCP Guided Prompts
+│   │   ├── index.ts
+│   │   ├── theme.ts
+│   │   ├── organization.ts
+│   │   ├── format.ts
+│   │   ├── recent.ts
+│   │   └── dataset-analysis.ts
 │   └── transport/
 │       ├── stdio.ts        # Stdio transport
 │       └── http.ts         # HTTP transport
-├── tests/                  # Test suite (179 tests)
+├── tests/                  # Test suite (184 tests)
 ├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md