@aborruso/ckan-mcp-server 0.4.16 → 0.4.18

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

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

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

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

package/openspec/changes/archive/2026-01-10-add-ckan-find-relevant-datasets/proposal.md

@@ -1,17 +0,0 @@
-# Change: Add ckan_find_relevant_datasets tool
-
-## Why
-Ranked discovery helps surface the best datasets for a query without manual sorting.
-
-## What Changes
-- Add MCP tool `ckan_find_relevant_datasets` wrapping `package_search`.
-- Score results using weighted fields (title, notes, tags, organization).
-- Return top N datasets with score breakdown.
-
-## Impact
-- Affected specs: `ckan-insights`
-- Affected code: `src/tools/package.ts` (or new insights module)
-
-## Open Questions
-- Default weights for title/notes/tags/organization?
-- Default `limit` when omitted?

package/openspec/changes/archive/2026-01-10-add-ckan-find-relevant-datasets/specs/ckan-insights/spec.md

@@ -1,7 +0,0 @@
-## ADDED Requirements
-### Requirement: Find relevant datasets
-The system SHALL provide a `ckan_find_relevant_datasets` tool that accepts `server_url`, `query`, `limit`, and optional weights for title, notes, tags, and organization, and returns the top N datasets ranked by score with a per-field score breakdown.
-
-#### Scenario: Ranked results returned
-- **WHEN** the tool is invoked with a query and limit
-- **THEN** the system uses `package_search` results to return the top N datasets with numeric scores and field contributions

package/openspec/changes/archive/2026-01-10-add-ckan-find-relevant-datasets/tasks.md

@@ -1,6 +0,0 @@
-## 1. Implementation
-- [ ] 1.1 Add tool schema and registration
-- [ ] 1.2 Implement weighted scoring + ranking
-- [ ] 1.3 Define markdown/json output shape
-- [ ] 1.4 Add fixtures + tests
-- [ ] 1.5 Update README/EXAMPLES