@aborruso/ckan-mcp-server 0.4.8 → 0.4.9

package/AGENTS.md

@@ -4,15 +4,202 @@
 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 -->
+<!-- OPENSPEC:END -->
+
+# Agent Guide
+
+## Scope
+
+- Repo: `ckan-mcp-server`
+- Stack: Node.js + TypeScript (ESM)
+- Tests: Vitest
+- Build: esbuild
+- Cloudflare Workers: `wrangler`
+
+## Cursor and Copilot Rules
+
+- No `.cursor/rules`, `.cursorrules`, or `.github/copilot-instructions.md` found
+
+## Core Commands
+
+Install deps:
+
+```bash
+npm install
+```
+
+Build (node bundle):
+
+```bash
+npm run build
+```
+
+Build (worker bundle):
+
+```bash
+npm run build:worker
+```
+
+TypeScript build (tsc):
+
+```bash
+npm run build:tsc
+```
+
+Start server (stdio or HTTP via env):
+
+```bash
+npm start
+```
+
+Dev build + run:
+
+```bash
+npm run dev
+```
+
+Watch build:
+
+```bash
+npm run watch
+```
+
+Cloudflare dev:
+
+```bash
+npm run dev:worker
+```
+
+Deploy worker:
+
+```bash
+npm run deploy
+```
+
+## Tests
+
+Run all tests:
+
+```bash
+npm test
+```
+
+Watch tests:
+
+```bash
+npm run test:watch
+```
+
+Coverage:
+
+```bash
+npm run test:coverage
+```
+
+Run a single file:
+
+```bash
+npm test -- tests/unit/http.test.ts
+```
+
+Run a single test name:
+
+```bash
+npm test -- -t "makeCkanRequest"
+```
+
+Run single file with Vitest directly:
+
+```bash
+npx vitest tests/unit/http.test.ts
+```
+
+## Lint and Format
+
+- No ESLint or Prettier config detected
+- Do not add new formatters unless requested
+- Keep formatting consistent with existing files
+
+## Project Layout
+
+- `src/index.ts` entry point
+- `src/server.ts` server wiring
+- `src/tools/` MCP tool handlers
+- `src/utils/` helpers (http, formatting, search)
+- `src/resources/` MCP resource templates
+- `src/transport/` stdio + HTTP
+- `tests/unit/` utilities
+- `tests/integration/` tool behavior
+- `tests/fixtures/` mocked CKAN API responses
+
+## TypeScript Style
+
+- Use strict typing (`tsconfig.json` has `strict: true`)
+- Avoid `any` unless unavoidable or from CKAN payloads
+- Prefer explicit return types for exported functions
+- Use `type` aliases for structured objects
+- Keep `noUnusedLocals` and `noUnusedParameters` clean
+- ESM imports with `.js` extensions for local modules
+
+## Import Conventions
+
+- Use `import type` for type-only imports
+- Group imports by kind: external, internal, types
+- Use double quotes for strings
+- Keep import paths relative and short
+
+## Naming
+
+- `camelCase` for vars/functions
+- `PascalCase` for types/classes
+- `UPPER_SNAKE_CASE` for constants
+- Tool names match MCP tool id strings
+
+## Error Handling
+
+- Wrap tool handlers in `try/catch`
+- Return `{ isError: true }` for MCP errors
+- Include user-facing error text with context
+- For HTTP errors, map to readable messages
+- Preserve error cause when rethrowing
+
+## Tool Responses
+
+- Use `ResponseFormat` for markdown vs JSON
+- Use `truncateText` for large payloads
+- Keep JSON output pretty-printed
+- Include `structuredContent` for JSON mode
+
+## Testing Guidelines
+
+- Tests use Vitest and `globals: true`
+- Place new tests in `tests/unit` or `tests/integration`
+- Follow AAA pattern: Arrange, Act, Assert
+- Mock CKAN API via fixtures under `tests/fixtures`
+- Name tests descriptively with expected behavior
+
+## Configuration Notes
+
+- Node engine: `>=18`
+- Worker build command set in `wrangler.toml`
+- Vitest coverage thresholds enforced in `vitest.config.ts`
+
+## Change Hygiene
+
+- Keep diffs minimal and focused
+- Avoid unrelated refactors
+- Update tests for behavior changes
+- Avoid editing `dist/` (generated)

package/CLAUDE.md

@@ -41,7 +41,7 @@ The server exposes MCP tools for:
 # Build project (uses esbuild - fast and lightweight)
 npm run build
 
-# Run test suite (113 tests - unit + integration)
+# Run test suite (179 tests - unit + integration)
 npm test
 
 # Watch mode for tests during development
@@ -73,8 +73,8 @@ npm run deploy            # Deploy to Cloudflare Workers
 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
+- **Tests**: 179 tests (unit + integration) with 100% success rate
+- **Coverage**: ~39% overall (utils: 98%, tools: 15-20%) - 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.
 
