@aborruso/ckan-mcp-server 0.4.6 → 0.4.7

package/EXAMPLES.md

@@ -50,6 +50,16 @@ ckan_package_search({
 })
 ```
 
+### Long OR query (force text-field parser)
+```typescript
+ckan_package_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  q: "hotel OR alberghi OR \"strutture ricettive\" OR ospitalità OR ricettività OR agriturismo OR \"bed and breakfast\"",
+  query_parser: "text",
+  rows: 0
+})
+```
+
 ### Regione Siciliana datasets
 ```typescript
 ckan_package_search({

package/LOG.md

@@ -2,6 +2,12 @@
 
 ## 2026-01-10
 
+### Version 0.4.7 - Portal search parser override
+- **Config**: Added per-portal search parser config
+- **Tool**: Added query parser override for package search and relevance
+
+## 2026-01-10
+
 ### Version 0.4.6 - Relevance ranking
 - **Tool**: Added `ckan_find_relevant_datasets`
 - **Docs**: Updated README/EXAMPLES

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).
 
@@ -92,7 +76,7 @@ Use the public Workers endpoint (no local install required):
 
 Want your own deployment? See [DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
-## Claude Desktop Configuration
+### Claude Desktop Configuration
 
 Configuration file location:
 
@@ -100,7 +84,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 +104,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 +121,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 +136,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):
 
@@ -226,6 +210,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 +472,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}
@@ -433,6 +488,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 +507,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 +524,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
           }
@@ -2087,7 +2149,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.5"
+    version: "0.4.7"
   });
 }
 function registerAll(server2) {