Skip to content

SousChef Documentation#

An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef, SaltStack, Puppet, PowerShell, and Bash to Ansible migration and Ansible upgrade planning capabilities for enterprise infrastructure and application transformation.

PyPI version Python Version License: MIT Test Coverage

Overview#

SousChef is a complete enterprise-grade platform with six major capabilities:

1. Core Migration Capability (39 tools)#

Complete enterprise-grade migration platform organised across 11 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 Chef Server integration, SousChef provides everything needed for a successful infrastructure automation migration.

2. Ansible Upgrade Assessment & Planning (5 tools)#

Comprehensive Ansible upgrade analysis and planning tools based on official Ansible-Python compatibility matrices:

  • Version Compatibility Assessment - Validate Ansible and Python version compatibility
  • EOL Status Checking - Track end-of-life dates and security support
  • Upgrade Path Planning - Generate detailed upgrade plans with risk assessment
  • Collection Compatibility - Validate collection versions against target Ansible releases
  • Breaking Change Analysis - Identify and plan for breaking changes (e.g., 2.9 → 2.10 collections split)
  • Python Upgrade Impact - Assess Python version upgrade requirements for control and managed nodes
  • Testing Plan Generation - Generate comprehensive upgrade testing plans

3. SaltStack to Ansible Migration (12 tools)#

Enterprise-grade SaltStack migration platform with 12 MCP tools covering the full migration lifecycle:

  • SLS Parsing - Parse state files, extract states, pillars, and grain references
  • Pillar Migration - Convert pillar data to Ansible vars/, group_vars/, and Ansible Vault
  • Inventory Generation - Convert top.sls targeting logic to Ansible INI inventory
  • Batch Conversion - Convert a full Salt state tree to an Ansible roles structure in one command
  • Complexity Assessment - Automated scoring and effort estimation for Salt directories
  • Migration Planning - Phased migration plans with timeline for AAP, AWX, or Ansible Core targets
  • Executive Reporting - Stakeholder-ready migration reports in Markdown or JSON
  • Live Salt Master Integration - Query the Salt Master REST API (CherryPy netapi) directly

4. Puppet to Ansible Migration (8 tools)#

Convert Puppet manifests and module directories to idiomatic Ansible playbooks:

  • Puppet Parsing - Parse .pp manifests and extract resource declarations, classes, and module structure
  • Resource Mapping - Map 14 Puppet resource types to idiomatic ansible.builtin modules
  • Module Conversion - Convert full Puppet module directories to Ansible roles
  • AI-Assisted Conversion - Handle complex DSL constructs (Hiera lookups, exported resources) with guidance
  • Unsupported Construct Warnings - Flag create_resources, exported resources, and custom functions
  • Single Resource Conversion - Convert individual Puppet resource declarations to standalone Ansible tasks

5. PowerShell & Bash Script Migration (10 tools)#

Enterprise migration for Windows PowerShell provisioning scripts and Linux/Mac Bash provisioning scripts:

  • PowerShell Parsing — Extract 28+ action types from .ps1 provisioning scripts
  • PowerShell Conversion — Map actions to ansible.windows.*, community.windows.*, chocolatey.chocolatey.*
  • Windows Artefact Generation — WinRM inventory, group_vars, requirements.yml, Ansible role, AWX job template
  • Fidelity Analysis — Score migration completeness (0–100 %) with actionable recommendations
  • Bash Parsing — Detect 13 operation categories with confidence scores and sensitive data alerts
  • Bash Conversion — Convert to idiomatic Ansible playbooks with quality scores (A–F) and AAP hints
  • Bash Role Generation — Full Ansible role structure with task categorisation and vault stubs

About Tool Counts

Complete tool inventory available in source code

The MCP server includes primary user-facing tools for Chef-to-Ansible migration, SaltStack migration, Puppet migration, PowerShell-to-Ansible Windows automation, Bash script migration, and Ansible upgrade planning. This documentation focuses on the primary user-facing tools that cover the main capabilities.

