@aborruso/ckan-mcp-server 0.4.4 → 0.4.6

package/EXAMPLES.md

@@ -20,6 +20,15 @@ ckan_package_search({
 })
 ```
 
+### Find relevant datasets
+```typescript
+ckan_find_relevant_datasets({
+  server_url: "https://demo.ckan.org",
+  query: "open data transport",
+  limit: 5
+})
+```
+
 ## Italy Examples - dati.gov.it
 
 ### Search recent datasets

package/LOG.md

@@ -2,6 +2,18 @@
 
 ## 2026-01-10
 
+### Version 0.4.6 - Relevance ranking
+- **Tool**: Added `ckan_find_relevant_datasets`
+- **Docs**: Updated README/EXAMPLES
+- **Tests**: Added relevance scoring checks
+
+## 2026-01-10
+
+### Version 0.4.5 - Health version
+- **Workers**: /health version/tools updated
+
+## 2026-01-10
+
 ### Version 0.4.4 - DataStore SQL
 - **Tool**: Added `ckan_datastore_search_sql`
 - **Docs**: Updated README/EXAMPLES/PRD for SQL support

package/README.md

@@ -56,7 +56,7 @@ TRANSPORT=http PORT=3000 npm start
 
 The server will be available at `http://localhost:3000/mcp`
 
-## Deployment Options
+## Usage Options
 
 ### Option 1: Local Installation (stdio mode)
 
@@ -173,6 +173,7 @@ Use the public Cloudflare Workers deployment (no local installation required):
 ### Search and Discovery
 
 - **ckan_package_search**: Search datasets with Solr queries
+- **ckan_find_relevant_datasets**: Rank datasets by relevance score
 - **ckan_package_show**: Complete details of a dataset
 - **ckan_package_list**: List all datasets
 - **ckan_tag_list**: List tags with counts
@@ -225,6 +226,16 @@ ckan_package_search({
 })
 ```
 
+### Rank datasets by relevance
+
+```typescript
+ckan_find_relevant_datasets({
+  server_url: "https://www.dati.gov.it/opendata",
+  query: "mobilità urbana",
+  limit: 5
+})
+```
+
 ### Filter by organization
 
 ```typescript

package/dist/index.js

@@ -126,6 +126,91 @@ function getOrganizationViewUrl(serverUrl, org) {
 }
 
 // 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",
@@ -137,7 +222,7 @@ Supports full Solr search capabilities including filters, facets, and sorting.
 Use this to discover datasets matching specific criteria.
 
 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)
@@ -335,6 +420,177 @@ ${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
+  - 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"),
+        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 searchResult = await makeCkanRequest(
+          params.server_url,
+          "package_search",
+          {
+            q: params.query,
+            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 +609,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 +1254,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 +2087,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.3"
+    version: "0.4.5"
   });
 }
 function registerAll(server2) {