@aborruso/ckan-mcp-server 0.4.7 → 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,104 @@
 # 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
+- **Fix**: On CKAN 500, fall back to `package_search` facets for org counts
+- **Output**: Facet lists show top 10; suggest `response_format: json` and `facet_limit`
+
+## 2026-01-10
+
+### Web GUI intelligent tool selection
+- **MCP tool awareness**: Gemini now selects appropriate tool from 15 available
+  - Loads tool list on startup via `tools/list`
+  - Passes available tools to Gemini with descriptions
+  - Gemini chooses tool and generates arguments based on query type
+  - Examples: `ckan_organization_list` for "organizations with most datasets"
+  - `ckan_find_relevant_datasets` for smart searches
+  - `ckan_tag_list` for tag statistics
+- **Multi-type results**: UI handles datasets, organizations, tags
+  - Organization cards show package count
+  - Dataset cards show resources and org name
+  - Status shows tool being used ("Using ckan_organization_list...")
+- **Fallback**: Defaults to `ckan_package_search` if Gemini fails
+- **Fix**: Query "quali organizzazioni con il maggior numero di dataset" now works correctly
+
+### Web GUI redesign + conversation context
+- **UI redesign**: Dark theme with data editorial aesthetic
+  - Typography: DM Serif Display + IBM Plex Sans
+  - Color scheme: Deep charcoal (#0f1419) with cyan accent (#06b6d4)
+  - Glass morphism effects, gradient text, subtle grid background
+  - Smooth animations: slide-in, hover transitions, status pulse
+  - Collapsible settings panel with icon-based controls
+  - Enhanced dataset cards with hover lift and glow
+  - Custom scrollbar, loading shimmer, SVG icons throughout
+- **Conversation context**: Added history management
+  - Gemini receives conversation history for contextual refinement
+  - Users can ask follow-up queries ("only from Tuscany", "last 5 years")
+  - History limited to 10 messages (5 exchanges) to avoid token overflow
+  - Reset button to clear conversation and start fresh
+- **UX improvements**: Better visual hierarchy, spacing, interaction patterns
+- **Responsive**: Mobile-friendly layout maintained
+
+### Web GUI chat MVP
+- **Web GUI**: Replaced landing with MCP-backed chat UI (vanilla + Tailwind)
+- **MCP**: Added JSON-RPC search flow with dataset cards
+- **Fix**: Added `Accept` header for MCP 406 requirement
+- **Fix**: Normalize natural-language queries before search
+- **Gemini**: Added API key input and NL→Solr query call
+
+### Web GUI landing + Pages deploy
+- **Web GUI**: Added static landing page in `web-gui/public`
+- **CI**: Added GitHub Pages workflow for auto deploy on HTML changes
+
 ## 2026-01-10
 
 ### Version 0.4.7 - Portal search parser override