As a user, you'll primarily interact with the documented tools. Your AI assistant may use additional tools automatically when needed, but you don't need to know about them for successful migrations.

See API Reference and souschef/server.py for the complete authoritative list of all MCP tools.

Model Agnostic - Works with Any AI Model#

SousChef works with ANY AI model through the Model Context Protocol (MCP). The MCP architecture separates tools from models:

  • Red Hat AI (Llama, IBM models)
  • Claude (Anthropic)
  • :material-openai: GPT-4/GPT-3.5 (OpenAI)
  • GitHub Copilot (Microsoft/OpenAI)
  • 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 specialized tools. The model calls these tools to help with your migration and upgrade planning.

Core Capabilities#

Chef Cookbook Analysis & Parsing#

Complete cookbook introspection and analysis tools for understanding your Chef infrastructure.

Learn more about parsing →

Chef-to-Ansible Conversion Engine#

Advanced resource-to-task conversion with intelligent module selection and guard handling.

Learn more about conversion →

Validation & Testing#

Comprehensive validation framework and InSpec integration for ensuring migration accuracy.

Learn more about validation →

Chef Habitat to Container Conversion#

Modernise Habitat applications to containerised deployments with Docker and Compose.

Learn more about Habitat conversion →

PowerShell to Ansible Migration#

Enterprise Windows automation migration — convert PowerShell provisioning scripts to idiomatic ansible.windows playbooks, roles, inventories, and AWX/AAP job templates.

Learn more about PowerShell migration →

Bash Script to Ansible Migration#

Enterprise-grade conversion of provisioning Bash scripts to idiomatic Ansible playbooks, roles, and AAP job templates with quality scoring and sensitive data detection.

Learn more about Bash migration →

SaltStack to Ansible Migration#

Enterprise-grade SaltStack migration — convert Salt states, pillars, and top.sls targeting to Ansible roles, group_vars, Ansible Vault, and INI inventory.

Learn more about Salt migration →

Puppet to Ansible Migration#

Convert Puppet manifests and module directories to idiomatic Ansible playbooks using ansible.builtin modules, with guidance for complex DSL constructs.

Learn more about Puppet migration →

Ansible Upgrade Assessment & Planning#

Comprehensive Ansible upgrade planning based on official compatibility matrices and EOL tracking.

Learn more about Ansible upgrades →

Visual Migration Planning Interface#

Interactive web-based interface for multi-platform-to-Ansible migration planning and visualisation.

Learn more about the UI →

Quick Start#

Get started with SousChef in minutes:

# Install from PyPI
pip install mcp-souschef

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

# Restart Claude and start using
# Ask: "What migration tools are available?"

# Install from PyPI
pip install mcp-souschef

# Copy config to VS Code (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, trust the server
# Use tools in Copilot Chat:
# "Analyze the cookbook at /path/to/cookbook"

```bash
# Run an end-to-end v2 migration
souschef-cli v2 migrate \
    --cookbook-path /path/to/cookbook \
    --chef-version 15.10.91 \
    --target-platform aap \
    --target-version 2.4.0 \
    --save-state

# Load the stored migration state later
souschef-cli v2 status --migration-id mig-abc123
```

Launch the Visual Interface: 

# Using Poetry (development)
poetry run souschef ui

# Using pip (installed)
souschef ui

# Custom port
souschef ui --port 8080

Features: - Interactive cookbook analysis with archive upload - Real-time dependency visualisation - Migration planning wizards - Progress tracking and validation reports

Learn more about the UI →

Get started →

Enterprise Features#

  • Migration Assessment & Reporting - Automated complexity analysis and executive reports
  • Modern Deployment Patterns - Blue/green, canary releases, and cloud-native strategies
  • Secrets Management - Secure data bag to Ansible Vault conversion
  • Performance Profiling - Identify bottlenecks and optimise large-scale migrations

What's Next?#

Community & Support#

SousChef - Transforming infrastructure automation, one recipe at a time.