@aborruso/ckan-mcp-server 0.4.49 → 0.4.50

package/AGENTS.md

@@ -118,6 +118,43 @@ Node `>=18`. Worker build in `wrangler.toml`. Vitest coverage thresholds enforce
 
 Minimal focused diffs. No unrelated refactors. Update tests for behavior changes. Avoid editing `dist/`.
 
+## Pre-commit Checklist
+
+Before committing and pushing any locally testable change:
+1. Build: `npm run build`
+2. Automated tests: `npm test` — all must pass
+3. Manual queries: run real requests against the built server to verify end-to-end behavior
+
+### How to run manual queries
+
+```bash
+# Terminal 1 — start server
+TRANSPORT=http PORT=3001 node dist/index.js
+
+# Terminal 2 — call a tool
+curl -s -X POST http://localhost:3001/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc":"2.0",
+    "method":"tools/call",
+    "params":{
+      "name":"ckan_package_search",
+      "arguments":{
+        "server_url":"https://www.dati.gov.it/opendata",
+        "q":"ambiente",
+        "page":1,
+        "page_size":3
+      }
+    },
+    "id":1
+  }'
+```
+
+- Always include both `Content-Type: application/json` and `Accept: application/json, text/event-stream`
+- Use `node dist/index.js` directly, not `npm start`
+- Use port 3001 to avoid conflicts
+
 ## Project Layout
 
 `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.

package/LOG.md

@@ -1,5 +1,14 @@
 # LOG
 
+## 2026-02-26 (v0.4.50)
+
+- `ckan_list_resources`: add `format_filter` param (case-insensitive, client-side) — e.g. 72 resources → 8 CSV; header shows "Total: 72 (showing 8 CSV)"
+- `ckan_package_search`: OR tip on zero results — when a plain multi-term query returns 0, suggest the OR version (e.g. `"a b c"` → `"a OR b OR c"`)
+- `ckan_package_search`: accent fallback — if query returns 0 results and contains accented chars, retry with accent-stripped query; note shown in output
+- `ckan_package_show`: always show DataStore status per resource
+  - `✅ Available` / `❌ Not available` / `❓ Not reported by portal`
+  - Previously silent when field absent (e.g. dati.gov.it); now explicit
+
 ## 2026-02-25 (v0.4.49)
 
 - Disable DataStore Table UI component (MCP Apps) pending use-case design

package/README.md

@@ -18,7 +18,7 @@ MCP (Model Context Protocol) server for interacting with CKAN-based open data po
 - 📄 MCP Resource Templates for direct data access
 - 🧭 Guided MCP prompts for common workflows
 - 🛡️ Browser-like headers to avoid WAF blocks
-- 🧪 Test suite with 214 tests (100% passing)
+- 🧪 Comprehensive test suite (100% passing)
 
 👉 If you want to dive deeper, the [**AI-generated DeepWiki**](https://deepwiki.com/ondata/ckan-mcp-server) is very well done.
 
@@ -188,6 +188,25 @@ npm install -g @aborruso/ckan-mcp-server
 
 ⚠️ **Warning**: Demo instance with 100,000 requests/month shared globally across all users. Not reliable for production use.
 
+**Claude Desktop on Windows reading from a local MCP server installed on WSL2**:
+
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "command": "wsl.exe",
+      "args": [
+        "-e",
+        "/usr/local/bin/node",
+        "/home/username/projects/ckan-mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+This requires the server to be built (`npm run build`) inside the WSL2 environment before use.
+
 ### Web Tools
 
 #### ChatGPT

package/dist/index.js

@@ -489,6 +489,24 @@ function convertDateMathForUnsupportedFields(query) {
     return `${field}:[${startIso} TO ${nowIso}]`;
   });
 }
+var EXPLICIT_BOOL_PATTERN = /\b(AND|OR|NOT)\b|[+\-!]/;
+function isPlainMultiTermQuery(query) {
+  const trimmed = query.trim();
+  if (trimmed === "*:*" || trimmed === "") return false;
+  if (FIELD_QUERY_PATTERN.test(trimmed)) return false;
+  if (EXPLICIT_BOOL_PATTERN.test(trimmed)) return false;
+  const words = trimmed.split(/\s+/).filter(Boolean);
+  return words.length > 1;
+}
+function buildOrQuery(query) {
+  return query.trim().split(/\s+/).filter(Boolean).join(" OR ");
+}
+function stripAccents(text) {
+  return text.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+}
+function hasAccents(text) {
+  return text !== stripAccents(text);
+}
 function resolveSearchQuery(serverUrl, query, parserOverride) {
   const portalSearchConfig = getPortalSearchConfig(serverUrl);
   const portalForce = portalSearchConfig.force_text_field ?? false;
@@ -761,8 +779,14 @@ ${result.notes}
 `;
       if (resource.last_modified) markdown += `- **Modified**: ${formatDate(resource.last_modified)}
 `;
