mcp-souschef 2.2.0__tar.gz → 2.8.0__tar.gz

mcp_souschef-2.2.0/README.md → mcp_souschef-2.8.0/PKG-INFO

@@ -1,11 +1,46 @@
+Metadata-Version: 2.4
+Name: mcp-souschef
+Version: 2.8.0
+Summary: AI-powered MCP server for Chef to Ansible conversion
+License: MIT
+License-File: LICENSE
+Keywords: chef,ansible,migration,infrastructure,automation,mcp,ai,conversion
+Author: SousChef Contributors
+Requires-Python: >=3.14,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Provides-Extra: ui
+Requires-Dist: anthropic (>=0.75.0)
+Requires-Dist: click (>=8.1.0)
+Requires-Dist: mcp (>=1.25.0)
+Requires-Dist: openai (>=1.0.0)
+Requires-Dist: pandas (>=2.0.0) ; extra == "ui"
+Requires-Dist: plotly (>=5.0.0)
+Requires-Dist: python-dotenv (>=1.2.1)
+Requires-Dist: pyyaml (>=6.0.0)
+Requires-Dist: streamlit (>=1.28.0)
+Requires-Dist: zod (>=0.8.0)
+Project-URL: Documentation, https://kpeacocke.github.io/souschef/
+Project-URL: Homepage, https://github.com/kpeacocke/souschef
+Project-URL: Repository, https://github.com/kpeacocke/souschef
+Description-Content-Type: text/markdown
+
 # Chef to Ansible migration - SousChef MCP
 
 An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities for enterprise infrastructure transformation.
 