@@ -101,7 +101,7 @@ tests/
     └── errors/                # Error scenario mocks
 ```
 
-**Test Coverage**: 101 tests total (36 unit + 65 integration)
+**Test Coverage**: 179 tests total (85 unit + 94 integration)
 
 When making changes:
 1. Run tests before committing: `npm test`
@@ -292,11 +292,14 @@ npm run test:watch
 npm run test:coverage
 ```
 
-Test coverage target is 80%. Current test suite includes:
-- Unit tests for utility functions (formatting, HTTP)
+Current test coverage: ~39% overall (utility modules: 98%, tool handlers: 15-20%).
+
+Test suite includes:
+- Unit tests for utility functions (formatting, HTTP, URI parsing, URL generation, search)
 - Integration tests for MCP tools with mocked CKAN API responses
 - Mock fixtures for CKAN API success and error scenarios
 
+Coverage is strong for utility modules but needs improvement for tool handlers.
 See `tests/README.md` for detailed testing guidelines and fixture structure.
 
 ### Manual Testing
@@ -338,8 +341,8 @@ To test with Claude Desktop, add the MCP configuration to the config file.
 - Direct data access for datasets, resources, organizations
 
 **v0.2.0 (2026-01-08)**: Comprehensive test suite
-- 113 tests (unit + integration)
-- 97%+ code coverage
+- 179 tests (unit + integration)
+- ~39% code coverage (utils well-tested, tools improving)
 
 **v0.1.0 (2026-01-08)**: Modular refactoring
 - Restructured from monolithic file to 11 modules

package/LOG.md

@@ -1,5 +1,53 @@
 # LOG
 
+## 2026-01-11
+
+### Version 0.4.9 - Security, Testing & Documentation
+- **Security**: Updated @modelcontextprotocol/sdk from 1.25.1 to 1.25.2 (fixes HIGH severity ReDoS vulnerability)
+- **Testing**: Added 49 new unit tests for package.ts scoring functions
+- **Coverage**: Improved from 37.33% to 38.63% (package.ts: 12.5% to 15%)
+- **Total tests**: 179 tests (all passing, +49 from 130)
+- **Documentation**: Corrected test coverage claims (was "113 tests, 97%+" now accurate "179 tests, ~39%")
+- **Deployment**: Added npm audit check to DEPLOYMENT.md
+- **Files modified**: package.json, src/server.ts, src/worker.ts, README.md, CLAUDE.md, docs/DEPLOYMENT.md
+- **New file**: tests/unit/package-scoring.test.ts
+- **No breaking changes**: All existing functionality preserved
+
+### Test improvements - package scoring functions
+- **Added**: 49 new unit tests for package.ts scoring functions
+- **Coverage improvement**: package.ts from 12.5% to 15%
+- **Overall coverage**: 37.33% to 38.63%
+- **Total tests**: 130 to 179 tests (all passing)
+- **New test file**: tests/unit/package-scoring.test.ts
+- **Functions tested**:
+  - extractQueryTerms (10 tests)
+  - escapeRegExp (6 tests)
+  - textMatchesTerms (10 tests)
+  - scoreTextField (6 tests)
+  - scoreDatasetRelevance (17 tests with edge cases)
+- **Exports**: Made internal functions testable (extractQueryTerms, escapeRegExp, textMatchesTerms, scoreTextField)
+- **Impact**: Better coverage of dataset relevance scoring logic
+
+### Documentation corrections - test coverage accuracy
+- **Fix**: Corrected test coverage claims in README.md and CLAUDE.md
+- **Previous claim**: "113 tests, 97%+ coverage"
+- **Actual values**: 130 tests passing, ~37% overall coverage
+  - Utility modules: 98% coverage (excellent)
+  - Tool handlers: 12-20% coverage (needs improvement)
+- **Impact**: Documentation now accurately reflects project state
+- **Files modified**: README.md, CLAUDE.md
+
+### Documentation enhancement - deployment security
+- **Added**: npm audit check to DEPLOYMENT.md (Step 4.5)
+- **Added**: Security audit to pre-release checklist
+- **Recommendation**: Always run `npm audit` before production deployment
+
+### Security fix - MCP SDK update
+- **Fix**: Update @modelcontextprotocol/sdk from 1.25.1 to 1.25.2
+- **Reason**: Resolves HIGH severity ReDoS vulnerability (GHSA-8r9q-7v3j-jr4g)
+- **Tests**: All 130 tests passing
+- **Audit**: 0 vulnerabilities
+
 ## 2026-01-10
 
 ### Version 0.4.8 - Organization list fallback

package/README.md

@@ -14,7 +14,7 @@ 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 (120 tests, 100% passing)
+- 🧪 Test suite with 179 tests (100% passing)
 
 ## Installation
 
@@ -36,7 +36,7 @@ npm install
 # Build with esbuild (fast, ~4ms)
 npm run build
 