-      if (resource.datastore_active !== void 0) {
-        markdown += `- **DataStore**: ${resource.datastore_active ? "\u2705 Available" : "\u274C Not available"}
+      if (resource.datastore_active === true) {
+        markdown += `- **DataStore**: \u2705 Available
+`;
+      } else if (resource.datastore_active === false) {
+        markdown += `- **DataStore**: \u274C Not available
+`;
+      } else {
+        markdown += `- **DataStore**: \u2753 Not reported by portal
 `;
       }
       markdown += "\n";
@@ -780,6 +804,12 @@ ${result.notes}
   }
   return markdown;
 };
+function resolvePageParams(page, pageSize, start, rows) {
+  if (page !== void 0) {
+    return { effectiveStart: (page - 1) * pageSize, effectiveRows: pageSize };
+  }
+  return { effectiveStart: start, effectiveRows: rows };
+}
 function registerPackageTools(server2) {
   server2.registerTool(
     "ckan_package_search",
@@ -819,6 +849,8 @@ Args:
   - fq (string): Filter query (e.g., "organization:comune-palermo")
   - rows (number): Number of results to return (default: 10, max: 1000)
   - start (number): Offset for pagination (default: 0)
+  - page (number): Page number (1-based); alias for start. Overrides start if provided.
+  - page_size (number): Results per page when using page (default: 10, max: 1000)
   - sort (string): Sort field and direction (e.g., "metadata_modified desc")
   - facet_field (array): Fields to facet on (e.g., ["organization", "tags"])
   - facet_limit (number): Max facet values per field (default: 50)
@@ -899,6 +931,8 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (get full metadat
         sort: z2.string().optional().describe("Sort field and direction (e.g., 'metadata_modified desc')"),
         facet_field: z2.array(z2.string()).optional().describe("Fields to facet on"),
         facet_limit: z2.number().int().min(1).optional().default(50).describe("Maximum facet values per field"),
+        page: z2.number().int().min(1).optional().describe("Page number (1-based); alias for start. Overrides start if provided."),
+        page_size: z2.number().int().min(1).max(1e3).optional().default(10).describe("Results per page when using page (default: 10)"),
         include_drafts: z2.boolean().optional().default(false).describe("Include draft datasets"),
         content_recent: z2.boolean().optional().default(false).describe("Use issued date with fallback to metadata_created for recent content"),
         content_recent_days: z2.number().int().min(1).optional().default(30).describe("Day window for content_recent (default 30)"),
@@ -928,10 +962,11 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (get full metadat
           query,
           params.query_parser
         );
+        const { effectiveRows, effectiveStart } = resolvePageParams(params.page, params.page_size, params.start, params.rows);
         const apiParams = {
           q: effectiveQuery,
-          rows: params.rows,
-          start: params.start,
+          rows: effectiveRows,
+          start: effectiveStart,
           include_private: params.include_drafts
         };
         if (params.fq) apiParams.fq = params.fq;
@@ -940,11 +975,29 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (get full metadat
           apiParams["facet.field"] = JSON.stringify(params.facet_field);
           apiParams["facet.limit"] = params.facet_limit;
         }
-        const result = await makeCkanRequest(
+        let result = await makeCkanRequest(
           params.server_url,
           "package_search",
           apiParams
         );
+        let accentFallbackUsed = false;
+        if (result.count === 0 && hasAccents(params.q)) {
+          const strippedQuery = stripAccents(params.q);
+          const { effectiveQuery: strippedEffective } = resolveSearchQuery(
+            params.server_url,
+            strippedQuery,
+            params.query_parser
+          );
+          const fallbackResult = await makeCkanRequest(
+            params.server_url,
+            "package_search",
+            { ...apiParams, q: strippedEffective }
+          );
+          if (fallbackResult.count > 0) {
+            result = fallbackResult;
+            accentFallbackUsed = true;
+          }
+        }
         if (params.response_format === "json" /* JSON */) {
           return {
             content: [{ type: "text", text: truncateText(JSON.stringify(result, null, 2)) }]
@@ -958,10 +1011,12 @@ ${params.content_recent ? `**Content Recent**: last ${params.content_recent_days
 ` : ""}
 ${effectiveQuery !== userQuery ? `**Effective Query**: ${effectiveQuery}
 ` : ""}
+${accentFallbackUsed ? `**Note**: Original query returned 0 results; retried with accent-stripped query "${stripAccents(params.q)}".
+` : ""}
 ${params.fq ? `**Filter**: ${params.fq}
 ` : ""}
 **Total Results**: ${result.count}
-**Showing**: ${result.results.length} results (from ${params.start})
+**Showing**: ${result.results.length} results (from ${effectiveStart})
 
 `;
         if (result.facets && Object.keys(result.facets).length > 0) {
@@ -1027,13 +1082,27 @@ Note: showing top ${sorted.length} only. Use \`response_format: json\` for full
         } else {
           markdown += `No datasets found matching your query.
 `;
+          if (isPlainMultiTermQuery(params.q)) {
+            markdown += `
+> **Tip**: Multi-term queries use AND by default (all terms must match). Try OR to broaden the search:
+`;
+            markdown += `> \`q: "${buildOrQuery(params.q)}"\`
+`;
+          }
         }
-        if (result.count > params.start + params.rows) {
-          const nextStart = params.start + params.rows;
-          markdown += `
+        if (result.count > effectiveStart + effectiveRows) {
+          if (params.page !== void 0) {
+            markdown += `
+---
+**More results available**: Use \`page: ${params.page + 1}\` to see next page.
+`;
+          } else {
+            const nextStart = effectiveStart + effectiveRows;
+            markdown += `
 ---
 **More results available**: Use \`start: ${nextStart}\` to see next page.
 `;
+          }
         }
         return {
           content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
@@ -1319,6 +1388,7 @@ Use this to quickly assess what files a dataset contains before deciding how to
 Args:
   - server_url (string): Base URL of CKAN server
   - id (string): Dataset ID or name
+  - format_filter (string): Filter resources by format, case-insensitive (e.g., "CSV", "json", "XLSX")
   - response_format ('markdown' | 'json'): Output format
 
 Returns:
@@ -1326,11 +1396,13 @@ Returns:
 
 Examples:
   - { server_url: "https://dati.gov.it/opendata", id: "dataset-name" }
+  - { server_url: "...", id: "dataset-name", format_filter: "CSV" }
 
 Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess available files) \u2192 ckan_datastore_search (for resources with DataStore=true)`,
       inputSchema: z2.object({
         server_url: z2.string().url().describe("Base URL of the CKAN server"),
         id: z2.string().min(1).describe("Dataset ID or name"),
+        format_filter: z2.string().optional().describe("Filter resources by format, case-insensitive (e.g., 'CSV', 'json', 'XLSX')"),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -1348,7 +1420,8 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
           { id: params.id }
         );
         const resources = Array.isArray(result.resources) ? result.resources : [];
-        const summary = resources.map((r) => {
+        const formatFilter = params.format_filter?.toUpperCase();
+        const summary = resources.filter((r) => !formatFilter || (r.format || "").toUpperCase() === formatFilter).map((r) => {
           const effectiveUrl = resolveDownloadUrl(r);
           return {
             name: r.name || "Unnamed Resource",
@@ -1364,7 +1437,9 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
             dataset_id: result.id,
             dataset_name: result.name,
             dataset_title: result.title || result.name,
-            total_resources: summary.length,
+            total_resources: resources.length,
+            filtered_resources: summary.length,
+            format_filter: formatFilter ?? null,
             resources: summary
           };
           return {
@@ -1379,7 +1454,11 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
 `;
         markdown += `**Dataset**: \`${result.name}\` (\`${result.id}\`)
 `;
-        markdown += `**Total Resources**: ${summary.length}
+        markdown += `**Total Resources**: ${resources.length}`;
+        if (formatFilter) {
+          markdown += ` (showing ${summary.length} ${formatFilter})`;
+        }
+        markdown += `
 
 `;
         if (summary.length === 0) {
@@ -3896,7 +3975,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.49"
+    version: "0.4.50"
   });
 }
 function registerAll(server2) {

package/package.json

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