-[![PyPI version](https://img.shields.io/pypi/v/mcp-souschef.svg)](https://pypi.org/project/mcp-souschef/)
+[![GitHub release](https://img.shields.io/github/v/release/kpeacocke/souschef)](https://github.com/kpeacocke/souschef/releases)
 [![Python Version](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](htmlcov/index.html)
+[![Test Coverage](https://img.shields.io/badge/coverage-91%25-brightgreen.svg)](htmlcov/index.html)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)
@@ -14,7 +49,17 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
 
 ## Overview - Chef to Ansible features
 
-SousChef is a complete enterprise-grade migration platform with 38 MCP tools organized across 9 major capability areas to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerized deployments, SousChef provides everything needed for a successful infrastructure automation migration.
+SousChef is a complete enterprise-grade migration platform with **32 primary MCP tools** organised across **10 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments and CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.
+
+### About Tool Counts
+
+**Why 32 tools in the documentation but more in the server?**
+
+The MCP server provides **37 total tools** (35 public + 2 internal). This documentation focuses on the **32 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations and helper utilities used internally by the main tools.
+
+As a user, you'll primarily interact with the 27 documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.
+
+> **For developers:** See `souschef/server.py` for the complete list of all 37 registered tools.
 
 ## Model Agnostic - Works with Any AI Model
 
@@ -27,10 +72,17 @@ SousChef is a complete enterprise-grade migration platform with 38 MCP tools org
 - **Local Models** (Ollama, llama.cpp, etc.)
 - **Custom Enterprise Models**
 
-**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 38 specialized tools. The model calls these tools to help with your migration.
+**How it works:** You choose your AI model provider in your MCP client. SousChef provides the Chef/Ansible expertise through 27 specialized tools. The model calls these tools to help with your migration.
 
 > See [config/CONFIGURATION.md](config/CONFIGURATION.md) for configuration examples with different model providers.
 
+## Quick Links
+
+- **[Terraform Provider](terraform-provider/README.md)** - Manage migrations with infrastructure-as-code
+- **[User Guide](docs/user-guide/)** - Complete documentation
+- **[API Reference](docs/api-reference/)** - Detailed tool documentation
+- **[Migration Guide](docs/migration-guide/)** - Step-by-step migration process
+
 ## Installation
 
 ```bash
@@ -55,7 +107,7 @@ Complete cookbook introspection and analysis tools:
 - **list_directory** - Navigate and explore cookbook directory structures
 - **read_file** - Read cookbook files with error handling
 - **read_cookbook_metadata** - Parse metadata.rb files for dependencies and cookbook information
-- **parse_recipe** - Analyze Chef recipes and extract resources, actions, and properties
+- **parse_recipe** - Analyse Chef recipes and extract resources, actions, and properties
 - **parse_attributes** - Parse attribute files with **advanced precedence resolution** (6 levels: default, force_default, normal, override, force_override, automatic)
 - **list_cookbook_structure** - Display complete cookbook directory hierarchy
 
@@ -76,7 +128,7 @@ Convert Chef search patterns to dynamic Ansible inventory:
 
 - **convert_chef_search_to_inventory** - Transform Chef search queries to Ansible inventory groups
 - **generate_dynamic_inventory_script** - Create dynamic inventory scripts from Chef server queries
-- **analyze_chef_search_patterns** - Discover and analyze search usage in cookbooks
+- **analyse_chef_search_patterns** - Discover and analyse search usage in cookbooks
 
 ### 4. InSpec Integration & Validation
 Complete InSpec-to-Ansible testing pipeline:
@@ -90,14 +142,14 @@ Chef data bags to Ansible vars/vault conversion:
 
 - **convert_chef_databag_to_vars** - Transform data bags to Ansible variable files
 - **generate_ansible_vault_from_databags** - Convert encrypted data bags to Ansible Vault
-- **analyze_chef_databag_usage** - Analyze data bag usage patterns in cookbooks
+- **analyse_chef_databag_usage** - Analyse data bag usage patterns in cookbooks
 
 ### 6. Environment & Configuration Management
 Chef environments to Ansible inventory groups:
 
 - **convert_chef_environment_to_inventory_group** - Transform Chef environments to inventory
 - **generate_inventory_from_chef_environments** - Generate complete inventory from environments
-- **analyze_chef_environment_usage** - Analyze environment usage in cookbooks
+- **analyse_chef_environment_usage** - Analyse environment usage in cookbooks
 
 ### 7. AWX/Ansible Automation Platform Integration
 Enterprise AWX/AAP configuration generation:
@@ -121,7 +173,67 @@ Modern deployment strategies and migration planning:
 - **generate_blue_green_deployment_playbook** - Create blue/green deployment playbooks
 - **generate_canary_deployment_strategy** - Generate canary deployment configurations
 
-### 10. Conversion Validation Framework
+### 10. CI/CD Pipeline Generation
+Generate Jenkins, GitLab CI, and GitHub Actions workflows from Chef cookbook CI patterns:
+
+- **generate_jenkinsfile_from_chef** - Generate Jenkinsfile (Declarative or Scripted) from Chef cookbook CI/CD patterns
+- **generate_gitlab_ci_from_chef** - Generate .gitlab-ci.yml from Chef cookbook testing tools
+- **generate_github_workflow_from_chef** - Generate GitHub Actions workflow from Chef cookbook CI/CD patterns
+
+Automatically detects and converts:
+- **Test Kitchen** configurations (.kitchen.yml) → Integration test stages
+- **ChefSpec** tests (spec/) → Unit test stages
+- **Cookstyle/Foodcritic** → Lint stages
+- Multiple test suites → Parallel execution strategies
+
+#### Example Usage
+
+```bash
+# Generate Jenkins Declarative pipeline
+souschef generate-jenkinsfile ./mycookbook
+
+# Generate Jenkins Scripted pipeline
+souschef generate-jenkinsfile ./mycookbook --pipeline-type scripted
+
+# Generate GitLab CI configuration
+souschef generate-gitlab-ci ./mycookbook
+
+# Generate GitHub Actions workflow
+souschef generate-github-workflow ./mycookbook
+
+# Customize with options
+souschef generate-gitlab-ci ./mycookbook --no-cache --no-artifacts
+souschef generate-github-workflow ./mycookbook --workflow-name "My CI" --no-cache
+```
+
+**MCP Tool Usage:**
+```python
+# From an AI assistant with SousChef MCP
+
+# Generate Jenkins pipeline
+generate_jenkinsfile_from_chef(
+    cookbook_path="/path/to/cookbook",
+    pipeline_type="declarative",  # or "scripted"
+    enable_parallel="yes"  # or "no"
+)
+
+# Generate GitLab CI
+generate_gitlab_ci_from_chef(
+    cookbook_path="/path/to/cookbook",
+    enable_cache="yes",  # or "no"
+    enable_artifacts="yes"  # or "no"
+)
+
+# Generate GitHub Actions workflow
+generate_github_workflow_from_chef(
+    cookbook_path="/path/to/cookbook",
+    workflow_name="Chef Cookbook CI",
+    enable_cache="yes",  # or "no"
+    enable_artifacts="yes"  # or "no"
+)
+```
+
+### 11. Conversion Validation Framework
 Comprehensive validation of Chef-to-Ansible conversions:
 
 - **validate_conversion** - Validate conversions across multiple dimensions
@@ -163,10 +275,10 @@ Output formats:
 - **json**: Structured JSON for programmatic processing
 - **summary**: Quick overview with counts only
 
-- **analyze_chef_application_patterns** - Identify application deployment patterns
+- **analyse_chef_application_patterns** - Identify application deployment patterns
 - **assess_chef_migration_complexity** - Comprehensive migration complexity assessment
 - **generate_migration_plan** - Create detailed migration execution plans
-- **analyze_cookbook_dependencies** - Analyze dependencies and migration order
+- **analyse_cookbook_dependencies** - Analyse dependencies and migration order
 - **generate_migration_report** - Generate executive and technical migration reports
 
 ## Migration Workflow
@@ -176,8 +288,8 @@ Output formats:
 # Assess migration complexity
 assess_chef_migration_complexity /path/to/cookbooks
 
-# Analyze cookbook dependencies
-analyze_cookbook_dependencies /path/to/cookbook
+# Analyse cookbook dependencies
+analyse_cookbook_dependencies /path/to/cookbook
 
 # Generate migration plan
 generate_migration_plan '{\"cookbooks\": [\"/path/to/cookbook1\", \"/path/to/cookbook2\"]}'
@@ -248,14 +360,84 @@ profile_cookbook_performance /path/to/large_cookbook
 profile_parsing_operation recipe /path/to/recipe.rb --detailed
 ```
 
-**Features:**
--  Execution time and peak memory tracking for all parsing operations
--  Detailed cProfile statistics with top function calls
--  Automatic performance recommendations based on thresholds
--  Before/after comparison for optimization validation
--  Integration with CLI and MCP for AI-assisted profiling
+### 10. Visual Migration Planning Interface
+Interactive web-based interface for Chef-to-Ansible migration planning and visualization:
+
+- **Cookbook Analysis Dashboard**: Interactive directory scanning with metadata parsing and complexity assessment
+- **Migration Planning Wizard**: Step-by-step migration planning with effort estimation and risk analysis
+- **Dependency Mapping**: Visual dependency graphs showing cookbook relationships and migration ordering
+- **Validation Reports**: Conversion validation results with syntax checking and best practice compliance
+- **Progress Tracking**: Real-time migration progress with completion metrics and bottleneck identification
+
+**Launch the UI:**
+```bash
+# Using Poetry (development)
+poetry run souschef ui
+
+# Using pip (installed)
+souschef ui
+
+# Custom port
+souschef ui --port 8080
+```
+
+**Run in Docker:**
+```bash
+# Build the image
+docker build -t souschef-ui .
 
-## Enterprise Features
+# Run the container
+docker run -p 8501:8501 souschef-ui
+
+# Or use docker-compose
+docker-compose up
+```
+
+**Docker Compose (recommended for development):**
+```yaml
+version: '3.8'
+services:
+  souschef-ui:
+    build: .
+    ports:
+      - "8501:8501"
+    restart: unless-stopped
+```
+
+**Features:**
+- Clean, professional design matching documentation standards
+- Real-time cookbook analysis with progress indicators
+- **Interactive dependency visualization** with Plotly graphs and NetworkX analysis
+- **Static graph visualization** with matplotlib for reports and documentation
+- **Real-time progress tracking** for all analysis operations
+- Migration planning wizards with effort estimation
+- Validation reporting dashboard with conversion quality metrics
+- Cross-platform compatibility (Linux, macOS, Windows)
+
+### Advanced UI Features
+
+#### Interactive Dependency Visualization
+The UI includes sophisticated dependency graph visualization powered by NetworkX and Plotly:
+
+- **Graph Analysis**: Automatic detection of cookbook dependencies, circular references, and migration ordering
+- **Interactive Exploration**: Zoom, pan, and hover over nodes to explore complex dependency relationships
+- **Color Coding**: Visual distinction between cookbooks, dependencies, community cookbooks, and circular dependencies
+- **Static Export**: Matplotlib-based static graphs for reports and documentation
+- **Large Graph Support**: Optimized layouts for complex cookbook ecosystems
+
+#### Real-Time Progress Tracking
+All analysis operations include comprehensive progress feedback:
+
+- **Progress Bars**: Visual progress indicators for long-running operations
+- **Status Updates**: Real-time status messages during analysis phases
+- **Operation Tracking**: Separate progress tracking for dependency analysis, validation, and migration planning
+- **Error Handling**: Graceful error display with recovery suggestions
+
+#### Enhanced User Experience
+- **Responsive Design**: Clean, professional interface that works across different screen sizes
+- **Export Options**: Download analysis results, graphs, and migration plans
+- **Session Persistence**: Maintain analysis state across page refreshes
+- **Quick Actions**: One-click access to common migration tasks
 
 ### Migration Assessment & Reporting
 - **Complexity Analysis**: Automated assessment of migration effort and risk factors
@@ -281,7 +463,7 @@ profile_parsing_operation recipe /path/to/recipe.rb --detailed
 ### Prerequisites
 - Python 3.14+
 - [Poetry](https://python-poetry.org/) for dependency management
-- MCP-compatible client (Claude Desktop, VS Code with MCP extension, etc.)
+- MCP-compatible client (Claude Desktop, VS Code 1.102+ with GitHub Copilot, etc.)
 
 ### Quick Start
 
@@ -294,9 +476,21 @@ profile_parsing_operation recipe /path/to/recipe.rb --detailed
 
    Use the pre-configured files in the `config/` directory for quick setup with Claude Desktop, VS Code Copilot, or other MCP clients.
 
+   **Claude Desktop** (macOS):
    ```bash
-   # Example: Claude Desktop (macOS)
    cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   # Restart Claude Desktop
+   ```
+
+   **VS Code + GitHub Copilot** (requires VS Code 1.102+):
+   ```bash
+   # macOS/Linux
+   cp config/vscode-copilot.json ~/.config/Code/User/mcp.json
+
+   # Windows
+   copy config\vscode-copilot.json %APPDATA%\Code\User\mcp.json
+
+   # Reload VS Code window, then trust the server when prompted
    ```
 
    ** See [config/CONFIGURATION.md](config/CONFIGURATION.md) for:**
@@ -340,6 +534,7 @@ souschef-cli inspec-convert controls.rb --format testinfra
 - `inspec-parse` - Parse InSpec profiles and controls
 - `inspec-convert` - Convert InSpec to Testinfra/Ansible tests
 - `inspec-generate` - Generate InSpec validation from recipes
+- `ui` - Launch the Visual Migration Planning Interface
 - `ls` / `cat` - File system operations
 
 ### Development Setup
@@ -432,7 +627,7 @@ Each MCP tool includes comprehensive documentation:
 - **[Testing Strategy Guide](docs/testing-strategy.md)** - Validation and testing approaches
 - **[Best Practices](docs/best-practices.md)** - Recommended patterns and approaches
 
-## 🤝 Contributing
+## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
 - Development setup and workflow
@@ -440,13 +635,13 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
 - Pull request process
 - Issue reporting guidelines
 
-## 📄 License
+## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Roadmap
 
-### Completed ✅
+### Completed
 -  Complete Chef cookbook parsing (recipes, attributes, metadata, templates)
 -  InSpec profile parsing and conversion to Testinfra/Ansible tests
 -  Chef resource to Ansible task conversion with module mapping
@@ -467,18 +662,29 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 -  Enhanced error handling with custom exceptions and actionable recovery suggestions
 -  Technical debt reduction - ALL PHASES COMPLETE: 16 functions refactored (15 C-grade eliminated, 70+ helpers extracted, average 77% complexity reduction, zero C-grade functions remaining)
 -  Performance profiling and optimization for large cookbooks (profiling module, CLI commands, MCP tools)
-
-### In Progress 🚧
--  Documentation website with MkDocs + Material theme
--  Documentation content (Getting Started, Tool Reference, Migration Guide)
-
-### Planned 📅
-- 📅 Integration with additional test frameworks (ServerSpec, Goss)
-- 📅 Visual migration planning and dependency mapping interface
+-  Code duplication elimination (InSpec functions refactored: 55 duplicate lines removed, improved architecture)
+-  Documentation website with MkDocs + Material theme (charcoal + teal colour scheme, 16 pages)
+-  Comprehensive documentation content (Getting Started, Tool Reference, Migration Guide, API docs, Examples)
+-  Integration with additional test frameworks (ServerSpec, Goss) - InSpec conversion now supports 4 output formats
+-  Jenkins/GitLab CI pipeline generation from Chef cookbook CI patterns (Test Kitchen, ChefSpec, Cookstyle)
+-  Visual migration planning interface with Streamlit-based web UI for interactive cookbook analysis and migration planning
+-  **Interactive dependency mapping and visualization** with Plotly graphs and NetworkX analysis
+-  **Real-time progress tracking** for all analysis operations with Streamlit progress bars
+-  **Static graph visualization** with matplotlib for reports and documentation
+
+### Planned
+- 📅 Enhanced graph layout algorithms for large dependency networks (force-directed, hierarchical)
+- 📅 Export functionality for graphs (PNG, SVG, PDF formats)
+- 📅 UI configuration options and themes
+- 📅 Performance caching for expensive analysis operations
+- 📅 Mobile-responsive design improvements
+- 📅 Accessibility enhancements (ARIA labels, keyboard navigation)
+- 📅 Integration testing for UI components
+- 📅 Advanced filtering and search in dependency graphs
+- 📅 Migration templates and presets
 - 📅 Terraform provider for infrastructure state management
-- 📅 Jenkins/GitLab CI pipeline generation
 
-## 🙋‍♀️ Support & Community
+## Support & Community
 
 - **Issues**: [GitHub Issues](https://github.com/kpeacocke/souschef/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/kpeacocke/souschef/discussions)
@@ -486,7 +692,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Transforming infrastructure automation, one recipe at a time.* ✨
+**SousChef** - *Transforming infrastructure automation, one recipe at a time.*
   desc 'Ensure package nginx is properly configured'
   impact 1.0
 
@@ -1203,4 +1409,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**SousChef** - *Ansible automation, one recipe at a time.* ✨
+**SousChef** - *Ansible automation, one recipe at a time.*
+