@aborruso/ckan-mcp-server 0.4.7 → 0.4.9

package/README.md

@@ -14,7 +14,7 @@ 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)
+- 🧪 Test suite with 179 tests (100% passing)
 
 ## Installation
 
@@ -36,7 +36,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (120 tests)
+# Run tests (179 tests)
 npm test
 ```
 
@@ -74,6 +74,8 @@ Use the public Workers endpoint (no local install required):
 }
 ```
 
+**NOTE**: This service uses the Cloudflare Workers free tier which has a limit of 100,000 requests per month.
+
 Want your own deployment? See [DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
 ### Claude Desktop Configuration
@@ -150,6 +152,8 @@ Use the public Cloudflare Workers deployment (no local installation required):
 }
 ```
 
+**NOTE**: This service uses the Cloudflare Workers free tier which has a limit of 100,000 requests per month.
+
 **Note**: This uses the public endpoint. You can also deploy your own Workers instance and use that URL instead.
 
 ## Available Tools
@@ -200,7 +204,7 @@ ckan://data.gov/organization/sample-org
 
 ## Usage Examples
 
-### Search datasets on dati.gov.it
+### Search datasets on dati.gov.it (natural language: "search for population datasets")
 
 ```typescript
 ckan_package_search({
@@ -210,7 +214,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({
@@ -221,7 +225,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({
@@ -231,7 +235,7 @@ ckan_find_relevant_datasets({
 })
 ```
 
-### Filter by organization
+### Filter by organization (natural language: "show recent datasets from Sicilian Region")
 
 ```typescript
 ckan_package_search({
@@ -241,7 +245,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
@@ -254,7 +258,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({
@@ -283,7 +287,7 @@ ckan_group_search({
 })
 ```
 
-### DataStore Query
+### DataStore Query (natural language: "query tabular data filtering by region and year")
 
 ```typescript
 ckan_datastore_search({
@@ -295,7 +299,7 @@ ckan_datastore_search({
 })
 ```
 
-### DataStore SQL Query
+### DataStore SQL Query (natural language: "count records by country with SQL")
 
 ```typescript
 ckan_datastore_search_sql({
@@ -361,7 +365,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:
 
@@ -383,7 +387,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:
 
@@ -405,7 +409,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:
 
@@ -428,7 +432,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:
 
@@ -496,7 +500,7 @@ ckan-mcp-server/
 │   └── transport/
 │       ├── stdio.ts        # Stdio transport
 │       └── http.ts         # HTTP transport
-├── tests/                  # Test suite (120 tests)
+├── tests/                  # Test suite (179 tests)
 ├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md
@@ -519,12 +523,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

@@ -411,6 +411,15 @@ ${params.fq ? `**Filter**: ${params.fq}
             const sorted = Object.entries(facetValues).sort((a, b) => b[1] - a[1]).slice(0, 10);
             for (const [value, count] of sorted) {
               markdown += `- **${value}**: ${count}
+`;
+            }
+            if (Object.keys(facetValues).length > sorted.length) {
+              markdown += `
+Note: showing top ${sorted.length} only. Use \`response_format: json\` or increase \`facet_limit\`.
+`;
+            } else {
+              markdown += `
+Note: showing top ${sorted.length} only. Use \`response_format: json\` for full list.
 `;
             }
             markdown += "\n";
@@ -897,16 +906,84 @@ Returns:
             content: [{ type: "text", text: markdown2 }]
           };
         }
-        const result = await makeCkanRequest(
-          params.server_url,
-          "organization_list",
-          {
-            all_fields: params.all_fields,
-            sort: params.sort,
-            limit: params.limit,
-            offset: params.offset
+        let result;
+        try {
+          result = await makeCkanRequest(
+            params.server_url,
+            "organization_list",
+            {
+              all_fields: params.all_fields,
+              sort: params.sort,
+              limit: params.limit,
+              offset: params.offset
+            }
+          );
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (message.includes("CKAN API error (500)")) {
+            const searchResult = await makeCkanRequest(
+              params.server_url,
+              "package_search",
+              {
+                rows: 0,
+                "facet.field": JSON.stringify(["organization"]),
+                "facet.limit": -1
+              }
+            );
+            const items = searchResult.search_facets?.organization?.items || [];
+            const sortValue = params.sort?.toLowerCase() ?? "name asc";
+            const sortedItems = [...items].sort((a, b) => {
+              if (sortValue.includes("package_count") || sortValue.includes("count")) {
+                return b.count - a.count;
+              }
+              if (sortValue.includes("name desc")) {
+                return String(b.name).localeCompare(String(a.name));
+              }
+              return String(a.name).localeCompare(String(b.name));
+            });
+            const pagedItems = sortedItems.slice(params.offset, params.offset + params.limit);
+            const organizations = pagedItems.map((item) => ({
+              id: item.name,
+              name: item.name,
+              title: item.display_name || item.name,
+              package_count: item.count
+            }));
+            if (params.response_format === "json" /* JSON */) {
+              const output = { count: items.length, organizations };
+              return {
+                content: [{ type: "text", text: truncateText(JSON.stringify(output, null, 2)) }],
+                structuredContent: output
+              };
+            }
+            let markdown2 = `# CKAN Organizations
+
+`;
+            markdown2 += `**Server**: ${params.server_url}
+`;
+            markdown2 += `**Total**: ${items.length}
+`;
+            markdown2 += `
+Note: organization_list returned 500; using package_search facets.
+
+`;
+            for (const org of organizations) {
+              markdown2 += `## ${org.title || org.name}
+
+`;
+              markdown2 += `- **Name**: \`${org.name}\`
+`;
+              markdown2 += `- **Datasets**: ${org.package_count || 0}
+`;
+              markdown2 += `- **Link**: ${getOrganizationViewUrl(params.server_url, org)}
+
+`;
+            }
+            return {
+              content: [{ type: "text", text: truncateText(markdown2) }]
+            };
           }
-        );
+          throw error;
+        }
         if (params.response_format === "json" /* JSON */) {
           const output = Array.isArray(result) ? { count: result.length, organizations: result } : result;
           return {
@@ -2149,7 +2226,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.7"
+    version: "0.4.8"
   });
 }
 function registerAll(server2) {