@aborruso/ckan-mcp-server 0.4.10 → 0.4.13

package/LOG.md

@@ -1,7 +1,64 @@
 # LOG
 
+## 2026-01-19
+
+### Search Parser Escaping
+- **Fix**: Escape Solr special characters when forcing `text:(...)` queries
+- **Tests**: Added unit coverage for escaping and forced parser output
+- **Files**: `src/utils/search.ts`, `tests/unit/search.test.ts`, `README.md`
+
+## 2026-01-17
+
+### Documentation Alignment
+- **Test counts updated**: README.md (184→190), PRD.md (130→190)
+- **Version updated**: PRD.md version 0.4.7→0.4.12
+- **Date updated**: PRD.md last updated 2026-01-10→2026-01-17
+- **Verification**: All 13 tools, 7 resources, 5 prompts implemented and documented
+- **Files**: `README.md`, `PRD.md`
+
+### GitHub Templates
+- **Issue templates**: Added bug report and feature request YAML forms
+  - Bug report: CKAN portal URL, steps, expected/actual, error, Node version
+  - Feature request: problem/use case, proposed solution, alternatives
+  - Auto-labels: `bug` and `enhancement`
+- **Issue chooser**: Routes questions to Discussions Q&A
+- **PR template**: Description, related issue, test/docs checklist
+- **Files**: `.github/ISSUE_TEMPLATE/{bug_report,feature_request,config}.yml`, `.github/PULL_REQUEST_TEMPLATE.md`
+
+## 2026-01-16
+
+### Demo Video Preparation
+- **Documentation**: Created complete demo video documentation suite in `docs/video/`
+  - `demo-script.md` - Commands and technical notes for 4 use cases
+  - `demo-expected-results.md` - Actual test results with data samples
+  - `demo-recording-guide.md` - Step-by-step recording guide with voiceover scripts
+  - `pre-recording-checklist.md` - Practical day-of checklist
+  - `demo-fallback-options.md` - Comprehensive fallback strategies for 8 scenarios
+  - `demo-timing-report.md` - Performance analysis and timing verification
+- **Testing**: Verified all demo commands working with dati.gov.it
+  - Portal overview: 67,614 datasets, top 10 organizations (~5s)
+  - Targeted search: 263 Milano transport datasets (~10s)
+  - Dataset details: Complete metadata with CSV/JSON resources (~10s)
+  - DuckDB analysis: DESCRIBE, SUMMARIZE, SAMPLE all working (~8s total)
+- **Target**: 5-7 minute video demonstrating MCP convenience for Italian open data
+- **Status**: Ready for recording with high confidence level
+
 ## 2026-01-15
 
+### Version 0.4.12 - Dataset filter resources
+- **Feature**: Added `ckan://{server}/.../datasets` resource templates for group, organization, tag, and format filters
+- **Fix**: Map `ckan://` hostnames to portal API base URLs (e.g., dati.gov.it → /opendata)
+- **Fix**: Format filtering now matches `res_format` and `distribution_format` (with case variants)
+- **Docs**: Updated README and future ideas with new URI templates
+- **Docs**: Updated `docs/proposta-spunti-datos-gob-es-mcp.md` marking resource templates as completed
+- **Tests**: Added unit tests for dataset filter resource templates
+- **Files**: New `src/resources/dataset-filters.ts`, updates in `src/resources/index.ts`, `src/worker.ts`
+
+### Version 0.4.11 - Prompt argument coercion
+- **Fix**: Prompt arguments now coerce numeric strings (e.g., rows) for MCP prompt requests
+- **Docs**: Updated evaluation notes for 0.4.11
+- **No breaking changes**: Prompt names and outputs unchanged
+
 ### Version 0.4.10 - Guided MCP prompts
 - **Feature**: Added 5 guided MCP prompts (theme, organization, format, recent datasets, dataset analysis)
 - **Docs**: README and new `docs/prompts.md` updated with usage examples

package/NOTICE.md

