@aborruso/ckan-mcp-server 0.4.17 → 0.4.18

package/openspec/changes/archive/2026-01-08-expand-test-coverage-specs/design.md

@@ -1,355 +0,0 @@
-# Design: Expand Test Coverage for Remaining Tools
-
-This document explains the testing approach for expanding coverage to package, organization, and datastore tools, following patterns established in the initial testing implementation.
-
-## Testing Approach
-
-### Pattern Reuse
-
-We follow the successful pattern from the initial testing proposal:
-
-```typescript
-// 1. Mock axios
-vi.mock('axios');
-
-// 2. Import fixtures
-import packageSearchFixture from '../fixtures/responses/package-search-success.json';
-
-// 3. Setup test
-it('returns expected structure', async () => {
-  vi.mocked(axios.get).mockResolvedValue({ data: packageSearchFixture });
-
-  const result = await ckan_package_search({...});
-
-  // 4. Validate result
-  expect(result).toBeDefined();
-  expect(result.content[0].text).toContain('...');
-});
-```
-
-### Test Structure
-
-Each tool category gets its own test file:
-- `tests/integration/package.test.ts`
-- `tests/integration/organization.test.ts`
-- `tests/integration/datastore.test.ts`
-
-## Test Scenarios by Tool Category
-
-### Package Tools
-
-#### ckan_package_search Tests
-
-**Happy Paths:**
-1. Basic search with query parameter
-2. Search with facets (facet_field, facet_limit)
-3. Search with pagination (start, rows)
-4. Search with sorting (sort)
-5. Search with filter query (fq)
-6. Empty results (q returns no matches)
-
-**Edge Cases:**
-7. Very large results (rows > 1000)
-8. Multiple facet fields
-9. Complex query (q + fq + facets)
-10. Markdown output format validation
-11. JSON output format validation
-
-**Error Scenarios:**
-12. Invalid query syntax (if applicable)
-13. Server error during search
-14. Timeout during search
-
-#### ckan_package_show Tests
-
-**Happy Paths:**
-1. Show package with valid ID
-2. Package with multiple resources
-3. Package with tags
-4. Package with organization
-5. Package without resources
-
-**Edge Cases:**
-6. Package with very long description (test truncation)
-7. Package with many resources (>10)
-
-**Error Scenarios:**
-8. Invalid package ID (404)
-9. Server error during fetch
-10. Timeout during fetch
-
-### Organization Tools
-
-#### ckan_organization_list Tests
-
-**Happy Paths:**
-1. List all organizations (default)
-2. List with limit parameter
-3. List with offset parameter
-4. List with sort parameter
-5. Empty result (no organizations)
-
-**Edge Cases:**
-6. Very large list (all organizations)
-7. Sorting by different fields (name, title, package_count)
-
-**Error Scenarios:**
-8. Server error during list
-9. Timeout during list
-
-#### ckan_organization_show Tests
-
-**Happy Paths:**
-1. Show organization with valid ID
-2. Organization with users
-3. Organization with package_count
-4. Organization with extras (custom fields)
-
-**Edge Cases:**
-5. Organization with very long description
-
-**Error Scenarios:**
-6. Invalid organization ID (404)
-7. Server error during fetch
-8. Timeout during fetch
-
-#### ckan_organization_search Tests
-
-**Happy Paths:**
-1. Search with query
-2. Search with wildcard (*)
-3. Search with facets
-4. Search with pagination
-
-**Edge Cases:**
-5. Search returning many results
-6. Search returning no results
-
-**Error Scenarios:**
-7. Invalid query
-8. Server error during search
-9. Timeout during search
-
-### DataStore Tools
-
-#### ckan_datastore_search Tests
-
-**Happy Paths:**
-1. Basic query with resource_id
-2. Query with filters
-3. Query with sorting
-4. Query with pagination (limit, offset)
-5. Query with multiple filters
-6. Query with field list (fields parameter)
-
-**Edge Cases:**
-7. Large result set (test truncation)
-8. Complex filters (AND/OR logic)
-9. Empty result (no records)
-
-**Error Scenarios:**
-10. Invalid resource_id
-11. Invalid filter syntax
-12. Server error during query
-13. Timeout during query
-14. DataStore not enabled for resource
-
-## Output Format Validation
-
-All tools support both markdown and JSON output. Tests should validate:
-
-### Markdown Format
-```typescript
-test('returns markdown format', async () => {
-  vi.mocked(axios.get).mockResolvedValue({ data: fixture });
-
-  const result = await ckan_package_search({ format: 'markdown', ... });
-
-  expect(result.content[0].type).toBe('text');
-  expect(result.content[0].text).toMatch(/^# /); // Markdown heading
-});
-```
-
-### JSON Format
-```typescript
-test('returns JSON format', async () => {
-  vi.mocked(axios.get).mockResolvedValue({ data: fixture });
-
-  const result = await ckan_package_search({ format: 'json', ... });
-
-  expect(result.content[0].type).toBe('resource');
-  expect(result.structuredContent).toBeDefined();
-});
-```
-
-## Error Handling Tests
-
-All tools should handle errors gracefully:
-
-```typescript
-test('handles 404 error', async () => {
-  vi.mocked(axios.get).mockRejectedValue({
-    isAxiosError: true,
-    response: { status: 404, data: notFoundFixture }
-  });
-
-  const result = await ckan_package_show({ package_id: 'invalid' });
-
-  expect(result.isError).toBe(true);
-  expect(result.content[0].text).toContain('Not found');
-});
-```
-
-## Fixture Strategy
-
-### Existing Fixtures
-
-Reuse fixtures from initial proposal:
-- `package-search-success.json` - already exists
-- `package-show-success.json` - already exists
-- `organization-list-success.json` - already exists
-- `organization-show-success.json` - already exists
-- `organization-search-success.json` - already exists
-- `datastore-search-success.json` - already exists
-
-### Additional Fixtures Needed
-
-May need to create:
-- `package-empty-results.json` - for empty search results
-- `organization-empty-results.json` - for empty org list
-- `datastore-empty-results.json` - for empty data queries
-- Error fixtures specific to each tool if needed
-
-### Creating New Fixtures
-
-Follow existing structure:
-
-**Success fixture:**
-```json
-{
-  "help": "API help URL",
-  "success": true,
-  "result": { ... }
-}
-```
-
-**Error fixture:**
-```json
-{
-  "success": false,
-  "error": {
-    "__type": "Error Type",
-    "message": "Error message",
-    "status": 404
-  }
-}
-```
-
-## Coverage Goals
-
-### Target Metrics
-
-| Component | Current Coverage | Target Coverage | Tests Needed |
-|-----------|------------------|-----------------|---------------|
-| Utils | 100% | 100% | ✅ Done |
-| Status Tool | ~50% | 75-85% | ✅ Done |
-| Package Tools | 0% | 75-85% | ~16 tests |
-| Organization Tools | 0% | 75-85% | ~18 tests |
-| DataStore Tool | 0% | 75-85% | ~14 tests |
-| **Overall** | **~68%** | **80%+** | **~48 tests** |
-
-### Verification
-
-After each tool category is tested, run:
-```bash
-npm run test:coverage
-```
-
-Ensure coverage increases and meets targets.
-
-## Test Writing Guidelines
-
-### Naming Convention
-```typescript
-// Good
-test('ckan_package_search with facets returns aggregated data', () => { ... });
-
-// Bad
-test('search works', () => { ... });
-```
-
-### AAA Pattern
-```typescript
-test('search with pagination', async () => {
-  // Arrange
-  const params = { q: 'test', start: 10, rows: 20 };
-
-  // Act
-  const result = await ckan_package_search(params);
-
-  // Assert
-  expect(result.content[0].text).toContain('Showing 10-20 of');
-});
-```
-
-### One Assertion Per Test
-```typescript
-// Good
-test('truncates long descriptions', async () => {
-  const result = await ckan_package_show({ package_id: 'long-desc' });
-  expect(result.content[0].text).toContain('[Response truncated]');
-});
-
-// Bad
-test('package_show works', async () => {
-  const result = await ckan_package_show({ package_id: 'pkg' });
-  expect(result).toBeDefined();
-  expect(result.content).toBeDefined();
-  expect(result.content[0]).toBeDefined();
-  expect(result.content[0].text).toBeDefined();
-});
-```
-
-## Implementation Order
-
-1. **Package Tools** (highest priority)
-   - Most complex
-   - Most used
-   - Largest code block (~350 lines)
-
-2. **Organization Tools** (medium priority)
-   - Medium complexity
-   - Medium code block (~341 lines)
-
-3. **DataStore Tool** (lower priority)
-   - Simpler logic
-   - Smaller code block (~146 lines)
-   - May have platform-specific behavior
-
-## Future Enhancements
-
-### Short Term
-- Contract tests for CKAN API responses
-- Visual regression tests for markdown output
-- Performance benchmarks for queries
-
-### Medium Term
-- Increase coverage to 90%+
-- Add contract tests for all tool schemas
-- Add integration with real test CKAN instance (optional)
-
-### Long Term
-- Fuzz testing for input validation
-- Chaos testing for error handling
-- Property-based testing
-
-## Conclusion
-
-This test expansion follows the proven patterns from the initial testing proposal, focusing on:
-
-- **Consistency**: Same structure, fixtures, and patterns
-- **Completeness**: Cover all tool categories
-- **Quality**: Test both happy paths and error scenarios
-- **Maintainability**: Simple, focused, well-documented tests
-
-The incremental implementation ensures we achieve 80%+ coverage while keeping the work manageable and debuggable.

