@aborruso/ckan-mcp-server 0.3.1

package/.claude/commands/openspec/apply.md

@@ -0,0 +1,23 @@
+---
+name: OpenSpec: Apply
+description: Implement an approved OpenSpec change and keep tasks in sync.
+category: OpenSpec
+tags: [openspec, apply]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

package/.claude/commands/openspec/archive.md

@@ -0,0 +1,27 @@
+---
+name: OpenSpec: Archive
+description: Archive a deployed OpenSpec change and update specs.
+category: OpenSpec
+tags: [openspec, archive]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

package/.claude/commands/openspec/proposal.md

@@ -0,0 +1,28 @@
+---
+name: OpenSpec: Proposal
+description: Scaffold a new OpenSpec change and validate strictly.
+category: OpenSpec
+tags: [openspec, change]
+---
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

package/.claude/settings.local.json

@@ -0,0 +1,31 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node --version:*)",
+      "Bash(npm --version:*)",
+      "Bash(npm run build:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npm install:*)",
+      "Bash(npx esbuild:*)",
+      "Bash(curl:*)",
+      "WebSearch",
+      "mcp__ckan-mcp__ckan_package_search",
+      "mcp__ckan-mcp__ckan_package_show",
+      "Bash(cat:*)",
+      "mcp__ckan-mcp__ckan_status_show",
+      "WebFetch(domain:docs.ckan.org)",
+      "mcp__ckan-mcp__ckan_organization_list",
+      "mcp__ckan-mcp__ckan_organization_search",
+      "Bash(npm test:*)",
+      "Bash(wc:*)",
+      "Bash(mkdir:*)",
+      "WebFetch(domain:skywork.ai)",
+      "Bash(grep:*)",
+      "Bash(find:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "ckan-mcp"
+  ]
+}

package/.gemini/commands/openspec/apply.toml

@@ -0,0 +1,21 @@
+description = "Implement an approved OpenSpec change and keep tasks in sync."
+
+prompt = """
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->
+"""

package/.gemini/commands/openspec/archive.toml

@@ -0,0 +1,25 @@
+description = "Archive a deployed OpenSpec change and update specs."
+
+prompt = """
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->
+"""

package/.gemini/commands/openspec/proposal.toml

@@ -0,0 +1,26 @@
+description = "Scaffold a new OpenSpec change and validate strictly."
+
+prompt = """
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->
+"""

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "ckan-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "/home/aborruso/git/idee/ckan-mcp-server/dist/index.js"
+      ],
+      "env": {}
+    }
+  }
+}

package/.opencode/command/openspec-apply.md

@@ -0,0 +1,24 @@
+---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+The user has requested to implement the following change proposal. Find the change proposal and follow the instructions below. If you're not sure or if ambiguous, ask for clarification from the user.
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+1. Read `changes/<id>/proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
+3. Confirm completion before updating statuses—make sure every item in `tasks.md` is finished.
+4. Update the checklist after all work is done so each task is marked `- [x]` and reflects reality.
+5. Reference `openspec list` or `openspec show <item>` when additional context is required.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` if you need additional context from the proposal while implementing.
+<!-- OPENSPEC:END -->

package/.opencode/command/openspec-archive.md

@@ -0,0 +1,27 @@
+---
+description: Archive a deployed OpenSpec change and update specs.
+---
+<ChangeId>
+  $ARGUMENTS
+</ChangeId>
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+
+**Steps**
+1. Determine the change ID to archive:
+   - If this prompt already includes a specific change ID (for example inside a `<ChangeId>` block populated by slash-command arguments), use that value after trimming whitespace.
+   - If the conversation references a change loosely (for example by title or summary), run `openspec list` to surface likely IDs, share the relevant candidates, and confirm which one the user intends.
+   - Otherwise, review the conversation, run `openspec list`, and ask the user which change to archive; wait for a confirmed change ID before proceeding.
+   - If you still cannot identify a single change ID, stop and tell the user you cannot archive anything yet.
+2. Validate the change ID by running `openspec list` (or `openspec show <id>`) and stop if the change is missing, already archived, or otherwise not ready to archive.
+3. Run `openspec archive <id> --yes` so the CLI moves the change and applies spec updates without prompts (use `--skip-specs` only for tooling-only work).
+4. Review the command output to confirm the target specs were updated and the change landed in `changes/archive/`.
+5. Validate with `openspec validate --strict` and inspect with `openspec show <id>` if anything looks off.
+
+**Reference**
+- Use `openspec list` to confirm change IDs before archiving.
+- Inspect refreshed specs with `openspec list --specs` and address any validation issues before handing off.
+<!-- OPENSPEC:END -->

