Portainer MCP

# 202504-2: Strict versioning for tools.yaml file **Date**: 08/04/2025 ### Context With tools.yaml being externalized and allowing user customization, there's a risk of incompatibility between the tool definitions and the application code. Changes to the schema or expected tool definitions could lead to runtime errors that are difficult to diagnose. ### Decision Implement strict versioning for the tools.yaml file with version validation at startup. The application will define a required/current version, check if the provided tools.yaml file uses this version, and fail fast if there's a version mismatch. ### Rationale 1. **Compatibility Assurance** - Prevents runtime errors caused by incompatible tool definitions - Clearly communicates version requirements to users - Makes version mismatches immediately apparent 2. **Error Handling** - Provides clear error messages about version mismatches - Fails fast instead of letting subtle errors occur during operation - Guides users toward proper resolution 3. **Recovery Path** - Users can update their tools.yaml file manually to match the required version - Alternatively, users can simply delete their customized file and let the application regenerate it - Regeneration uses the embedded version which is guaranteed to be compatible 4. **Upgrade Management** - Clear versioning creates explicit upgrade paths - Version checks provide a mechanism to enforce schema migrations - Makes breaking changes in tool definitions more manageable ### Trade-offs **Benefits** - Prevents subtle runtime errors - Provides clear error messages - Offers straightforward recovery options - Makes version incompatibilities immediately apparent - Simplifies upgrade paths **Challenges** - Need to manage version numbers across releases - Must communicate version changes to users - Requires additional validation logic at startup - Necessitates documentation of version compatibility