-# Run tests (120 tests)
+# Run tests (179 tests)
 npm test
 ```
 
@@ -204,7 +204,7 @@ ckan://data.gov/organization/sample-org
 
 ## Usage Examples
 
-### Search datasets on dati.gov.it
+### Search datasets on dati.gov.it (natural language: "search for population datasets")
 
 ```typescript
 ckan_package_search({
@@ -214,7 +214,7 @@ ckan_package_search({
 })
 ```
 
-### Force text-field parser for long OR queries
+### Force text-field parser for long OR queries (natural language: "find hotel or accommodation datasets")
 
 ```typescript
 ckan_package_search({
@@ -225,7 +225,7 @@ ckan_package_search({
 })
 ```
 
-### Rank datasets by relevance
+### Rank datasets by relevance (natural language: "find most relevant datasets about urban mobility")
 
 ```typescript
 ckan_find_relevant_datasets({
@@ -235,7 +235,7 @@ ckan_find_relevant_datasets({
 })
 ```
 
-### Filter by organization
+### Filter by organization (natural language: "show recent datasets from Sicilian Region")
 
 ```typescript
 ckan_package_search({
@@ -245,7 +245,7 @@ ckan_package_search({
 })
 ```
 
-### Search organizations with wildcard
+### Search organizations with wildcard (natural language: "find all organizations with health/salute in name")
 
 ```typescript
 // Find all organizations containing "salute" in the name
@@ -258,7 +258,7 @@ ckan_package_search({
 })
 ```
 
-### Get statistics with faceting
+### Get statistics with faceting (natural language: "show statistics by organization, tags and format")
 
 ```typescript
 ckan_package_search({
@@ -287,7 +287,7 @@ ckan_group_search({
 })
 ```
 
-### DataStore Query
+### DataStore Query (natural language: "query tabular data filtering by region and year")
 
 ```typescript
 ckan_datastore_search({
@@ -299,7 +299,7 @@ ckan_datastore_search({
 })
 ```
 
-### DataStore SQL Query
+### DataStore SQL Query (natural language: "count records by country with SQL")
 
 ```typescript
 ckan_datastore_search_sql({
@@ -365,7 +365,7 @@ fq: "metadata_modified:[2023-01-01T00:00:00Z TO *]"
 
 These real-world examples demonstrate powerful Solr query combinations tested on the Italian open data portal (dati.gov.it):
 
-#### 1. Fuzzy Search + Date Math + Boosting
+#### 1. Fuzzy Search + Date Math + Boosting (natural language: "find healthcare datasets modified in last 6 months")
 
 Find healthcare datasets (tolerating spelling errors) modified in the last 6 months, prioritizing title matches:
 
@@ -387,7 +387,7 @@ ckan_package_search({
 
 **Results**: 871 datasets including hospital units, healthcare organizations, medical services
 
-#### 2. Proximity Search + Complex Boolean
+#### 2. Proximity Search + Complex Boolean (natural language: "find air pollution datasets excluding water")
 
 Environmental datasets where "inquinamento" and "aria" (air pollution) appear close together, excluding water-related datasets:
 
@@ -409,7 +409,7 @@ ckan_package_search({
 
 **Results**: 306 datasets, primarily air quality monitoring from Milan (44) and Palermo (161), formats: XML (150), CSV (124), JSON (76)
 
-#### 3. Wildcard + Field Existence + Range Queries
+#### 3. Wildcard + Field Existence + Range Queries (natural language: "regional datasets with many resources from last year")
 
 Regional datasets with at least 5 resources, published in the last year:
 
@@ -432,7 +432,7 @@ ckan_package_search({
 
 **Results**: 5,318 datasets, top contributors: Lombardy (3,012), Tuscany (1,151), Puglia (460)
 
-#### 4. Date Ranges + Exclusive Bounds
+#### 4. Date Ranges + Exclusive Bounds (natural language: "ISTAT datasets with 10-50 resources from specific period")
 
 ISTAT datasets with moderate resource count (10-50), modified in specific date range:
 
@@ -500,7 +500,7 @@ ckan-mcp-server/
 │   └── transport/
 │       ├── stdio.ts        # Stdio transport
 │       └── http.ts         # HTTP transport
-├── tests/                  # Test suite (120 tests)
+├── tests/                  # Test suite (179 tests)
 ├── dist/                   # Compiled files (generated)
 ├── package.json
 └── README.md
@@ -523,12 +523,14 @@ npm run test:watch
 npm run test:coverage
 ```
 
-Test coverage target is 80%. Current test suite includes:
+Current test coverage: ~39% (utils: 98%, tools: 15-20%).
 
-- Unit tests for utility functions (formatting, HTTP)
+Test suite includes:
+- Unit tests for utility functions (formatting, HTTP, URI parsing, URL generation)
 - Integration tests for MCP tools with mocked CKAN API responses
 - Mock fixtures for CKAN API success and error scenarios
 
+Coverage is higher for utility modules and lower for tool handlers.
 See `tests/README.md` for detailed testing guidelines.
 
 ### Build