Skip to content

SousChef Documentation#

An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-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 two major capabilities:

1. Chef to Ansible Migration (38 tools)#

Complete enterprise-grade migration platform with 38 primary MCP tools organised across 9 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

About Tool Counts

Complete tool inventory available in source code

The MCP server includes primary user-facing tools for Chef-to-Ansible migration and Ansible upgrade planning. This documentation focuses on the primary user-facing tools (38 migration + 5 upgrade) 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 →

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 Chef-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 Chef 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?#

  • Installation

    Install SousChef and configure your MCP client

    Get started

  • Quick Start

    Start migrating Chef cookbooks in minutes

    Quick start

  • User Guide

    Explore MCP tools and CLI usage

    User guide

  • Migration Guide

    Plan and execute your Chef-to-Ansible migration

    Migration guide

  • v2.0 API Reference

    Complete API documentation for the v2.0 Migration Orchestrator

    API reference

  • Advanced Workflows

    Complex migration patterns and integration strategies

    Advanced workflows

  • Troubleshooting

    Common issues and solutions for migrations

    Troubleshooting

Community & Support#

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