@aborruso/ckan-mcp-server 0.3.1

package/openspec/changes/archive/add-automated-tests/design.md

@@ -0,0 +1,324 @@
+# Design: Automated Testing Strategy
+
+This document explains the testing architecture, patterns, and trade-offs for the CKAN MCP Server automated tests.
+
+## Architecture Overview
+
+```
+tests/
+├── unit/              # Test individual functions in isolation
+│   ├── formatting.test.ts
+│   └── http.test.ts
+├── integration/       # Test tool behavior with mocked API
+│   ├── status.test.ts
+│   ├── package.test.ts
+│   ├── organization.test.ts
+│   └── datastore.test.ts
+├── fixtures/          # Mock CKAN API responses
+│   ├── responses/      # Success scenarios
+│   │   ├── status-success.json
+│   │   ├── package-search-success.json
+│   │   └── ...
+│   └── errors/        # Error scenarios
+│       ├── timeout.json
+│       ├── not-found.json
+│       └── server-error.json
+└── README.md          # Test writing guide
+```
+
+## Testing Pyramid
+
+```
+          E2e Tests
+          (0% - excluded)
+             ▲
+             │
+    Integration Tests
+       (30% - tools)
+             ▲
+             │
+      Unit Tests
+      (70% - utils)
+             ▲
+```
+
+### Rationale
+
+- **Unit tests (70%)**: Fast, stable, cover utility functions completely
+- **Integration tests (30%)**: Medium speed, test tool behavior with mocked API
+- **E2e tests (0%)**: Excluded - too slow, depends on external servers
+
+## Mock Strategy
+
+### Why Mock CKAN API?
+
+**Benefits:**
+- Fast execution (no network I/O)
+- Deterministic results (same every time)
+- Test error scenarios easily (404, timeout, 500)
+- No dependency on external servers
+- Offline development possible
+
+**Drawbacks:**
+- Mocks may diverge from real API
+- Doesn't catch API integration bugs
+- Maintenance overhead when API changes
+
+**Mitigation:**
+- Use real CKAN API documentation for fixtures
+- Periodically validate fixtures against demo.ckan.org
+- Keep mocks focused on API contract, not implementation
+
+### Mock Implementation
+
+Use Vitest's built-in `vi.fn()` to mock axios:
+
+```typescript
+import { vi } from 'vitest';
+import axios from 'axios';
+
+// Mock axios at module level
+vi.mock('axios');
+
+// In test, set return value
+(axios.get as Mock).mockResolvedValue(fixtureResponse);
+```
+
+### Fixture Structure
+
+Fixtures represent realistic CKAN API v3 responses:
+
+**Success Response Structure:**
+```json
+{
+  "success": true,
+  "result": { ... }
+}
+```
+
+**Error Response Structure:**
+```json
+{
+  "success": false,
+  "error": { ... }
+}
+```
+
+## Test Categories
+
+### Unit Tests
+
+**Target:** Utility functions in `src/utils/`
+
+**Characteristics:**
+- Test single function in isolation
+- Mock external dependencies (axios, formatting libs)
+- Focus on inputs/outputs
+- Fast execution (< 1ms each)
+
+**Example:**
+```typescript
+test('formatDate formats ISO date correctly', () => {
+  const result = formatDate('2024-01-15T10:30:00Z');
+  expect(result).toBe('15/01/2024');
+});
+```
+
+### Integration Tests
+
+**Target:** MCP tools in `src/tools/`
+
+**Characteristics:**
+- Test tool end-to-end with mocked API
+- Mock CKAN API responses
+- Validate output format (markdown/json)
+- Test error handling
+- Medium execution speed (~10-50ms each)
+
+**Example:**
+```typescript
+test('ckan_package_search returns markdown format', async () => {
+  vi.mocked(axios.get).mockResolvedValue(fixture);
+  const result = await ckan_package_search({...});
+  expect(result.content[0].type).toBe('text');
+  expect(result.content[0].text).toContain('# Search Results');
+});
+```
+
+## Coverage Strategy
+
+### Target: 80%
+
+**Breakdown:**
+- Utility functions: 100% (essential, easy to test)
+- Tool implementations: 75%+ (focus on critical paths)
+- Edge cases: 60% (lower priority, add incrementally)
+
+### What NOT to Test
+
+- External library code (axios, express, zod)
+- MCP SDK internals
+- Simple getters/setters
+- Type definitions
+- Configuration constants
+
+### When to Stop Testing
+
+When tests provide diminishing returns:
+- Error handling code already tested elsewhere
+- Simple boolean logic
+- One-line functions with clear behavior
+- Delegation to tested functions
+
+## Test Writing Guidelines
+
+### Naming Convention
+
+```typescript
+// Good: Describes what and expected outcome
+test('truncateText limits text to 50000 characters', () => { ... });
+
+// Bad: Vague
+test('truncateText works', () => { ... });
+```
+
+### AAA Pattern
+
+Arrange, Act, Assert:
+
+```typescript
+test('formatBytes converts bytes to KB', () => {
+  // Arrange
+  const bytes = 1500;
+
+  // Act
+  const result = formatBytes(bytes);
+
+  // Assert
+  expect(result).toBe('1.46 KB');
+});
+```
+
+### One Assertion Per Test
+
+```typescript
+// Good: One test, one assertion
+test('formatDate returns formatted date', () => {
+  const result = formatDate('2024-01-15');
+  expect(result).toMatch(/\d{2}\/\d{2}\/\d{4}/);
+});
+
+// Bad: Multiple assertions, harder to debug
+test('formatDate works', () => {
+  const result = formatDate('2024-01-15');
+  expect(result).toBeDefined();
+  expect(typeof result).toBe('string');
+  expect(result).toMatch(/\d{2}\/\d{2}\/\d{4}/);
+});
+```
+
+### Testing Error Scenarios
+
+```typescript
+test('ckan_package_show handles 404 error', async () => {
+  vi.mocked(axios.get).mockRejectedValue(new Error('404 Not Found'));
+
+  const result = await ckan_package_show({...});
+
+  expect(result.isError).toBe(true);
+  expect(result.content[0].text).toContain('Not found');
+});
+```
+
+## CI/CD Integration
+
+If CI/CD exists (GitHub Actions, GitLab CI, etc.):
+
+```yaml
+- name: Run tests
+  run: npm test
+
+- name: Generate coverage
+  run: npm run test:coverage
+
+- name: Upload coverage
+  run: # Upload to coverage service (optional)
+```
+
+## Trade-offs
+
+### Vitest vs Jest
+
+**Chosen: Vitest**
+
+**Why Vitest:**
+- 10x faster than Jest
+- Native ESM support
+- Built-in TypeScript support
+- Modern, actively maintained
+- API compatible with Jest
+
+**Trade-off:**
+- Newer ecosystem than Jest
+- Fewer community examples
+
+### Mocking Real API
+
+**Chosen: Mock fixtures**
+
+**Why Mock:**
+- Fast and reliable
+- Test error scenarios
+- No external dependencies
+
+**Trade-off:**
+- Doesn't catch API integration bugs
+- Mocks may become outdated
+
+**Mitigation:**
+- Validate fixtures periodically against demo.ckan.org
+- Document fixture structure
+- Keep tests focused on API contract
+
+### Coverage Target 80%
+
+**Why 80%:**
+- High enough to catch most bugs
+- Not so high to be wasteful
+- Industry standard for first iteration
+
+**Trade-off:**
+- 20% of code untested
+- Edge cases may slip through
+
+**Mitigation:**
+- Focus testing on critical paths
+- Add tests for bugs found in production
+- Incrementally improve coverage over time
+
+## Future Enhancements
+
+### Short Term
+- Add performance benchmarks
+- Test output formatting edge cases
+- Add more error scenario tests
+
+### Medium Term
+- Increase coverage to 90%
+- Add contract tests for CKAN API
+- Visual regression tests for markdown output
+
+### Long Term
+- Fuzz testing for input validation
+- Chaos testing for error handling
+- Integration with external testing services
+
+## Conclusion
+
+This testing strategy balances:
+- **Speed**: Unit tests + mocked integration tests
+- **Reliability**: Deterministic mocks, no external dependencies
+- **Maintainability**: Clear patterns, simple fixtures
+- **Effectiveness**: 80% coverage, focus on critical paths
+
+The incremental approach ensures we get value from tests early while keeping the investment manageable.

