@aborruso/ckan-mcp-server 0.4.5 → 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,13 @@
 
 ## 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
 

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) {

package/dist/worker.js

@@ -518,7 +518,7 @@ Returns:
 `,i+=`| Group | Datasets |
 `,i+=`|-------|----------|
 `;for(let a of o)i+=`| ${a.display_name||a.name} | ${a.count} |
-`}return{content:[{type:"text",text:re(i)}]}}catch(r){return{content:[{type:"text",text:`Error searching groups: ${r instanceof Error?r.message:String(r)}`}],isError:!0}}})}function Jn(t){let e=t.hostname;if(!e)throw new Error("Invalid ckan:// URI: missing server hostname");let r=t.pathname.split("/").filter(a=>a.length>0);if(r.length<2)throw new Error(`Invalid ckan:// URI: expected /{type}/{id}, got ${t.pathname}`);let[n,...o]=r,s=o.join("/");if(!n||!s)throw new Error("Invalid ckan:// URI: missing type or id");return{server:`https://${e}`,type:n,id:s}}function lv(t){t.registerResource("ckan-dataset",new vr("ckan://{server}/dataset/{id}",{list:void 0}),{title:"CKAN Dataset",description:"Access dataset metadata from any CKAN server. URI format: ckan://{server}/dataset/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.id,s=await le(n,"package_show",{id:o}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching dataset: ${o}`}]}}})}function dv(t){t.registerResource("ckan-resource",new vr("ckan://{server}/resource/{id}",{list:void 0}),{title:"CKAN Resource",description:"Access resource metadata and download URL from any CKAN server. URI format: ckan://{server}/resource/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.id,s=await le(n,"resource_show",{id:o}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching resource: ${o}`}]}}})}function pv(t){t.registerResource("ckan-organization",new vr("ckan://{server}/organization/{name}",{list:void 0}),{title:"CKAN Organization",description:"Access organization metadata from any CKAN server. URI format: ckan://{server}/organization/{name}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.name,s=await le(n,"organization_show",{id:o,include_datasets:!1}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching organization: ${o}`}]}}})}function fv(t){lv(t),dv(t),pv(t)}function mv(){return new na({name:"ckan-mcp-server",version:"0.4.3"})}function hv(t){nv(t),ov(t),sv(t),iv(t),av(t),uv(t),fv(t)}var va=class{constructor(e={}){this._started=!1,this._streamMapping=new Map,this._requestToStreamMapping=new Map,this._requestResponseMap=new Map,this._initialized=!1,this._enableJsonResponse=!1,this._standaloneSseStreamId="_GET_stream",this.sessionIdGenerator=e.sessionIdGenerator,this._enableJsonResponse=e.enableJsonResponse??!1,this._eventStore=e.eventStore,this._onsessioninitialized=e.onsessioninitialized,this._onsessionclosed=e.onsessionclosed,this._allowedHosts=e.allowedHosts,this._allowedOrigins=e.allowedOrigins,this._enableDnsRebindingProtection=e.enableDnsRebindingProtection??!1,this._retryInterval=e.retryInterval}async start(){if(this._started)throw new Error("Transport already started");this._started=!0}createJsonErrorResponse(e,r,n,o){let s={code:r,message:n};return o?.data!==void 0&&(s.data=o.data),new Response(JSON.stringify({jsonrpc:"2.0",error:s,id:null}),{status:e,headers:{"Content-Type":"application/json",...o?.headers}})}validateRequestHeaders(e){if(this._enableDnsRebindingProtection){if(this._allowedHosts&&this._allowedHosts.length>0){let r=e.headers.get("host");if(!r||!this._allowedHosts.includes(r)){let n=`Invalid Host header: ${r}`;return this.onerror?.(new Error(n)),this.createJsonErrorResponse(403,-32e3,n)}}if(this._allowedOrigins&&this._allowedOrigins.length>0){let r=e.headers.get("origin");if(r&&!this._allowedOrigins.includes(r)){let n=`Invalid Origin header: ${r}`;return this.onerror?.(new Error(n)),this.createJsonErrorResponse(403,-32e3,n)}}}}async handleRequest(e,r){let n=this.validateRequestHeaders(e);if(n)return n;switch(e.method){case"POST":return this.handlePostRequest(e,r);case"GET":return this.handleGetRequest(e);case"DELETE":return this.handleDeleteRequest(e);default:return this.handleUnsupportedRequest()}}async writePrimingEvent(e,r,n,o){if(!this._eventStore||o<"2025-11-25")return;let s=await this._eventStore.storeEvent(n,{}),i=`id: ${s}
+`}return{content:[{type:"text",text:re(i)}]}}catch(r){return{content:[{type:"text",text:`Error searching groups: ${r instanceof Error?r.message:String(r)}`}],isError:!0}}})}function Jn(t){let e=t.hostname;if(!e)throw new Error("Invalid ckan:// URI: missing server hostname");let r=t.pathname.split("/").filter(a=>a.length>0);if(r.length<2)throw new Error(`Invalid ckan:// URI: expected /{type}/{id}, got ${t.pathname}`);let[n,...o]=r,s=o.join("/");if(!n||!s)throw new Error("Invalid ckan:// URI: missing type or id");return{server:`https://${e}`,type:n,id:s}}function lv(t){t.registerResource("ckan-dataset",new vr("ckan://{server}/dataset/{id}",{list:void 0}),{title:"CKAN Dataset",description:"Access dataset metadata from any CKAN server. URI format: ckan://{server}/dataset/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.id,s=await le(n,"package_show",{id:o}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching dataset: ${o}`}]}}})}function dv(t){t.registerResource("ckan-resource",new vr("ckan://{server}/resource/{id}",{list:void 0}),{title:"CKAN Resource",description:"Access resource metadata and download URL from any CKAN server. URI format: ckan://{server}/resource/{id}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.id,s=await le(n,"resource_show",{id:o}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching resource: ${o}`}]}}})}function pv(t){t.registerResource("ckan-organization",new vr("ckan://{server}/organization/{name}",{list:void 0}),{title:"CKAN Organization",description:"Access organization metadata from any CKAN server. URI format: ckan://{server}/organization/{name}",mimeType:"application/json"},async(e,r)=>{try{let{server:n}=Jn(e),o=r.name,s=await le(n,"organization_show",{id:o,include_datasets:!1}),i=re(JSON.stringify(s,null,2));return{contents:[{uri:e.href,mimeType:"application/json",text:i}]}}catch(n){let o=n instanceof Error?n.message:String(n);return{contents:[{uri:e.href,mimeType:"text/plain",text:`Error fetching organization: ${o}`}]}}})}function fv(t){lv(t),dv(t),pv(t)}function mv(){return new na({name:"ckan-mcp-server",version:"0.4.5"})}function hv(t){nv(t),ov(t),sv(t),iv(t),av(t),uv(t),fv(t)}var va=class{constructor(e={}){this._started=!1,this._streamMapping=new Map,this._requestToStreamMapping=new Map,this._requestResponseMap=new Map,this._initialized=!1,this._enableJsonResponse=!1,this._standaloneSseStreamId="_GET_stream",this.sessionIdGenerator=e.sessionIdGenerator,this._enableJsonResponse=e.enableJsonResponse??!1,this._eventStore=e.eventStore,this._onsessioninitialized=e.onsessioninitialized,this._onsessionclosed=e.onsessionclosed,this._allowedHosts=e.allowedHosts,this._allowedOrigins=e.allowedOrigins,this._enableDnsRebindingProtection=e.enableDnsRebindingProtection??!1,this._retryInterval=e.retryInterval}async start(){if(this._started)throw new Error("Transport already started");this._started=!0}createJsonErrorResponse(e,r,n,o){let s={code:r,message:n};return o?.data!==void 0&&(s.data=o.data),new Response(JSON.stringify({jsonrpc:"2.0",error:s,id:null}),{status:e,headers:{"Content-Type":"application/json",...o?.headers}})}validateRequestHeaders(e){if(this._enableDnsRebindingProtection){if(this._allowedHosts&&this._allowedHosts.length>0){let r=e.headers.get("host");if(!r||!this._allowedHosts.includes(r)){let n=`Invalid Host header: ${r}`;return this.onerror?.(new Error(n)),this.createJsonErrorResponse(403,-32e3,n)}}if(this._allowedOrigins&&this._allowedOrigins.length>0){let r=e.headers.get("origin");if(r&&!this._allowedOrigins.includes(r)){let n=`Invalid Origin header: ${r}`;return this.onerror?.(new Error(n)),this.createJsonErrorResponse(403,-32e3,n)}}}}async handleRequest(e,r){let n=this.validateRequestHeaders(e);if(n)return n;switch(e.method){case"POST":return this.handlePostRequest(e,r);case"GET":return this.handleGetRequest(e);case"DELETE":return this.handleDeleteRequest(e);default:return this.handleUnsupportedRequest()}}async writePrimingEvent(e,r,n,o){if(!this._eventStore||o<"2025-11-25")return;let s=await this._eventStore.storeEvent(n,{}),i=`id: ${s}
 data: 
 
 `;this._retryInterval!==void 0&&(i=`id: ${s}
@@ -529,4 +529,4 @@ data:
 `;return o&&(s+=`id: ${o}
 `),s+=`data: ${JSON.stringify(n)}
 
-`,e.enqueue(r.encode(s)),!0}catch{return!1}}handleUnsupportedRequest(){return new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Method not allowed."},id:null}),{status:405,headers:{Allow:"GET, POST, DELETE","Content-Type":"application/json"}})}async handlePostRequest(e,r){try{let n=e.headers.get("accept");if(!n?.includes("application/json")||!n.includes("text/event-stream"))return this.createJsonErrorResponse(406,-32e3,"Not Acceptable: Client must accept both application/json and text/event-stream");let o=e.headers.get("content-type");if(!o||!o.includes("application/json"))return this.createJsonErrorResponse(415,-32e3,"Unsupported Media Type: Content-Type must be application/json");let s={headers:Object.fromEntries(e.headers.entries())},i;if(r?.parsedBody!==void 0)i=r.parsedBody;else try{i=await e.json()}catch{return this.createJsonErrorResponse(400,-32700,"Parse error: Invalid JSON")}let a;try{Array.isArray(i)?a=i.map(_=>Zu.parse(_)):a=[Zu.parse(i)]}catch{return this.createJsonErrorResponse(400,-32700,"Parse error: Invalid JSON-RPC message")}let c=a.some(Mu);if(c){if(this._initialized&&this.sessionId!==void 0)return this.createJsonErrorResponse(400,-32600,"Invalid Request: Server already initialized");if(a.length>1)return this.createJsonErrorResponse(400,-32600,"Invalid Request: Only one initialization request is allowed");this.sessionId=this.sessionIdGenerator?.(),this._initialized=!0,this.sessionId&&this._onsessioninitialized&&await Promise.resolve(this._onsessioninitialized(this.sessionId))}if(!c){let _=this.validateSession(e);if(_)return _;let x=this.validateProtocolVersion(e);if(x)return x}if(!a.some(cr)){for(let _ of a)this.onmessage?.(_,{authInfo:r?.authInfo,requestInfo:s});return new Response(null,{status:202})}let l=crypto.randomUUID(),d=a.find(_=>Mu(_)),g=d?d.params.protocolVersion:e.headers.get("mcp-protocol-version")??Tm;if(this._enableJsonResponse)return new Promise(_=>{this._streamMapping.set(l,{resolveJson:_,cleanup:()=>{this._streamMapping.delete(l)}});for(let x of a)cr(x)&&this._requestToStreamMapping.set(x.id,l);for(let x of a)this.onmessage?.(x,{authInfo:r?.authInfo,requestInfo:s})});let h=new TextEncoder,p,f=new ReadableStream({start:_=>{p=_},cancel:()=>{this._streamMapping.delete(l)}}),m={"Content-Type":"text/event-stream","Cache-Control":"no-cache",Connection:"keep-alive"};this.sessionId!==void 0&&(m["mcp-session-id"]=this.sessionId);for(let _ of a)cr(_)&&(this._streamMapping.set(l,{controller:p,encoder:h,cleanup:()=>{this._streamMapping.delete(l);try{p.close()}catch{}}}),this._requestToStreamMapping.set(_.id,l));await this.writePrimingEvent(p,h,l,g);for(let _ of a){let x,w;cr(_)&&this._eventStore&&g>="2025-11-25"&&(x=()=>{this.closeSSEStream(_.id)},w=()=>{this.closeStandaloneSSEStream()}),this.onmessage?.(_,{authInfo:r?.authInfo,requestInfo:s,closeSSEStream:x,closeStandaloneSSEStream:w})}return new Response(f,{status:200,headers:m})}catch(n){return this.onerror?.(n),this.createJsonErrorResponse(400,-32700,"Parse error",{data:String(n)})}}async handleDeleteRequest(e){let r=this.validateSession(e);if(r)return r;let n=this.validateProtocolVersion(e);return n||(await Promise.resolve(this._onsessionclosed?.(this.sessionId)),await this.close(),new Response(null,{status:200}))}validateSession(e){if(this.sessionIdGenerator===void 0)return;if(!this._initialized)return this.createJsonErrorResponse(400,-32e3,"Bad Request: Server not initialized");let r=e.headers.get("mcp-session-id");if(!r)return this.createJsonErrorResponse(400,-32e3,"Bad Request: Mcp-Session-Id header is required");if(r!==this.sessionId)return this.createJsonErrorResponse(404,-32001,"Session not found")}validateProtocolVersion(e){let r=e.headers.get("mcp-protocol-version");if(r!==null&&!po.includes(r))return this.createJsonErrorResponse(400,-32e3,`Bad Request: Unsupported protocol version: ${r} (supported versions: ${po.join(", ")})`)}async close(){this._streamMapping.forEach(({cleanup:e})=>{e()}),this._streamMapping.clear(),this._requestResponseMap.clear(),this.onclose?.()}closeSSEStream(e){let r=this._requestToStreamMapping.get(e);if(!r)return;let n=this._streamMapping.get(r);n&&n.cleanup()}closeStandaloneSSEStream(){let e=this._streamMapping.get(this._standaloneSseStreamId);e&&e.cleanup()}async send(e,r){let n=r?.relatedRequestId;if((Ut(e)||vn(e))&&(n=e.id),n===void 0){if(Ut(e)||vn(e))throw new Error("Cannot send a response on a standalone SSE stream unless resuming a previous client request");let i;this._eventStore&&(i=await this._eventStore.storeEvent(this._standaloneSseStreamId,e));let a=this._streamMapping.get(this._standaloneSseStreamId);if(a===void 0)return;a.controller&&a.encoder&&this.writeSSEEvent(a.controller,a.encoder,e,i);return}let o=this._requestToStreamMapping.get(n);if(!o)throw new Error(`No connection established for request ID: ${String(n)}`);let s=this._streamMapping.get(o);if(!this._enableJsonResponse&&s?.controller&&s?.encoder){let i;this._eventStore&&(i=await this._eventStore.storeEvent(o,e)),this.writeSSEEvent(s.controller,s.encoder,e,i)}if(Ut(e)||vn(e)){this._requestResponseMap.set(n,e);let i=Array.from(this._requestToStreamMapping.entries()).filter(([c,u])=>u===o).map(([c])=>c);if(i.every(c=>this._requestResponseMap.has(c))){if(!s)throw new Error(`No connection established for request ID: ${String(n)}`);if(this._enableJsonResponse&&s.resolveJson){let c={"Content-Type":"application/json"};this.sessionId!==void 0&&(c["mcp-session-id"]=this.sessionId);let u=i.map(l=>this._requestResponseMap.get(l));u.length===1?s.resolveJson(new Response(JSON.stringify(u[0]),{status:200,headers:c})):s.resolveJson(new Response(JSON.stringify(u),{status:200,headers:c}))}else s.cleanup();for(let c of i)this._requestResponseMap.delete(c),this._requestToStreamMapping.delete(c)}}}};var gv=mv();hv(gv);var yv=new va({sessionIdGenerator:void 0,enableJsonResponse:!0});await gv.connect(yv);var c4={async fetch(t){let e=new URL(t.url);if(t.method==="GET"&&e.pathname==="/health")return new Response(JSON.stringify({status:"ok",version:"0.4.3",tools:11,resources:3,runtime:"cloudflare-workers"}),{headers:{"Content-Type":"application/json","Access-Control-Allow-Origin":"*"}});if(e.pathname==="/mcp")try{let r=await yv.handleRequest(t),n=new Headers(r.headers);return n.set("Access-Control-Allow-Origin","*"),new Response(r.body,{status:r.status,statusText:r.statusText,headers:n})}catch(r){return console.error("Worker error:",r),new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32603,message:"Internal error",data:r instanceof Error?r.message:String(r)},id:null}),{status:500,headers:{"Content-Type":"application/json","Access-Control-Allow-Origin":"*"}})}return new Response("Not Found",{status:404,headers:{"Access-Control-Allow-Origin":"*"}})}};export{c4 as default};
+`,e.enqueue(r.encode(s)),!0}catch{return!1}}handleUnsupportedRequest(){return new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32e3,message:"Method not allowed."},id:null}),{status:405,headers:{Allow:"GET, POST, DELETE","Content-Type":"application/json"}})}async handlePostRequest(e,r){try{let n=e.headers.get("accept");if(!n?.includes("application/json")||!n.includes("text/event-stream"))return this.createJsonErrorResponse(406,-32e3,"Not Acceptable: Client must accept both application/json and text/event-stream");let o=e.headers.get("content-type");if(!o||!o.includes("application/json"))return this.createJsonErrorResponse(415,-32e3,"Unsupported Media Type: Content-Type must be application/json");let s={headers:Object.fromEntries(e.headers.entries())},i;if(r?.parsedBody!==void 0)i=r.parsedBody;else try{i=await e.json()}catch{return this.createJsonErrorResponse(400,-32700,"Parse error: Invalid JSON")}let a;try{Array.isArray(i)?a=i.map(_=>Zu.parse(_)):a=[Zu.parse(i)]}catch{return this.createJsonErrorResponse(400,-32700,"Parse error: Invalid JSON-RPC message")}let c=a.some(Mu);if(c){if(this._initialized&&this.sessionId!==void 0)return this.createJsonErrorResponse(400,-32600,"Invalid Request: Server already initialized");if(a.length>1)return this.createJsonErrorResponse(400,-32600,"Invalid Request: Only one initialization request is allowed");this.sessionId=this.sessionIdGenerator?.(),this._initialized=!0,this.sessionId&&this._onsessioninitialized&&await Promise.resolve(this._onsessioninitialized(this.sessionId))}if(!c){let _=this.validateSession(e);if(_)return _;let x=this.validateProtocolVersion(e);if(x)return x}if(!a.some(cr)){for(let _ of a)this.onmessage?.(_,{authInfo:r?.authInfo,requestInfo:s});return new Response(null,{status:202})}let l=crypto.randomUUID(),d=a.find(_=>Mu(_)),g=d?d.params.protocolVersion:e.headers.get("mcp-protocol-version")??Tm;if(this._enableJsonResponse)return new Promise(_=>{this._streamMapping.set(l,{resolveJson:_,cleanup:()=>{this._streamMapping.delete(l)}});for(let x of a)cr(x)&&this._requestToStreamMapping.set(x.id,l);for(let x of a)this.onmessage?.(x,{authInfo:r?.authInfo,requestInfo:s})});let h=new TextEncoder,p,f=new ReadableStream({start:_=>{p=_},cancel:()=>{this._streamMapping.delete(l)}}),m={"Content-Type":"text/event-stream","Cache-Control":"no-cache",Connection:"keep-alive"};this.sessionId!==void 0&&(m["mcp-session-id"]=this.sessionId);for(let _ of a)cr(_)&&(this._streamMapping.set(l,{controller:p,encoder:h,cleanup:()=>{this._streamMapping.delete(l);try{p.close()}catch{}}}),this._requestToStreamMapping.set(_.id,l));await this.writePrimingEvent(p,h,l,g);for(let _ of a){let x,w;cr(_)&&this._eventStore&&g>="2025-11-25"&&(x=()=>{this.closeSSEStream(_.id)},w=()=>{this.closeStandaloneSSEStream()}),this.onmessage?.(_,{authInfo:r?.authInfo,requestInfo:s,closeSSEStream:x,closeStandaloneSSEStream:w})}return new Response(f,{status:200,headers:m})}catch(n){return this.onerror?.(n),this.createJsonErrorResponse(400,-32700,"Parse error",{data:String(n)})}}async handleDeleteRequest(e){let r=this.validateSession(e);if(r)return r;let n=this.validateProtocolVersion(e);return n||(await Promise.resolve(this._onsessionclosed?.(this.sessionId)),await this.close(),new Response(null,{status:200}))}validateSession(e){if(this.sessionIdGenerator===void 0)return;if(!this._initialized)return this.createJsonErrorResponse(400,-32e3,"Bad Request: Server not initialized");let r=e.headers.get("mcp-session-id");if(!r)return this.createJsonErrorResponse(400,-32e3,"Bad Request: Mcp-Session-Id header is required");if(r!==this.sessionId)return this.createJsonErrorResponse(404,-32001,"Session not found")}validateProtocolVersion(e){let r=e.headers.get("mcp-protocol-version");if(r!==null&&!po.includes(r))return this.createJsonErrorResponse(400,-32e3,`Bad Request: Unsupported protocol version: ${r} (supported versions: ${po.join(", ")})`)}async close(){this._streamMapping.forEach(({cleanup:e})=>{e()}),this._streamMapping.clear(),this._requestResponseMap.clear(),this.onclose?.()}closeSSEStream(e){let r=this._requestToStreamMapping.get(e);if(!r)return;let n=this._streamMapping.get(r);n&&n.cleanup()}closeStandaloneSSEStream(){let e=this._streamMapping.get(this._standaloneSseStreamId);e&&e.cleanup()}async send(e,r){let n=r?.relatedRequestId;if((Ut(e)||vn(e))&&(n=e.id),n===void 0){if(Ut(e)||vn(e))throw new Error("Cannot send a response on a standalone SSE stream unless resuming a previous client request");let i;this._eventStore&&(i=await this._eventStore.storeEvent(this._standaloneSseStreamId,e));let a=this._streamMapping.get(this._standaloneSseStreamId);if(a===void 0)return;a.controller&&a.encoder&&this.writeSSEEvent(a.controller,a.encoder,e,i);return}let o=this._requestToStreamMapping.get(n);if(!o)throw new Error(`No connection established for request ID: ${String(n)}`);let s=this._streamMapping.get(o);if(!this._enableJsonResponse&&s?.controller&&s?.encoder){let i;this._eventStore&&(i=await this._eventStore.storeEvent(o,e)),this.writeSSEEvent(s.controller,s.encoder,e,i)}if(Ut(e)||vn(e)){this._requestResponseMap.set(n,e);let i=Array.from(this._requestToStreamMapping.entries()).filter(([c,u])=>u===o).map(([c])=>c);if(i.every(c=>this._requestResponseMap.has(c))){if(!s)throw new Error(`No connection established for request ID: ${String(n)}`);if(this._enableJsonResponse&&s.resolveJson){let c={"Content-Type":"application/json"};this.sessionId!==void 0&&(c["mcp-session-id"]=this.sessionId);let u=i.map(l=>this._requestResponseMap.get(l));u.length===1?s.resolveJson(new Response(JSON.stringify(u[0]),{status:200,headers:c})):s.resolveJson(new Response(JSON.stringify(u),{status:200,headers:c}))}else s.cleanup();for(let c of i)this._requestResponseMap.delete(c),this._requestToStreamMapping.delete(c)}}}};var gv=mv();hv(gv);var yv=new va({sessionIdGenerator:void 0,enableJsonResponse:!0});await gv.connect(yv);var c2={async fetch(t){let e=new URL(t.url);if(t.method==="GET"&&e.pathname==="/health")return new Response(JSON.stringify({status:"ok",version:"0.4.5",tools:12,resources:3,runtime:"cloudflare-workers"}),{headers:{"Content-Type":"application/json","Access-Control-Allow-Origin":"*"}});if(e.pathname==="/mcp")try{let r=await yv.handleRequest(t),n=new Headers(r.headers);return n.set("Access-Control-Allow-Origin","*"),new Response(r.body,{status:r.status,statusText:r.statusText,headers:n})}catch(r){return console.error("Worker error:",r),new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32603,message:"Internal error",data:r instanceof Error?r.message:String(r)},id:null}),{status:500,headers:{"Content-Type":"application/json","Access-Control-Allow-Origin":"*"}})}return new Response("Not Found",{status:404,headers:{"Access-Control-Allow-Origin":"*"}})}};export{c2 as default};

