@aborruso/ckan-mcp-server 0.4.6 → 0.4.8

package/README.md

@@ -40,27 +40,11 @@ npm run build
 npm test
 ```
 
-## Usage
-
-### Start with stdio (for local integration)
-
-```bash
-npm start
-```
-
-### Start with HTTP (for remote access)
-
-```bash
-TRANSPORT=http PORT=3000 npm start
-```
-
-The server will be available at `http://localhost:3000/mcp`
-
 ## Usage Options
 
 ### Option 1: Local Installation (stdio mode)
 
-**Best for**: Personal use with Claude Desktop
+**Best for**: Personal use with local MCP clients
 
 Install and run locally on your machine (see Installation section above).
 
@@ -90,9 +74,11 @@ 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
+### Claude Desktop Configuration
 
 Configuration file location:
 
@@ -100,7 +86,7 @@ Configuration file location:
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 - **Linux**: `~/.config/Claude/claude_desktop_config.json`
 
-### Option 1: Global Installation (Recommended)
+#### Option 1: Global Installation (Recommended)
 
 Install globally to use across all projects:
 
@@ -120,7 +106,7 @@ Then add to `claude_desktop_config.json`:
 }
 ```
 
-### Option 2: Local Installation (Optional)
+#### Option 2: Local Installation (Optional)
 
 If you installed locally (see Installation), use this config:
 
@@ -137,7 +123,7 @@ If you installed locally (see Installation), use this config:
 
 Replace `/absolute/path/to/project` with your actual project path.
 
-### Option 3: From Source
+#### Option 3: From Source
 
 If you cloned the repository:
 
@@ -152,7 +138,7 @@ If you cloned the repository:
 }
 ```
 
-### Option 4: Cloudflare Workers (HTTP transport)
+#### Option 4: Cloudflare Workers (HTTP transport)
 
 Use the public Cloudflare Workers deployment (no local installation required):
 
@@ -166,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
@@ -226,6 +214,17 @@ ckan_package_search({
 })
 ```
 
+### Force text-field parser for long OR queries
+
+```typescript
+ckan_package_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  q: "hotel OR alberghi OR \"strutture ricettive\" OR ospitalità OR ricettività",
+  query_parser: "text",
+  rows: 0
+})
+```
+
 ### Rank datasets by relevance
 
 ```typescript
@@ -477,28 +476,32 @@ ckan_package_search({
 ```
 ckan-mcp-server/
 ├── src/
-│   ├── index.ts          # Entry point
-│   ├── server.ts         # MCP server setup
-│   ├── types.ts          # Types & schemas
+│   ├── index.ts            # Entry point
+│   ├── server.ts           # MCP server setup
+│   ├── worker.ts           # Cloudflare Workers entry
+│   ├── types.ts            # Types & schemas
 │   ├── utils/
-│   │   ├── http.ts       # CKAN API client
-│   │   └── formatting.ts # Output formatting
+│   │   ├── http.ts         # CKAN API client
+│   │   ├── formatting.ts   # Output formatting
+│   │   └── url-generator.ts
 │   ├── tools/
-│   │   ├── package.ts    # Package search/show
+│   │   ├── package.ts      # Package search/show
 │   │   ├── organization.ts # Organization tools
-│   │   ├── datastore.ts  # DataStore queries
-│   │   └── status.ts     # Server status
-│   ├── resources/        # MCP Resource Templates
+│   │   ├── datastore.ts    # DataStore queries
+│   │   ├── status.ts       # Server status
+│   │   ├── tag.ts          # Tag tools
+│   │   └── group.ts        # Group tools
+│   ├── resources/          # MCP Resource Templates
 │   │   ├── index.ts
-│   │   ├── uri.ts        # URI parsing
+│   │   ├── uri.ts          # URI parsing
 │   │   ├── dataset.ts
 │   │   ├── resource.ts
 │   │   └── organization.ts
 │   └── transport/
-│       ├── stdio.ts      # Stdio transport
-│       └── http.ts       # HTTP transport
-├── tests/                # Test suite (113 tests)
-├── dist/                 # Compiled files (generated)
+│       ├── stdio.ts        # Stdio transport
+│       └── http.ts         # HTTP transport
+├── tests/                  # Test suite (120 tests)
+├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md
 ```

package/dist/index.js

@@ -90,41 +90,82 @@ var portals_default = {
         "http://www.dati.gov.it/opendata",
         "http://dati.gov.it/opendata"
       ],
+      search: {
+        force_text_field: true
+      },
       dataset_view_url: "https://www.dati.gov.it/view-dataset/dataset?id={id}",
       organization_view_url: "https://www.dati.gov.it/view-dataset?organization={name}"
     }
   ],
   defaults: {
     dataset_view_url: "{server_url}/dataset/{name}",
-    organization_view_url: "{server_url}/organization/{name}"
+    organization_view_url: "{server_url}/organization/{name}",
+    search: {
+      force_text_field: false
+    }
   }
 };
 