package/openspec/changes/archive/add-automated-tests/proposal.md

@@ -0,0 +1,167 @@
+# Proposal: Add Automated Testing
+
+**Status:** Draft
+**Created:** 2026-01-08
+**Author:** OpenCode
+
+## Summary
+
+Add automated tests to the CKAN MCP Server project using Vitest framework, focusing on unit tests for utilities and integration tests for tools with mocked CKAN API responses.
+
+## Motivation
+
+The project currently has no automated tests (mentioned in CLAUDE.md), which creates several risks:
+- No regression detection when modifying code
+- Difficult to refactor confidently
+- No validation of tool behavior against CKAN API specifications
+- Harder for new contributors to understand expected behavior
+- No safety net for future changes
+
+Adding automated tests will:
+- Catch bugs early before deployment
+- Enable confident refactoring
+- Document expected behavior through tests
+- Improve code quality and maintainability
+- Lower barrier for contributions
+
+## Scope
+
+### Included
+- **Unit tests** for utility functions (`src/utils/formatting.ts`, `src/utils/http.ts`)
+- **Integration tests** for MCP tools with mocked CKAN API responses
+- Test setup and configuration (Vitest)
+- Mock fixtures for CKAN API responses
+- Test scripts in package.json
+- CI/CD integration for running tests (if CI exists)
+- Documentation for running and writing tests
+
+### Excluded
+- E2e tests with real CKAN servers (too slow/unstable)
+- Performance/benchmark tests (future enhancement)
+- UI/interaction tests (no UI in this project)
+- Manual testing procedures (already documented in CLAUDE.md)
+
+## Proposed Changes
+
+### Technology Stack
+
+**Framework**: Vitest
+- Fast and modern test runner
+- Native TypeScript support
+- Jest-compatible API (easy to learn)
+- Built-in mocking and spying
+- Excellent watch mode for development
+
+**Mock Library**: Built-in Vitest vi.fn()
+- No additional dependencies
+- Simple and powerful mocking
+- Easy to mock CKAN API responses
+
+**Coverage**: c8 (Vitest's built-in coverage tool)
+- Generates coverage reports
+- Integrates with Vitest
+
+### Test Strategy
+
+#### Phase 1: Foundation (Priority: High)
+- Configure Vitest with TypeScript support
+- Create test directory structure
+- Add test scripts to package.json
+- Set up coverage reporting
+
+#### Phase 2: Unit Tests (Priority: High)
+- `src/utils/formatting.ts`: truncateText, formatDate, formatBytes
+- `src/utils/http.ts`: makeCkanRequest (with mocked axios)
+
+#### Phase 3: Integration Tests (Priority: Medium)
+- `tools/status.ts`: ckan_status_show
+- `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
+
+### Mock Strategy
+
+Create fixture files with realistic CKAN API responses:
+- `fixtures/responses/status-success.json`
+- `fixtures/responses/package-search-success.json`
+- `fixtures/responses/organization-list-success.json`
+- `fixtures/responses/datastore-search-success.json`
+- Error scenarios: timeouts, 404, 500 errors
+
+Mock `axios` to return fixture data without making real HTTP requests.
+
+### Coverage Target
+
+**Initial goal**: 80% code coverage
+- All utility functions: 100%
+- Tool implementations: 75%+
+- Focus on critical paths, not edge cases
+
+**Future goal**: 90%+ (incremental improvement)
+
+### Incremental Approach
+
+Start small and iterate:
+1. Test 1-2 tools + all utils
+2. Validate approach works
+3. Add tests for remaining tools
+4. Improve coverage over time
+5. Add more edge case tests as needed
+
+## Alternatives Considered
+
+1. **Jest** as test framework
+   - *Rejected*: Vitest is faster, has better TypeScript support, and is more modern
+
+2. **E2e tests with real CKAN servers**
+   - *Rejected*: Too slow (network calls), unstable (depends on external servers), non-deterministic
+
+3. **No mocking - test with demo.ckan.org**
+   - *Rejected*: Requires network, slow, test results vary, can't test error scenarios easily
+
+4. **100% coverage from start**
+   - *Rejected*: Too much effort, diminishing returns, 80% is reasonable for first iteration
+
+5. **Testing framework with separate dependencies** (supertest, nock)
+   - *Rejected*: Vitest has built-in mocking sufficient for this project
+
+## Impact Assessment
+
+### Benefits
+- + Early bug detection
+- + Safer refactoring
+- + Behavior documentation through tests
+- + Improved code quality
+- + Easier onboarding for new contributors
+- + Faster development cycle (tests catch issues early)
+
+### Risks
+- - Initial time investment for writing first tests
+- - Test maintenance overhead as code evolves
+- - Possible brittle tests if mocking not done well
+- - False sense of security if tests don't cover real scenarios
+
+### Mitigation
+- Start with critical paths only (incremental approach)
+- Keep mocks simple and focused on API contracts
+- Review tests in code review
+- Update tests when CKAN API changes
+- Regular test maintenance in future development
+
+## Open Questions
+
+None - clarified with project owner.
+
+## Dependencies
+
+None - this is a new capability that doesn't depend on other changes.
+
+## Success Criteria
+
+- [ ] Vitest configured and running
+- [ ] Test scripts in package.json work
+- [ ] Unit tests for utils passing
+- [ ] Integration tests for at least 2 tools passing
+- [ ] Coverage at least 80% for tested code
+- [ ] Tests documented in README or test files
+- [ ] Validation: `openspec validate add-automated-tests --strict` passes

package/openspec/changes/archive/add-automated-tests/specs/automated-testing/spec.md

@@ -0,0 +1,143 @@
+# Spec: Automated Testing
+
+Defines requirements for automated testing infrastructure and test coverage.
+
+## ADDED Requirements
+
+### Requirement: Automated test suite
+
+The project SHALL have an automated test suite using Vitest that runs unit tests for utility functions and integration tests for MCP tools.
+
+#### Scenario: Run test suite
+Given the project has tests configured
+When a developer runs `npm test`
+Then all tests pass
+And the test run completes in under 10 seconds
+And the output shows pass/fail status for each test
+
+#### Scenario: Run tests in watch mode
+Given a developer is actively writing code
+When they run `npm run test:watch`
+Then Vitest starts in watch mode
+And tests re-run automatically when files change
+And the developer receives immediate feedback
+
+### Requirement: Test coverage reporting
+
+The project SHALL provide code coverage reporting with a minimum threshold of 80% for tested code.
+
+#### Scenario: Generate coverage report
+Given the project has tests configured
+When a developer runs `npm run test:coverage`
+Then a coverage report is generated
+And the report shows line-by-line coverage
+And coverage meets 80% threshold
+And the report is saved in coverage/ directory
+
+#### Scenario: Coverage below threshold
+Given new code is added without tests
+When coverage is checked
+Then the coverage report shows below 80%
+And the report highlights untested lines
+And developer knows which files need tests
+
+### Requirement: Unit tests for utilities
+
+The project SHALL have unit tests for all utility functions in `src/utils/` directory.
+
+#### Scenario: Unit test for formatting function
+Given a utility function exists (e.g., formatDate)
+When a unit test is written for it
+Then the test covers all branches
+And the test provides realistic inputs
+And the test validates expected output
+
+#### Scenario: Unit test for HTTP client
+Given the makeCkanRequest function
+When a unit test is written for it
+Then axios is mocked
+And the test validates successful responses
+And the test validates error scenarios (404, 500, timeout)
+And the test validates URL normalization
+
+### Requirement: Integration tests for tools
+
+The project SHALL have integration tests for MCP tools that validate tool behavior with mocked CKAN API responses.
+
+#### Scenario: Integration test for search tool
+Given the ckan_package_search tool
+When an integration test is written for it
+Then CKAN API responses are mocked
+And the test validates output format (markdown/json)
+And the test validates successful search
+And the test validates error handling
+
+#### Scenario: Integration test for DataStore tool
+Given the ckan_datastore_search tool
+When an integration test is written for it
+Then DataStore API responses are mocked
+And the test validates query processing
+And the test validates output formatting
+And the test validates filter and sort parameters
+
+### Requirement: Mock fixtures for API responses
+
+The project SHALL provide mock fixtures that represent realistic CKAN API v3 responses for both success and error scenarios.
+
+#### Scenario: Success response fixture
+Given a CKAN API success response is needed
+When a fixture is created
+Then the fixture follows CKAN API v3 format
+And the fixture includes "success": true
+And the fixture includes realistic "result" data
+
+#### Scenario: Error response fixture
+Given an error scenario is tested
+When an error fixture is created
+Then the fixture follows CKAN API v3 format
+And the fixture includes "success": false
+And the fixture includes error details
+
+#### Scenario: Timeout error fixture
+Given timeout scenarios are tested
+When a timeout fixture is used
+Then axios is mocked to throw timeout error
+And the tool handles the error gracefully
+And the tool returns user-friendly error message
+
+### Requirement: Test documentation
+
+The project SHALL provide documentation for running and writing tests to help developers understand testing practices.
+
+#### Scenario: Running tests
+Given a new developer joins the project
+When they read test documentation
+Then they know how to run tests
+Then they know how to run tests in watch mode
+Then they know how to generate coverage reports
+
+#### Scenario: Writing tests
+Given a developer needs to write a new test
+When they read test documentation
+Then they see examples of unit tests
+Then they see examples of integration tests
+Then they understand the mocking strategy
+Then they follow naming conventions
+
+### Requirement: Incremental test development
+
+The project SHALL allow incremental development of tests, starting with critical tools and expanding over time.
+
+#### Scenario: Initial test coverage
+Given the first iteration of tests
+When tests are implemented
+Then at least 2 tools have tests
+Then all utility functions have tests
+And coverage meets 80% threshold for tested code
+
+#### Scenario: Expanding test coverage
+Given new tools are added to the project
+When a developer adds tests for the new tool
+Then the tests follow existing patterns
+And the tests are added incrementally
+And the project maintains overall quality