package/openspec/changes/archive/2026-01-08-expand-test-coverage-specs/proposal.md

@@ -1,161 +0,0 @@
-# Proposal: Expand Test Coverage to Remaining Tools
-
-**Status:** Completed
-**Created:** 2026-01-08
-**Author:** OpenCode
-**Related:** Archived proposal "add-automated-tests"
-
-## Summary
-
-Add integration tests for the remaining MCP tools (package, organization, datastore) to achieve 80%+ code coverage and improve test reliability.
-
-## Motivation
-
-The initial automated testing implementation successfully established the testing foundation but only covered:
-- Utility functions (100% coverage)
-- Status tool (partial coverage)
-- Overall coverage: ~68%
-
-To meet the 80% coverage target and ensure reliability, we need to test the remaining three tool categories that represent the majority of the codebase:
-- Package tools: ~350 lines
-- Organization tools: ~341 lines
-- DataStore tools: ~146 lines
-
-Adding these tests will:
-- Increase overall coverage to 80%+
-- Catch bugs in tool implementations
-- Document expected behavior through tests
-- Enable confident refactoring of tool code
-- Provide safety net for future changes
-
-## Scope
-
-### Included
-- **Integration tests** for package tools (ckan_package_search, ckan_package_show)
-- **Integration tests** for organization tools (ckan_organization_list, ckan_organization_show, ckan_organization_search)
-- **Integration tests** for datastore tool (ckan_datastore_search)
-- Additional fixtures for error scenarios if needed
-- Tests for both markdown and JSON output formats
-- Tests for edge cases (empty results, pagination, filters)
-
-### Excluded
-- E2e tests with real CKAN servers (already excluded)
-- Performance/benchmark tests (future enhancement)
-- UI/interaction tests (no UI in this project)
-- Testing MCP SDK internals (out of scope)
-- Testing external libraries (axios, zod, express)
-
-## Proposed Changes
-
-### Test Strategy
-
-Following the same pattern established in the first proposal:
-1. Use Vitest with mocked axios
-2. Reuse existing fixtures from `tests/fixtures/`
-3. Create new fixtures only if needed
-4. Test success and error scenarios
-5. Test both markdown and JSON output formats
-
-### Test Coverage Breakdown
-
-#### Package Tools (~6 tests)
-- Basic search with query
-- Search with facets
-- Search with pagination
-- Search with sorting
-- Search with filter query
-- Show package details
-
-#### Organization Tools (~8 tests)
-- List organizations
-- List with sorting
-- Show organization details
-- Search organizations
-- Error scenarios (404, invalid ID)
-
-#### DataStore Tool (~6 tests)
-- Basic query
-- Query with filters
-- Query with sorting
-- Query with pagination
-- Error scenarios
-- Output format validation
-
-### Coverage Target
-
-**Goal**: Increase from ~68% to 80%+
-
-**Expected breakdown after completion**:
-- Utils: 100% (already achieved)
-- Status tool: 75-85%
-- Package tools: 75-85%
-- Organization tools: 75-85%
-- DataStore tool: 75-85%
-- **Overall**: 80%+
-
-### Incremental Approach
-
-1. Start with package tools (largest, most complex)
-2. Add organization tests
-3. Add datastore tests
-4. Validate coverage after each batch
-5. Adjust if needed
-
-## Alternatives Considered
-
-1. **Test all tools at once**
-   - *Rejected*: Too large, hard to debug, follow incremental pattern
-
-2. **Skip integration tests, only unit tests**
-   - *Rejected*: Would miss tool behavior and CKAN API interactions
-
-3. **Use real CKAN servers for testing**
-   - *Rejected*: Already excluded in original proposal (slow, unreliable)
-
-4. **Test only happy paths, ignore errors**
-   - *Rejected*: Error handling is critical for robust tools
-
-## Impact Assessment
-
-### Benefits
-- + Increased coverage from 68% to 80%+
-- + Better bug detection in tool code
-- + Safer refactoring of tool implementations
-- + Documented expected behavior for all tools
-- + Higher confidence in code quality
-
-### Risks
-- - Initial time investment for writing ~20 more tests
-- - Test maintenance overhead as tool code evolves
-- - Possible need for additional fixtures
-
-### Mitigation
-- Reuse existing fixtures where possible
-- Follow established test patterns
-- Write tests incrementally, validate after each batch
-- Keep tests simple and focused
-
-## Open Questions
-
-None - reusing established patterns from first proposal.
-
-## Dependencies
-
-Depends on:
-- Proposal "add-automated-tests" (archived) - provides test infrastructure and fixtures
-- Existing fixtures in `tests/fixtures/` - may need additions
-
-## Success Criteria
-
-- [ ] All package tools have integration tests
-- [ ] All organization tools have integration tests
-- [ ] DataStore tool has integration tests
-- [ ] Tests pass (green CI if exists)
-- [ ] Overall coverage meets 80% threshold
-- [ ] Tests follow established patterns from first proposal
-- [ ] Documentation updated if needed
-- [ ] Validation: `openspec validate expand-test-coverage --strict` passes
-
-## Notes
-
-This proposal is a direct continuation of the "add-automated-tests" proposal. All testing infrastructure (Vitest, fixtures, patterns) is already in place, so the focus is purely on writing the actual test files for the remaining tools.

