@aborruso/ckan-mcp-server 0.4.1 → 0.4.3

package/LOG.md

@@ -2,6 +2,15 @@
 
 ## 2026-01-10
 
+### Version 0.4.3 - Tags and Groups
+- **Tags**: Added `ckan_tag_list` with faceting and filtering
+- **Groups**: Added `ckan_group_list`, `ckan_group_show`, `ckan_group_search`
+- **Docs**: Updated README with examples and tool list
+- **Tests**: Added tag/group fixtures and tests
+
+### Version 0.4.2 - Packaging
+- **npm package**: Added `.npmignore` to exclude dev artifacts
+
 ### Version 0.4.1 - Maintenance
 - **Date formatting**: ISO `YYYY-MM-DD` output, tests aligned
 - **HTTP transport**: Single shared transport per process

package/README.md

@@ -1,5 +1,7 @@
 # CKAN MCP Server
 
+[![npm version](https://img.shields.io/npm/v/@aborruso/ckan-mcp-server)](https://www.npmjs.com/package/@aborruso/ckan-mcp-server)
+
 MCP (Model Context Protocol) server for interacting with CKAN-based open data portals.
 
 ## Features
@@ -12,14 +14,14 @@ MCP (Model Context Protocol) server for interacting with CKAN-based open data po
 - 🎨 Output in Markdown or JSON format
 - ⚡ Pagination and faceting support
 - 📄 MCP Resource Templates for direct data access
-- 🧪 Comprehensive test suite (113 tests, 100% passing)
+- 🧪 Comprehensive test suite (120 tests, 100% passing)
 
 ## Installation
 
 ### From npm (recommended)
 
 ```bash
-npm install ckan-mcp-server
+npm install -g @aborruso/ckan-mcp-server
 ```
 
 ### From source
@@ -34,7 +36,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (113 tests)
+# Run tests (120 tests)
 npm test
 ```
 
@@ -76,38 +78,19 @@ TRANSPORT=http PORT=3000 npm start
 
 **Best for**: Global access, zero infrastructure, free hosting
 
-Deploy to Cloudflare's edge network for worldwide low-latency access.
-
-**Prerequisites**:
-- Cloudflare account (free): https://dash.cloudflare.com/sign-up
-- Wrangler CLI: `npm install -g wrangler`
-
-**Quick Deploy**:
-
-```bash
-# Clone repository
-git clone https://github.com/aborruso/ckan-mcp-server.git
-cd ckan-mcp-server
-
-# Install dependencies
-npm install
-
-# Authenticate with Cloudflare
-wrangler login
+Use the public Workers endpoint (no local install required):
 
-# Deploy to Workers
-npm run deploy
+```json
+{
+  "mcpServers": {
+    "ckan": {
+      "url": "https://ckan-mcp-server.andy-pr.workers.dev/mcp"
+    }
+  }
+}
 ```
 
-Your server will be live at: `https://ckan-mcp-server.<your-account>.workers.dev`
-
-**Free tier includes**:
-- 100,000 requests/day
-- Global edge deployment
-- Automatic HTTPS
-- No cold starts
-
-For detailed deployment instructions, see [DEPLOYMENT.md](docs/DEPLOYMENT.md).
+Want your own deployment? See [DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
 ## Claude Desktop Configuration
 
@@ -137,22 +120,16 @@ Then add to `claude_desktop_config.json`:
 }
 ```
 
-### Option 2: Local Installation
-
-Install in a specific project:
-
-```bash
-npm install @aborruso/ckan-mcp-server
-```
+### Option 2: Local Installation (Optional)
 
-Then add to `claude_desktop_config.json`:
+If you installed locally (see Installation), use this config:
 
 ```json
 {
   "mcpServers": {
     "ckan": {
       "command": "node",
-      "args": ["/absolute/path/to/project/node_modules/@aborruso/ckan-mcp-server/dist/index.js"]
+      "args": ["/absolute/path/to/project/node_modules/@username/ckan-mcp-server/dist/index.js"]
     }
   }
 }
@@ -198,6 +175,7 @@ Use the public Cloudflare Workers deployment (no local installation required):
 - **ckan_package_search**: Search datasets with Solr queries
 - **ckan_package_show**: Complete details of a dataset
 - **ckan_package_list**: List all datasets
+- **ckan_tag_list**: List tags with counts
 
 ### Organizations
 
@@ -209,6 +187,12 @@ Use the public Cloudflare Workers deployment (no local installation required):
 - **ckan_datastore_search**: Query tabular data
 - **ckan_datastore_search_sql**: SQL queries (in development)
 
+### Groups
+
+- **ckan_group_list**: List groups
+- **ckan_group_show**: Show group details
+- **ckan_group_search**: Search groups by name
+
 ### Utilities
 
 - **ckan_status_show**: Verify server status
@@ -274,6 +258,25 @@ ckan_package_search({
 })
 ```
 
+### List tags (natural language: "show top tags about health")
+
+```typescript
+ckan_tag_list({
+  server_url: "https://www.dati.gov.it/opendata",
+  tag_query: "salute",
+  limit: 25
+})
+```
+
+### Search groups (natural language: "find groups about environment")
+
+```typescript
+ckan_group_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  pattern: "ambiente"
+})
+```
+
 ### DataStore Query
 
 ```typescript

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.1"
+    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);
 }