@aborruso/ckan-mcp-server 0.4.0 → 0.4.1

package/CLAUDE.md

@@ -348,7 +348,7 @@ To test with Claude Desktop, add the MCP configuration to the config file.
 ### Known Limitations
 
 - **Output limit**: 50,000 characters hardcoded in `types.ts` (could be configurable)
-- **Date formatting**: Uses 'it-IT' locale in `utils/formatting.ts` (could be parameterized)
+- **Date formatting**: Uses fixed ISO `YYYY-MM-DD` in `utils/formatting.ts` (could be configurable)
 - **Read-only**: All tools are read-only (no data modification on CKAN)
 - **No caching**: Every request makes fresh HTTP call to CKAN APIs
 - **No authentication**: Uses only public CKAN endpoints
@@ -358,7 +358,7 @@ To test with Claude Desktop, add the MCP configuration to the config file.
 
 1. Create new file in `src/tools/`
 2. Export `registerXxxTools(server: McpServer)` function
-3. Import and call in both `src/index.ts` and `src/worker.ts`
+3. Add to `registerAll()` in `src/server.ts`
 4. Add tests in `tests/integration/`
 5. Build and test: `npm run build && npm test`
 

package/EXAMPLES.md

@@ -289,6 +289,56 @@ ckan_package_search({
 
 CKAN uses Apache Solr for search. The `q` parameter supports advanced Solr query syntax including fuzzy matching, proximity search, boosting, and complex boolean logic.
 
+### Understanding Solr Field Types: Exact vs Fuzzy Search
+
+**Important**: CKAN's Solr schema defines two main field types that behave differently in searches:
+
+#### String Fields (type="string")
+- **Behavior**: Exact match, case-sensitive, no normalization
+- **Fields**: `res_format`, `tags`, `organization`, `license`, `license_id`, `state`, `name`
+- **Example**: `res_format:CSV` finds 43,836 results, but `res_format:csv` finds 0 results
+
+```typescript
+// Works - exact match
+ckan_package_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  fq: "res_format:CSV",
+  rows: 10
+})
+// → 43,836 results
+
+// Fails - wrong case
+ckan_package_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  fq: "res_format:csv",
+  rows: 10
+})
+// → 0 results
+```
+
+#### Text Fields (type="text")
+- **Behavior**: Fuzzy search enabled, normalized (accents/punctuation removed), tokenized
+- **Fields**: `title`, `notes`, `author`, `maintainer`, `res_name`, `res_description`
+- **Example**: `title:sanità` also finds "sanita", "sanità", "Sanità" (variations)
+
+```typescript
+// Fuzzy search automatically applied on text fields
+ckan_package_search({
+  server_url: "https://www.dati.gov.it/opendata",
+  q: "title:sanità~2",  // Finds variations with up to 2 character differences
+  rows: 20
+})
+```
+
+#### Accessing the Schema
+
+You can view CKAN's Solr schema to see all field types:
+
+1. **GitHub**: https://github.com/ckan/ckan/blob/master/ckan/config/solr/schema.xml
+2. **Solr API** (if available): `http://your-ckan-server:8983/solr/ckan/schema`
+
+Note: Public CKAN portals (like dati.gov.it) do not expose the Solr endpoint directly for security reasons - only the CKAN API is public.
+
 ### Fuzzy Search
 
 Find terms with similar spelling (edit distance matching). Useful for typos or variations.

package/LOG.md

@@ -2,6 +2,24 @@
 
 ## 2026-01-10
 
+### Version 0.4.1 - Maintenance
+- **Date formatting**: ISO `YYYY-MM-DD` output, tests aligned
+- **HTTP transport**: Single shared transport per process
+- **Registration**: Centralized tool/resource setup via `registerAll()`
+- **Docs**: Updated CLAUDE/PRD/REFACTORING notes
+
+## 2026-01-10
+
+### Documentation Enhancement - Solr Field Types
+- **New section in EXAMPLES.md**: "Understanding Solr Field Types: Exact vs Fuzzy Search"
+  - Documents difference between `type=string` (exact match) and `type=text` (fuzzy)
+  - String fields: res_format, tags, organization, license, state, name (case-sensitive)
+  - Text fields: title, notes, author, maintainer (normalized, fuzzy enabled)
+  - Practical example: `res_format:CSV` (43,836 results) vs `res_format:csv` (0 results)
+  - Links to CKAN Solr schema on GitHub
+  - Explains why some searches are exact and others are fuzzy
+- **Impact**: Users understand when exact matching is required vs when fuzzy search works
+
 ### Version 0.4.0 - Cloudflare Workers Deployment ⭐
 
 - **Production deployment**: Server now live on Cloudflare Workers

package/PRD.md

@@ -662,7 +662,7 @@ ckan_package_search({
    - Non configurabile
 
 7. **Locale**:
-   - Date formattate in 'it-IT'
+   - Date formattate in ISO `YYYY-MM-DD`
    - Non parametrizzato
 
 ### 9.2 External Dependencies

package/REFACTORING.md

@@ -70,7 +70,7 @@ src/
 
 **`utils/formatting.ts`** (Output Formatting)
 - `truncateText()` - Limita output a CHARACTER_LIMIT
-- `formatDate()` - Format date in Italian locale
+- `formatDate()` - Format date in ISO `YYYY-MM-DD`
 - `formatBytes()` - Human-readable file sizes
 
 ### Tools
@@ -98,6 +98,7 @@ src/
 
 **`transport/http.ts`** (HTTP Transport)
 - `runHTTP()` - HTTP server on configurable port
+- Single shared transport per process
 - For remote access via HTTP POST
 
 ## Build Configuration

package/dist/index.js

@@ -2,12 +2,6 @@
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-function createServer() {
-  return new McpServer({
-    name: "ckan-mcp-server",
-    version: "0.1.0"
-  });
-}
 
 // src/tools/package.ts
 import { z as z2 } from "zod";
@@ -71,9 +65,16 @@ function truncateText(text, limit = CHARACTER_LIMIT) {
 }
 function formatDate(dateStr) {
   try {
-    return new Date(dateStr).toLocaleString("it-IT");
+    if (!dateStr) {
+      return "Invalid Date";
+    }
+    const date = new Date(dateStr);
+    if (Number.isNaN(date.getTime())) {
+      return "Invalid Date";
+    }
+    return date.toISOString().slice(0, 10);
   } catch {
-    return dateStr;
+    return "Invalid Date";
   }
 }
 
@@ -1227,6 +1228,21 @@ function registerAllResources(server2) {
   registerOrganizationResource(server2);
 }
 
+// src/server.ts
+function createServer() {
+  return new McpServer({
+    name: "ckan-mcp-server",
+    version: "0.4.1"
+  });
+}
+function registerAll(server2) {
+  registerPackageTools(server2);
+  registerOrganizationTools(server2);
+  registerDatastoreTools(server2);
+  registerStatusTools(server2);
+  registerAllResources(server2);
+}
+
 // src/transport/stdio.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 async function runStdio(server2) {
@@ -1241,13 +1257,12 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 async function runHTTP(server2) {
   const app = express();
   app.use(express.json());
+  const transport2 = new StreamableHTTPServerTransport({
+    sessionIdGenerator: void 0,
+    enableJsonResponse: true
+  });
+  await server2.connect(transport2);
   app.post("/mcp", async (req, res) => {
-    const transport2 = new StreamableHTTPServerTransport({
-      sessionIdGenerator: void 0,
-      enableJsonResponse: true
-    });
-    res.on("close", () => transport2.close());
-    await server2.connect(transport2);
     await transport2.handleRequest(req, res, req.body);
   });
   const port = parseInt(process.env.PORT || "3000");
@@ -1258,11 +1273,7 @@ async function runHTTP(server2) {
 
 // src/index.ts
 var server = createServer();
-registerPackageTools(server);
-registerOrganizationTools(server);
-registerDatastoreTools(server);
-registerStatusTools(server);
-registerAllResources(server);
+registerAll(server);
 var transport = process.env.TRANSPORT || "stdio";
 if (transport === "http") {
   runHTTP(server).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aborruso/ckan-mcp-server",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP server for interacting with CKAN open data portals",
   "main": "dist/index.js",
   "type": "module",