@aborruso/ckan-mcp-server 0.4.51 → 0.4.53

package/LOG.md

@@ -1,5 +1,18 @@
 # LOG
 
+## 2026-02-28 (v0.4.53)
+
+- feat: new tool `ckan_analyze_datasets` — search + DataStore schema introspection in one call; includes `info.label`/`info.notes` from DataStore Dictionary when available
+- feat: new tool `ckan_catalog_stats` — portal overview (total datasets, categories, formats, organizations) via single faceted query
+- refactor: `quality.ts` tools migrated from deprecated `server.tool()` to `registerTool()` with full annotations
+- tests: 287 passing (+15 new tests)
+
+## 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

package/dist/index.js

@@ -2043,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
@@ -2056,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')"),
@@ -3383,13 +3388,22 @@ function formatQualityDetailsMarkdown(data, datasetId) {
   return lines.join("\n");
 }
 function registerQualityTools(server2) {
-  server2.tool(
+  server2.registerTool(
     "ckan_get_mqa_quality",
-    "Get MQA (Metadata Quality Assurance) quality metrics for a dataset on dati.gov.it. Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability, contextuality) from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_package_show (get dataset ID) \u2192 ckan_get_mqa_quality \u2192 ckan_get_mqa_quality_details (for non-max dimensions)",
     {
-      server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
-      dataset_id: z8.string().describe("Dataset ID or name"),
-      response_format: ResponseFormatSchema.optional()
+      title: "Get MQA Quality Score",
+      description: "Get MQA (Metadata Quality Assurance) quality metrics for a dataset on dati.gov.it. Returns quality score and detailed metrics (accessibility, reusability, interoperability, findability, contextuality) from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_package_show (get dataset ID) \u2192 ckan_get_mqa_quality \u2192 ckan_get_mqa_quality_details (for non-max dimensions)",
+      inputSchema: z8.object({
+        server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
+        dataset_id: z8.string().describe("Dataset ID or name"),
+        response_format: ResponseFormatSchema.optional()
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ server_url, dataset_id, response_format }) => {
       if (!isValidMqaServer(server_url)) {
@@ -3423,13 +3437,22 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
       }
     }
   );
-  server2.tool(
+  server2.registerTool(
     "ckan_get_mqa_quality_details",
-    "Get detailed MQA (Metadata Quality Assurance) quality reasons for a dataset on dati.gov.it. Returns dimension scores, non-max reasons, and raw MQA flags from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_get_mqa_quality (get overview scores) \u2192 ckan_get_mqa_quality_details (inspect failing metrics)",
     {
-      server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
-      dataset_id: z8.string().describe("Dataset ID or name"),
-      response_format: ResponseFormatSchema.optional()
+      title: "Get MQA Quality Details",
+      description: "Get detailed MQA (Metadata Quality Assurance) quality reasons for a dataset on dati.gov.it. Returns dimension scores, non-max reasons, and raw MQA flags from data.europa.eu. Only works with dati.gov.it server. Typical workflow: ckan_get_mqa_quality (get overview scores) \u2192 ckan_get_mqa_quality_details (inspect failing metrics)",
+      inputSchema: z8.object({
+        server_url: z8.string().url().describe("Base URL of dati.gov.it (e.g., https://www.dati.gov.it/opendata)"),
+        dataset_id: z8.string().describe("Dataset ID or name"),
+        response_format: ResponseFormatSchema.optional()
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
     },
     async ({ server_url, dataset_id, response_format }) => {
       if (!isValidMqaServer(server_url)) {
@@ -3465,6 +3488,281 @@ The MQA (Metadata Quality Assurance) system is operated by data.europa.eu and on
   );
 }
 
+// src/tools/analyze.ts
+import { z as z9 } from "zod";
+function formatAnalyzeDatasetsMarkdown(serverUrl, query, total, datasets) {
+  let md = `# Dataset Analysis
+
+`;
+  md += `**Server**: ${serverUrl}
+`;
+  md += `**Query**: ${query}
+`;
+  md += `**Total datasets found**: ${total}
+`;
+  md += `**Datasets analyzed**: ${datasets.length}
+
+`;
+  for (const { dataset, datastoreResources, nonDatastoreResources } of datasets) {
+    md += `---
+
+`;
+    md += `## ${dataset.title || dataset.name}
+
+`;
+    md += `- **ID**: \`${dataset.id}\`
+`;
+    md += `- **Name**: \`${dataset.name}\`
+`;
+    if (dataset.organization) {
+      md += `- **Organization**: ${dataset.organization.title || dataset.organization.name}
+`;
+    }
+    if (datastoreResources.length > 0) {
+      md += `
+### DataStore Resources
+
+`;
+      for (const { resource, schema, error } of datastoreResources) {
+        md += `#### ${resource.name || resource.id}
+
+`;
+        md += `- **Resource ID**: \`${resource.id}\`
+`;
+        if (resource.format) md += `- **Format**: ${resource.format}
+`;
+        if (error) {
+          md += `- **Error**: ${error}
+`;
+        } else if (schema) {
+          md += `- **Total Records**: ${schema.total}
+`;
+          const fields = schema.fields.filter((f) => f.id !== "_id");
+          if (fields.length > 0) {
+            md += `
+**Fields** (${fields.length}):
+
+`;
+            for (const f of fields) {
+              let line = `- \`${f.id}\` (${f.type})`;
+              if (f.info?.label) line += ` \u2014 ${f.info.label}`;
+              if (f.info?.notes) line += `: ${f.info.notes}`;
+              md += line + "\n";
+            }
+          }
+        }
+        md += "\n";
+      }
+    }
+    if (nonDatastoreResources.length > 0) {
+      md += `### Other Resources (not queryable)
+
+`;
+      for (const r of nonDatastoreResources) {
+        md += `- ${r.name || "(unnamed)"}${r.format ? ` (${r.format})` : ""}
+`;
+      }
+      md += "\n";
+    }
+    if (datastoreResources.length === 0 && nonDatastoreResources.length === 0) {
+      md += `_No resources available._
+
+`;
+    }
+  }
+  return md;
+}
+function registerAnalyzeTools(server2) {
+  server2.registerTool(
+    "ckan_analyze_datasets",
+    {
+      title: "Analyze CKAN Datasets and DataStore Schema",
+      description: `Search datasets and inspect the DataStore schema of queryable resources.
+
+For each dataset found, lists all resources. For DataStore-enabled resources, fetches the full
+field schema (name, type, and label/notes when available) plus total record count \u2014 all in one call.
+
+Use this before ckan_datastore_search to understand what fields are available and what data to expect.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - q (string): Solr search query (e.g. "incidenti", "title:ambiente")
+  - rows (number): Max datasets to analyze (default 5, max 20)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  For each dataset: title, ID, organization, and per DataStore resource: field schema with
+  label/notes (when available from DataStore Dictionary) and record count.
+
+Typical workflow: ckan_analyze_datasets \u2192 ckan_datastore_search (with known field names)`,
+      inputSchema: z9.object({
+        server_url: z9.string().url().describe("Base URL of the CKAN server (e.g., https://dati.comune.messina.it)"),
+        q: z9.string().min(1).describe("Solr search query (e.g. 'incidenti', 'title:ambiente')"),
+        rows: z9.number().int().min(1).max(20).optional().default(5).describe("Max datasets to analyze (default 5, max 20)"),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const searchResult = await makeCkanRequest(
+          params.server_url,
+          "package_search",
+          { q: params.q, rows: params.rows }
+        );
+        const datasets = searchResult.results || [];
+        const analyzed = await Promise.all(datasets.map(async (dataset) => {
+          const resources = dataset.resources || [];
+          const datastoreResources = [];
+          const nonDatastoreResources = [];
+          for (const resource of resources) {
+            if (resource.datastore_active === true) {
+              try {
+                const schema = await makeCkanRequest(
+                  params.server_url,
+                  "datastore_search",
+                  { resource_id: resource.id, limit: 0 }
+                );
+                datastoreResources.push({
+                  resource: { id: resource.id, name: resource.name, format: resource.format },
+                  schema
+                });
+              } catch (err) {
+                datastoreResources.push({
+                  resource: { id: resource.id, name: resource.name, format: resource.format },
+                  schema: null,
+                  error: err instanceof Error ? err.message : String(err)
+                });
+              }
+            } else {
+              nonDatastoreResources.push({ name: resource.name, format: resource.format });
+            }
+          }
+          return { dataset, datastoreResources, nonDatastoreResources };
+        }));
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify({ total: searchResult.count, datasets: analyzed }, null, 2)) }]
+          };
+        }
+        const markdown = formatAnalyzeDatasetsMarkdown(
+          params.server_url,
+          params.q,
+          searchResult.count,
+          analyzed
+        );
+        return {
+          content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error analyzing datasets: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+function formatCatalogStatsMarkdown(serverUrl, total, facets) {
+  const LABELS = {
+    groups: "Categories",
+    res_format: "Formats",
+    organization: "Organizations"
+  };
+  let md = `# CKAN Portal Statistics
+
+`;
+  md += `**Server**: ${serverUrl}
+`;
+  md += `**Total datasets**: ${total}
+`;
+  for (const [field, label] of Object.entries(LABELS)) {
+    const values = facets[field];
+    if (!values || Object.keys(values).length === 0) continue;
+    const sorted = Object.entries(values).sort((a, b) => b[1] - a[1]);
+    md += `
+## ${label}
+
+`;
+    for (const [name, count] of sorted) {
+      md += `- **${name}**: ${count}
+`;
+    }
+  }
+  return md;
+}
+function registerCatalogStatsTools(server2) {
+  server2.registerTool(
+    "ckan_catalog_stats",
+    {
+      title: "Get CKAN Portal Statistics",
+      description: `Get a statistical overview of a CKAN portal: total dataset count and breakdown by category, format, and organization.
+
+Single CKAN call (package_search with rows=0 and facets). No query needed.
+
+Args:
+  - server_url (string): Base URL of the CKAN server
+  - facet_limit (number): Max entries per facet section (default 20)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Total dataset count, categories ranked by count, file formats ranked by count, organizations ranked by count.
+
+Typical workflow: ckan_catalog_stats (understand the portal) \u2192 ckan_package_search (query specific data)`,
+      inputSchema: z9.object({
+        server_url: z9.string().url().describe("Base URL of the CKAN server (e.g., https://dati.comune.messina.it)"),
+        facet_limit: z9.number().int().min(1).max(100).optional().default(20).describe("Max entries per facet section (default 20)"),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const result = await makeCkanRequest(
+          params.server_url,
+          "package_search",
+          {
+            q: "*:*",
+            rows: 0,
+            "facet.field": JSON.stringify(["groups", "res_format", "organization"]),
+            "facet.limit": params.facet_limit
+          }
+        );
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify({ total: result.count, facets: result.facets }, null, 2)) }]
+          };
+        }
+        const markdown = formatCatalogStatsMarkdown(params.server_url, result.count, result.facets);
+        return {
+          content: [{ type: "text", text: truncateText(addDemoFooter(markdown)) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error retrieving catalog stats: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/resources/dataset.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -3734,7 +4032,7 @@ function registerAllResources(server2) {
 }
 
 // src/prompts/theme.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/prompts/types.ts
 var createTextPrompt = (text) => ({
@@ -3795,9 +4093,9 @@ var registerThemePrompt = (server2) => {
       title: "Search datasets by theme",
       description: "Guided prompt to discover a theme and search datasets under it.",
       argsSchema: {
-        server_url: z9.string().url().describe("Base URL of the CKAN server"),
-        theme: z9.string().min(1).describe("Theme or group name to search"),
-        rows: z9.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z10.string().url().describe("Base URL of the CKAN server"),
+        theme: z10.string().min(1).describe("Theme or group name to search"),
+        rows: z10.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
@@ -3805,7 +4103,7 @@ var registerThemePrompt = (server2) => {
 };
 
 // src/prompts/organization.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var ORGANIZATION_PROMPT_NAME = "ckan-search-by-organization";
 var buildOrganizationPromptText = (serverUrl, organization, rows) => `# Guided search: datasets by organization
 
@@ -3840,9 +4138,9 @@ var registerOrganizationPrompt = (server2) => {
       title: "Search datasets by organization",
       description: "Guided prompt to find a publisher and list its datasets.",
       argsSchema: {
-        server_url: z10.string().url().describe("Base URL of the CKAN server"),
-        organization: z10.string().min(1).describe("Organization name or keyword"),
-        rows: z10.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z11.string().url().describe("Base URL of the CKAN server"),
+        organization: z11.string().min(1).describe("Organization name or keyword"),
+        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
@@ -3850,7 +4148,7 @@ var registerOrganizationPrompt = (server2) => {
 };
 
 // src/prompts/format.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var FORMAT_PROMPT_NAME = "ckan-search-by-format";
 var buildFormatPromptText = (serverUrl, format, rows) => `# Guided search: datasets by resource format
 
@@ -3874,9 +4172,9 @@ var registerFormatPrompt = (server2) => {
       title: "Search datasets by resource format",
       description: "Guided prompt to find datasets with a given resource format.",
       argsSchema: {
-        server_url: z11.string().url().describe("Base URL of the CKAN server"),
-        format: z11.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
-        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z12.string().url().describe("Base URL of the CKAN server"),
+        format: z12.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
+        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
@@ -3884,7 +4182,7 @@ var registerFormatPrompt = (server2) => {
 };
 
 // src/prompts/recent.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var RECENT_PROMPT_NAME = "ckan-recent-datasets";
 var buildRecentPromptText = (serverUrl, rows) => `# Guided search: recent datasets
 
@@ -3932,8 +4230,8 @@ var registerRecentPrompt = (server2) => {
       title: "Find recently updated datasets",
       description: "Guided prompt to list recently updated datasets on a CKAN portal.",
       argsSchema: {
-        server_url: z12.string().url().describe("Base URL of the CKAN server"),
-        rows: z12.coerce.number().int().positive().default(10).describe("Max results to return")
+        server_url: z13.string().url().describe("Base URL of the CKAN server"),
+        rows: z13.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
@@ -3941,7 +4239,7 @@ var registerRecentPrompt = (server2) => {
 };
 
 // src/prompts/dataset-analysis.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var DATASET_ANALYSIS_PROMPT_NAME = "ckan-analyze-dataset";
 var buildDatasetAnalysisPromptText = (serverUrl, id) => `# Guided analysis: dataset
 
@@ -3983,8 +4281,8 @@ var registerDatasetAnalysisPrompt = (server2) => {
       title: "Analyze a dataset",
       description: "Guided prompt to inspect dataset metadata and explore DataStore tables.",
       argsSchema: {
-        server_url: z13.string().url().describe("Base URL of the CKAN server"),
-        id: z13.string().min(1).describe("Dataset id or name (CKAN package id)")
+        server_url: z14.string().url().describe("Base URL of the CKAN server"),
+        id: z14.string().min(1).describe("Dataset id or name (CKAN package id)")
       }
     },
     async ({ server_url, id }) => createTextPrompt(buildDatasetAnalysisPromptText(server_url, id))
@@ -4004,7 +4302,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.50"
+    version: "0.4.53"
   });
 }
 function registerAll(server2) {
@@ -4015,6 +4313,8 @@ function registerAll(server2) {
   registerTagTools(server2);
   registerGroupTools(server2);
   registerQualityTools(server2);
+  registerAnalyzeTools(server2);
+  registerCatalogStatsTools(server2);
   registerAllResources(server2);
   registerAllPrompts(server2);
 }
@@ -4038,6 +4338,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);
   });