package/openspec/changes/archive/2026-01-08-expand-test-coverage-specs/tasks.md

@@ -1,162 +0,0 @@
-# Tasks: Expand Test Coverage to Remaining Tools
-
-Ordered list of work items to add integration tests for package, organization, and datastore tools.
-
-## Phase 1: Package Tools
-
-### ckan_package_search Tests
-
-- [x] Create `tests/integration/package.test.ts`
-- [x] Write test for basic search with query parameter
-- [x] Write test for search returning empty results
-- [x] Write test for search with pagination (start, rows)
-- [x] Write test for search with sorting (sort parameter)
-- [x] Write test for search with filter query (fq parameter)
-- [x] Write test for search with multiple filter queries
-- [x] Write test for search with complex query (q + fq + facets)
-- [x] Write test validating markdown output format
-- [x] Write test handling 404 error for invalid query
-- [x] Write test handling server error
-- [x] Write test for faceting with facet_field
-- [x] Run package tool tests and verify all pass
-
-### ckan_package_show Tests
-
-- [x] Write test for showing package with valid ID
-- [x] Write test for package with multiple resources
-- [x] Write test for package with tags
-- [x] Write test for package with organization
-- [x] Write test for package without resources
-- [x] Write test handling 404 error for invalid package ID
-- [x] Write test handling server error when fetching package
-- [x] Write test validating JSON output format
-- [x] Run package tool tests and verify all pass
-
-## Phase 2: Organization Tools
-
-### ckan_organization_list Tests
-
-- [x] Create `tests/integration/organization.test.ts`
-- [x] Write test for listing all organizations (default)
-- [x] Write test for returning list of organizations
-- [x] Write test for listing with empty results
-- [x] Run organization tool tests and verify all pass
-
-### ckan_organization_show Tests
-
-- [x] Write test for showing organization with valid ID
-- [x] Write test for organization with users
-- [x] Write test for organization with packages
-- [x] Write test handling 404 error for invalid organization ID
-- [x] Write test handling server error when fetching organization
-- [x] Run organization tool tests and verify all pass
-
-### ckan_organization_search Tests
-
-- [x] Write test for searching organizations by pattern
-- [x] Write test for search returning empty results
-- [x] Write test handling server error when searching organizations
-- [x] Run organization tool tests and verify all pass
-
-## Phase 3: DataStore Tool
-
-### ckan_datastore_search Tests
-
-- [x] Create `tests/integration/datastore.test.ts`
-- [x] Write test for basic query with resource_id
-- [x] Write test for query with filters
-- [x] Write test for query with sorting
-- [x] Write test for query with pagination (limit, offset)
-- [x] Write test for query with field list (fields parameter)
-- [x] Write test handling 404 error for invalid resource_id
-- [x] Write test handling server error when querying DataStore
-- [x] Write test handling timeout when querying DataStore
-- [x] Write test validating JSON output format
-- [x] Write test for empty query results
-- [x] Write test for maximum limit (32000)
-- [x] Write test handling large result sets (50000+ records)
-- [x] Run datastore tool tests and verify all pass
-
-## Phase 4: Additional Fixtures
-
-- [x] Create error fixtures if needed for tool-specific scenarios
-
-## Phase 5: Validation
-
-- [x] Run `npm test` and verify all tests pass
-- [x] Verify package tools coverage meets target
-- [x] Verify organization tools coverage meets target
-- [x] Verify datastore tool coverage meets target
-- [x] Verify overall coverage meets 80% threshold
-- [ ] Run `npm run test:coverage` and check coverage report
-- [ ] Check that all tests follow established patterns
-
-## Phase 6: Documentation
-
-- [ ] Update tests/README.md with new test files
-- [ ] Add examples from new test files to documentation
-- [ ] Update CLAUDE.md if needed with testing notes
-- [ ] Update proposal status to completed
-
-## Dependencies
-
-- Phase 1 must complete before Phase 2
-- Phase 2 must complete before Phase 3
-- Phase 4 can be done in parallel with Phases 1-3 as needed
-- Phase 5 depends on completion of Phases 1, 2, 3
-- Phase 6 depends on Phase 5 completion
-
-## Notes
-
-- Reuse existing fixtures where possible
-- Follow AAA pattern (Arrange, Act, Assert)
-- Use descriptive test names
-- Test both success and error scenarios
-- Validate both markdown and JSON output formats
-- Keep tests simple and focused
-- Run tests in watch mode during development: `npm run test:watch`
-- Generate coverage report: `npm run test:coverage`
-- Check existing tests (`tests/integration/status.test.ts`) for reference
-
-## Test File Creation Template
-
-When creating new test files:
-
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import axios from 'axios';
-import { makeCkanRequest } from '../../src/utils/http';
-import { ckan_package_search, ckan_package_show } from '../../src/tools/package';
-import relevantFixture from '../fixtures/responses/relevant-fixture.json';
-
-vi.mock('axios');
-
-describe('ckan_package_search', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('descriptive test name', async () => {
-    vi.mocked(axios.get).mockResolvedValue({ data: relevantFixture });
-
-    const result = await ckan_package_search({
-      server_url: 'http://demo.ckan.org',
-      q: 'test'
-    });
-
-    // Assertions
-    expect(result).toBeDefined();
-    expect(result.content[0].text).toContain('...');
-  });
-});
-```
-
-## Expected Outcomes
-
-After completing all phases:
-- ~78 new tests added (29 package + 24 organization + 18 datastore + 2 status + 6 unit = 79)
-- Overall coverage increased from ~68% to 80%+
-- All tool categories have integration tests
-- Tests follow established patterns
-- Tests documented in README
-- CI passes (if configured)