Release v0.7.0: Comprehensive MCP Host Configuration System #42
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
added 30 commits
September 19, 2025 00:11
Version number were wrong because of version tag detection issue by `semantic-release`. This would fail only for this v0.6.3. Next updates will have correct version number.
Add automated Discord notifications for both stable releases and pre-releases: - release-discord-notification.yml: Full announcements with role mentions for stable releases - prerelease-discord-notification.yml: Testing-focused notifications without role pings Features: - Personalized "Cracking Shells" branding with MCP references - Direct links to GitHub release pages for changelog access - Role mentions (<@&1418053865818951721> --> ) for stable releases only - Different visual styling (green vs orange) to distinguish release types - Triggers on 'released' and 'prereleased' events respectively Integrates with existing semantic-release workflow for automated release management.
Add comprehensive backup and restore functionality for MCP host configuration files with atomic operations and Pydantic data validation. Key components: - MCPHostConfigBackupManager: Core backup management with timestamped backups - AtomicFileOperations: Safe file operations with rollback capability - BackupInfo/BackupResult: Pydantic models with validation - BackupAwareOperation: Base class for backup-aware operations Features: - Automatic backup creation before configuration changes - Manual backup restoration by hostname - Backup listing and management with cleanup capabilities - Atomic file operations preventing data corruption - Support for all MCP host types (claude-desktop, claude-code, vscode, cursor, lmstudio, gemini) - Microsecond-precision timestamps for unique backup identification Backup location: ~/.hatch/mcp_host_config_backups/ Naming convention: mcp.json.<hostname>.<timestamp> Resolves core backup system requirements from final design specification.
Extend existing test data utilities with MCPBackupTestDataLoader for host-agnostic test configurations. Changes: - Add MCPBackupTestDataLoader class to test_data_utils.py - Create host-agnostic test configuration templates (simple_server, complex_server, empty_config) - Integrate with existing TestDataLoader hierarchy - Support for dynamic test configuration generation Test configurations are completely host-agnostic and validate backup system functionality without depending on specific host JSON structures. Follows CrackingShells testing standards and integrates with existing Hatch test infrastructure.
Add complete test suite for core backup manager functionality with host-agnostic design. Test coverage: - Backup directory creation and permissions - Successful backup creation for all supported host types - Backup content integrity validation - Multiple backup management and isolation - Pydantic model validation for BackupInfo and BackupResult - Backup cleanup operations (older_than_days, keep_count) - Error handling for nonexistent files and unsupported hostnames - Host isolation verification across multiple backup operations All tests use host-agnostic configurations and validate backup system functionality without depending on specific host JSON structures. Uses wobble decorators (@regression_test) and follows CrackingShells testing standards. Test results: 11/11 tests passing (100% success rate)
Add comprehensive test suite for atomic file operations and backup-aware operation patterns. AtomicFileOperations test coverage: - Atomic write with automatic backup creation - Atomic write with backup skipping - Atomic copy operations with integrity verification - Failure handling with automatic rollback - Temporary file cleanup on operation failure BackupAwareOperation test coverage: - Explicit backup preparation workflow - No-backup mode operation - Backup failure exception handling - Rollback functionality on operation failure - Integration with MCPHostConfigBackupManager All tests use host-agnostic configurations and validate the simplified API design that forces consumers to explicitly acknowledge backup creation. Uses wobble decorators (@regression_test) and follows CrackingShells testing standards. Test results: 11/11 tests passing (100% success rate)
Add comprehensive integration and performance test suite for end-to-end backup workflows. Integration test coverage (@integration_test): - Complete backup creation and restoration cycles - Multi-host backup management and isolation - Configuration update workflows with backup integration - Integration with existing Hatch test utilities - Backup-aware operation workflow patterns Performance test coverage (@slow_test): - Large configuration file backup performance (<1 second for 1000 servers) - Pydantic model validation performance (<0.1 second) - Concurrent backup operations across multiple hosts - Backup listing performance with many backup files (<0.1 second for 50 backups) All tests validate backup system integration with existing Hatch infrastructure while maintaining host-agnostic design principles. Uses wobble decorators (@integration_test, @slow_test, @regression_test) and follows CrackingShells testing standards. Test results: 9/9 tests passing (100% success rate)
Add comprehensive developer documentation for the MCP host configuration backup system following CrackingShells documentation standards. Documentation covers: - Core architecture components and design patterns - Host-agnostic design principles and implementation - Atomic file operations with rollback capabilities - Pydantic data models for type safety and validation - Performance characteristics and security model - Integration points with environment manager and CLI - Testing architecture and future extension plans Follows organizational documentation guidelines: - Focused technical clarity with compelling conciseness - Structured in docs/articles/devs/architecture/ as per standards - Cross-linked with existing Hatch architecture documentation - Includes code examples and implementation details Supports Phase 6 (Documentation) of development workflow.
Renamed the source code directory `hatch/mcp` to `hatch/mcp_host_config` to better reflect the fact that this is about controlling the mcp configuration files in hosts not MCP itself.
Add consolidated MCPServerConfig model supporting both local and remote server configurations with proper Pydantic v2 validation patterns. Key features: - Single model replacing separate local/remote server configs - Cross-field validation ensuring either command or URL (not both) - Field combination validation (args with command, headers with URL) - Environment data models with corrected single-server-per-package structure - Configuration result models for operation tracking Eliminates redundant HostServerConfig class and future extension fields (timeout, retry_attempts, ssl_verify) as specified in v2 requirements. Follows organizational standards for Pydantic v2 compatibility with @field_validator and @model_validator decorators.
Add MCPHostRegistry with @register_host_strategy decorator for automatic strategy discovery following established Hatchling patterns. Key components: - MCPHostRegistry: Central registry with decorator-based registration - @register_host_strategy: Decorator for automatic strategy registration - MCPHostStrategy: Abstract base class with inheritance validation - MCPHostConfigurationManager: Core manager with backup integration - Family-based host organization (Claude, Cursor, Independent) Features: - Singleton instance management for registered strategies - Inheritance validation ensuring proper MCPHostStrategy subclassing - Host availability detection and family mappings - Integration with backup system for atomic operations - Environment synchronization capabilities Replaces manual registration patterns with automatic discovery, reducing maintenance overhead and improving code organization.
Add concrete host strategy implementations using decorator registration with inheritance patterns for code reuse and maintainability. Strategy families: - Claude family: ClaudeDesktopHostStrategy, ClaudeCodeHostStrategy * Shared validation requiring absolute command paths * Common Anthropic-specific configuration handling - Cursor family: CursorHostStrategy, LMStudioHostStrategy * Flexible path handling and shared configuration format * Common cursor-based editor patterns - Independent: VSCodeHostStrategy, GeminiHostStrategy * Unique configuration formats and validation rules * Updated Gemini strategy based on official documentation Features: - @register_host_strategy decorator usage for all strategies - Inheritance-based code sharing within families - Host-specific configuration path resolution - Atomic configuration operations with backup integration - Consolidated MCPServerConfig model usage throughout Updates Gemini strategy to use official ~/.gemini/settings.json configuration path and mcpServers key structure.
Update module initialization to expose new MCP host configuration components and trigger automatic decorator-based strategy registration. Changes: - Import and expose MCPServerConfig, MCPHostType, and core models - Import and expose MCPHostRegistry and MCPHostConfigurationManager - Import strategies module to trigger @register_host_strategy decorators - Provide comprehensive public API for MCP host configuration functionality The import of strategies module ensures all host strategies are automatically registered with the MCPHostRegistry when the package is imported, following the established decorator pattern for automatic component discovery.
Add MCPHostConfigTestDataLoader class to existing test utilities for comprehensive MCP-specific test data management. Features: - Host configuration templates for all supported host types - Inheritance pattern templates (Claude family, Cursor family, Independent) - Corrected environment data structure templates (v2) - Consolidated MCPServerConfig templates (local and remote) - Automatic template generation with realistic test data Templates include: - Claude family: Absolute path requirements and Anthropic-specific settings - Cursor family: Flexible path handling and shared configuration format - Independent strategies: Unique formats for VSCode and Gemini - Environment data: Single-server-per-package constraint validation - Server configs: Local (command-based) and remote (URL-based) variants Extends existing TestDataLoader infrastructure while maintaining compatibility with current test patterns and organizational standards.
Implement 14 regression tests validating consolidated MCPServerConfig Pydantic model with both local and remote server configurations. Test coverage: - Local server validation (command, args, env fields) - Remote server validation (url, headers fields) - Cross-field validation preventing both command and URL - Field combination validation (args with command, headers with URL) - Empty/whitespace command validation with proper error messages - URL format validation requiring http:// or https:// protocols - Future extension field rejection (timeout, retry_attempts, ssl_verify) - Serialization roundtrip testing with model_dump/model_dump_json - JSON compatibility validation for API integration - Minimal configuration testing for both server types All tests use Pydantic v2 methods (model_dump, model_dump_json) and follow organizational testing standards with wobble framework integration. Validates elimination of redundant HostServerConfig class per v2 requirements.
Implement 10 regression tests validating @register_host_strategy decorator functionality and inheritance patterns following Hatchling patterns. Test coverage: - Decorator registration functionality with automatic strategy discovery - Inheritance pattern validation with Claude and Cursor family bases - Duplicate registration warning logging for strategy overrides - Inheritance validation ensuring MCPHostStrategy subclassing - Unknown host type error handling with available strategy listing - Singleton instance behavior for registered strategies - Host detection functionality with availability checking - Family-based host mappings (claude, cursor families) - Host configuration path resolution through registry - Strategy class validation and error reporting Tests validate decorator-based automatic registration replacing manual patterns, inheritance architecture for code reuse, and proper error handling for unknown or invalid host types. Includes family-based strategy organization tests demonstrating shared functionality between related host types (Claude Desktop/Code, Cursor/LMStudio).
Implement 7 regression tests validating MCPHostConfigurationManager core operations with backup system integration and error handling. Test coverage: - Server configuration operations with consolidated MCPServerConfig model - Server removal operations with existence validation - Unknown host type handling with proper error reporting - Strategy validation failure handling with detailed error messages - Environment synchronization with EnvironmentData integration - Empty environment handling with appropriate success responses - Backup integration testing with atomic operations Tests validate: - Integration between configuration manager and decorator registry - Proper error handling and ConfigurationResult reporting - Environment data structure compatibility with corrected v2 format - Backup system integration for atomic configuration operations - Host strategy validation and configuration writing workflows Uses temporary file system for isolated testing and validates real configuration file operations with JSON serialization. Demonstrates end-to-end functionality from server configuration through file system persistence.
Implement 12 regression tests validating corrected environment data structure integration with MCP host configuration system. Test coverage: - EnvironmentData validation with corrected v2 structure - Multi-host configuration validation across different host types - PackageHostConfiguration validation with server config integration - EnvironmentPackageEntry validation with inheritance patterns - Invalid host name rejection with supported host validation - Invalid package name format validation with proper error messages - MCP package extraction from environment data - Serialization roundtrip testing with datetime handling - Single-server-per-package constraint enforcement - JSON serialization compatibility for API integration - MCPHostType enum validation with all supported host types - Host type validation error handling for invalid values Tests validate the corrected environment data structure that enforces realistic single-server-per-package constraints, replacing the previous multiple-servers-per-package model. Demonstrates proper integration between environment management and MCP host configuration systems with comprehensive validation of data model relationships.
Add complete documentation suite for MCP host configuration management system following organizational documentation standards. Documentation includes: - Implementation Guide: Complete architecture overview, usage examples, testing information, and integration patterns - API Reference: Comprehensive API documentation with examples for all models, managers, strategies, and decorators - Performance considerations and error handling patterns - Migration guidance and future enhancement roadmap Key documentation features: - Decorator-based strategy registration patterns - Consolidated MCPServerConfig model usage examples - Inheritance architecture explanation (Claude/Cursor families) - Environment data structure with corrected v2 constraints - Integration with backup system for atomic operations - Comprehensive test coverage documentation (74 tests, 100% pass rate) Documentation demonstrates successful implementation of v2 architecture with decorator-based automatic discovery, consolidated Pydantic models, and inheritance patterns for code reuse and maintainability.
Replace inappropriate auto-generated documentation with proper user and developer documentation following organizational standards. Changes: - Remove auto-generated API reference (APIs are auto-generated in api/ directory) - Remove implementation guide that didn't guide implementation - Add proper architecture documentation explaining design patterns and extension points - Add developer implementation guide for extending MCP host support - Add user documentation focused on CLI usage and practical scenarios - Update navigation and index files with proper cross-references Documentation now follows organizational standards: - Focused, professional tone with technical clarity - Proper separation of user vs developer concerns - Value-driven content serving specific user needs - Integration with existing Hatch documentation structure - Follows mkdocs standards and navigation patterns User documentation covers: - Practical CLI usage examples for MCP host configuration - Multi-host configuration and synchronization - Backup and recovery procedures - Troubleshooting common issues - Integration with Hatch environments and package management Developer documentation covers: - Architecture patterns (decorator registration, inheritance) - Extension points for adding new host platforms - Implementation guide with concrete examples - Testing strategies and integration patterns - Design decisions and future enhancement opportunities
Implement Phase 3a: Core Package Management Enhancement with MCP integration following the approved CLI integration design specification. CLI Enhancements: - Add --host flag to 'hatch package add' for MCP host configuration - Add --no-mcp-config flag to skip automatic MCP configuration - Implement new 'hatch package sync' command for syncing package MCP servers - Add helper functions for host list parsing and user confirmation Implementation Details: - parse_host_list(): Parse comma-separated hosts or 'all' with validation - request_confirmation(): User confirmation following Hatch patterns - Enhanced package add with MCP host configuration integration - Package sync command with host validation and package existence checking - Proper error handling and user feedback for MCP operations Testing: - Add comprehensive test suite with 17 tests covering CLI functionality - Test host list parsing, confirmation prompts, and command execution - Follow CrackingShells testing standards with Wobble decorators - Maintain 100% compatibility with existing backend (91 tests passing) Integration: - Seamless integration with MCPHostConfigurationManager - Follows established Hatch CLI patterns and error handling - Maintains flag consistency with final design specification v5 - Preserves existing package management functionality Next Phase: Implement package-MCP integration with actual MCP server detection and configuration synchronization to host platforms.
Complete Phase 3b: Package-MCP Integration Commands using existing CrackingShells ecosystem APIs following DRY principles. Implementation Details: - Replace redundant MCP server detection with existing PackageService API - Use get_hatch_mcp_entry_point() for schema-aware entry point access - Implement get_package_mcp_server_config() using established patterns - Full package sync functionality with host configuration - Enhanced package add with actual MCP server configuration API Integration: - Leverage hatch_validator.package.package_service.PackageService - Follow existing patterns from environment_manager.py:716-727 - Schema-aware access supporting v1.2.0 and v1.2.1 packages - Proper error handling and user feedback CLI Functionality: - 'hatch package sync' with dry-run, confirmation, and backup options - 'hatch package add --host' with automatic MCP configuration - Comprehensive error handling and progress reporting - Success/failure reporting with detailed status messages Testing: - Updated 20 CLI tests to match new implementation behavior - Added tests for get_package_mcp_server_config() function - Comprehensive coverage of success and error scenarios - Maintained 100% compatibility with existing backend (94 tests passing) Quality Improvements: - Removed redundant code in favor of existing APIs - Proper separation of concerns and DRY compliance - Consistent error messages and user experience - Schema version abstraction through PackageService Next Phase: Implement discovery and listing commands for comprehensive MCP host management functionality.
Add comprehensive MCP discovery and listing functionality: Core Commands: - hatch mcp discover hosts: Detect available MCP host platforms - hatch mcp discover servers: Find MCP servers in environment packages - hatch mcp list hosts: List all host platforms with status and config paths - hatch mcp list servers: List configured MCP servers in tabular format Implementation Details: - Integration with MCPHostRegistry.detect_available_hosts() API - Environment-aware server discovery using existing PackageService patterns - Formatted table output for improved user experience - Comprehensive error handling for nonexistent environments - Support for default environment when --env not specified Testing: - 12 comprehensive test cases covering argument parsing and backend integration - Component-level integration tests with mocked dependencies - Error scenario validation and output format verification - Regression tests for CLI argument handling Next: Implement backup management commands (Phase 3d) for complete MCP host configuration management functionality.
Add comprehensive backup management functionality for MCP host configurations: Core Commands: - hatch mcp backup restore: Restore host configuration from backup with confirmation - hatch mcp backup list: List available backups with detailed/summary views - hatch mcp backup clean: Clean old backups with age/count-based criteria Implementation Details: - Integration with MCPHostConfigBackupManager for all backup operations - Support for dry-run mode across all backup commands - Auto-approval flags to skip confirmation prompts for automation - Detailed backup information display with timestamps, sizes, and ages - Flexible cleanup criteria (older-than-days, keep-count) with safety confirmations - Comprehensive error handling for invalid hosts and missing backups Testing: - 15 comprehensive test cases covering all backup command scenarios - Component-level integration tests with mocked backup manager - Error scenario validation and confirmation prompt testing - Dry-run functionality verification and output format validation Next: Implement direct MCP management commands (Phase 3e) for server and host configuration without package dependencies.
- Add proper TTY detection using sys.stdin.isatty() - Support HATCH_AUTO_APPROVE environment variable - Handle EOFError and KeyboardInterrupt gracefully - Fix MCPServerConfig validation for headers field - Ensure tests run without hanging on user prompts Resolves critical testing issue where CLI commands would block in automated test environments waiting for user input.
Replace direct input() call in Python environment removal with TTY-aware request_confirmation() function to prevent hanging in non-TTY environments during automated testing. Ensures consistent non-TTY handling across all CLI confirmation prompts in the Hatch package manager.
Root cause analysis and systematic fixes: 1. **CLI Argument Parsing Conflict**: Fixed naming conflict between main parser's 'command' attribute and MCP configure parser's 'command' argument by renaming to 'server_command' 2. **Pydantic Model Validation**: Fixed test configuration to respect MCPServerConfig validation rules - cannot specify both 'command' and 'url' simultaneously 3. **Unicode Character Encoding**: Replaced Unicode symbols (✓/✗) with ASCII-compatible text ([SUCCESS]/[ERROR]) to prevent Windows console encoding errors 4. **Mock Patch Path Issues**: Corrected import paths in tests to patch the actual imported classes rather than their source modules 5. **TTY-aware Confirmation Logic**: Fixed request_confirmation() function to properly handle mocked input in test environments while maintaining non-TTY auto-approval **Test Results**: - Before: 51/58 passing (87.9% success rate) - After: 58/58 passing (100.0% success rate) All originally failing tests now pass: - TestMCPConfigureCommand.test_configure_argument_parsing_basic ✅ - TestMCPConfigureCommand.test_configure_argument_parsing_with_options ✅ - TestMCPConfigureCommand.test_configure_dry_run ✅ - TestMCPConfigureCommand.test_configure_failed ✅ - TestMCPConfigureCommand.test_configure_successful ✅ - TestMCPRemoveCommand.test_remove_failed ✅ - TestMCPRemoveCommand.test_remove_successful ✅ - TestMCPCLIPackageManagement.test_request_confirmation_user_* ✅ Follows Phase 4 development workflow with systematic debugging approach.
Root cause: Package sync command was passing MCPHostType enum objects instead of string values to backup system, creating filenames like 'mcp.json.MCPHostType.GEMINI.*' instead of 'mcp.json.gemini.*' Changes: - Fix sync command to pass host.value (string) instead of host (enum object) - Add backward compatibility to backup discovery for legacy incorrect filenames - Replace Unicode symbols with ASCII-compatible text for better compatibility Resolves backup system malfunction where existing backups couldn't be found by list/restore commands despite files existing on disk. Tested: All backup operations (list, restore) now work correctly with both new correct format and existing legacy format backup files.
Root cause: MCP server configurations were using hardcoded 'python' command instead of environment-specific Python executable paths, causing servers to run with wrong Python interpreter. Changes: - Update get_package_mcp_server_config() to use env_manager.get_current_python_executable() - Fallback to 'python' if no environment-specific executable available - Update test to mock get_current_python_executable() method properly - Test now expects environment-specific path instead of generic 'python' Resolves Issue 3: Incorrect Python Executable Path Now generates proper paths like 'C:\Users\eliot\miniforge3\envs\hatch_modeling\python.exe' instead of generic 'python' command. Tested: All MCP CLI tests pass (100% success rate)
Root cause: MCPServerConfig model was rejecting host-specific fields and configuration writing was overwriting existing servers instead of merging. Critical fixes: 1. **Allow host-specific fields**: Changed MCPServerConfig.Config.extra from 'forbid' to 'allow' to support Gemini's cwd, timeout, trust fields 2. **Preserve existing servers**: Modified write_configuration to merge new servers with existing ones instead of complete replacement 3. **Enhanced JSON validation**: Added JSON verification after write to prevent invalid output with missing brackets 4. **Improved error handling**: Better cleanup and error reporting for JSON serialization failures Resolves Issue 1: Configuration File Corruption and Data Loss - ✅ Existing mcpServers configuration preserved (no data loss) - ✅ Valid JSON output with proper structure - ✅ Host-specific fields (cwd, timeout, trust) supported Tested: All MCP CLI tests pass (100% success rate) Verified: Configuration merge preserves existing servers while adding new ones
The content of `how_to_contribute.md` was deprecated while `CONTRIBUTING.md` was up to date.
This documentation is more for developpers and, even then, the content was hardly useful
The content was not enough grounded in real cases or redundant with the previous steps of the tutorial
## [0.7.0-dev.8](v0.7.0-dev.7...v0.7.0-dev.8) (2025-11-24) ### Bug Fixes * **docs:** describe actual commit policy ([d42777e](d42777e)) * **docs:** repair all broken links ([7378ebb](7378ebb)) ### Documentation * CONTRIBUTING becomes `how_to_contribute.md` ([e2b1b13](e2b1b13)) * **fix:** release policy ([8a6c5a0](8a6c5a0)) * update CLIReference ([fa801e9](fa801e9)) * **user:** remove advanced synchronization tutorial step ([bd0cbff](bd0cbff)) * **users:** remove low impact `CICDIntegration.md` ([996e99d](996e99d)) * **user:** update tutorial on mcp host configuration ([6033841](6033841))
Claude Desktop accepts both absolute and relative paths for commands, resolving them at runtime using the system PATH. The validation logic incorrectly enforced absolute path requirements that Claude Desktop itself does not have. Changes: - Remove Path.is_absolute() check from ClaudeHostStrategy.validate_server_config() - Accept any command (relative or absolute) or URL - Update test mock to match fixed behavior - Add documentation explaining Claude Desktop's actual behavior Evidence: User's working configuration contains relative path 'mamba' that was successfully synced and functions correctly in Claude Desktop. Impact: - Fixes: hatch mcp configure fails for claude-desktop with relative paths - Backward compatible: absolute paths still work - Test results: 284/286 MCP tests passing (2 unrelated failures) Root cause: Misinterpretation of Claude Desktop requirements led to overly restrictive validation that didn't match actual behavior.
## [0.7.0-dev.9](v0.7.0-dev.8...v0.7.0-dev.9) (2025-12-02) ### Bug Fixes * **mcp:** remove incorrect absolute path validation for Claude Desktop ([1029991](1029991))
Use newly published `hatch-validator` and `wobble` for the deps.
## [0.7.0-dev.10](v0.7.0-dev.9...v0.7.0-dev.10) (2025-12-07) ### Bug Fixes * **pypi-deploy:** remove direct dependencies ([0875cf8](0875cf8))
Although we had been using `hatch` since the beginning, this name is already taken on PyPI so we decided to take `hatch-xclam` and had not updated the `pyproject.toml`correctly until now.
## [0.7.0-dev.11](v0.7.0-dev.10...v0.7.0-dev.11) (2025-12-07) ### Bug Fixes * **pypi-deploy:** wrong project name ([f94df05](f94df05))
- Fix MCP backup commands: host is now a required positional argument, not optional flag - Fix hatch mcp backup restore: correct syntax from <backup-id> to <host> [--backup-file FILE] - Fix hatch mcp backup clean: correct parameter name from --older-than to --older-than-days - Remove non-existent --host parameter from hatch mcp list servers - Document --env parameter in hatch mcp remove server as reserved for future use - Clarify --include-tools and --exclude-tools use space-separated values, not comma-separated - Add note that --older-than-days or --keep-count must be specified for backup clean
Corrected 12 critical issues in the MCP host configuration extension documentation: CRITICAL FIXES: - Added missing is_host_available() method to core interface (was causing NotImplementedError) - Added missing get_config_key() method to interface and examples - Fixed incorrect claim that Claude requires absolute paths (actually accepts any command/URL) - Clarified that base classes provide full read/write implementations IMPORTANT ADDITIONS: - Listed all existing host types (CLAUDE_DESKTOP, CLAUDE_CODE, VSCODE, CURSOR, LMSTUDIO, GEMINI) - Added comprehensive error handling examples with try-catch patterns - Added atomic write pattern to prevent config file corruption - Added preservation of non-MCP settings in config files - Clarified backup handling is managed by MCPHostConfigurationManager, not strategies - Added explanation of get_config_key() and when to override it - Added import requirement for CLI discovery IMPROVED EXAMPLES: - Split implementation examples into two paths: inheriting from base classes vs. from scratch - Added platform-specific path detection with platform.system() - Added nested configuration structure handling - Added multi-file configuration support - Added host-specific validation examples - Improved test examples with proper imports and more test cases DOCUMENTATION IMPROVEMENTS: - Clarified that base classes inherit read/write logic - Added explanation of registration mechanism - Added CLI import requirement explanation - Improved section on common patterns with better organization
Make the core features of Hatch! clearer
- Add detailed introduction explaining Hatch's core value proposition - Expand supported MCP hosts section with all platform targets - Enhance quick start with practical examples for environment and package creation - Add package-first deployment workflow with recommended best practices - Include direct configuration examples for advanced use cases - Reorganize documentation links for better discoverability - Add contributing quick start for developers - Improve getting help section with troubleshooting references
- Split semantic-release and publish workflows for better separation of concerns - semantic-release.yml: handles testing and automated version bumping on branch pushes - publish.yml: handles PyPI publication on stable release tags (v[0-9]+.[0-9]+.[0-9]+) - Add workflow_dispatch to publish.yml for manual publication of any tag - Eliminates double-execution issue by using git-native tag triggers instead of text matching - Supports both automatic releases and manual on-demand publishing
- Document separate semantic-release and publish workflows - Explain automatic publishing for stable releases (v[0-9]+.[0-9]+.[0-9]+) - Document manual publishing via workflow_dispatch - Add workflow execution flow diagrams - Document key design decisions and rationale - Update contributor guidance for new release process - Remove outdated local versioning commands - Clarify that dev releases are available from GitHub releases docs: update release-policy Update the release policy documentation example to reflect the actual current state of the project: - Package name: hatch-xclam (was: hatch) - Description: Package manager for the Cracking Shells ecosystem - Dependencies: Updated to match current pyproject.toml Update the version information to be a pattern: MAJOR.MINOR.PATCH[-dev.N] (was: 0.4.2) This ensures the documentation accurately represents the project's release configuration and versioning strategy.
Replace GitHub blob URLs with raw.githubusercontent.com URLs to ensure Discord embeds can properly display images. Blob URLs serve HTML pages rather than direct image content, which Discord webhooks cannot render. Changes: - prerelease-discord-notification.yml: Update image and avatar_url - release-discord-notification.yml: Update image and avatar_url Both workflows now use raw.githubusercontent.com URLs that return direct image data with proper MIME types for Discord embed rendering.
cracking-shells-semantic-release bot
pushed a commit
that referenced
this pull request
Dec 11, 2025
## 0.7.0 (2025-12-11) * Merge pull request #42 from CrackingShells/dev ([be3a9a3](be3a9a3)), closes [#42](#42) * chore: add submodule `cracking-shells-playbook` ([c7fb36b](c7fb36b)) * chore: clean remove __temp__/ and ignore it ([40b4a00](40b4a00)) * chore: cleaning up old reports ([0119d0f](0119d0f)) * chore: configure semantic-release for 0.x.x versioning behavior ([b04757a](b04757a)) * chore: fix version numbers in changelog ([cfa6498](cfa6498)) * chore(.gitignore): ignoring .augment and .github/instructions ([294ca04](294ca04)) * chore(.gititnore): directory Laghari/ ([aa58720](aa58720)) * chore(ci): clean semantic release commit message ([033ccc1](033ccc1)) * chore(cli): remove useless --no-mcp-config flag ([7385763](7385763)) * chore(release): 0.7.0-dev.1 ([700f190](700f190)) * chore(release): 0.7.0-dev.10 ([4947480](4947480)) * chore(release): 0.7.0-dev.11 ([d20de17](d20de17)) * chore(release): 0.7.0-dev.12 ([09b7bcb](09b7bcb)) * chore(release): 0.7.0-dev.13 ([0d94e4c](0d94e4c)) * chore(release): 0.7.0-dev.2 ([a7bea4b](a7bea4b)) * chore(release): 0.7.0-dev.3 ([28313b2](28313b2)) * chore(release): 0.7.0-dev.4 ([c04984f](c04984f)) * chore(release): 0.7.0-dev.5 ([66724ca](66724ca)) * chore(release): 0.7.0-dev.6 ([321d2f1](321d2f1)) * chore(release): 0.7.0-dev.7 ([35e25d8](35e25d8)) * chore(release): 0.7.0-dev.8 ([72ff2be](72ff2be)) * chore(release): 0.7.0-dev.9 ([dda6513](dda6513)) * fix: backup system filename format ([f7af78a](f7af78a)) * fix: config backup restore system ([981ff0c](981ff0c)) * fix: correct report display logic to exclude unset fields ([478c655](478c655)) * fix: implement environment-specific Python executable path resolution ([6119fe2](6119fe2)) * fix: replace blocking input() with TTY-aware request_confirmation ([84caa7c](84caa7c)) * fix: resolve all MCP CLI test failures achieving 100% pass rate ([e355bd7](e355bd7)) * fix: resolve configuration file corruption and data loss issues ([55efeaa](55efeaa)) * fix: resolve non-TTY environment blocking in request_confirmation ([799e1fa](799e1fa)) * fix: use the FastMCP instance and not HatchMCP ([7179d31](7179d31)) * fix(ci): Discord notification image URLs to use raw GitHub content ([0b8ce7c](0b8ce7c)) * fix(ci): Discord pre-release notification should happen when on `dev` ([505ad2b](505ad2b)) * fix(ci): plugin definition structure ([a5ed541](a5ed541)) * fix(ci): using custom `@artessan-devs/sr-uv-plugin` ([fa47900](fa47900)) * fix(claude-code): user-wide config file of the mcp ([ba5a02a](ba5a02a)) * fix(cli): allow --http-url as standalone option for Gemini ([49e91bc](49e91bc)) * fix(cli): enable partial configuration updates for existing MCP servers ([d545e90](d545e90)) * fix(cli): implement shlex.split() for --args parsing ([a7e21d2](a7e21d2)) * fix(cli): mcp host configuration when using paths to hatch pkgs ([902fa8a](902fa8a)) * fix(cli): pass in expected mcp server configuration ([17d1cc3](17d1cc3)) * fix(cli): resolve argparse naming conflict ([44d6a73](44d6a73)) * fix(cli): resolve critical UnboundLocalError in hatch package add ([bdfa4c5](bdfa4c5)) * fix(cli): string value usage ([aae1e85](aae1e85)) * fix(deps): add pydantic dep ([bfa4aed](bfa4aed)) * fix(dev): overwrite server config in mcp host rather than merging ([ce6ecc6](ce6ecc6)) * fix(dev): remove host configuration ([6c5bc07](6c5bc07)) * fix(docs): describe actual commit policy ([fee6da4](fee6da4)) * fix(docs): repair all broken links ([e911324](e911324)) * fix(docs): Tutorial 04-01 ([e855749](e855749)) * fix(host): configuration cleanup after package and environment removal ([2824de7](2824de7)) * fix(host): multi-environment mcp configuration conflict resolution ([1eb86e4](1eb86e4)) * fix(lmstudio): user-wide config file of the mcp ([58b7613](58b7613)) * fix(mcp): add Claude Desktop transport validation ([dede78e](dede78e)) * fix(mcp): clear type field during transport switching ([1933351](1933351)) * fix(mcp): remove incorrect absolute path validation for Claude Desktop ([50345a3](50345a3)) * fix(pypi-deploy): remove direct dependencies ([2fc9313](2fc9313)) * fix(pypi-deploy): wrong project name ([3957c75](3957c75)) * fix(serialization): explicit model dump of server configuration ([fa273a4](fa273a4)) * fix(test): function signatures and environment variable interference ([04838bc](04838bc)) * fix(test): resolve failing integration tests with proper error handling ([5638299](5638299)) * fix(tests): add missing mock ([1774610](1774610)) * fix(tests): correct dependency dummy metadata extraction ([cbbdf40](cbbdf40)) * fix(tests): update simple_dep_pkg to use local base_pkg ([f21ec7d](f21ec7d)) * fix(vscode): set mcp configure to user-wide by default ([a688f52](a688f52)) * fix(vscode): update configuration format from settings.json to mcp.json ([d08a202](d08a202)) * fix(workaround): relax Pydantic data model constraint ([16c7990](16c7990)) * docs: add --version flag documentation and installation verification ([724c957](724c957)) * docs: add comprehensive MCP host configuration documentation ([e188c90](e188c90)) * docs: add MCP backup system architecture documentation ([de7d16a](de7d16a)) * docs: consolidate MCP/ subdirectory into MCPHostConfiguration.md ([3d5d11e](3d5d11e)) * docs: CONTRIBUTING becomes `how_to_contribute.md` ([e10c236](e10c236)) * docs: fix CLI reference documentation accuracy ([6d8c322](6d8c322)) * docs: fix critical CLI command inaccuracies across documentation ([8ca57c3](8ca57c3)) * docs: fix MCP host configuration dev guide ([0813ee2](0813ee2)) * docs: minor legacy typos ([c48be5c](c48be5c)) * docs: rewrite MCP host configuration ([b3597a8](b3597a8)) * docs: update CLI reference for environment-scoped list hosts ([b2e5a80](b2e5a80)) * docs: update CLI reference for MCP host configuration integration ([5a98b64](5a98b64)) * docs: update CLIReference ([fb30d37](fb30d37)) * docs: update cross-references following corrected alignment strategy ([79086a0](79086a0)) * docs: update release policy for new CI/CD architecture ([a444c65](a444c65)) * docs(cli): update CLI reference for parameter naming changes ([3d0a7a7](3d0a7a7)) * docs(fix): release policy ([d326328](d326328)) * docs(mcp): add comprehensive synchronization command documentation ([dab37fd](dab37fd)) * docs(mcp): add user guide for direct management commands ([456971c](456971c)) * docs(mcp): correct command examples and enhance configuration guidance ([edcca56](edcca56)) * docs(mcp): streamline architecture documentation ([5b6ab9e](5b6ab9e)) * docs(README): rewrite ([31ce6f9](31ce6f9)) * docs(README): updating ([3b1cbd3](3b1cbd3)) * docs(tutorials): update MCP host configuration tutorial content ([c06378f](c06378f)) * docs(user): remove advanced synchronization tutorial step ([390ddff](390ddff)) * docs(user): update tutorial on mcp host configuration ([8137957](8137957)) * docs(users): remove low impact `CICDIntegration.md` ([27aafe0](27aafe0)) * ci: add `artessan-devs/sr-uv-plugin` to semantic release ([7f5c7d2](7f5c7d2)) * ci: add Discord notifications for releases and pre-releases ([ea6ecb2](ea6ecb2)) * ci: add pypi publication ([a86fa7c](a86fa7c)) * ci: avoid publishing release on commit `fix(docs)` ([fb62e0a](fb62e0a)) * ci: refactor CI/CD pipeline into separate workflows ([8342999](8342999)) * style: apply ruff to `template_generator.py` ([638a9dd](638a9dd)) * style: json formating of the `.releaserc.json` ([681a922](681a922)) * refactor: directory name ([c5858ff](c5858ff)) * refactor: remove outdated __version__ from hatch/__init__.py ([4d06b40](4d06b40)) * refactor(cli): rename --headers to --header for consistency ([5d84755](5d84755)) * refactor(cli): rename --inputs to --input for consistency ([0807712](0807712)) * refactor(cli): replace --env with --env-var in mcp configure ([945f66b](945f66b)) * refactor(test): mark tests taking around 30 secs as slow ([535843c](535843c)) * feat: add --version flag to CLI argument parser ([c3410c3](c3410c3)) * feat: add decorator registration for new MCP host configs ([61681be](61681be)) * feat: add get_server_config method for server existence detection ([7b53e42](7b53e42)) * feat: add host-specific CLI arguments for MCP configure command ([40faabb](40faabb)) * feat: add host-specific MCP configuration models with type field ([655cf0a](655cf0a)) * feat: add user feedback reporting system for MCP configuration ([fa8fa42](fa8fa42)) * feat: add user feedback reporting to package add/sync commands ([f244c61](f244c61)) * feat: enhance package management with MCP host configuration integration ([7da69aa](7da69aa)) * feat: implement ALL host-specific CLI arguments with new reporting ([6726bbb](6726bbb)) * feat: implement comprehensive host configuration tracking system ([4e496bc](4e496bc)) * feat: implement consolidated MCPServerConfig Pydantic model ([e984a82](e984a82)) * feat: implement decorator-based strategy registration system ([b424520](b424520)) * feat: implement environment-scoped list hosts command ([d098b0b](d098b0b)) * feat: implement host strategy classes with inheritance architecture ([1e8d95b](1e8d95b)) * feat: implement MCP backup management commands (Phase 3d) ([ee04223](ee04223)) * feat: implement MCP host configuration backup system ([de661e2](de661e2)) * feat: implement MCP host discovery and listing commands (Phase 3c) ([f8fdbe9](f8fdbe9)) * feat: implement package-MCP integration with existing APIs ([f4dd2fc](f4dd2fc)) * feat: implement partial update merge logic in CLI handler ([4268d4e](4268d4e)) * feat: integrate Pydantic model hierarchy into CLI handlers ([d59fc6a](d59fc6a)) * feat(cli): enhance mcp configure command argument structure ([7d385e6](7d385e6)) * feat(cli): implement hatch mcp sync command with advanced options ([80f67a1](80f67a1)) * feat(cli): implement object-action pattern for MCP remove commands ([b172ab4](b172ab4)) * feat(mcp): add host configuration removal functionality ([ca82163](ca82163)) * feat(mcp): implement advanced synchronization backend ([9ed6ec6](9ed6ec6)) * feat(mcp): implement Gemini dual-transport validation ([f715df1](f715df1)) * feat(tutorials): add complete MCP Host Configuration tutorial series ([a0a5ba4](a0a5ba4)) * test: add atomic file operations and backup-aware operation tests ([aac323e](aac323e)) * test: add CLI integration tests for MCP host configuration ([a1e3c21](a1e3c21)) * test: add comprehensive MCPHostConfigBackupManager tests ([0bfeecf](0bfeecf)) * test: add comprehensive MCPServerConfig model validation tests ([391f2b9](391f2b9)) * test: add comprehensive test suite for environment-scoped commands ([077c532](077c532)) * test: add comprehensive test suite for partial configuration updates ([47dd21e](47dd21e)) * test: add comprehensive tests for MCP configuration models ([0265d48](0265d48)) * test: add configuration manager integration tests ([502ab4c](502ab4c)) * test: add decorator-based strategy registration validation tests ([ff80500](ff80500)) * test: add environment integration validation tests ([99302fe](99302fe)) * test: add integration and performance tests for backup system ([7b6a261](7b6a261)) * test: add MCP backup test infrastructure and data utilities ([ed5cd35](ed5cd35)) * test: add tests for user feedback reporting ([d8076e2](d8076e2)) * test: add version command test suite ([ac9919b](ac9919b)) * test: extend test data infrastructure for MCP host configuration ([688b4ed](688b4ed)) * test(env): enhance environment cleanup to prevent debris accumulation ([b0c9c7f](b0c9c7f)) * test(mcp): add comprehensive test coverage for new remove commands ([73f39f2](73f39f2)) * test(mcp): add comprehensive test suite for sync functionality ([969c793](969c793)) ### Breaking change * Code that relied on hatch.__version__ will need to use importlib.metadata.version('hatch') instead. Related to: Phase 1 analysis (version_command_analysis_v1.md)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Version 0.7.0 introduces a complete Model Context Protocol (MCP) host configuration management system with a powerful new CLI interface. Users can now configure and synchronize MCP servers across multiple AI development environments directly from the command line, eliminating the need for manual configuration file editing.
Supported MCP Hosts
The system provides first-class support for all major AI development platforms:
Each host has a dedicated strategy implementation that handles platform-specific configuration requirements, transport validation, and file path resolution.
New CLI Commands
The CLI has been completely redesigned around MCP management with intuitive, composable commands:
Configuration Management: The
hatch mcp configurecommand allows users to add or update MCP servers on any supported host with host-specific arguments like--command,--args,--env-varfor local servers, or--url,--headerfor remote servers. The system intelligently validates that servers are configured as either local or remote, never both.Synchronization: The new
hatch mcp synccommand enables powerful cross-environment and cross-host synchronization. Users can sync configurations from one environment to multiple hosts, copy settings between hosts, filter by server name or regex pattern, and preview changes with--dry-runbefore applying them.Discovery & Listing: The
hatch mcp discover hostscommand shows all available MCP host platforms on the system with their configuration paths and availability status. Thehatch mcp list hostscommand displays which hosts have servers configured in the current environment, with optional detailed output showing package-level information.Server Management: The
hatch mcp removecommand supports both individual server removal and complete host configuration cleanup, with automatic backup creation and optional dry-run preview.Key CLI features include:
--command,--args,--env-var,--url,--header,--timeout,--trust,--include-tools,--exclude-tools--serversfor specific servers or--patternfor regex-based selection--dry-runfor preview,--auto-approvefor automation,--no-backupfor advanced users--envflag for environment-scoped operationsRobust Configuration System
The system is built on a Pydantic-based model hierarchy providing type-safe configuration handling. Sophisticated validation ensures Gemini dual-transport compatibility (stdio + HTTP) and Claude Desktop transport requirements. The decorator-based strategy registration pattern makes it straightforward to extend support for additional hosts in the future.
Critical Fixes & Improvements
This release resolves production issues including configuration file corruption, backup discovery failures, and non-TTY environment blocking. All MCP CLI tests now pass, and the backup restore system has been completely reimplemented to handle edge cases properly. Multi-environment configuration conflicts are now resolved intelligently.
Breaking Changes
hatch.__version__should useimportlib.metadata.version('hatch')instead. The new--versionflag is the recommended way to check the installed version.