package/openspec/changes/add-ckan-analyze-dataset-structure/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_analyze_dataset_structure tool
+
+## Why
+Users need quick schema and quality signals without manual inspection.
+
+## What Changes
+- Add MCP tool `ckan_analyze_dataset_structure` for schema summaries.
+- Use resource schema or DataStore fields for columns and types.
+- Compute null-rate stats when DataStore is available.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/datastore.ts` and resource utilities
+
+## Open Questions
+- Default `sample_size` for null-rate analysis?
+- How to select resource when only dataset id is provided?

package/openspec/changes/add-ckan-analyze-dataset-structure/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Analyze dataset structure
+The system SHALL provide a `ckan_analyze_dataset_structure` tool that accepts `server_url`, a `resource_id` or `dataset_id`, and optional `sample_size`, returning column names and types; when a DataStore is available it MUST compute per-column null rates from a sampled query.
+
+#### Scenario: Schema summary with null rates
+- **WHEN** the tool is invoked for a DataStore-enabled resource
+- **THEN** the system returns columns, types, and null-rate statistics

package/openspec/changes/add-ckan-analyze-dataset-structure/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Resolve resource selection (resource_id or dataset)
+- [ ] 1.3 Compute schema summary + null rates
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-analyze-dataset-updates/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_analyze_dataset_updates tool
+
+## Why
+Users need quick insight on dataset freshness and update cadence.
+
+## What Changes
+- Add MCP tool `ckan_analyze_dataset_updates` for dataset freshness analysis.
+- Combine `metadata_modified` and resource `last_modified` to estimate cadence.
+- Flag stale datasets based on a configurable threshold.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/package.ts` and `src/tools/datastore.ts`
+
+## Open Questions
+- Default `stale_days` threshold?
+- How to handle resources without `last_modified`?

