SousChef: Chef-to-Ansible Migration & Ansible Upgrade Planning

Transform Chef automation to Ansible and plan Ansible version upgrades. Works with any AI assistant via MCP (Model Context Protocol)—Claude, GPT-4, GitHub Copilot, Red Hat AI, local models, and more.

Quick Facts: MIT License | Python 3.10+ | 44 MCP Tools | 91% Test Coverage

---

Warning I did not hand craft 100k lines of code in two days while doing my actual day job (which, for the record, isn’t this). A lot of this is AI generated. Architected, hand edited, and personally sworn at yes, but the heavy hand of AI is all over this repo.

I’ve pushed it to include a lot of tests, and I run it through its paces before pushing, but some things may break, or may have always been broken. If you find something, raise it and I’ll fix it.

A fair bit of this relies on mocked Chef/AWX/AAP APIs because shockingly I don’t have a fleet of enterprise grade installs with enterprise grade data sitting around to test against. Buyer beware (doubly so, since you didn’t actually buy anything).

---

What It Does

Chef-to-Ansible Migration — Convert cookbooks, recipes, custom resources, data bags, and Habitat plans to Ansible playbooks, roles, and containers. Supports infrastructure, applications, and day-2 operations.

Ansible Upgrade Planning — Assess compatibility, plan version upgrades, validate collections, identify breaking changes, and generate testing strategies.

Installation & Setup

# Install from PyPI
pip install mcp-souschef

# Configure your MCP client (Claude Desktop example)
cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart your AI assistant and start using
# Ask: "What Chef migration tools are available?"

Other MCP clients: See config/CONFIGURATION.md for VS Code Copilot, custom setups, and Docker deployment.

Key Features

• 44 MCP tools for Chef migration and Ansible upgrades
• Web UI with interactive migration planner and visualisation
• CLI for automation and CI/CD integration
• Production-ready with 91% test coverage and comprehensive validation
• Model-agnostic — works with any AI assistant supporting MCP
• Chef Server ingestion with dependency closure and offline bundle export

Common Use Cases

Chef Migration:

• Convert cookbooks to Ansible playbooks and roles
• Migrate Chef Habitat apps to Docker containers
• Transform data bags to Ansible Vault
• Generate AWX/AAP job templates and workflows
• Convert InSpec tests to Ansible validation tasks
• Fetch cookbooks from Chef Server with run_list or policy selection

Ansible Upgrades:

• Assess Python and Ansible version compatibility
• Plan upgrades with breaking change analysis
• Validate collection compatibility
• Generate testing strategies
• Track end-of-life dates

Both Infrastructure & Applications:

• Infrastructure provisioning and configuration
• Application deployment automation
• Day-2 operations (backups, scaling, updates)
• CI/CD pipeline migration
• Multi-cloud automation

Command-Line Examples

# Chef migration
souschef-cli recipe /path/to/recipe.rb
souschef-cli template /path/to/template.erb
souschef-cli convert package nginx --action install

# Ansible upgrades
souschef ansible assess --environment-path /path/to/ansible
souschef ansible plan --current 2.9 --target 2.17
souschef ansible validate-collections --requirements-file requirements.yml

# Web UI
souschef ui  # Launch interactive dashboard

Documentation

Start Here

• Quick Start Guide — Get running in 5 minutes
• Production Safety — Validate migrations before deploying ⚠️
• User Guide — All 44 tools explained with examples
• Migration Guide — Step-by-step migration process
• Ansible Upgrades — Version upgrade planning workflows

Reference

• API Documentation — Complete technical reference
• Architecture Guide — Code structure and design decisions
• Contributing Guide — Development standards and workflow
• Security Policy — Vulnerability reporting and security features
• Changelog — Complete release history

Recent Updates

v6.0.0 — v2 core foundation with enhanced migration capabilities

v5.1.4 — Modular architecture, 91% test coverage, full type safety, production-ready

v5.0.0 — Complete Ansible upgrade planning with version matrices and EOL tracking

Contributing

# Development setup
git clone https://github.com/kpeacocke/souschef.git && cd souschef
poetry install
poetry run pytest           # Run tests
poetry run ruff check .     # Lint
poetry run mypy souschef    # Type check

Standards: Zero warnings policy, type hints required, 90%+ test coverage, Australian English spelling.

See CONTRIBUTING.md for complete guidelines.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md

License

MIT License — see LICENSE for details.