@aborruso/ckan-mcp-server 0.3.1

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

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

package/openspec/changes/archive/2026-01-08-translate-project-to-english/proposal.md

@@ -0,0 +1,115 @@
+# Proposal: Translate Project to English
+
+**Status:** Completed
+**Created:** 2026-01-08
+**Author:** OpenCode
+**Archived:** 2026-01-08 (as expand-test-coverage-specs)
+
+## Summary
+
+Translate the CKAN MCP Server project documentation from Italian to English to improve accessibility and align with international open data standards.
+
+## Motivation
+
+The CKAN MCP Server project is currently documented in Italian, which limits its accessibility to the global open data community. Since:
+- CKAN is an international platform used by 500+ portals worldwide
+- The MCP protocol and most technical documentation are in English
+- The target audience (data scientists, developers, researchers) is primarily English-speaking
+- The source code comments are already in English
+
+Translating the documentation will:
+- Lower adoption barriers for international users
+- Improve discoverability through search engines
+- Align with CKAN's global community
+- Maintain consistency with the already-English codebase
+
+## Scope
+
+### Included
+- **README.md**: Main project documentation (285 lines)
+- **EXAMPLES.md**: Usage examples and workflows (427 lines)
+
+### Excluded
+- Source code files (already in English)
+- SKILL.md (English skill documentation)
+- AGENTS.md, LOG.md, other internal docs
+- Package metadata (package.json, package-lock.json)
+- API/tool names (already English)
+- User-facing tool outputs (already English)
+
+## Proposed Changes
+
+### Files to Translate
+
+1. **README.md**
+   - Project description and features
+   - Installation and usage instructions
+   - Tool descriptions and examples
+   - Troubleshooting guide
+   - Links and support section
+
+2. **EXAMPLES.md**
+   - Connection tests
+   - Italy-specific examples (dati.gov.it)
+   - USA examples (data.gov)
+   - Demo CKAN examples
+   - DataStore queries
+   - Advanced Solr queries
+   - Complete workflows
+
+### Translation Approach
+
+- Direct translation maintaining technical accuracy
+- Preserve all code examples (already in English)
+- Keep Italian portal names, organization titles, and data values in Italian (e.g., "Regione Siciliana")
+- Maintain structure and formatting
+- Use official CKAN terminology (DataStore, faceting, Solr)
+- Use ISO format for dates
+- Keep current examples (Italy, USA, demo.ckan.org)
+
+## Alternatives Considered
+
+1. **Bilingual documentation**: Keep Italian and add English sections
+   - *Rejected*: Increases maintenance burden, creates version drift issues
+
+2. **Auto-translation tools only**: Use machine translation without review
+   - *Rejected*: Quality concerns, potential technical errors
+
+3. **No translation**: Keep Italian only
+   - *Rejected*: Limits project adoption and community growth
+
+## Impact Assessment
+
+### Benefits
+- + Improved accessibility for international users
+- + Better alignment with CKAN global community
+- + Consistent language across code and documentation
+- + Easier onboarding for new contributors
+
+### Risks
+- - Loss of Italy-specific context in translation
+- - Possible translation errors in technical terms
+- - Need to maintain English for future updates
+
+### Mitigation
+- Review all technical translations against CKAN API documentation
+- Keep Italian portal names and organization titles in Italian
+- Use official CKAN terminology for technical terms
+
+## Open Questions
+
+None - clarified with project owner.
+
+## Dependencies
+
+None - this is a documentation-only change with no code modifications.
+
+## Success Criteria
+
+- [ ] README.md fully translated to English
+- [ ] EXAMPLES.md fully translated to English
+- [ ] All technical terms accurate and consistent with CKAN API docs
+- [ ] Code examples unchanged
+- [ ] Markdown formatting preserved
+- [ ] No broken links or references
+- [ ] Validation: `openspec validate translate-project-to-english --strict` passes

package/openspec/changes/archive/2026-01-08-translate-project-to-english/specs/documentation-language/spec.md

@@ -0,0 +1,32 @@
+# Spec: Documentation Language
+
+Defines the language requirements for project documentation.
+
+## ADDED Requirements
+
+### Requirement: Project documentation in English
+
+The project SHALL provide all user-facing documentation in English to ensure accessibility for the international open data community.
+
+#### Scenario: English documentation
+Given a CKAN MCP Server project
+When a user reads the documentation
+Then the documentation is in English
+And code examples are in English
+And technical terms follow CKAN API terminology
+
+### Requirement: Preserve multilingual examples
+
+The project SHALL preserve non-English portal names, organization titles, or data values in their original language to accurately reflect real-world CKAN portals.
+
+#### Scenario: Italian portal example
+Given an example using dati.gov.it
+When the example references Italian organizations
+Then organization names remain in Italian (e.g., "Regione Siciliana")
+And descriptions are in English
+
+#### Scenario: Non-English data values
+Given an example query with data filters
+When the data contains non-English values
+Then those values are preserved in their original language
+And the surrounding documentation explains the context in English

package/openspec/changes/archive/2026-01-08-translate-project-to-english/tasks.md