-// src/utils/url-generator.ts
+// src/utils/portal-config.ts
 function normalizeUrl(url) {
   return url.replace(/\/$/, "");
 }
-function getDatasetViewUrl(serverUrl, pkg) {
+function getPortalConfig(serverUrl) {
   const cleanServerUrl = normalizeUrl(serverUrl);
   const portal = portals_default.portals.find((p) => {
     const mainUrl = normalizeUrl(p.api_url);
     const aliases = (p.api_url_aliases || []).map(normalizeUrl);
     return mainUrl === cleanServerUrl || aliases.includes(cleanServerUrl);
   });
+  return portal || null;
+}
+function getPortalSearchConfig(serverUrl) {
+  const portal = getPortalConfig(serverUrl);
+  const defaults = portals_default.defaults?.search || {};
+  return {
+    force_text_field: portal?.search?.force_text_field ?? defaults.force_text_field ?? false
+  };
+}
+function normalizePortalUrl(serverUrl) {
+  return normalizeUrl(serverUrl);
+}
+
+// src/utils/url-generator.ts
+function getDatasetViewUrl(serverUrl, pkg) {
+  const cleanServerUrl = normalizePortalUrl(serverUrl);
+  const portal = getPortalConfig(serverUrl);
   const template = portal?.dataset_view_url || portals_default.defaults.dataset_view_url;
   return template.replace("{server_url}", cleanServerUrl).replace("{id}", pkg.id).replace("{name}", pkg.name);
 }
 function getOrganizationViewUrl(serverUrl, org) {
-  const cleanServerUrl = normalizeUrl(serverUrl);
-  const portal = portals_default.portals.find((p) => {
-    const mainUrl = normalizeUrl(p.api_url);
-    const aliases = (p.api_url_aliases || []).map(normalizeUrl);
-    return mainUrl === cleanServerUrl || aliases.includes(cleanServerUrl);
-  });
+  const cleanServerUrl = normalizePortalUrl(serverUrl);
+  const portal = getPortalConfig(serverUrl);
   const template = portal?.organization_view_url || portals_default.defaults.organization_view_url;
   return template.replace("{server_url}", cleanServerUrl).replace("{id}", org.id).replace("{name}", org.name);
 }
 
+// src/utils/search.ts
+var DEFAULT_SEARCH_QUERY = "*:*";
+var FIELD_QUERY_PATTERN = /\b[a-zA-Z_][\w-]*:/;
+function isFieldedQuery(query) {
+  return FIELD_QUERY_PATTERN.test(query);
+}
+function resolveSearchQuery(serverUrl, query, parserOverride) {
+  const portalSearchConfig = getPortalSearchConfig(serverUrl);
+  const portalForce = portalSearchConfig.force_text_field ?? false;
+  let forceTextField = false;
+  if (parserOverride === "text") {
+    forceTextField = true;
+  } else if (parserOverride === "default") {
+    forceTextField = false;
+  } else if (portalForce) {
+    const trimmedQuery = query.trim();
+    forceTextField = trimmedQuery !== DEFAULT_SEARCH_QUERY && !isFieldedQuery(trimmedQuery);
+  }
+  const effectiveQuery = forceTextField ? `text:(${query})` : query;
+  return { effectiveQuery, forcedTextField: forceTextField };
+}
+
 // src/tools/package.ts
 var DEFAULT_RELEVANCE_WEIGHTS = {
   title: 4,
@@ -221,6 +262,11 @@ function registerPackageTools(server2) {
 Supports full Solr search capabilities including filters, facets, and sorting.
 Use this to discover datasets matching specific criteria.
 
+Note on parser behavior:
+Some CKAN portals use a restrictive default query parser that can break long OR queries.
+For those portals, this tool may force the query into 'text:(...)' based on per-portal config.
+You can override with 'query_parser' to force or disable this behavior per request.
+
 Args:
   - server_url (string): Base URL of CKAN server (e.g., "https://dati.gov.it/opendata")
   - q (string): Search query using Solr syntax (default: "*:*" for all)
@@ -231,6 +277,7 @@ Args:
   - facet_field (array): Fields to facet on (e.g., ["organization", "tags"])
   - facet_limit (number): Max facet values per field (default: 50)
   - include_drafts (boolean): Include draft datasets (default: false)
+  - query_parser ('default' | 'text'): Override search parser behavior
   - response_format ('markdown' | 'json'): Output format
 
 Returns:
@@ -300,6 +347,7 @@ Examples:
         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"),
         include_drafts: z2.boolean().optional().default(false).describe("Include draft datasets"),
+        query_parser: z2.enum(["default", "text"]).optional().describe("Override search parser ('text' forces text:(...) on non-fielded queries)"),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -311,8 +359,13 @@ Examples:
     },
     async (params) => {
       try {
+        const { effectiveQuery } = resolveSearchQuery(
+          params.server_url,
+          params.q,
+          params.query_parser
+        );
         const apiParams = {
-          q: params.q,
+          q: effectiveQuery,
           rows: params.rows,
           start: params.start,
           include_private: params.include_drafts
@@ -338,6 +391,8 @@ Examples:
 
 **Server**: ${params.server_url}
 **Query**: ${params.q}
+${effectiveQuery !== params.q ? `**Effective Query**: ${effectiveQuery}
+` : ""}
 ${params.fq ? `**Filter**: ${params.fq}
 ` : ""}
 **Total Results**: ${result.count}
@@ -356,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";
@@ -433,6 +497,7 @@ Args:
   - query (string): Search query text
   - limit (number): Number of datasets to return (default: 10)
   - weights (object): Optional weights for title/notes/tags/organization
+  - query_parser ('default' | 'text'): Override search parser behavior
   - response_format ('markdown' | 'json'): Output format
 
 Returns:
@@ -451,6 +516,7 @@ Examples:
           tags: z2.number().min(0).optional(),
           organization: z2.number().min(0).optional()
         }).optional().describe("Optional weights per field"),
+        query_parser: z2.enum(["default", "text"]).optional().describe("Override search parser ('text' forces text:(...) on non-fielded queries)"),
         response_format: ResponseFormatSchema
       }).strict(),
       annotations: {
@@ -467,11 +533,16 @@ Examples:
           ...params.weights ?? {}
         };
         const rows = Math.min(Math.max(params.limit * 5, params.limit), 100);
+        const { effectiveQuery } = resolveSearchQuery(
+          params.server_url,
+          params.query,
+          params.query_parser
+        );
         const searchResult = await makeCkanRequest(
           params.server_url,
           "package_search",
           {
-            q: params.query,
+            q: effectiveQuery,
             rows,
             start: 0
           }
@@ -835,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 {
@@ -2087,7 +2226,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.5"
+    version: "0.4.8"
   });
 }
 function registerAll(server2) {