@aborruso/ckan-mcp-server 0.4.2 → 0.4.4

package/dist/index.js

@@ -1059,6 +1059,501 @@ ${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;
+  if (Array.isArray(searchItems)) {
+    return searchItems.map((item) => ({
+      name: item?.name || item?.display_name || String(item),
+      count: typeof item?.count === "number" ? item.count : 0,
+      display_name: item?.display_name
+    }));
+  }
+  const facets = result?.facets?.tags;
+  if (Array.isArray(facets)) {
+    if (facets.length > 0 && typeof facets[0] === "object") {
+      return facets.map((item) => ({
+        name: item?.name || item?.display_name || String(item),
+        count: typeof item?.count === "number" ? item.count : 0,
+        display_name: item?.display_name
+      }));
+    }
+    return facets.map((name) => ({ name, count: 0 }));
+  }
+  if (facets && typeof facets === "object") {
+    return Object.entries(facets).map(([name, count]) => ({
+      name,
+      count: typeof count === "number" ? count : Number(count) || 0
+    }));
+  }
+  return [];
+}
+function registerTagTools(server2) {
+  server2.registerTool(
+    "ckan_tag_list",
+    {
+      title: "List CKAN Tags",
+      description: `List tags from a CKAN server using faceting.
+
+This returns tag names with counts, optionally filtered by dataset query or tag substring.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - q (string): Dataset search query (default: "*:*")
+  - fq (string): Filter query (optional)
+  - tag_query (string): Filter tags by substring (optional)
+  - limit (number): Max tags to return (default: 100, max: 1000)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  List of tags with counts (from faceting)`,
+      inputSchema: z6.object({
+        server_url: z6.string().url(),
+        q: z6.string().optional().default("*:*"),
+        fq: z6.string().optional(),
+        tag_query: z6.string().optional(),
+        limit: z6.number().int().min(1).max(1e3).optional().default(100),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const apiParams = {
+          q: params.q,
+          rows: 0,
+          "facet.field": JSON.stringify(["tags"]),
+          "facet.limit": params.limit
+        };
+        if (params.fq) apiParams.fq = params.fq;
+        const result = await makeCkanRequest(
+          params.server_url,
+          "package_search",
+          apiParams
+        );
+        let tags = normalizeTagFacets(result);
+        if (params.tag_query) {
+          const needle = params.tag_query.toLowerCase();
+          tags = tags.filter((tag) => tag.name.toLowerCase().includes(needle));
+        }
+        tags = tags.sort((a, b) => b.count - a.count || a.name.localeCompare(b.name)).slice(0, params.limit);
+        if (params.response_format === "json" /* JSON */) {
+          const output = {
+            count: tags.length,
+            tags
+          };
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(output, null, 2)) }],
+            structuredContent: output
+          };
+        }
+        let markdown = `# CKAN Tags
+
+`;
+        markdown += `**Server**: ${params.server_url}
+`;
+        markdown += `**Query**: ${params.q}
+`;
+        if (params.fq) markdown += `**Filter**: ${params.fq}
+`;
+        if (params.tag_query) markdown += `**Tag Query**: ${params.tag_query}
+`;
+        markdown += `**Count**: ${tags.length}
+
+`;
+        if (tags.length === 0) {
+          markdown += `No tags found.
+`;
+        } else {
+          for (const tag of tags) {
+            markdown += `- **${tag.name}**: ${tag.count}
+`;
+          }
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error listing tags: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// src/tools/group.ts
+import { z as z7 } from "zod";
+function getGroupViewUrl(serverUrl, group) {
+  const cleanServerUrl = serverUrl.replace(/\/$/, "");
+  return `${cleanServerUrl}/group/${group.name}`;
+}
+function normalizeGroupFacets(result) {
+  const items = result?.search_facets?.groups?.items;
+  if (Array.isArray(items)) {
+    return items.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;
+  if (Array.isArray(facets)) {
+    if (facets.length > 0 && typeof facets[0] === "object") {
+      return facets.map((item) => ({
+        name: item?.name || item?.display_name || String(item),
+        display_name: item?.display_name,
+        count: typeof item?.count === "number" ? item.count : 0
+      }));
+    }
+    return facets.map((name) => ({ name, count: 0 }));
+  }
+  if (facets && typeof facets === "object") {
+    return Object.entries(facets).map(([name, count]) => ({
+      name,
+      count: typeof count === "number" ? count : Number(count) || 0
+    }));
+  }
+  return [];
+}
+function registerGroupTools(server2) {
+  server2.registerTool(
+    "ckan_group_list",
+    {
+      title: "List CKAN Groups",
+      description: `List all groups on a CKAN server.
+
+Groups are thematic collections of datasets.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - all_fields (boolean): Return full objects vs just names (default: false)
+  - sort (string): Sort field (default: "name asc")
+  - limit (number): Maximum results (default: 100). Use 0 to get only the count via faceting
+  - offset (number): Pagination offset (default: 0)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  List of groups with metadata. When limit=0, returns only the count of groups with datasets.`,
+      inputSchema: z7.object({
+        server_url: z7.string().url(),
+        all_fields: z7.boolean().optional().default(false),
+        sort: z7.string().optional().default("name asc"),
+        limit: z7.number().int().min(0).optional().default(100),
+        offset: z7.number().int().min(0).optional().default(0),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        if (params.limit === 0) {
+          const searchResult = await makeCkanRequest(
+            params.server_url,
+            "package_search",
+            {
+              rows: 0,
+              "facet.field": JSON.stringify(["groups"]),
+              "facet.limit": -1
+            }
+          );
+          const groupCount = searchResult.search_facets?.groups?.items?.length || 0;
+          if (params.response_format === "json" /* JSON */) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ count: groupCount }, null, 2) }],
+              structuredContent: { count: groupCount }
+            };
+          }
+          const markdown2 = `# CKAN Groups Count
+
+**Server**: ${params.server_url}
+**Total groups (with datasets)**: ${groupCount}
+`;
+          return {
+            content: [{ type: "text", text: markdown2 }]
+          };
+        }
+        const result = await makeCkanRequest(
+          params.server_url,
+          "group_list",
+          {
+            all_fields: params.all_fields,
+            sort: params.sort,
+            limit: params.limit,
+            offset: params.offset
+          }
+        );
+        if (params.response_format === "json" /* JSON */) {
+          const output = Array.isArray(result) ? { count: result.length, groups: result } : result;
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(output, null, 2)) }],
+            structuredContent: output
+          };
+        }
+        let markdown = `# CKAN Groups
+
+`;
+        markdown += `**Server**: ${params.server_url}
+`;
+        markdown += `**Total**: ${Array.isArray(result) ? result.length : "Unknown"}
+
+`;
+        if (Array.isArray(result)) {
+          if (params.all_fields) {
+            for (const group of result) {
+              markdown += `## ${group.title || group.name}
+
+`;
+              markdown += `- **ID**: \`${group.id}\`
+`;
+              markdown += `- **Name**: \`${group.name}\`
+`;
+              if (group.description) markdown += `- **Description**: ${group.description.substring(0, 200)}
+`;
+              markdown += `- **Datasets**: ${group.package_count || 0}
+`;
+              markdown += `- **Created**: ${formatDate(group.created)}
+`;
+              markdown += `- **Link**: ${getGroupViewUrl(params.server_url, group)}
+
+`;
+            }
+          } else {
+            markdown += result.map((name) => `- ${name}`).join("\n");
+          }
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error listing groups: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.registerTool(
+    "ckan_group_show",
+    {
+      title: "Show CKAN Group Details",
+      description: `Get details of a specific group.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - id (string): Group ID or name
+  - include_datasets (boolean): Include list of datasets (default: true)
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  Group details with optional datasets`,
+      inputSchema: z7.object({
+        server_url: z7.string().url(),
+        id: z7.string().min(1),
+        include_datasets: z7.boolean().optional().default(true),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async (params) => {
+      try {
+        const result = await makeCkanRequest(
+          params.server_url,
+          "group_show",
+          {
+            id: params.id,
+            include_datasets: params.include_datasets
+          }
+        );
+        if (params.response_format === "json" /* JSON */) {
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(result, null, 2)) }],
+            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";
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error fetching group: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+  server2.registerTool(
+    "ckan_group_search",
+    {
+      title: "Search CKAN Groups by Name",
+      description: `Search for groups by name pattern.
+
+This tool provides a simpler interface than package_search for finding groups.
+Wildcards are automatically added around the search pattern.
+
+Args:
+  - server_url (string): Base URL of CKAN server
+  - pattern (string): Search pattern (e.g., "energia", "salute")
+  - response_format ('markdown' | 'json'): Output format
+
+Returns:
+  List of matching groups with dataset counts`,
+      inputSchema: z7.object({
+        server_url: z7.string().url(),
+        pattern: z7.string().min(1).describe("Search pattern (wildcards added automatically)"),
+        response_format: ResponseFormatSchema
+      }).strict(),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async (params) => {
+      try {
+        const query = `groups:*${params.pattern}*`;
+        const result = await makeCkanRequest(
+          params.server_url,
+          "package_search",
+          {
+            q: query,
+            rows: 0,
+            "facet.field": JSON.stringify(["groups"]),
+            "facet.limit": 500
+          }
+        );
+        const groupFacets = normalizeGroupFacets(result);
+        const totalDatasets = result.count || 0;
+        if (params.response_format === "json" /* JSON */) {
+          const jsonResult = {
+            count: groupFacets.length,
+            total_datasets: totalDatasets,
+            groups: groupFacets.map((group) => ({
+              name: group.name,
+              display_name: group.display_name,
+              dataset_count: group.count
+            }))
+          };
+          return {
+            content: [{ type: "text", text: truncateText(JSON.stringify(jsonResult, null, 2)) }],
+            structuredContent: jsonResult
+          };
+        }
+        let markdown = `# CKAN Group Search Results
+
+`;
+        markdown += `**Server**: ${params.server_url}
+`;
+        markdown += `**Pattern**: "${params.pattern}"
+`;
+        markdown += `**Groups Found**: ${groupFacets.length}
+`;
+        markdown += `**Total Datasets**: ${totalDatasets}
+
+`;
+        if (groupFacets.length === 0) {
+          markdown += `No groups found matching pattern "${params.pattern}".
+`;
+        } else {
+          markdown += `## Matching Groups
+
+`;
+          markdown += `| Group | Datasets |
+`;
+          markdown += `|-------|----------|
+`;
+          for (const group of groupFacets) {
+            markdown += `| ${group.display_name || group.name} | ${group.count} |
+`;
+          }
+        }
+        return {
+          content: [{ type: "text", text: truncateText(markdown) }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error searching groups: ${error instanceof Error ? error.message : String(error)}`
+          }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // src/resources/dataset.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -1232,7 +1727,7 @@ function registerAllResources(server2) {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.2"
+    version: "0.4.3"
   });
 }
 function registerAll(server2) {
@@ -1240,6 +1735,8 @@ function registerAll(server2) {
   registerOrganizationTools(server2);
   registerDatastoreTools(server2);
   registerStatusTools(server2);
+  registerTagTools(server2);
+  registerGroupTools(server2);
   registerAllResources(server2);
 }