@@ -0,0 +1,77 @@
+# Third-Party Software Notices
+
+This software incorporates material from third parties. The following sets forth attribution notices for third-party software that may be included in this software.
+
+## Production Dependencies
+
+### @modelcontextprotocol/sdk
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2024 Anthropic, PBC
+- **Repository**: https://github.com/modelcontextprotocol/typescript-sdk
+- **Description**: Official TypeScript SDK for the Model Context Protocol (MCP)
+
+### axios
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2014-present Matt Zabriskie & Collaborators
+- **Repository**: https://github.com/axios/axios
+- **Description**: Promise-based HTTP client for the browser and node.js
+
+### express
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2009-2014 TJ Holowaychuk <tj@vision-media.ca>
+- **Copyright**: Copyright (c) 2013-2014 Roman Shtylman <shtylman+expressjs@gmail.com>
+- **Copyright**: Copyright (c) 2014-2015 Douglas Christopher Wilson <doug@somethingdoug.com>
+- **Repository**: https://github.com/expressjs/express
+- **Description**: Fast, unopinionated, minimalist web framework for Node.js
+
+### zod
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2025 Colin McDonnell
+- **Repository**: https://github.com/colinhacks/zod
+- **Description**: TypeScript-first schema validation with static type inference
+
+## Development Dependencies (Build Tools)
+
+### TypeScript
+- **License**: Apache License 2.0
+- **Copyright**: Copyright (c) Microsoft Corporation
+- **Repository**: https://github.com/microsoft/TypeScript
+- **Description**: TypeScript language compiler
+
+### esbuild
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2020 Evan Wallace
+- **Repository**: https://github.com/evanw/esbuild
+- **Description**: An extremely fast JavaScript bundler
+
+### Vitest
+- **License**: MIT License
+- **Copyright**: Copyright (c) 2021-Present Anthony Fu, Matías Capeletto
+- **Repository**: https://github.com/vitest-dev/vitest
+- **Description**: Next generation testing framework
+
+### Wrangler
+- **License**: MIT OR Apache-2.0 (dual license)
+- **Copyright**: Copyright (c) 2017-2022 Cloudflare, Inc.
+- **Repository**: https://github.com/cloudflare/workers-sdk
+- **Description**: Cloudflare Workers CLI and deployment tool
+
+---
+
+## License Information
+
+All production dependencies use permissive open-source licenses (MIT, ISC, BSD) that are fully compatible with this project's MIT License.
+
+Full license texts for all dependencies are available in the respective `node_modules` directories and on their respective repository pages.
+
+## Compliance
+
+This project complies with all license obligations of its dependencies:
+- Attribution notices are preserved
+- Original copyright statements are maintained
+- License files are distributed with the software
+- No modifications have been made to third-party code without proper attribution
+
+---
+
+For questions about licensing, please contact: Andrea Borruso <aborruso@gmail.com>

package/PRD.md

@@ -2,9 +2,9 @@
 
 ## CKAN MCP Server
 
-**Version**: 0.4.7  
-**Last Updated**: 2026-01-10  
-**Author**: onData  
+**Version**: 0.4.12
+**Last Updated**: 2026-01-17
+**Author**: onData
 **Status**: Production
 
 ---
@@ -214,7 +214,7 @@ An MCP server that exposes tools to interact with CKAN API v3, enabling AI agent
 - `wrangler@^4.58.0` - Cloudflare Workers CLI
 
 **Test Framework**:
-- `vitest@^4.0.16` - Test runner (130 tests, 100% passing)
+- `vitest@^4.0.16` - Test runner (190 tests, 100% passing)
 
 ### 4.2 Architecture Diagram
 