@@ -0,0 +1,115 @@
+# Tasks: Translate Project to English
+
+Ordered list of work items to translate the project documentation to English.
+
+## Phase 1: Preparation
+
+- [x] Create backup copies of README.md and EXAMPLES.md
+- [x] Review CKAN API documentation for standard English terminology
+- [x] Identify technical terms requiring precise translation (e.g., "DataStore", "facet", "Solr")
+- [x] Note any Italy-specific context to preserve (e.g., portal names, organization titles)
+
+## Phase 2: Translate README.md
+
+- [x] Translate header and project description (lines 1-4)
+- [x] Translate features section (lines 5-13)
+- [x] Translate installation instructions (lines 15-26)
+- [x] Translate usage section (lines 28-42)
+- [x] Translate Claude Desktop configuration (lines 44-61)
+- [x] Translate available tools section (lines 63-83)
+- [x] Translate usage examples (lines 85-140)
+- [x] Translate supported CKAN portals section (lines 142-152)
+- [x] Translate advanced Solr queries section (lines 154-181)
+- [x] Translate project structure section (lines 183-194)
+- [x] Translate development section (lines 196-221)
+- [x] Translate troubleshooting section (lines 223-252)
+- [x] Translate contributing section (lines 254-262)
+- [x] Translate license and useful links sections (lines 264-274)
+- [x] Translate support section and footer (lines 276-285)
+- [x] Verify all links remain functional
+- [x] Check markdown formatting consistency
+
+## Phase 3: Translate EXAMPLES.md
+
+- [x] Translate header and introduction (lines 1-4)
+- [x] Translate connection tests section (lines 5-21)
+- [x] Translate Italy examples header (line 23)
+- [x] Translate recent datasets example (lines 25-33)
+- [x] Translate COVID-19 datasets example (lines 35-42)
+- [x] Translate Regione Siciliana datasets example (lines 44-52)
+- [x] Translate organization search examples (lines 54-73)
+- [x] Translate wildcard organization search example (lines 75-85)
+- [x] Translate organization statistics examples (lines 87-95)
+- [x] Translate format statistics example (lines 97-105)
+- [x] Translate organization list example (lines 107-115)
+- [x] Translate organization details example (lines 117-124)
+- [x] Translate CSV datasets example (lines 126-133)
+- [x] Translate USA examples header (line 135)
+- [x] Translate government datasets example (lines 137-144)
+- [x] Translate tag-based datasets example (lines 146-153)
+- [x] Translate demo CKAN examples (lines 155-178)
+- [x] Translate DataStore queries header (line 180)
+- [x] Translate basic DataStore query example (lines 182-189)
+- [x] Translate filtered DataStore query example (lines 191-201)
+- [x] Translate sorted DataStore query example (lines 203-211)
+- [x] Translate advanced Solr queries header (line 213)
+- [x] Translate AND combination example (lines 215-222)
+- [x] Translate OR combination example (lines 224-231)
+- [x] Translate NOT exclusion example (lines 233-240)
+- [x] Translate title search example (lines 242-249)
+- [x] Translate description search example (lines 251-258)
+- [x] Translate wildcard search example (lines 260-267)
+- [x] Translate date range filter example (lines 269-276)
+- [x] Translate recent datasets example (lines 278-286)
+- [x] Translate complete workflows header (line 288)
+- [x] Translate workflow 1: regional dataset analysis (lines 290-314)
+- [x] Translate workflow 2: monitoring new publications (lines 316-334)
+- [x] Translate workflow 3: data coverage analysis (lines 336-370)
+- [x] Translate workflow 4: thematic search (lines 372-401)
+- [x] Translate output formats section (lines 403-418)
+- [x] Translate notes section (lines 420-427)
+- [x] Verify all code examples unchanged
+- [x] Check markdown formatting consistency
+
+## Phase 4: Review and Validation
+
+- [x] Proofread README.md for English grammar and flow
+- [x] Proofread EXAMPLES.md for English grammar and flow
+- [x] Verify technical terminology matches CKAN API docs
+- [x] Check all tool names are consistent with code
+- [x] Ensure all URLs remain correct
+- [x] Validate markdown syntax using a linter or manual check
+- [x] Test all code examples for syntax errors
+- [x] Confirm no Italian text remains in translated sections
+- [x] Verify formatting, spacing, and indentation preserved
+- [x] Check section headings follow markdown conventions
+
+## Phase 5: Documentation Updates
+
+- [x] Update README.md to reflect English-only documentation
+- [x] Update any references to Italian docs in project files
+- [x] Update project.md if it references language conventions
+- [x] Verify package.json metadata remains accurate
+- [x] Add note about translation history if appropriate
+
+## Phase 6: Final Verification
+
+- [x] Run `openspec validate translate-project-to-english --strict`
+- [x] Resolve all validation errors
+- [x] Final review of translated files
+- [x] Prepare commit message (concise, following project conventions)
+
+## Dependencies
+
+- All tasks in Phase 2 and Phase 3 can be done in parallel after Phase 1
+- Phase 4 depends on completion of Phase 2 and Phase 3
+- Phase 5 depends on completion of Phase 4
+- Phase 6 is final verification, depends on all previous phases
+
+## Notes
+
+- Preserve all Italian proper nouns (Regione Siciliana, Autorità Idrica Toscana, etc.)
+- Keep all code examples and function names in English
+- Maintain existing markdown structure and formatting
+- Use standard English technical documentation style
+- Refer to CKAN API docs (https://docs.ckan.org/en/latest/api/) for terminology