@aborruso/ckan-mcp-server 0.4.5 → 0.4.7

package/dist/index.js

@@ -90,42 +90,168 @@ 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,
+  notes: 2,
+  tags: 3,
+  organization: 1
+};
+var QUERY_STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "as",
+  "is",
+  "was",
+  "are",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "must",
+  "can",
+  "this",
+  "that",
+  "these",
+  "those"
+]);
+var extractQueryTerms = (query) => {
+  const matches = query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+  const terms = matches.filter((term) => term.length > 1 && !QUERY_STOPWORDS.has(term));
+  return Array.from(new Set(terms));
+};
+var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var textMatchesTerms = (text, terms) => {
+  if (!text || terms.length === 0) return false;
+  const normalized = text.toLowerCase().replace(/_/g, " ");
+  return terms.some((term) => new RegExp(`\\b${escapeRegExp(term)}\\b`, "i").test(normalized));
+};
+var scoreTextField = (text, terms, weight) => {
+  return textMatchesTerms(text, terms) ? weight : 0;
+};
+var scoreDatasetRelevance = (query, dataset, weights = DEFAULT_RELEVANCE_WEIGHTS) => {
+  const terms = extractQueryTerms(query);
+  const titleText = dataset.title || dataset.name || "";
+  const notesText = dataset.notes || "";
+  const orgText = dataset.organization?.title || dataset.organization?.name || dataset.owner_org || "";
+  const breakdown = {
+    title: scoreTextField(titleText, terms, weights.title),
+    notes: scoreTextField(notesText, terms, weights.notes),
+    tags: 0,
+    organization: scoreTextField(orgText, terms, weights.organization),
+    total: 0
+  };
+  if (Array.isArray(dataset.tags) && dataset.tags.length > 0 && terms.length > 0) {
+    const tagMatch = dataset.tags.some((tag) => {
+      const tagValue = typeof tag === "string" ? tag : tag?.name;
+      return textMatchesTerms(tagValue, terms);
+    });
+    breakdown.tags = tagMatch ? weights.tags : 0;
+  }
+  breakdown.total = breakdown.title + breakdown.notes + breakdown.tags + breakdown.organization;
+  return { total: breakdown.total, breakdown, terms };
+};
 function registerPackageTools(server2) {
   server2.registerTool(
     "ckan_package_search",
@@ -136,8 +262,13 @@ 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")
+  - 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)
   - fq (string): Filter query (e.g., "organization:comune-palermo")
   - rows (number): Number of results to return (default: 10, max: 1000)
@@ -146,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:
@@ -215,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: {
@@ -226,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
@@ -253,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}
@@ -335,6 +475,184 @@ ${params.fq ? `**Filter**: ${params.fq}
       }
     }
   );
+  server2.registerTool(
+    "ckan_find_relevant_datasets",
+    {
+      title: "Find Relevant CKAN Datasets",
+      description: `Find and rank datasets by relevance to a query using weighted fields.
+
+Uses package_search for discovery and applies a local scoring model.
+
+Args:
+  - server_url (string): Base URL of CKAN server (e.g., "https://dati.gov.it/opendata")
+  - 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:
+  Ranked datasets with relevance scores and breakdowns
+
+Examples:
+  - { server_url: "https://dati.gov.it/opendata", query: "mobilit\xE0" }
+  - { server_url: "...", query: "trasporti", limit: 5, weights: { title: 5, notes: 2 } }`,
+      inputSchema: z2.object({
+        server_url: z2.string().url().describe("Base URL of the CKAN server (e.g., https://dati.gov.it/opendata)"),
+        query: z2.string().min(2).describe("Search query text"),
+        limit: z2.number().int().min(1).max(50).optional().default(10).describe("Number of datasets to return"),
+        weights: z2.object({
+          title: z2.number().min(0).optional(),
+          notes: z2.number().min(0).optional(),
+          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: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const weights = {
+          ...DEFAULT_RELEVANCE_WEIGHTS,
+          ...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: effectiveQuery,
+            rows,
+            start: 0
+          }
+        );
+        const scored = (searchResult.results || []).map((dataset) => {
+          const { total, breakdown } = scoreDatasetRelevance(
+            params.query,
+            dataset,
+            weights
+          );
+          return {
+            dataset,
+            score: total,
+            breakdown
+          };
+        });
+        scored.sort((a, b) => b.score - a.score);
+        const top = scored.slice(0, params.limit).map((item) => {
+          const dataset = item.dataset;
+          return {
+            id: dataset.id,
+            name: dataset.name,
+            title: dataset.title || dataset.name,
+            organization: dataset.organization?.title || dataset.organization?.name || dataset.owner_org,
+            tags: Array.isArray(dataset.tags) ? dataset.tags.map((tag) => tag.name) : [],
+            metadata_modified: dataset.metadata_modified,
+            score: item.score,
+            breakdown: item.breakdown
+          };
+        });
+        const payload = {
+          query: params.query,
+          terms: extractQueryTerms(params.query),
+          weights,
+          total_results: searchResult.count ?? 0,
+          returned: top.length,
+          results: top
+        };
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(payload, null, 2)) }],
+            structuredContent: payload
+          };
+        }
+        let markdown = `# Relevant CKAN Datasets
+
+`;
+        markdown += `**Server**: ${params.server_url}
+`;
+        markdown += `**Query**: ${params.query}
+`;
+        markdown += `**Terms**: ${payload.terms.length > 0 ? payload.terms.join(", ") : "n/a"}
+`;
+        markdown += `**Total Results**: ${payload.total_results}
+`;
+        markdown += `**Returned**: ${payload.returned}
+
+`;
+        markdown += `## Weights
+
+`;
+        markdown += `- **Title**: ${weights.title}
+`;
+        markdown += `- **Notes**: ${weights.notes}
+`;
+        markdown += `- **Tags**: ${weights.tags}
+`;
+        markdown += `- **Organization**: ${weights.organization}
+
+`;
+        if (top.length === 0) {
+          markdown += "No datasets matched the query terms.\n";
+        } else {
+          markdown += `## Results
+
+`;
+          markdown += `| Rank | Dataset | Score | Title | Org | Tags |
+`;
+          markdown += `| --- | --- | --- | --- | --- | --- |
+`;
+          top.forEach((dataset, index) => {
+            const tags = dataset.tags.slice(0, 3).join(", ");
+            markdown += `| ${index + 1} | ${dataset.name} | ${dataset.score} | ${dataset.title} | ${dataset.organization || "-"} | ${tags || "-"} |
+`;
+          });
+          markdown += `
+### Score Breakdown
+
+`;
+          top.forEach((dataset, index) => {
+            markdown += `**${index + 1}. ${dataset.title}**
+`;
+            markdown += `- Title: ${dataset.breakdown.title}
+`;
+            markdown += `- Notes: ${dataset.breakdown.notes}
+`;
+            markdown += `- Tags: ${dataset.breakdown.tags}
+`;
+            markdown += `- Organization: ${dataset.breakdown.organization}
+`;
+            markdown += `- Total: ${dataset.breakdown.total}
+
+`;
+          });
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error ranking datasets: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
   server2.registerTool(
     "ckan_package_show",
     {
@@ -353,7 +671,7 @@ Returns:
   Complete dataset object with all metadata and resources
 
 Examples:
-  - { server_url: "https://dati.gov.it", id: "dataset-name" }
+  - { server_url: "https://dati.gov.it/opendata", id: "dataset-name" }
   - { server_url: "...", id: "abc-123-def", include_tracking: true }`,
       inputSchema: z2.object({
         server_url: z2.string().url().describe("Base URL of the CKAN server"),
@@ -998,6 +1316,110 @@ Examples:
       }
     }
   );
+  server2.registerTool(
+    "ckan_datastore_search_sql",
+    {
+      title: "Search CKAN DataStore with SQL",
+      description: `Run SQL queries on a CKAN DataStore resource.
+
+This endpoint is only available on CKAN portals with DataStore enabled and SQL access exposed.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - sql (string): SQL query (e.g., SELECT * FROM "resource_id" LIMIT 10)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  SQL query results from DataStore
+
+Examples:
+  - { server_url: "...", sql: "SELECT * FROM "abc-123" LIMIT 10" }
+  - { server_url: "...", sql: "SELECT COUNT(*) AS total FROM "abc-123"" }`,
+      inputSchema: z4.object({
+        server_url: z4.string().url(),
+        sql: z4.string().min(1),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const result = await makeCkanRequest(
+          params.server_url,
+          "datastore_search_sql",
+          { sql: params.sql }
+        );
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(result, null, 2)) }],
+            structuredContent: result
+          };
+        }
+        const records = result.records || [];
+        const fieldIds = result.fields?.map((field) => field.id) || Object.keys(records[0] || {});
+        let markdown = `# DataStore SQL Results
+
+`;
+        markdown += `**Server**: ${params.server_url}
+`;
+        markdown += `**SQL**: \`${params.sql}\`
+`;
+        markdown += `**Returned**: ${records.length} records
+
+`;
+        if (result.fields && result.fields.length > 0) {
+          markdown += `## Fields
+
+`;
+          markdown += result.fields.map((field) => `- **${field.id}** (${field.type})`).join("\n") + "\n\n";
+        }
+        if (records.length > 0 && fieldIds.length > 0) {
+          markdown += `## Records
+
+`;
+          const displayFields = fieldIds.slice(0, 8);
+          markdown += `| ${displayFields.join(" | ")} |
+`;
+          markdown += `| ${displayFields.map(() => "---").join(" | ")} |
+`;
+          for (const record of records.slice(0, 50)) {
+            const values = displayFields.map((field) => {
+              const value = record[field];
+              if (value === null || value === void 0) return "-";
+              const text = String(value);
+              return text.length > 50 ? text.substring(0, 47) + "..." : text;
+            });
+            markdown += `| ${values.join(" | ")} |
+`;
+          }
+          if (records.length > 50) {
+            markdown += `
+... and ${records.length - 50} more records
+`;
+          }
+          markdown += "\n";
+        } else {
+          markdown += "No records returned by the SQL query.\n";
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error querying DataStore SQL: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
 }
 
 // src/tools/status.ts
@@ -1727,7 +2149,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.3"
+    version: "0.4.7"
   });
 }
 function registerAll(server2) {