@aborruso/ckan-mcp-server 0.4.50 → 0.4.52

package/LOG.md

@@ -1,5 +1,37 @@
 # LOG
 
+## 2026-02-28 (v0.4.52)
+
+- fix: HTTP transport — `/.well-known/oauth-authorization-server` now returns JSON 404 instead of HTML; fixes Claude Code HTTP transport connection failure
+- fix: `ckan_datastore_search` — `limit` min changed 1→0; allows column discovery without fetching data
+- docs: `ckan_datastore_search` description updated — fields always returned, `limit=0` pattern documented
+
+## 2026-02-27 (v0.4.51)
+
+- refactor: domain types for all tool files — `CkanTag`, `CkanResource`, `CkanPackage`, `CkanOrganization`, `CkanField`, `CkanDatastoreResult` in `src/types.ts`; `any` reduced 32 → 1
+- refactor: extract rendering functions from handler closures → named exports in `datastore.ts`, `organization.ts`, `group.ts`, `status.ts`; +26 unit tests
+- fix: datastore table — skip `_id` column, increase cell truncation 50 → 80 chars
+- fix: org/group show — dataset heading now shows `showing M of N returned — T total`
+- tests: 191 → 272; all passing
+
+## 2026-02-27 (continued 2)
+
+- fix: datastore table — skip `_id` column, increase cell truncation 50→80 chars
+- fix: org/group show — `## Datasets (N)` → `## Datasets (showing M of N returned — T total)`
+- tests: 270 → 272; all passing
+
+## 2026-02-27 (continued)
+
+- refactor: extract markdown rendering from handler closures into exported functions in `datastore.ts`, `organization.ts`, `group.ts`, `status.ts`
+- add 26 unit tests across 4 new test files (`datastore-formatting`, `organization-formatting`, `group-formatting`, `status-formatting`)
+- test count: 244 → 270; all passing
+
+## 2026-02-27
+
+- refactor: add CKAN domain types (`CkanTag`, `CkanResource`, `CkanPackage`, `CkanOrganization`, `CkanField`, `CkanDatastoreResult`) to `src/types.ts`
+- replace `any` in exported tool functions across `package.ts`, `datastore.ts`, `organization.ts`, `group.ts`, `quality.ts`, `tag.ts` — 32 → 1 remaining (internal handler variable)
+- no behavioral change; 244 tests passing
+
 ## 2026-02-26 (v0.4.50)
 
 - `ckan_list_resources`: add `format_filter` param (case-insensitive, client-side) — e.g. 72 resources → 8 CSV; header shows "Total: 72 (showing 8 CSV)"

package/dist/index.js