package/.opencode/command/openspec-proposal.md

@@ -0,0 +1,29 @@
+---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>
+<!-- OPENSPEC:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Refer to `openspec/AGENTS.md` (located inside the `openspec/` directory—run `ls openspec` or `openspec update` if you don't see it) if you need additional OpenSpec conventions or clarifications.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.
+
+**Steps**
+1. Review `openspec/project.md`, run `openspec list` and `openspec list --specs`, and inspect related code or docs (e.g., via `rg`/`ls`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, and `design.md` (when needed) under `openspec/changes/<id>/`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in `design.md` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in `changes/<id>/specs/<capability>/spec.md` (one folder per capability) using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement and cross-reference related capabilities when relevant.
+6. Draft `tasks.md` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with `openspec validate <id> --strict` and resolve every issue before sharing the proposal.
+
+**Reference**
+- Use `openspec show <id> --json --deltas-only` or `openspec show <spec> --type spec` to inspect details when validation fails.
+- Search existing requirements with `rg -n "Requirement:|Scenario:" openspec/specs` before writing new ones.
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities.
+<!-- OPENSPEC:END -->

package/AGENTS.md

@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->

package/CLAUDE.md

@@ -0,0 +1,320 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->
+
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**Important**: This project uses **English** as its primary language. All documentation, code comments, and commit messages should be in English.
+
+## Project Overview
+
+CKAN MCP Server - MCP (Model Context Protocol) server for interacting with CKAN-based open data portals (dati.gov.it, data.gov, demo.ckan.org, etc.).
+
+The server exposes MCP tools for:
+- Advanced dataset search with Solr syntax
+- DataStore queries for tabular data analysis
+- Organization and group exploration
+- Complete metadata access
+
+## Build and Development
+
+### Main Commands
+
+```bash
+# Build project (uses esbuild - fast and lightweight)
+npm run build
+
+# Run test suite (79 tests - unit + integration)
+npm test
+
+# Watch mode for tests during development
+npm run test:watch
+
+# Test coverage report
+npm run test:coverage
+
+# Start server in stdio mode (default for local integration)
+npm start
+
+# Start server in HTTP mode (for remote access)
+TRANSPORT=http PORT=3000 npm start
+
+# Watch mode for development
+npm run watch
+
+# Build + run
+npm run dev
+```
+
+### Build System
+
+The project uses **esbuild** for compilation and **vitest** for testing:
+
+- **Build**: Ultra-fast builds (milliseconds instead of minutes)
+- **Tests**: 101 tests (unit + integration) with 100% success rate
+- **Coverage**: Available via vitest with v8 coverage engine
+
+The `build:tsc` script is available as a fallback but can cause memory issues in some environments (particularly WSL). Always use `npm run build` which uses esbuild.
+
+The esbuild build bundles all internal modules but keeps external dependencies (`@modelcontextprotocol/sdk`, `axios`, `express`, `zod`) as external, so they must be present in `node_modules`.
+
+### Testing
+
+The project has a comprehensive test suite using **Vitest**:
+
+```
+tests/
+├── unit/
+│   ├── formatting.test.ts    # Utility functions (19 tests)
+│   ├── http.test.ts           # HTTP client (6 tests)
+│   └── uri.test.ts            # URI parsing (11 tests)
+├── integration/
+│   ├── package.test.ts        # Package tools (29 tests)
+│   ├── organization.test.ts   # Organization tools (6 tests)
+│   ├── datastore.test.ts      # DataStore tools (17 tests)
+│   ├── resources.test.ts      # MCP Resources (11 tests)
+│   └── status.test.ts         # Status tools (2 tests)
+└── fixtures/
+    ├── responses/             # Success response mocks
+    └── errors/                # Error scenario mocks
+```
+
+**Test Coverage**: 101 tests total (36 unit + 65 integration)
+
+When making changes:
+1. Run tests before committing: `npm test`
+2. Ensure all tests pass
+3. Add tests for new features or bug fixes
+4. Follow existing test patterns in `tests/` directory
+
+## Architecture
+
+### Code Structure
+
+The server is implemented with a modular structure to improve maintainability and testability:
+
+```
+src/
+├── index.ts              # Entry point (42 lines)
+├── server.ts             # MCP server setup (12 lines)
+├── types.ts              # Types & schemas (16 lines)
+├── utils/
+│   ├── http.ts           # CKAN API client (51 lines)
+│   └── formatting.ts     # Output formatting (37 lines)
+├── tools/
+│   ├── package.ts        # Package tools (350 lines)
+│   ├── organization.ts   # Organization tools (341 lines)
+│   ├── datastore.ts      # DataStore tools (146 lines)
+│   └── status.ts         # Status tools (66 lines)
+├── resources/            # MCP Resource Templates
+│   ├── index.ts          # Resource registration (19 lines)
+│   ├── uri.ts            # URI parsing utilities (50 lines)
+│   ├── dataset.ts        # Dataset resource (56 lines)
+│   ├── resource.ts       # Resource resource (56 lines)
+│   └── organization.ts   # Organization resource (58 lines)
+└── transport/
+    ├── stdio.ts          # Stdio transport (12 lines)
+    └── http.ts           # HTTP transport (27 lines)
+```
+
+**Total**: ~1350 lines (including new resources module)
+
+The server (`src/index.ts`):
+
+1. **Entry Point** (`index.ts`)
+   - Imports and registers all tools
+   - Chooses transport (stdio/http) from environment variable
+   - Handles startup and error handling
+
+2. **Registered Tools** (in separate modules)
+   - `tools/package.ts`: `ckan_package_search`, `ckan_package_show`
+   - `tools/organization.ts`: `ckan_organization_list`, `ckan_organization_show`, `ckan_organization_search`
+   - `tools/datastore.ts`: `ckan_datastore_search`
+   - `tools/status.ts`: `ckan_status_show`
+
+3. **MCP Resource Templates** (`resources/`)
+   - `ckan://{server}/dataset/{id}` - Dataset metadata
+   - `ckan://{server}/resource/{id}` - Resource metadata
+   - `ckan://{server}/organization/{name}` - Organization metadata
+
+4. **Utility Functions** (`utils/`)
+   - `http.ts`: `makeCkanRequest<T>()` - HTTP client for CKAN API v3
+   - `formatting.ts`: `truncateText()`, `formatDate()`, `formatBytes()`
+
+5. **Type Definitions** (`types.ts`)
+   - `ResponseFormat` enum (MARKDOWN, JSON)
+   - `ResponseFormatSchema` Zod validator
+   - `CHARACTER_LIMIT` constant
+
+5. **Transport Layer** (`transport/`)
+   - `stdio.ts`: Standard input/output (Claude Desktop)
+   - `http.ts`: HTTP server (remote access)
+
+6. **Validation Schema**
+   - Uses Zod to validate all tool inputs
+   - Each tool has a strict schema that rejects extra parameters
+
+7. **Output Formatting**
+   - All tools support two formats: `markdown` (default) and `json`
+   - Markdown format optimized for human readability
+   - JSON format for programmatic processing
+
+### Transport Modes
+
+The server automatically selects the transport mode based on the `TRANSPORT` environment variable:
+
+- **stdio** (default): for integration with Claude Desktop and other local MCP clients
+- **http**: exposes POST `/mcp` endpoint on configurable port (default 3000)
+
+### CKAN API Integration
+
+The server uses CKAN API v3 available on any CKAN portal. All requests:
+
+- Use `axios` with 30 second timeout
+- Send User-Agent `CKAN-MCP-Server/1.0`
+- Handle HTTP errors, timeouts, and server not found
+- Normalize server URL (removing trailing slash)
+- Validate that `response.success === true`
+
+### Solr Queries
+
+CKAN uses Apache Solr for search. The `ckan_package_search` tool supports:
+
+- **q** (query): complete Solr syntax (field:value, AND/OR/NOT, wildcard, range)
+- **fq** (filter query): additional filters without affecting score
+- **facet_field**: aggregations for statistical analysis
+- **sort**: result ordering
+- **start/rows**: pagination
+
+Common query examples are documented in `EXAMPLES.md`.
+
+## TypeScript Configuration
+
+The project uses ES2022 as target and module system.
+
+**Note**: `tsconfig.json` is present mainly for editor support (IDE, LSP). The actual compilation uses esbuild which ignores most TypeScript options to maximize speed.
+
+TypeScript configuration (for IDE):
+- Output in `dist/` directory
+- Strict mode enabled
+- Strict type checking with noUnusedLocals, noUnusedParameters, noImplicitReturns
+- Skip lib check to reduce overhead
+- Declaration and source map disabled
+
+## Dependencies
+
+**Runtime**:
+- `@modelcontextprotocol/sdk` - Official MCP SDK
+- `axios` - HTTP client for CKAN API
+- `zod` - Schema validation
+- `express` - HTTP server (only for http mode)
+
+**Dev**:
+- `esbuild` - Build tool (bundler and compiler)
+- `typescript` - Only for type checking and editor support
+- `@types/node`, `@types/express` - Type definitions
+
+## Supported CKAN Portals
+
+The server can connect to any CKAN instance. Some main portals:
+
+- 🇮🇹 https://dati.gov.it (Italy)
+- 🇺🇸 https://catalog.data.gov (United States)
+- 🇨🇦 https://open.canada.ca/data (Canada)
+- 🇬🇧 https://data.gov.uk (United Kingdom)
+- 🇪🇺 https://data.europa.eu (European Union)
+- 🌍 https://demo.ckan.org (Official CKAN Demo)
+
+Each portal may have different configurations for:
+- DataStore availability
+- Custom dataset fields
+- Available organizations and tags
+- Supported resource formats
+
+
+The project uses **Vitest** for automated testing:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+```
+
+Test coverage target is 80%. Current test suite includes:
+- Unit tests for utility functions (formatting, HTTP)
+- Integration tests for MCP tools with mocked CKAN API responses
+- Mock fixtures for CKAN API success and error scenarios
+
+See `tests/README.md` for detailed testing guidelines and fixture structure.
+
+### Manual Testing
+
+For manual testing:
+
+```bash
+# Build project
+npm run build
+
+# Test stdio mode
+npm start
+# (Server will wait for MCP commands on stdin)
+
+# Test HTTP mode in a terminal
+TRANSPORT=http PORT=3000 npm start
+
+# In another terminal, test with curl
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d {"jsonrpc":"2.0","method":"tools/list","id":1}
+```
+
+To test with Claude Desktop, add MCP configuration to config file.
+To test with Claude Desktop, add the MCP configuration to the config file.
+
+## Note di Sviluppo
+
+### Refactoring 2026-01-08
+Il codebase è stato refactorizzato da un singolo file di 1021 righe a 11 moduli. Vedi `REFACTORING.md` per dettagli.
+
+**Vantaggi**:
+- File più piccoli (max 350 righe)
+- Modifiche localizzate e sicure
+- Testing isolato possibile
+- Manutenzione semplificata
+- Zero breaking changes
+
+### To Do
+- Non ci sono test automatizzati - considerare di aggiungerli per tool critici
+- Il limite di 50000 caratteri per l'output è hardcoded in `types.ts` - potrebbe essere configurabile
+- Formato date usa locale 'it-IT' in `utils/formatting.ts` - potrebbe essere parametrizzato
+- Il server supporta solo lettura (tutti i tool sono read-only, non modificano dati su CKAN)
+- Non c'è caching - ogni richiesta fa una chiamata HTTP fresca alle API CKAN
+- Non c'è autenticazione - usa solo endpoint pubblici CKAN
+
+### Adding New Tools
+1. Crea nuovo file in `src/tools/`
+2. Esporta `registerXxxTools(server: McpServer)`
+3. Importa e chiama in `src/index.ts`
+4. Build e test