@aborruso/ckan-mcp-server 0.3.1

package/openspec/changes/archive/2026-01-08-add-mcp-resources/specs/mcp-resources/spec.md

@@ -0,0 +1,92 @@
+# MCP Resources Capability
+
+## ADDED Requirements
+
+### Requirement: Dataset Resource Template
+
+The system SHALL expose a resource template for accessing CKAN dataset metadata via the URI pattern `ckan://{server}/dataset/{id}`.
+
+#### Scenario: Read dataset metadata successfully
+
+- **WHEN** client reads `ckan://dati.gov.it/dataset/vaccini-covid`
+- **THEN** server returns JSON with complete dataset metadata including title, description, resources, organization, tags
+
+#### Scenario: Dataset not found
+
+- **WHEN** client reads `ckan://demo.ckan.org/dataset/nonexistent-id`
+- **THEN** server returns error indicating dataset not found
+
+#### Scenario: Server unreachable
+
+- **WHEN** client reads `ckan://invalid-server.example/dataset/test`
+- **THEN** server returns error indicating server unreachable
+
+### Requirement: Resource Resource Template
+
+The system SHALL expose a resource template for accessing CKAN resource metadata via the URI pattern `ckan://{server}/resource/{id}`.
+
+#### Scenario: Read resource metadata successfully
+
+- **WHEN** client reads `ckan://dati.gov.it/resource/abc-123-def`
+- **THEN** server returns JSON with resource metadata including name, format, URL, size, and download link
+
+#### Scenario: Resource not found
+
+- **WHEN** client reads `ckan://demo.ckan.org/resource/invalid-id`
+- **THEN** server returns error indicating resource not found
+
+### Requirement: Organization Resource Template
+
+The system SHALL expose a resource template for accessing CKAN organization metadata via the URI pattern `ckan://{server}/organization/{name}`.
+
+#### Scenario: Read organization metadata successfully
+
+- **WHEN** client reads `ckan://dati.gov.it/organization/regione-toscana`
+- **THEN** server returns JSON with organization metadata including title, description, and dataset count
+
+#### Scenario: Organization not found
+
+- **WHEN** client reads `ckan://demo.ckan.org/organization/nonexistent-org`
+- **THEN** server returns error indicating organization not found
+
+### Requirement: URI Scheme Parsing
+
+The system SHALL parse `ckan://` URIs extracting server hostname and path components.
+
+#### Scenario: Parse standard URI
+
+- **WHEN** URI is `ckan://dati.gov.it/dataset/test-id`
+- **THEN** server extracts: server=`https://dati.gov.it`, type=`dataset`, id=`test-id`
+
+#### Scenario: Parse URI with www prefix
+
+- **WHEN** URI is `ckan://www.dati.gov.it/dataset/test-id`
+- **THEN** server extracts: server=`https://www.dati.gov.it`, type=`dataset`, id=`test-id`
+
+#### Scenario: Reject malformed URI
+
+- **WHEN** URI is `ckan://invalid` (missing path)
+- **THEN** server returns validation error
+
+### Requirement: Resource Response Format
+
+The system SHALL return resource content as JSON with standard MCP resource response structure.
+
+#### Scenario: JSON response structure
+
+- **WHEN** client reads any valid resource URI
+- **THEN** response contains `contents` array with `uri`, `mimeType` (application/json), and `text` (JSON string)
+
+#### Scenario: Large response truncation
+
+- **WHEN** resource content exceeds CHARACTER_LIMIT
+- **THEN** response is truncated to CHARACTER_LIMIT with truncation indicator
+
+### Requirement: Resource Discovery
+
+The system SHALL list available resource templates when client requests resource list.
+
+#### Scenario: List resource templates
+
+- **WHEN** client calls `resources/listTemplates`
+- **THEN** server returns list of available URI templates with descriptions

package/openspec/changes/archive/2026-01-08-add-mcp-resources/tasks.md

@@ -0,0 +1,56 @@
+# Tasks: Add MCP Resource Templates
+
+## 1. Setup
+
+- [x] 1.1 Create `src/resources/` directory
+- [x] 1.2 Create `src/resources/index.ts` with `registerAllResources()` export
+
+## 2. URI Utilities
+
+- [x] 2.1 Create URI parsing function for `ckan://` scheme
+- [x] 2.2 Add validation for malformed URIs
+- [x] 2.3 Handle edge cases (www prefix, trailing slashes)
+
+## 3. Dataset Resource
+
+- [x] 3.1 Create `src/resources/dataset.ts`
+- [x] 3.2 Register template `ckan://{server}/dataset/{id}`
+- [x] 3.3 Implement handler using `makeCkanRequest('package_show')`
+- [x] 3.4 Return JSON response with dataset metadata
+
+## 4. Resource Resource
+
+- [x] 4.1 Create `src/resources/resource.ts`
+- [x] 4.2 Register template `ckan://{server}/resource/{id}`
+- [x] 4.3 Implement handler using `makeCkanRequest('resource_show')`
+- [x] 4.4 Include download URL in response
+
+## 5. Organization Resource
+
+- [x] 5.1 Create `src/resources/organization.ts`
+- [x] 5.2 Register template `ckan://{server}/organization/{name}`
+- [x] 5.3 Implement handler using `makeCkanRequest('organization_show')`
+- [x] 5.4 Return JSON response with organization metadata
+
+## 6. Integration
+
+- [x] 6.1 Import `registerAllResources` in `src/index.ts`
+- [x] 6.2 Call `registerAllResources(server)` after tool registration
+- [x] 6.3 Build and verify no compilation errors
+
+## 7. Testing
+
+- [x] 7.1 Create `tests/integration/resources.test.ts`
+- [x] 7.2 Add tests for dataset resource template
+- [x] 7.3 Add tests for resource resource template
+- [x] 7.4 Add tests for organization resource template
+- [x] 7.5 Add tests for URI parsing edge cases
+- [x] 7.6 Add tests for error handling (invalid URI, server errors)
+- [x] 7.7 Run full test suite, ensure 100% pass
+
+## 8. Documentation
+
+- [x] 8.1 Update README.md with resource templates section
+- [x] 8.2 Update CLAUDE.md architecture section
+- [x] 8.3 Add examples to EXAMPLES.md (deferred - basic examples in README)
+- [x] 8.4 Update LOG.md with changes

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

@@ -0,0 +1,355 @@
+# 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

@@ -0,0 +1,161 @@
+# 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.