@@ -1505,6 +1505,65 @@ Typical workflow: ckan_package_search \u2192 ckan_list_resources (assess availab
 
 // src/tools/organization.ts
 import { z as z3 } from "zod";
+function formatOrganizationShowMarkdown(result, serverUrl) {
+  let markdown = `# Organization: ${result.title || result.name}
+
+`;
+  markdown += `**Server**: ${serverUrl}
+`;
+  markdown += `**Link**: ${getOrganizationViewUrl(serverUrl, result)}
+
+`;
+  markdown += `## Details
+
+`;
+  markdown += `- **ID**: \`${result.id}\`
+`;
+  markdown += `- **Name**: \`${result.name}\`
+`;
+  markdown += `- **Datasets**: ${result.package_count || 0}
+`;
+  markdown += `- **Created**: ${formatDate(result.created)}
+`;
+  markdown += `- **State**: ${result.state}
+
+`;
+  if (result.description) {
+    markdown += `## Description
+
+${result.description}
+
+`;
+  }
+  if (result.packages && result.packages.length > 0) {
+    const displayed = Math.min(result.packages.length, 20);
+    const totalHint = result.package_count && result.package_count !== result.packages.length ? ` \u2014 ${result.package_count} total` : "";
+    markdown += `## Datasets (showing ${displayed} of ${result.packages.length} returned${totalHint})
+
+`;
+    for (const pkg of result.packages.slice(0, 20)) {
+      markdown += `- **${pkg.title || pkg.name}** (\`${pkg.name}\`)
+`;
+    }
+    if (result.packages.length > 20) {
+      markdown += `
+... and ${result.packages.length - 20} more datasets
+`;
+    }
+    markdown += "\n";
+  }
+  if (result.users && result.users.length > 0) {
+    markdown += `## Users (${result.users.length})
+
+`;
+    for (const user of result.users) {
+      markdown += `- **${user.name}** (${user.capacity})
+`;
+    }
+    markdown += "\n";
+  }
+  return markdown;
+}
 function registerOrganizationTools(server2) {
   server2.registerTool(
     "ckan_organization_list",
@@ -1748,60 +1807,7 @@ Typical workflow: ckan_organization_show \u2192 ckan_package_show (inspect a dat
             structuredContent: result
           };
         }
-        let markdown = `# Organization: ${result.title || result.name}
-
-`;
-        markdown += `**Server**: ${params.server_url}
-`;
-        markdown += `**Link**: ${getOrganizationViewUrl(params.server_url, result)}
-
-`;
-        markdown += `## Details
-
-`;
-        markdown += `- **ID**: \`${result.id}\`
-`;
-        markdown += `- **Name**: \`${result.name}\`
-`;
-        markdown += `- **Datasets**: ${result.package_count || 0}
-`;
-        markdown += `- **Created**: ${formatDate(result.created)}
-`;
-        markdown += `- **State**: ${result.state}
-
-`;
-        if (result.description) {
-          markdown += `## Description
-
-${result.description}
-
-`;
-        }
-        if (result.packages && result.packages.length > 0) {
-          markdown += `## Datasets (${result.packages.length})
-
-`;
-          for (const pkg of result.packages.slice(0, 20)) {
-            markdown += `- **${pkg.title || pkg.name}** (\`${pkg.name}\`)
-`;
-          }
-          if (result.packages.length > 20) {
-            markdown += `
-... and ${result.packages.length - 20} more datasets
-`;
-          }
-          markdown += "\n";
-        }
-        if (result.users && result.users.length > 0) {
-          markdown += `## Users (${result.users.length})
-
-`;
-          for (const user of result.users) {
-            markdown += `- **${user.name}** (${user.capacity})
-`;
-          }
-          markdown += "\n";
-        }
+        const markdown = formatOrganizationShowMarkdown(result, params.server_url);
         return {
           content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
         };
@@ -1926,6 +1932,108 @@ Typical workflow: ckan_organization_search \u2192 ckan_organization_show (get de
 
 // src/tools/datastore.ts
 import { z as z4 } from "zod";
+function formatDatastoreSearchMarkdown(result, serverUrl, resourceId, offset, limit) {
+  let markdown = `# DataStore Query Results
+
+`;
+  markdown += `**Server**: ${serverUrl}
+`;
+  markdown += `**Resource ID**: \`${resourceId}\`
+`;
+  markdown += `**Total Records**: ${result.total || 0}
+`;
+  markdown += `**Returned**: ${result.records ? result.records.length : 0} records
+
+`;
+  if (result.fields && result.fields.length > 0) {
+    markdown += `## Fields
+
+`;
+    markdown += result.fields.map((f) => `- **${f.id}** (${f.type})`).join("\n") + "\n\n";
+  }
+  if (result.records && result.records.length > 0) {
+    markdown += `## Records
+
+`;
+    const fields = result.fields ? result.fields.map((f) => f.id).filter((id) => id !== "_id") : [];
+    const displayFields = fields.slice(0, 8);
+    markdown += `| ${displayFields.join(" | ")} |
+`;
+    markdown += `| ${displayFields.map(() => "---").join(" | ")} |
+`;
+    for (const record of result.records.slice(0, 50)) {
+      const values = displayFields.map((field) => {
+        const val = record[field];
+        if (val === null || val === void 0) return "-";
+        const str = String(val);
+        return str.length > 80 ? str.substring(0, 77) + "..." : str;
+      });
+      markdown += `| ${values.join(" | ")} |
+`;
+    }
+    if (result.records.length > 50) {
+      markdown += `
+... and ${result.records.length - 50} more records
+`;
+    }
+    markdown += "\n";
+  }
+  if (result.total && result.total > offset + (result.records?.length || 0)) {
+    const nextOffset = offset + limit;
+    markdown += `**More results available**: Use \`offset: ${nextOffset}\` for next page.
+`;
+  }
+  return markdown;
+}
+function formatDatastoreSqlMarkdown(result, serverUrl, sql) {
+  const records = result.records || [];
+  const fieldIds = (result.fields?.map((field) => field.id) || Object.keys(records[0] || {})).filter((id) => id !== "_id");
+  let markdown = `# DataStore SQL Results
+
+`;
+  markdown += `**Server**: ${serverUrl}
+`;
+  markdown += `**SQL**: \`${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 > 80 ? text.substring(0, 77) + "..." : 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 markdown;
+}
 function registerDatastoreTools(server2) {
   server2.registerTool(
     "ckan_datastore_search",
@@ -1935,6 +2043,10 @@ function registerDatastoreTools(server2) {
 
 The DataStore allows SQL-like queries on tabular data. Not all resources have DataStore enabled.
 
+The response always includes a Fields section listing all available column names and types.
+Use limit=0 to discover column names without fetching data \u2014 do this before using filters
+to avoid guessing column names and getting HTTP 400 errors.
+
 Args:
   - server_url (string): Base URL of CKAN server
   - resource_id (string): ID of the DataStore resource
@@ -1948,20 +2060,21 @@ Args:
   - response_format ('markdown' | 'json'): Output format
 
 Returns:
-  DataStore records matching query
+  DataStore records matching query, always including available column names and types
 
 Examples:
+  - { server_url: "...", resource_id: "abc-123", limit: 0 }  \u2190 discover columns first
   - { server_url: "...", resource_id: "abc-123", limit: 50 }
   - { server_url: "...", resource_id: "...", filters: { "regione": "Sicilia" } }
   - { server_url: "...", resource_id: "...", sort: "anno desc", limit: 100 }
 
-Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id with datastore_active=true) \u2192 ckan_datastore_search`,
+Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id with datastore_active=true) \u2192 ckan_datastore_search (limit=0 to get columns) \u2192 ckan_datastore_search (with filters)`,
       inputSchema: z4.object({
         server_url: z4.string().url().describe("Base URL of the CKAN server (e.g., https://dati.gov.it/opendata)"),
         resource_id: z4.string().min(1).describe("UUID of the DataStore resource (from ckan_package_show resource.id where datastore_active is true)"),
         q: z4.string().optional().describe("Full-text search across all fields"),
         filters: z4.record(z4.any()).optional().describe('Key-value filters for exact matches (e.g., { "regione": "Sicilia", "anno": 2023 })'),
-        limit: z4.number().int().min(1).max(32e3).optional().default(100).describe("Max rows to return (default 100, max 32000)"),
+        limit: z4.number().int().min(0).max(32e3).optional().default(100).describe("Max rows to return (default 100, max 32000); use 0 to get only column names without data"),
         offset: z4.number().int().min(0).optional().default(0).describe("Pagination offset"),
         fields: z4.array(z4.string()).optional().describe("Specific field names to return; omit to return all fields"),
         sort: z4.string().optional().describe("Sort expression (e.g., 'anno desc', 'nome asc')"),
@@ -1997,56 +2110,7 @@ Typical workflow: ckan_package_search \u2192 ckan_package_show (find resource_id
             content: [{ type: "text", text: truncateText(JSON.stringify(result, null, 2)) }]
           };
         }
-        let markdown = `# DataStore Query Results
-
-`;
-        markdown += `**Server**: ${params.server_url}
-`;
-        markdown += `**Resource ID**: \`${params.resource_id}\`
-`;
-        markdown += `**Total Records**: ${result.total || 0}
-`;
-        markdown += `**Returned**: ${result.records ? result.records.length : 0} records
-
-`;
-        if (result.fields && result.fields.length > 0) {
-          markdown += `## Fields
-
-`;
-          markdown += result.fields.map((f) => `- **${f.id}** (${f.type})`).join("\n") + "\n\n";
-        }
-        if (result.records && result.records.length > 0) {
-          markdown += `## Records
-
-`;
-          const fields = result.fields.map((f) => f.id);
-          const displayFields = fields.slice(0, 8);
-          markdown += `| ${displayFields.join(" | ")} |
-`;
-          markdown += `| ${displayFields.map(() => "---").join(" | ")} |
-`;
-          for (const record of result.records.slice(0, 50)) {
-            const values = displayFields.map((field) => {
-              const val = record[field];
-              if (val === null || val === void 0) return "-";
-              const str = String(val);
-              return str.length > 50 ? str.substring(0, 47) + "..." : str;
-            });
-            markdown += `| ${values.join(" | ")} |
-`;
-          }
-          if (result.records.length > 50) {
-            markdown += `
-... and ${result.records.length - 50} more records
-`;
-          }
-          markdown += "\n";
-        }
-        if (result.total && result.total > params.offset + (result.records?.length || 0)) {
-          const nextOffset = params.offset + params.limit;
-          markdown += `**More results available**: Use \`offset: ${nextOffset}\` for next page.
-`;
-        }
+        const markdown = formatDatastoreSearchMarkdown(result, params.server_url, params.resource_id, params.offset, params.limit);
         return {
           content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
         };
@@ -2107,52 +2171,7 @@ Typical workflow: ckan_package_show (get resource_id) \u2192 ckan_datastore_sear
             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";
-        }
+        const markdown = formatDatastoreSqlMarkdown(result, params.server_url, params.sql);
         return {
           content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
         };
@@ -2171,6 +2190,16 @@ Typical workflow: ckan_package_show (get resource_id) \u2192 ckan_datastore_sear
 
 // src/tools/status.ts
 import { z as z5 } from "zod";
+function formatStatusMarkdown(result, serverUrl) {
+  return `# CKAN Server Status
+
+**Server**: ${serverUrl}
+**Status**: \u2705 Online
+**CKAN Version**: ${result.ckan_version || "Unknown"}
+**Site Title**: ${result.site_title || "N/A"}
+**Site URL**: ${result.site_url || "N/A"}
+`;
+}
 function registerStatusTools(server2) {
   server2.registerTool(
     "ckan_status_show",
@@ -2204,14 +2233,7 @@ Typical workflow: ckan_status_show (verify server is up) \u2192 ckan_package_sea
           "status_show",
           {}
         );
-        const markdown = `# CKAN Server Status
-
-**Server**: ${params.server_url}
-**Status**: \u2705 Online
-**CKAN Version**: ${result.ckan_version || "Unknown"}
-**Site Title**: ${result.site_title || "N/A"}
-**Site URL**: ${result.site_url || "N/A"}
-`;
+        const markdown = formatStatusMarkdown(result, params.server_url);
         return {
           content: [{ type: "text", text: addDemoFooter(markdown) }],
           structuredContent: result
@@ -2233,7 +2255,10 @@ ${error instanceof Error ? error.message : String(error)}`
 // src/tools/tag.ts
 import { z as z6 } from "zod";
 function normalizeTagFacets(result) {
-  const searchItems = result?.search_facets?.tags?.items;
+  const r = result;
+  const searchFacets = r?.search_facets;
+  const tagsGroup = searchFacets?.tags;
+  const searchItems = tagsGroup?.items;
   if (Array.isArray(searchItems)) {
     return searchItems.map((item) => ({
       name: item?.name || item?.display_name || String(item),
@@ -2241,7 +2266,7 @@ function normalizeTagFacets(result) {
       display_name: item?.display_name
     }));
   }
-  const facets = result?.facets?.tags;
+  const facets = r?.facets?.tags;
   if (Array.isArray(facets)) {
     if (facets.length > 0 && typeof facets[0] === "object") {
       return facets.map((item) => ({
@@ -2371,16 +2396,67 @@ function getGroupViewUrl(serverUrl, group) {
   const cleanServerUrl = serverUrl.replace(/\/$/, "");
   return `${cleanServerUrl}/group/${group.name}`;
 }
+function formatGroupShowMarkdown(result, serverUrl) {
+  let markdown = `# Group: ${result.title || result.name}
+
+`;
+  markdown += `**Server**: ${serverUrl}
+`;
+  markdown += `**Link**: ${getGroupViewUrl(serverUrl, result)}
+
+`;
+  markdown += `## Details
+
+`;
+  markdown += `- **ID**: \`${result.id}\`
+`;
+  markdown += `- **Name**: \`${result.name}\`
+`;
+  markdown += `- **Datasets**: ${result.package_count || 0}
+`;
+  markdown += `- **Created**: ${formatDate(result.created)}
+`;
+  markdown += `- **State**: ${result.state}
+
+`;
+  if (result.description) {
+    markdown += `## Description
+
+${result.description}
+
+`;
+  }
+  if (result.packages && result.packages.length > 0) {
+    const displayed = Math.min(result.packages.length, 20);
+    const totalHint = result.package_count && result.package_count !== result.packages.length ? ` \u2014 ${result.package_count} total` : "";
+    markdown += `## Datasets (showing ${displayed} of ${result.packages.length} returned${totalHint})
+
+`;
+    for (const pkg of result.packages.slice(0, 20)) {
+      markdown += `- **${pkg.title || pkg.name}** (\`${pkg.name}\`)
+`;
+    }
+    if (result.packages.length > 20) {
+      markdown += `
+... and ${result.packages.length - 20} more datasets
+`;
+    }
+    markdown += "\n";
+  }
+  return markdown;
+}
 function normalizeGroupFacets(result) {
-  const items = result?.search_facets?.groups?.items;
-  if (Array.isArray(items)) {
-    return items.map((item) => ({
+  const r = result;
+  const items = r?.search_facets?.groups;
+  const itemsArr = items?.items;
+  if (Array.isArray(itemsArr)) {
+    return itemsArr.map((item) => ({
       name: item?.name || item?.display_name || String(item),
       display_name: item?.display_name,
       count: typeof item?.count === "number" ? item.count : 0
     }));
   }
-  const facets = result?.facets?.groups;
+  const facets = r?.facets?.groups;
   if (Array.isArray(facets)) {
     if (facets.length > 0 && typeof facets[0] === "object") {
       return facets.map((item) => ({
@@ -2571,50 +2647,7 @@ Typical workflow: ckan_group_show \u2192 ckan_package_show (inspect a dataset) \
             structuredContent: result
           };
         }
-        let markdown = `# Group: ${result.title || result.name}
-
-`;
-        markdown += `**Server**: ${params.server_url}
-`;
-        markdown += `**Link**: ${getGroupViewUrl(params.server_url, result)}
-
-`;
-        markdown += `## Details
-
-`;
-        markdown += `- **ID**: \`${result.id}\`
-`;
-        markdown += `- **Name**: \`${result.name}\`
-`;
-        markdown += `- **Datasets**: ${result.package_count || 0}
-`;
-        markdown += `- **Created**: ${formatDate(result.created)}
-`;
-        markdown += `- **State**: ${result.state}
-
-`;
-        if (result.description) {
-          markdown += `## Description
-
-${result.description}
-
-`;
-        }
-        if (result.packages && result.packages.length > 0) {
-          markdown += `## Datasets (${result.packages.length})
-
-`;
-          for (const pkg of result.packages.slice(0, 20)) {
-            markdown += `- **${pkg.title || pkg.name}** (\`${pkg.name}\`)
-`;
-          }
-          if (result.packages.length > 20) {
-            markdown += `
-... and ${result.packages.length - 20} more datasets
-`;
-          }
-          markdown += "\n";
-        }
+        const markdown = formatGroupShowMarkdown(result, params.server_url);
         return {
           content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
         };
@@ -3168,8 +3201,9 @@ function metricAvailability(section, availabilityKey, statusKey) {
   return void 0;
 }
 function normalizeQualityData(data) {
-  const mqaData = data?.mqa ?? data;
-  const breakdown = data?.breakdown;
+  const d = data;
+  const mqaData = d?.mqa ?? data;
+  const breakdown = d?.breakdown;
   const resultEntry = mqaData?.result?.results?.[0];
   if (!resultEntry || typeof resultEntry !== "object") {
     return { ...data, breakdown };
@@ -3975,7 +4009,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.50"
+    version: "0.4.52"
   });
 }
 function registerAll(server2) {
@@ -4009,6 +4043,9 @@ async function runHTTP(server2) {
     enableJsonResponse: true
   });
   await server2.connect(transport2);
+  app.get("/.well-known/oauth-authorization-server", (_req, res) => {
+    res.status(404).json({ error: "authorization_not_supported", error_description: "This server does not require authentication" });
+  });
   app.post("/mcp", async (req, res) => {
     await transport2.handleRequest(req, res, req.body);
   });