@aborruso/ckan-mcp-server 0.4.8 → 0.4.10

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
-- 🧪 Comprehensive test suite (120 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 (120 tests)
+# Run tests (184 tests)
 npm test
 ```
 
@@ -202,9 +211,32 @@ 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
+### Search datasets on dati.gov.it (natural language: "search for population datasets")
 
 ```typescript
 ckan_package_search({
@@ -214,7 +246,7 @@ ckan_package_search({
 })
 ```
 
-### Force text-field parser for long OR queries
+### Force text-field parser for long OR queries (natural language: "find hotel or accommodation datasets")
 
 ```typescript
 ckan_package_search({
@@ -225,7 +257,7 @@ ckan_package_search({
 })
 ```
 
-### Rank datasets by relevance
+### Rank datasets by relevance (natural language: "find most relevant datasets about urban mobility")
 
 ```typescript
 ckan_find_relevant_datasets({
@@ -235,7 +267,7 @@ ckan_find_relevant_datasets({
 })
 ```
 
-### Filter by organization
+### Filter by organization (natural language: "show recent datasets from Sicilian Region")
 
 ```typescript
 ckan_package_search({
@@ -245,7 +277,7 @@ ckan_package_search({
 })
 ```
 
-### Search organizations with wildcard
+### Search organizations with wildcard (natural language: "find all organizations with health/salute in name")
 
 ```typescript
 // Find all organizations containing "salute" in the name
@@ -258,7 +290,7 @@ ckan_package_search({
 })
 ```
 
-### Get statistics with faceting
+### Get statistics with faceting (natural language: "show statistics by organization, tags and format")
 
 ```typescript
 ckan_package_search({
@@ -287,7 +319,7 @@ ckan_group_search({
 })
 ```
 
-### DataStore Query
+### DataStore Query (natural language: "query tabular data filtering by region and year")
 
 ```typescript
 ckan_datastore_search({
@@ -299,7 +331,7 @@ ckan_datastore_search({
 })
 ```
 
-### DataStore SQL Query
+### DataStore SQL Query (natural language: "count records by country with SQL")
 
 ```typescript
 ckan_datastore_search_sql({
@@ -365,7 +397,7 @@ fq: "metadata_modified:[2023-01-01T00:00:00Z TO *]"
 
 These real-world examples demonstrate powerful Solr query combinations tested on the Italian open data portal (dati.gov.it):
 
-#### 1. Fuzzy Search + Date Math + Boosting
+#### 1. Fuzzy Search + Date Math + Boosting (natural language: "find healthcare datasets modified in last 6 months")
 
 Find healthcare datasets (tolerating spelling errors) modified in the last 6 months, prioritizing title matches:
 
@@ -387,7 +419,7 @@ ckan_package_search({
 
 **Results**: 871 datasets including hospital units, healthcare organizations, medical services
 
-#### 2. Proximity Search + Complex Boolean
+#### 2. Proximity Search + Complex Boolean (natural language: "find air pollution datasets excluding water")
 
 Environmental datasets where "inquinamento" and "aria" (air pollution) appear close together, excluding water-related datasets:
 
@@ -409,7 +441,7 @@ ckan_package_search({
 
 **Results**: 306 datasets, primarily air quality monitoring from Milan (44) and Palermo (161), formats: XML (150), CSV (124), JSON (76)
 
-#### 3. Wildcard + Field Existence + Range Queries
+#### 3. Wildcard + Field Existence + Range Queries (natural language: "regional datasets with many resources from last year")
 
 Regional datasets with at least 5 resources, published in the last year:
 
@@ -432,7 +464,7 @@ ckan_package_search({
 
 **Results**: 5,318 datasets, top contributors: Lombardy (3,012), Tuscany (1,151), Puglia (460)
 
-#### 4. Date Ranges + Exclusive Bounds
+#### 4. Date Ranges + Exclusive Bounds (natural language: "ISTAT datasets with 10-50 resources from specific period")
 
 ISTAT datasets with moderate resource count (10-50), modified in specific date range:
 
@@ -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 (120 tests)
+├── tests/                  # Test suite (184 tests)
 ├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md
@@ -523,12 +562,14 @@ npm run test:watch
 npm run test:coverage
 ```
 
-Test coverage target is 80%. Current test suite includes:
+Current test coverage: ~39% (utils: 98%, tools: 15-20%).
 
-- Unit tests for utility functions (formatting, HTTP)
+Test suite includes:
+- Unit tests for utility functions (formatting, HTTP, URI parsing, URL generation)
 - Integration tests for MCP tools with mocked CKAN API responses
 - Mock fixtures for CKAN API success and error scenarios
 
+Coverage is higher for utility modules and lower for tool handlers.
 See `tests/README.md` for detailed testing guidelines.
 
 ### Build

package/dist/index.js

@@ -2222,11 +2222,247 @@ function registerAllResources(server2) {
   registerOrganizationResource(server2);
 }
 
+// src/prompts/theme.ts
+import { z as z8 } from "zod";
+
+// src/prompts/types.ts
+var createTextPrompt = (text) => ({
+  messages: [
+    {
+      role: "user",
+      content: {
+        type: "text",
+        text
+      }
+    }
+  ]
+});
+
+// src/prompts/theme.ts
+var THEME_PROMPT_NAME = "ckan-search-by-theme";
+var buildThemePromptText = (serverUrl, theme, rows) => `# Guided search: datasets by theme
+
+## Step 1: Find the theme/group
+Use \`ckan_group_search\` to locate the group that matches the theme.
+
+Example:
+
+ckan_group_search({
+  server_url: "${serverUrl}",
+  pattern: "${theme}"
+})
+
+## Step 2: Search datasets in that group
+Use \`ckan_package_search\` with a group filter.
+
+Example:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  fq: "groups:<group_name>",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})
+
+## If no group matches
+Fallback to a tag-based search using facets:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  q: "tags:${theme}",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})`;
+var registerThemePrompt = (server2) => {
+  server2.registerPrompt(
+    THEME_PROMPT_NAME,
+    {
+      title: "Search datasets by theme",
+      description: "Guided prompt to discover a theme and search datasets under it.",
+      argsSchema: {
+        server_url: z8.string().url().describe("Base URL of the CKAN server"),
+        theme: z8.string().min(1).describe("Theme or group name to search"),
+        rows: z8.number().int().positive().default(10).describe("Max results to return")
+      }
+    },
+    async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
+  );
+};
+
+// src/prompts/organization.ts
+import { z as z9 } from "zod";
+var ORGANIZATION_PROMPT_NAME = "ckan-search-by-organization";
+var buildOrganizationPromptText = (serverUrl, organization, rows) => `# Guided search: datasets by organization
+
+## Step 1: Discover matching organizations
+Use \`ckan_package_search\` with an organization wildcard and facets:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  q: "organization:*${organization}*",
+  rows: 0,
+  facet_field: ["organization"],
+  facet_limit: 50
+})
+
+## Step 2: Search datasets for the chosen organization
+Use \`ckan_package_search\` with a filter query:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  fq: "organization:<org-id>",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})`;
+var registerOrganizationPrompt = (server2) => {
+  server2.registerPrompt(
+    ORGANIZATION_PROMPT_NAME,
+    {
+      title: "Search datasets by organization",
+      description: "Guided prompt to find a publisher and list its datasets.",
+      argsSchema: {
+        server_url: z9.string().url().describe("Base URL of the CKAN server"),
+        organization: z9.string().min(1).describe("Organization name or keyword"),
+        rows: z9.number().int().positive().default(10).describe("Max results to return")
+      }
+    },
+    async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
+  );
+};
+
+// src/prompts/format.ts
+import { z as z10 } from "zod";
+var FORMAT_PROMPT_NAME = "ckan-search-by-format";
+var buildFormatPromptText = (serverUrl, format, rows) => `# Guided search: datasets by resource format
+
+Use \`ckan_package_search\` with a format filter:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  fq: "res_format:${format}",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})
+
+Tip: try uppercase (CSV/JSON) or common variants if results are sparse.`;
+var registerFormatPrompt = (server2) => {
+  server2.registerPrompt(
+    FORMAT_PROMPT_NAME,
+    {
+      title: "Search datasets by resource format",
+      description: "Guided prompt to find datasets with a given resource format.",
+      argsSchema: {
+        server_url: z10.string().url().describe("Base URL of the CKAN server"),
+        format: z10.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
+        rows: z10.number().int().positive().default(10).describe("Max results to return")
+      }
+    },
+    async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
+  );
+};
+
+// src/prompts/recent.ts
+import { z as z11 } from "zod";
+var RECENT_PROMPT_NAME = "ckan-recent-datasets";
+var buildRecentPromptText = (serverUrl, rows) => `# Guided search: recent datasets
+
+Use \`ckan_package_search\` sorted by modification date:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  q: "*:*",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})
+
+Optional: add a date filter for the last N days:
+
+ckan_package_search({
+  server_url: "${serverUrl}",
+  q: "metadata_modified:[NOW-30DAYS TO *]",
+  sort: "metadata_modified desc",
+  rows: ${rows}
+})`;
+var registerRecentPrompt = (server2) => {
+  server2.registerPrompt(
+    RECENT_PROMPT_NAME,
+    {
+      title: "Find recently updated datasets",
+      description: "Guided prompt to list recently updated datasets on a CKAN portal.",
+      argsSchema: {
+        server_url: z11.string().url().describe("Base URL of the CKAN server"),
+        rows: z11.number().int().positive().default(10).describe("Max results to return")
+      }
+    },
+    async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
+  );
+};
+
+// src/prompts/dataset-analysis.ts
+import { z as z12 } from "zod";
+var DATASET_ANALYSIS_PROMPT_NAME = "ckan-analyze-dataset";
+var buildDatasetAnalysisPromptText = (serverUrl, id) => `# Guided analysis: dataset
+
+## Step 1: Get dataset metadata
+Use \`ckan_package_show\` to load full metadata and resources:
+
+ckan_package_show({
+  server_url: "${serverUrl}",
+  id: "${id}"
+})
+
+## Step 2: Inspect resources
+For each resource, use \`ckan_resource_show\` to confirm fields like format, url, and datastore availability:
+
+ckan_resource_show({
+  server_url: "${serverUrl}",
+  id: "<resource-id>"
+})
+
+## Step 3: Explore DataStore (if available)
+If a resource has \`datastore_active=true\`, use:
+
+ckan_datastore_search({
+  server_url: "${serverUrl}",
+  resource_id: "<resource-id>",
+  limit: 10
+})
+
+For aggregates, use SQL:
+
+ckan_datastore_search_sql({
+  server_url: "${serverUrl}",
+  sql: "SELECT * FROM "<resource-id>" LIMIT 10"
+})`;
+var registerDatasetAnalysisPrompt = (server2) => {
+  server2.registerPrompt(
+    DATASET_ANALYSIS_PROMPT_NAME,
+    {
+      title: "Analyze a dataset",
+      description: "Guided prompt to inspect dataset metadata and explore DataStore tables.",
+      argsSchema: {
+        server_url: z12.string().url().describe("Base URL of the CKAN server"),
+        id: z12.string().min(1).describe("Dataset id or name (CKAN package id)")
+      }
+    },
+    async ({ server_url, id }) => createTextPrompt(buildDatasetAnalysisPromptText(server_url, id))
+  );
+};
+
+// src/prompts/index.ts
+var registerAllPrompts = (server2) => {
+  registerThemePrompt(server2);
+  registerOrganizationPrompt(server2);
+  registerFormatPrompt(server2);
+  registerRecentPrompt(server2);
+  registerDatasetAnalysisPrompt(server2);
+};
+
 // src/server.ts
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.8"
+    version: "0.4.10"
   });
 }
 function registerAll(server2) {
@@ -2237,6 +2473,7 @@ function registerAll(server2) {
   registerTagTools(server2);
   registerGroupTools(server2);
   registerAllResources(server2);
+  registerAllPrompts(server2);
 }
 
 // src/transport/stdio.ts