@@ -825,7 +825,7 @@ ckan_package_search({
 ### 10.3 Testing & Quality
 
 ✅ **Current State**:
-- 130 unit and integration tests (100% passing)
+- 190 unit and integration tests (100% passing)
 - vitest test runner
 - Coverage for all 13 tools
 - Fixtures for offline testing
@@ -860,7 +860,7 @@ ckan_package_search({
 - **Memory Usage**: < 50MB runtime (Node.js), Workers limits apply
 - **Response Time**: < 30s (CKAN API timeout), < 10s (Workers)
 - **Cold Start**: < 60ms (Cloudflare Workers)
-- **Test Coverage**: 130 tests (100% passing)
+- **Test Coverage**: 190 tests (100% passing)
 
 ### 11.2 Distribution Metrics
 

package/README.md

@@ -1,6 +1,6 @@
 [![npm version](https://img.shields.io/npm/v/@aborruso/ckan-mcp-server)](https://www.npmjs.com/package/@aborruso/ckan-mcp-server)
-[![GitHub](https://img.shields.io/badge/github-aborruso%2Fckan--mcp--server-blue?logo=github)](https://github.com/aborruso/ckan-mcp-server)
-[![deepwiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aborruso/ckan-mcp-server)
+[![GitHub](https://img.shields.io/badge/github-ondata%2Fckan--mcp--server-blue?logo=github)](https://github.com/ondata/ckan-mcp-server)
+[![deepwiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/ondata/ckan-mcp-server)
 
 # CKAN MCP Server
 
@@ -17,11 +17,11 @@ MCP (Model Context Protocol) server for interacting with CKAN-based open data po
 - ⚡ Pagination and faceting support
 - 📄 MCP Resource Templates for direct data access
 - 🧭 Guided MCP prompts for common workflows
-- 🧪 Test suite with 184 tests (100% passing)
+- 🧪 Test suite with 186 tests (100% passing)
 
 ---
 
-👉 If you want to dive deeper, the [**AI-generated DeepWiki**](https://deepwiki.com/aborruso/ckan-mcp-server) is very well done.
+👉 If you want to dive deeper, the [**AI-generated DeepWiki**](https://deepwiki.com/ondata/ckan-mcp-server) is very well done.
 
 ---
 
@@ -45,7 +45,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (184 tests)
+# Run tests (186 tests)
 npm test
 ```
 
@@ -87,6 +87,8 @@ Use the public Workers endpoint (no local install required):
 
 Want your own deployment? See [DEPLOYMENT.md](docs/DEPLOYMENT.md).
 
+## Guides
+
 ### Claude Desktop Configuration
 
 Configuration file location:
@@ -147,6 +149,8 @@ If you cloned the repository:
 }
 ```
 
+[A detailed guide](https://github.com/ondata/ckan-mcp-server/discussions/4#discussion-9359684)
+
 #### Option 4: Cloudflare Workers (HTTP transport)
 
 Use the public Cloudflare Workers deployment (no local installation required):
@@ -165,6 +169,13 @@ Use the public Cloudflare Workers deployment (no local installation required):
 
 **Note**: This uses the public endpoint. You can also deploy your own Workers instance and use that URL instead.
 
+### Web Tools Configuration
+
+- [ChatGPT web](docs/guide/chatgpt/chatgpt_web.md)
+- [Claude web](docs/guide/claude/claude_web.md)
+
+These guides are based on a public demo server, which has a limit of 100,000 calls per month. For reliable usage, it is recommended to install the CKAN MCP Server on your own machine.
+
 ## Available Tools
 
 ### Search and Discovery
@@ -172,13 +183,13 @@ Use the public Cloudflare Workers deployment (no local installation required):
 - **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
 
 ### Organizations
 
 - **ckan_organization_list**: List all organizations
 - **ckan_organization_show**: Details of an organization
+- **ckan_organization_search**: Search organizations by name
 
 ### DataStore
 
@@ -202,6 +213,10 @@ Direct data access via `ckan://` URI scheme:
 - `ckan://{server}/dataset/{id}` - Dataset metadata
 - `ckan://{server}/resource/{id}` - Resource metadata and download URL
 - `ckan://{server}/organization/{name}` - Organization details
+- `ckan://{server}/group/{name}/datasets` - Datasets by group (theme)
+- `ckan://{server}/organization/{name}/datasets` - Datasets by organization
+- `ckan://{server}/tag/{name}/datasets` - Datasets by tag
+- `ckan://{server}/format/{format}/datasets` - Datasets by resource format (res_format + distribution_format)
 
 Examples:
 
@@ -209,6 +224,10 @@ Examples:
 ckan://dati.gov.it/dataset/vaccini-covid
 ckan://demo.ckan.org/resource/abc-123
 ckan://data.gov/organization/sample-org
+ckan://dati.gov.it/group/ambiente/datasets
+ckan://dati.gov.it/organization/regione-toscana/datasets
+ckan://dati.gov.it/tag/turismo/datasets
+ckan://dati.gov.it/format/csv/datasets
 ```
 
 ## Guided Prompts
@@ -256,6 +275,7 @@ ckan_package_search({
   rows: 0
 })
 ```
+Note: when `query_parser: "text"` is used, Solr special characters in the query are escaped automatically.
 
 ### Rank datasets by relevance (natural language: "find most relevant datasets about urban mobility")
 
@@ -354,15 +374,15 @@ Some of the main compatible portals:
 
 ### Portal View URL Templates
 
-Some CKAN portals expose non-standard web URLs for viewing datasets or organizations. To support those cases, this project ships with `src/portals.json`, which maps known portal API URLs (and aliases) to custom view URL templates.
+Some CKAN portals expose non-standard web URLs for viewing datasets or organizations. To support those cases, this project ships with [`src/portals.json`](src/portals.json), which maps known portal API URLs (and aliases) to custom view URL templates.
 
 When generating a dataset or organization view link, the server:
 
-- matches the `server_url` against `api_url` and `api_url_aliases` in `src/portals.json`
+- matches the `server_url` against `api_url` and `api_url_aliases` in [`src/portals.json`](src/portals.json)
 - uses the portal-specific `dataset_view_url` / `organization_view_url` template when available
 - falls back to the generic defaults (`{server_url}/dataset/{name}` and `{server_url}/organization/{name}`)
 
-You can extend `src/portals.json` by adding new entries under `portals` if a portal uses different web URL patterns.
+You can extend [`src/portals.json`](src/portals.json) by adding new entries under `portals` if a portal uses different web URL patterns.
 
 ## Advanced Solr Queries
 
@@ -547,6 +567,8 @@ ckan-mcp-server/
 
 ## Development
 
+This project uses [OpenSpec](https://github.com/Fission-AI/OpenSpec) to manage change proposals and keep specifications aligned with implementation.
+
 ### Testing
 
 The project uses **Vitest** for automated testing:
@@ -640,7 +662,9 @@ Contributions are welcome! Please:
 
 ## License
 
-MIT License - See LICENSE.txt file for complete details.
+MIT License - See [LICENSE.txt](LICENSE.txt) for complete details.
+
+Third-party attributions: See [NOTICE.md](NOTICE.md) for third-party software notices and information.
 
 ## Useful Links
 
@@ -650,10 +674,7 @@ MIT License - See LICENSE.txt file for complete details.
 
 ## Support
 
-For issues or questions:
-
-- Open an issue on GitHub
-- Contact onData: https://www.ondata.it/
+For issues or questions, [open an issue on GitHub](https://github.com/ondata/ckan-mcp-server/issues/new/choose).
 
 ---
 

package/dist/index.js

@@ -110,6 +110,13 @@ var portals_default = {
 function normalizeUrl(url) {
   return url.replace(/\/$/, "");
 }
+function extractHostname(url) {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
 function getPortalConfig(serverUrl) {
   const cleanServerUrl = normalizeUrl(serverUrl);
   const portal = portals_default.portals.find((p) => {
@@ -129,6 +136,13 @@ function getPortalSearchConfig(serverUrl) {
 function normalizePortalUrl(serverUrl) {
   return normalizeUrl(serverUrl);
 }
+function getPortalApiUrlForHostname(hostname) {
+  const portal = portals_default.portals.find((p) => {
+    const urls = [p.api_url, ...p.api_url_aliases || []];
+    return urls.some((url) => extractHostname(url) === hostname);
+  });
+  return portal ? normalizeUrl(portal.api_url) : null;
+}
 
 // src/utils/url-generator.ts
 function getDatasetViewUrl(serverUrl, pkg) {
@@ -147,9 +161,13 @@ function getOrganizationViewUrl(serverUrl, org) {
 // src/utils/search.ts
 var DEFAULT_SEARCH_QUERY = "*:*";
 var FIELD_QUERY_PATTERN = /\b[a-zA-Z_][\w-]*:/;
+var SOLR_SPECIAL_CHARS = /[+\-!(){}[\]^"~*?:\\/|&]/g;
 function isFieldedQuery(query) {
   return FIELD_QUERY_PATTERN.test(query);
 }
+function escapeSolrQuery(query) {
+  return query.replace(SOLR_SPECIAL_CHARS, "\\$&");
+}
 function resolveSearchQuery(serverUrl, query, parserOverride) {
   const portalSearchConfig = getPortalSearchConfig(serverUrl);
   const portalForce = portalSearchConfig.force_text_field ?? false;
@@ -162,7 +180,7 @@ function resolveSearchQuery(serverUrl, query, parserOverride) {
     const trimmedQuery = query.trim();
     forceTextField = trimmedQuery !== DEFAULT_SEARCH_QUERY && !isFieldedQuery(trimmedQuery);
   }
-  const effectiveQuery = forceTextField ? `text:(${query})` : query;
+  const effectiveQuery = forceTextField ? `text:(${escapeSolrQuery(query)})` : query;
   return { effectiveQuery, forcedTextField: forceTextField };
 }
 
@@ -2073,7 +2091,7 @@ function parseCkanUri(uri) {
   if (!type || !id) {
     throw new Error("Invalid ckan:// URI: missing type or id");
   }
-  const server2 = `https://${hostname}`;
+  const server2 = getPortalApiUrlForHostname(hostname) || `https://${hostname}`;
   return { server: server2, type, id };
 }
 
@@ -2215,11 +2233,110 @@ function registerOrganizationResource(server2) {
   );
 }
 
+// src/resources/dataset-filters.ts
+import { ResourceTemplate as ResourceTemplate4 } from "@modelcontextprotocol/sdk/server/mcp.js";
+var escapeSolrTerm = (value) => value.replace(/["\\]/g, "\\$&");
+var buildFormatFilter = (rawFormat) => {
+  const format = rawFormat.trim();
+  const variants = [format];
+  const upper = format.toUpperCase();
+  if (upper !== format) {
+    variants.push(upper);
+  }
+  const fields = ["res_format", "distribution_format"];
+  const clauses = fields.flatMap(
+    (field) => variants.map((value) => `${field}:"${escapeSolrTerm(value)}"`)
+  );
+  return `(${clauses.join(" OR ")})`;
+};
+var registerDatasetFilterResource = (server2, config) => {
+  server2.registerResource(
+    config.name,
+    new ResourceTemplate4(config.template, { list: void 0 }),
+    {
+      title: config.title,
+      description: config.description,
+      mimeType: "application/json"
+    },
+    async (uri, variables) => {
+      try {
+        const { server: serverUrl } = parseCkanUri(uri);
+        const fq = config.buildFq(variables);
+        const result = await makeCkanRequest(serverUrl, "package_search", {
+          q: "*:*",
+          fq
+        });
+        const content = truncateText(JSON.stringify(result, null, 2));
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: content
+            }
+          ]
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "text/plain",
+              text: `Error fetching datasets: ${errorMessage}`
+            }
+          ]
+        };
+      }
+    }
+  );
+};
+function registerGroupDatasetsResource(server2) {
+  registerDatasetFilterResource(server2, {
+    name: "ckan-group-datasets",
+    template: "ckan://{server}/group/{name}/datasets",
+    title: "CKAN Group Datasets",
+    description: "List datasets in a CKAN group (theme). URI format: ckan://{server}/group/{name}/datasets",
+    buildFq: (variables) => `groups:"${escapeSolrTerm(variables.name)}"`
+  });
+}
+function registerOrganizationDatasetsResource(server2) {
+  registerDatasetFilterResource(server2, {
+    name: "ckan-organization-datasets",
+    template: "ckan://{server}/organization/{name}/datasets",
+    title: "CKAN Organization Datasets",
+    description: "List datasets for a CKAN organization. URI format: ckan://{server}/organization/{name}/datasets",
+    buildFq: (variables) => `organization:"${escapeSolrTerm(variables.name)}"`
+  });
+}
+function registerTagDatasetsResource(server2) {
+  registerDatasetFilterResource(server2, {
+    name: "ckan-tag-datasets",
+    template: "ckan://{server}/tag/{name}/datasets",
+    title: "CKAN Tag Datasets",
+    description: "List datasets matching a CKAN tag. URI format: ckan://{server}/tag/{name}/datasets",
+    buildFq: (variables) => `tags:"${escapeSolrTerm(variables.name)}"`
+  });
+}
+function registerFormatDatasetsResource(server2) {
+  registerDatasetFilterResource(server2, {
+    name: "ckan-format-datasets",
+    template: "ckan://{server}/format/{format}/datasets",
+    title: "CKAN Format Datasets",
+    description: "List datasets by resource format. URI format: ckan://{server}/format/{format}/datasets",
+    buildFq: (variables) => buildFormatFilter(variables.format)
+  });
+}
+
 // src/resources/index.ts
 function registerAllResources(server2) {
   registerDatasetResource(server2);
   registerResourceResource(server2);
   registerOrganizationResource(server2);
+  registerGroupDatasetsResource(server2);
+  registerOrganizationDatasetsResource(server2);
+  registerTagDatasetsResource(server2);
+  registerFormatDatasetsResource(server2);
 }
 
 // src/prompts/theme.ts
@@ -2282,7 +2399,7 @@ var registerThemePrompt = (server2) => {
       argsSchema: {
         server_url: z8.string().url().describe("Base URL of the CKAN server"),
         theme: z8.string().min(1).describe("Theme or group name to search"),
-        rows: z8.number().int().positive().default(10).describe("Max results to return")
+        rows: z8.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, theme, rows }) => createTextPrompt(buildThemePromptText(server_url, theme, rows))
@@ -2323,7 +2440,7 @@ var registerOrganizationPrompt = (server2) => {
       argsSchema: {
         server_url: z9.string().url().describe("Base URL of the CKAN server"),
         organization: z9.string().min(1).describe("Organization name or keyword"),
-        rows: z9.number().int().positive().default(10).describe("Max results to return")
+        rows: z9.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, organization, rows }) => createTextPrompt(buildOrganizationPromptText(server_url, organization, rows))
@@ -2354,7 +2471,7 @@ var registerFormatPrompt = (server2) => {
       argsSchema: {
         server_url: z10.string().url().describe("Base URL of the CKAN server"),
         format: z10.string().min(1).describe("Resource format (e.g., CSV, JSON)"),
-        rows: z10.number().int().positive().default(10).describe("Max results to return")
+        rows: z10.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, format, rows }) => createTextPrompt(buildFormatPromptText(server_url, format, rows))
@@ -2391,7 +2508,7 @@ var registerRecentPrompt = (server2) => {
       description: "Guided prompt to list recently updated datasets on a CKAN portal.",
       argsSchema: {
         server_url: z11.string().url().describe("Base URL of the CKAN server"),
-        rows: z11.number().int().positive().default(10).describe("Max results to return")
+        rows: z11.coerce.number().int().positive().default(10).describe("Max results to return")
       }
     },
     async ({ server_url, rows }) => createTextPrompt(buildRecentPromptText(server_url, rows))
@@ -2462,7 +2579,7 @@ var registerAllPrompts = (server2) => {
 function createServer() {
   return new McpServer({
     name: "ckan-mcp-server",
-    version: "0.4.10"
+    version: "0.4.13"
   });
 }
 function registerAll(server2) {