package/openspec/changes/add-ckan-analyze-dataset-updates/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Analyze dataset updates
+The system SHALL provide a `ckan_analyze_dataset_updates` tool that accepts `server_url`, `dataset_id`, and optional `stale_days`, and returns update cadence based on `metadata_modified` and resource `last_modified`, including a `stale` flag when the most recent update exceeds the threshold.
+
+#### Scenario: Update cadence and stale flag
+- **WHEN** the tool is invoked with a dataset id and stale threshold
+- **THEN** the system returns last update timestamps, cadence summary, and a stale flag

package/openspec/changes/add-ckan-analyze-dataset-updates/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Compute update cadence from metadata/resource dates
+- [ ] 1.3 Add stale detection output
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-audit-tool/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_audit tool
+
+## Why
+Operators need an automated probe to detect datastore/SQL/alias support and capture portal quirks.
+
+## What Changes
+- Add MCP tool `ckan_audit` to probe CKAN API capabilities.
+- Detect DataStore availability, SQL endpoint, and datastore id alias support.
+- Return suggested overrides for portal configuration.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/status.ts` or new insights module
+
+## Open Questions
+- Should audit run only read-only GET probes?
+- Which overrides format to return (JSON block vs markdown list)?

package/openspec/changes/add-ckan-audit-tool/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Audit CKAN portal capabilities
+The system SHALL provide a `ckan_audit` tool that accepts `server_url` and returns detected capabilities for DataStore, SQL endpoint availability, and datastore id alias support, plus suggested portal override values.
+
+#### Scenario: Capability probe
+- **WHEN** the tool probes a CKAN portal
+- **THEN** the response includes datastore availability, SQL support, alias support, and recommended overrides

package/openspec/changes/add-ckan-audit-tool/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Probe datastore_search and datastore_search_sql
+- [ ] 1.3 Detect datastore id alias support
+- [ ] 1.4 Return override suggestions
+- [ ] 1.5 Add fixtures + tests

package/openspec/changes/add-ckan-dataset-insights/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_dataset_insights tool
+
+## Why
+Users want a single call that returns ranked datasets plus freshness and structure insights.
+
+## What Changes
+- Add MCP tool `ckan_dataset_insights` as a wrapper.
+- Combine outputs from `ckan_find_relevant_datasets`, `ckan_analyze_dataset_updates`, and `ckan_analyze_dataset_structure`.
+- Provide compact summary per dataset.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: new insights module orchestrating existing tools
+
+## Open Questions
+- Default number of datasets to enrich?
+- Should structure analysis be optional for non-DataStore resources?

package/openspec/changes/add-ckan-dataset-insights/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Dataset insights wrapper
+The system SHALL provide a `ckan_dataset_insights` tool that accepts `server_url`, `query`, `limit`, and optional analysis parameters, and returns per-dataset summaries combining relevance scores, update cadence, and structure metrics.
+
+#### Scenario: Combined insights output
+- **WHEN** the tool is invoked with a query and limit
+- **THEN** the system returns the top N datasets with combined relevance, update, and structure insights

package/openspec/changes/add-ckan-dataset-insights/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Orchestrate find/update/structure analyses
+- [ ] 1.3 Define merged output format
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/changes/add-ckan-find-relevant-datasets/proposal.md

@@ -0,0 +1,17 @@
+# Change: Add ckan_find_relevant_datasets tool
+
+## Why
+Ranked discovery helps surface the best datasets for a query without manual sorting.
+
+## What Changes
+- Add MCP tool `ckan_find_relevant_datasets` wrapping `package_search`.
+- Score results using weighted fields (title, notes, tags, organization).
+- Return top N datasets with score breakdown.
+
+## Impact
+- Affected specs: `ckan-insights`
+- Affected code: `src/tools/package.ts` (or new insights module)
+
+## Open Questions
+- Default weights for title/notes/tags/organization?
+- Default `limit` when omitted?

package/openspec/changes/add-ckan-find-relevant-datasets/specs/ckan-insights/spec.md

@@ -0,0 +1,7 @@
+## ADDED Requirements
+### Requirement: Find relevant datasets
+The system SHALL provide a `ckan_find_relevant_datasets` tool that accepts `server_url`, `query`, `limit`, and optional weights for title, notes, tags, and organization, and returns the top N datasets ranked by score with a per-field score breakdown.
+
+#### Scenario: Ranked results returned
+- **WHEN** the tool is invoked with a query and limit
+- **THEN** the system uses `package_search` results to return the top N datasets with numeric scores and field contributions

package/openspec/changes/add-ckan-find-relevant-datasets/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+- [ ] 1.1 Add tool schema and registration
+- [ ] 1.2 Implement weighted scoring + ranking
+- [ ] 1.3 Define markdown/json output shape
+- [ ] 1.4 Add fixtures + tests
+- [ ] 1.5 Update README/EXAMPLES

package/openspec/specs/ckan-insights/spec.md

@@ -0,0 +1,12 @@
+# ckan-insights Specification
+
+## Purpose
+Describe dataset insight tools (relevance, freshness, structure) once implemented.
+
+## Requirements
+### Requirement: Insights capability reserved
+The system SHALL maintain this specification to document dataset insight tools when they are added.
+
+#### Scenario: Insight tools documented
+- **WHEN** new insight tools are implemented
+- **THEN** their requirements are captured in this specification

package/openspec/specs/cloudflare-deployment/spec.md

@@ -0,0 +1,344 @@
+# cloudflare-deployment Specification
+
+## Purpose
+TBD - created by archiving change add-cloudflare-workers. Update Purpose after archive.
+## Requirements
+### Requirement: Workers Entry Point
+
+The system SHALL provide a Cloudflare Workers-compatible entry point that handles HTTP requests using the Workers fetch API.
+
+#### Scenario: Health check endpoint
+
+- **WHEN** client sends `GET /health` to Workers endpoint
+- **THEN** server returns JSON with status, version, tool count, and resource count
+
+#### Scenario: MCP protocol endpoint
+
+- **WHEN** client sends `POST /mcp` with JSON-RPC request to Workers endpoint
+- **THEN** server processes MCP request and returns JSON-RPC response
+
+#### Scenario: Invalid route
+
+- **WHEN** client requests any path other than `/health` or `/mcp`
+- **THEN** server returns 404 Not Found
+
+#### Scenario: Invalid method on MCP endpoint
+
+- **WHEN** client sends non-POST request to `/mcp`
+- **THEN** server returns 404 Not Found
+
+---
+
+### Requirement: MCP Server Integration
+
+The system SHALL initialize MCP server instance on each Workers invocation and register all tools and resources.
+
+#### Scenario: Server initialization
+
+- **WHEN** Workers receives MCP request
+- **THEN** server creates MCP Server instance with name "ckan-mcp-server" and version "0.4.0"
+
+#### Scenario: Tool registration
+
+- **WHEN** Workers initializes MCP server
+- **THEN** server registers all 7 CKAN tools (package_search, package_show, organization_list, organization_show, organization_search, datastore_search, status_show)
+
+#### Scenario: Resource registration
+
+- **WHEN** Workers initializes MCP server
+- **THEN** server registers all 3 resource templates (dataset, resource, organization)
+
+#### Scenario: Tools list request
+
+- **WHEN** client calls `tools/list` method via Workers endpoint
+- **THEN** response includes all 7 registered CKAN tools with descriptions
+
+---
+
+### Requirement: Web Standards HTTP Client
+
+The system SHALL use native Web Fetch API for CKAN API requests instead of Node.js-specific libraries.
+
+#### Scenario: CKAN API request with fetch
+
+- **WHEN** tool calls `makeCkanRequest()` in Workers runtime
+- **THEN** client uses native `fetch()` with 30-second timeout
+
+#### Scenario: Query parameter encoding
+
+- **WHEN** CKAN request includes parameters (e.g., `q`, `rows`, `start`)
+- **THEN** client encodes parameters in URL using `URLSearchParams`
+
+#### Scenario: Request timeout
+
+- **WHEN** CKAN API takes longer than 30 seconds
+- **THEN** client aborts request using `AbortController` and returns timeout error
+
+#### Scenario: HTTP error handling
+
+- **WHEN** CKAN API returns HTTP error status (4xx, 5xx)
+- **THEN** client throws error with status code and message
+
+#### Scenario: CKAN API validation
+
+- **WHEN** CKAN API returns 200 OK but `success: false`
+- **THEN** client throws error with CKAN error message
+
+---
+
+### Requirement: Workers Build Configuration
+
+The system SHALL provide separate build configuration for Workers deployment targeting browser platform with ESM format.
+
+#### Scenario: Workers build script
+
+- **WHEN** user runs `npm run build:worker`
+- **THEN** esbuild compiles `src/worker.ts` to `dist/worker.js` in ESM format
+
+#### Scenario: Bundle all dependencies
+
+- **WHEN** esbuild builds Workers bundle
+- **THEN** all dependencies are bundled (no external modules)
+
+#### Scenario: Platform targeting
+
+- **WHEN** esbuild builds Workers bundle
+- **THEN** platform is set to `browser` and target is `es2022`
+
+#### Scenario: Output format
+
+- **WHEN** Workers build completes
+- **THEN** output is ESM format (not CommonJS)
+
+#### Scenario: Bundle size validation
+
+- **WHEN** Workers build completes
+- **THEN** bundle size is less than 1MB (Workers script size limit)
+
+---
+
+### Requirement: Wrangler Configuration
+
+The system SHALL provide Wrangler configuration file for Workers deployment and local development.
+
+#### Scenario: Wrangler configuration file
+
+- **WHEN** project contains `wrangler.toml` in root directory
+- **THEN** configuration specifies name, main entry point, and compatibility date
+
+#### Scenario: Build command
+
+- **WHEN** `wrangler deploy` or `wrangler dev` runs
+- **THEN** Wrangler executes `npm run build:worker` before deployment
+
+#### Scenario: Local development server
+
+- **WHEN** user runs `npm run dev:worker`
+- **THEN** Wrangler starts local Workers server on http://localhost:8787
+
+---
+
+### Requirement: Workers Deployment
+
+The system SHALL deploy to Cloudflare Workers and provide public HTTPS endpoint.
+
+#### Scenario: Deploy to Workers
+
+- **WHEN** user runs `npm run deploy`
+- **THEN** Wrangler builds and uploads worker to Cloudflare
+
+#### Scenario: Public endpoint
+
+- **WHEN** deployment succeeds
+- **THEN** Workers script is accessible at `https://ckan-mcp-server.<account>.workers.dev`
+
+#### Scenario: HTTPS support
+
+- **WHEN** client accesses Workers endpoint
+- **THEN** connection uses HTTPS with valid certificate
+
+---
+
+### Requirement: Tool Functionality Preservation
+
+The system SHALL maintain identical functionality for all CKAN tools in Workers runtime compared to Node.js runtime.
+
+#### Scenario: Package search in Workers
+
+- **WHEN** client calls `ckan_package_search` via Workers endpoint
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Datastore query in Workers
+
+- **WHEN** client calls `ckan_datastore_search` via Workers endpoint
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Resource template in Workers
+
+- **WHEN** client reads `ckan://{server}/dataset/{id}` via Workers
+- **THEN** response is identical to Node.js runtime response
+
+#### Scenario: Error handling in Workers
+
+- **WHEN** CKAN API is unreachable in Workers runtime
+- **THEN** error response matches Node.js runtime error format
+
+---
+
+### Requirement: Response Format Compatibility
+
+The system SHALL support both markdown and JSON output formats in Workers runtime.
+
+#### Scenario: Markdown format
+
+- **WHEN** client requests tool with `response_format: "markdown"`
+- **THEN** Workers returns formatted markdown text
+
+#### Scenario: JSON format
+
+- **WHEN** client requests tool with `response_format: "json"`
+- **THEN** Workers returns raw JSON data
+
+#### Scenario: Character limit
+
+- **WHEN** response exceeds CHARACTER_LIMIT (50000 characters)
+- **THEN** Workers truncates response identically to Node.js runtime
+
+---
+
+### Requirement: Error Handling
+
+The system SHALL handle Workers-specific errors gracefully with JSON-RPC error responses.
+
+#### Scenario: Malformed JSON-RPC request
+
+- **WHEN** client sends invalid JSON to `/mcp` endpoint
+- **THEN** Workers returns JSON-RPC error with code -32700 (Parse error)
+
+#### Scenario: Internal worker error
+
+- **WHEN** worker encounters unexpected exception
+- **THEN** Workers returns JSON-RPC error with code -32603 (Internal error)
+
+#### Scenario: Method not found
+
+- **WHEN** client calls non-existent MCP method
+- **THEN** Workers returns JSON-RPC error with code -32601 (Method not found)
+
+---
+
+### Requirement: CORS Support
+
+The system SHALL include CORS headers to enable browser-based MCP clients.
+
+#### Scenario: CORS headers on success
+
+- **WHEN** Workers returns successful response
+- **THEN** response includes `Access-Control-Allow-Origin: *` header
+
+#### Scenario: CORS headers on error
+
+- **WHEN** Workers returns error response
+- **THEN** response includes `Access-Control-Allow-Origin: *` header
+
+#### Scenario: Preflight request
+
+- **WHEN** browser sends OPTIONS request for CORS preflight
+- **THEN** Workers returns allowed methods and headers
+
+---
+
+### Requirement: Deployment Documentation
+
+The system SHALL provide comprehensive documentation for deploying to Cloudflare Workers.
+
+#### Scenario: Deployment guide
+
+- **WHEN** contributor wants to deploy Workers instance
+- **THEN** `docs/DEPLOYMENT.md` provides step-by-step instructions
+
+#### Scenario: Prerequisites documentation
+
+- **WHEN** contributor reads DEPLOYMENT.md
+- **THEN** document lists all prerequisites (Cloudflare account, wrangler CLI)
+
+#### Scenario: Troubleshooting guide
+
+- **WHEN** deployment fails
+- **THEN** DEPLOYMENT.md includes common errors and solutions
+
+#### Scenario: README update
+
+- **WHEN** user reads README.md
+- **THEN** deployment options section includes Cloudflare Workers option
+
+---
+
+### Requirement: Backwards Compatibility
+
+The system SHALL maintain all existing deployment modes (stdio, self-hosted HTTP) without breaking changes.
+
+#### Scenario: Stdio mode unchanged
+
+- **WHEN** user runs `npm start` after Workers implementation
+- **THEN** stdio transport works identically to pre-Workers version
+
+#### Scenario: Self-hosted HTTP mode unchanged
+
+- **WHEN** user runs `TRANSPORT=http PORT=3000 npm start` after Workers implementation
+- **THEN** HTTP server works identically to pre-Workers version
+
+#### Scenario: Existing tests pass
+
+- **WHEN** user runs `npm test` after Workers implementation
+- **THEN** all 113 existing tests pass without modification
+
+#### Scenario: Node.js bundle unchanged
+
+- **WHEN** user runs `npm run build` after Workers implementation
+- **THEN** Node.js bundle (`dist/index.js`) is unchanged
+
+---
+
+### Requirement: Development Workflow
+
+The system SHALL support efficient local development and testing of Workers deployment.
+
+#### Scenario: Local Workers testing
+
+- **WHEN** developer runs `npm run dev:worker`
+- **THEN** wrangler starts local server with hot reload
+
+#### Scenario: Quick iteration
+
+- **WHEN** developer modifies `src/worker.ts`
+- **THEN** wrangler automatically rebuilds and reloads
+
+#### Scenario: curl testing
+
+- **WHEN** developer sends curl request to local Workers
+- **THEN** response matches expected MCP protocol format
+
+---
+
+### Requirement: Monitoring and Debugging
+
+The system SHALL provide access to Workers logs and metrics for troubleshooting.
+
+#### Scenario: Real-time logs
+
+- **WHEN** developer runs `wrangler tail`
+- **THEN** console.log output from worker appears in terminal
+
+#### Scenario: Error logs
+
+- **WHEN** worker throws exception
+- **THEN** stack trace appears in `wrangler tail` output
+
+#### Scenario: Cloudflare dashboard
+
+- **WHEN** user accesses Cloudflare Workers dashboard
+- **THEN** metrics show request count, error rate, and CPU time
+
+---
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "MCP server for interacting with CKAN open data portals",
   "main": "dist/index.js",
   "type": "module",