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.

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.

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)
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 38 specialized tools. The model calls these tools to help with your migration.

See config/CONFIGURATION.md for configuration examples with different model providers.

Installation

# PyPI Installation
pip install mcp-souschef

# Development Installation
git clone https://github.com/kpeacocke/souschef.git
cd souschef
poetry install

For detailed installation instructions, MCP setup, and configuration, see Installation & Setup

Core Capabilities

1. Chef Cookbook Analysis & Parsing

Complete cookbook introspection and analysis tools:

parse_template - Parse ERB templates with Jinja2 conversion and variable extraction
parse_custom_resource - Extract properties, attributes, and actions from custom resources and LWRPs
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_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

2. Chef-to-Ansible Conversion Engine

Advanced resource-to-task conversion with intelligent module selection:

convert_resource_to_task - Transform individual Chef resources to Ansible tasks
generate_playbook_from_recipe - Generate complete Ansible playbooks from Chef recipes
Enhanced Guard Handling - Convert complex Chef guards to Ansible when/unless conditions
- Array-based guards: only_if ['condition1', 'condition2']
- Lambda/proc syntax: only_if { ::File.exist?('/path') }
- Do-end blocks: not_if do ... end
- Multiple guard types per resource with proper AND/OR logic
- Platform checks, node attributes, file/directory existence, and command execution

3. Chef Search & Inventory Integration

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

4. InSpec Integration & Validation

Complete InSpec-to-Ansible testing pipeline:

parse_inspec_profile - Parse InSpec profiles and extract controls
convert_inspec_to_test - Convert InSpec controls to Testinfra or Ansible assert tasks
generate_inspec_from_recipe - Auto-generate InSpec validation from Chef recipes

5. Data Bags & Secrets Management

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

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

7. AWX/Ansible Automation Platform Integration

Enterprise AWX/AAP configuration generation:

generate_awx_job_template_from_cookbook - Create AWX job templates from cookbooks
generate_awx_workflow_from_chef_runlist - Transform Chef run-lists to AWX workflows
generate_awx_project_from_cookbooks - Generate AWX projects from cookbook collections
generate_awx_inventory_source_from_chef - Create dynamic inventory sources from Chef server

8. Chef Habitat to Container Conversion

Modernize Habitat applications to containerized deployments:

parse_habitat_plan - Parse Chef Habitat plan files (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration
convert_habitat_to_dockerfile - Convert Chef Habitat plans to production-ready Dockerfiles with security validation
generate_compose_from_habitat - Generate docker-compose.yml from multiple Habitat plans for multi-service deployments

9. Advanced Deployment Patterns & Migration Assessment

Modern deployment strategies and migration planning:

convert_chef_deployment_to_ansible_strategy - Convert deployment recipes to Ansible strategies
generate_blue_green_deployment_playbook - Create blue/green deployment playbooks
generate_canary_deployment_strategy - Generate canary deployment configurations

10. Conversion Validation Framework

Comprehensive validation of Chef-to-Ansible conversions:

validate_conversion - Validate conversions across multiple dimensions
- Syntax Validation: YAML, Jinja2, Python syntax checking
- Semantic Validation: Logic equivalence, variable usage, resource dependencies
- Best Practice Checks: Naming conventions, idempotency, task organization
- Security Validation: Privilege escalation patterns, sensitive data handling
- Performance Recommendations: Efficiency suggestions and optimizations

Validation Levels

ERROR: Critical issues that will prevent execution
WARNING: Potential problems or anti-patterns that may cause issues
INFO: Suggestions for improvements and best practices

Validation Categories

Syntax: Code structure and syntax correctness
Semantic: Logical equivalence and meaning preservation
Best Practice: Ansible community standards and patterns
Security: Security considerations and recommendations
Performance: Efficiency and optimization suggestions

Example Usage

# Validate a resource conversion
validate_conversion(
    conversion_type="resource",
    result_content="""- name: Install nginx
  ansible.builtin.package:
    name: "nginx"
    state: present
""",
    output_format="text"  # Options: text, json, summary
)

Output formats:

text: Detailed report with all findings grouped by severity
json: Structured JSON for programmatic processing
summary: Quick overview with counts only
analyze_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
generate_migration_report - Generate executive and technical migration reports

Migration Workflow

Phase 1: Discovery & Assessment

# Assess migration complexity
assess_chef_migration_complexity /path/to/cookbooks

# Analyze cookbook dependencies
analyze_cookbook_dependencies /path/to/cookbook

# Generate migration plan
generate_migration_plan '{\"cookbooks\": [\"/path/to/cookbook1\", \"/path/to/cookbook2\"]}'

Phase 2: Content Conversion

# Convert recipes to playbooks
generate_playbook_from_recipe /path/to/recipe.rb

# Convert data bags to Ansible Vault
generate_ansible_vault_from_databags /path/to/databags

# Convert environments to inventory
generate_inventory_from_chef_environments /path/to/environments

Phase 3: AWX/AAP Integration

# Generate AWX job templates
generate_awx_job_template_from_cookbook /path/to/cookbook cookbook_name

# Create AWX workflows from run-lists
generate_awx_workflow_from_chef_runlist \"recipe[app::deploy]\" workflow_name

# Setup dynamic inventory from Chef server
generate_awx_inventory_source_from_chef https://chef.example.com production web_servers

Phase 4: Habitat to Container Migration

# Parse Habitat plan
parse_habitat_plan /path/to/plan.sh

# Convert to Dockerfile
convert_habitat_to_dockerfile /path/to/plan.sh ubuntu:22.04

# Generate docker-compose for multiple services
generate_compose_from_habitat "/path/to/plan1.sh,/path/to/plan2.sh" my_network

Phase 5: Validation & Testing

# Generate InSpec validation
generate_inspec_from_recipe /path/to/recipe.rb

# Convert existing InSpec to Ansible tests
convert_inspec_to_test /path/to/inspec_profile testinfra

Enterprise Features

Migration Assessment & Reporting

Complexity Analysis: Automated assessment of migration effort and risk factors
Dependency Mapping: Complete cookbook dependency analysis with migration ordering
Impact Analysis: Resource usage patterns and conversion recommendations
Executive Reports: Stakeholder-ready migration reports with timelines and costs

Modern Deployment Patterns

Blue/Green Deployments: Zero-downtime deployment strategies
Canary Releases: Gradual rollout configurations
Application Patterns: Modern containerized and cloud-native deployment patterns
Rollback Strategies: Automated failure recovery procedures
Habitat to Container: Convert Chef Habitat plans to Docker and Docker Compose configurations

Enterprise Integration

AWX/AAP Ready: Native Ansible Automation Platform integration
Dynamic Inventory: Chef server integration for hybrid environments
Secrets Management: Secure data bag to Vault conversion
Multi-Environment: Production-ready inventory and variable management

Installation & Setup

Prerequisites

Python 3.14+
Poetry for dependency management
MCP-compatible client (Claude Desktop, VS Code with MCP extension, etc.)

Quick Start

Install SousChef:
```
pip install mcp-souschef
```
Configure Your MCP Client:

Use the pre-configured files in the config/ directory for quick setup with Claude Desktop, VS Code Copilot, or other MCP clients.
```
# Example: Claude Desktop (macOS)
cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
** See config/CONFIGURATION.md for:**
- Platform-specific setup (macOS/Linux/Windows)
- Model provider configurations (Red Hat AI, OpenAI, local models)
- Development setup
- Troubleshooting
Start Using SousChef:
- Restart your MCP client
- Ask: "What Chef migration tools are available?"
- Begin analyzing your cookbooks!

Command Line Interface (CLI)

SousChef includes a standalone CLI for direct cookbook parsing and conversion:

# Basic usage examples
souschef-cli --help
souschef-cli recipe /path/to/recipe.rb
souschef-cli template /path/to/template.erb
souschef-cli convert package nginx --action install
souschef-cli cookbook /path/to/cookbook

# Parse and convert with output formats
souschef-cli recipe recipe.rb --format json
souschef-cli inspec-generate recipe.rb > validation.rb
souschef-cli inspec-convert controls.rb --format testinfra

Available Commands:

recipe - Parse Chef recipe files and extract resources
template - Convert ERB templates to Jinja2 with variable extraction
resource - Parse custom resources and LWRPs
attributes - Extract Chef attribute definitions
metadata - Parse cookbook metadata.rb files
structure - Display cookbook directory structure
convert - Convert Chef resources to Ansible tasks
cookbook - Comprehensive cookbook analysis
inspec-parse - Parse InSpec profiles and controls
inspec-convert - Convert InSpec to Testinfra/Ansible tests
inspec-generate - Generate InSpec validation from recipes
ls / cat - File system operations

Development Setup

# Install dependencies
poetry install

# Install pre-commit hooks (one-time - auto-handles poetry.lock)
poetry run pre-commit install

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=souschef --cov-report=html

# Lint and format
poetry run ruff check .
poetry run ruff format .

# Type check
poetry run mypy souschef

Dependency Management

Poetry manages dependencies with automatic lock file synchronization:

# Add dependencies
poetry add package-name              # Production
poetry add --group dev package-name  # Development

# Update lock file after manual pyproject.toml edits
poetry lock  # Poetry 2.x preserves versions automatically

# Update dependencies
poetry update package-name  # Specific package
poetry update              # All packages

Automated Systems:

Pre-commit hooks auto-update poetry.lock when pyproject.toml changes
CI validates lock file on every PR
Dependabot sends weekly dependency updates

See CONTRIBUTING.md for detailed dependency management guide.

Architecture & Design

MCP Protocol Integration

SousChef leverages the Model Context Protocol (MCP) to provide seamless integration with AI assistants and development environments:

38 Specialized Tools: Each migration capability exposed as dedicated MCP tool
Type-Safe Interfaces: Full Python type hints for reliable AI interactions
Comprehensive Error Handling: Graceful degradation and helpful error messages
Streaming Support: Efficient handling of large cookbook conversions

Testing Strategy

Following enterprise-grade testing standards with comprehensive test coverage:

Unit Tests: Mock-based testing for individual functions (test_server.py, test_cli.py, test_mcp.py)
Integration Tests: Real cookbook testing with fixtures (test_integration.py, test_integration_accuracy.py)
Property-Based Tests: Hypothesis fuzz testing for edge cases (test_property_based.py)
Specialized Tests: Enhanced guards (test_enhanced_guards.py), error handling (test_error_paths.py, test_error_recovery.py), real-world fixtures (test_real_world_fixtures.py)
Performance Tests: Benchmarking and optimization validation (test_performance.py)
Snapshot Tests: Regression testing for output stability (test_snapshots.py)
92% Coverage: Comprehensive test coverage exceeding the 90% target for production readiness

Quality Assurance

Zero Warnings Policy: All code passes linting without disabling checks
Type Safety: Complete type annotations throughout the codebase
Automated Testing: CI/CD pipeline with comprehensive test suites
Documentation: Detailed docstrings and usage examples

Documentation

Tool Reference

Each MCP tool includes comprehensive documentation:

Purpose and use cases
Parameter descriptions and types
Return value specifications
Usage examples and patterns
Error handling behaviors

Migration Guides

Enterprise Migration Guide - Complete methodology for large-scale migrations
AWX Integration Guide - Step-by-step AWX/AAP setup and configuration
Testing Strategy Guide - Validation and testing approaches
Best Practices - Recommended patterns and approaches

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

Development setup and workflow
Code style and testing requirements
Pull request process
Issue reporting guidelines

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Roadmap

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
Data bags to Ansible Vault conversion
Chef environments to Ansible inventory conversion
Chef search patterns to dynamic inventory conversion
AWX/AAP job templates, workflows, and project generation
Blue/green and canary deployment pattern generation
Migration complexity assessment and planning tools
Comprehensive testing suite (unit, integration, property-based)
Command-line interface (CLI) for standalone usage
Enhanced Chef guard handling (arrays, lambda syntax, complex nested conditions)
Advanced attribute precedence resolution (6 levels with conflict detection)
Automated release management with Release Please
Automated branch cleanup for release PRs
Automated conversion validation and testing framework
Chef Habitat to containerized deployment conversion (parse_habitat_plan, convert_habitat_to_dockerfile, generate_compose_from_habitat)

In Progress

Enhanced error handling and user experience improvements
Documentation website and interactive examples
Performance optimizations for large-scale enterprise migrations
Technical debt reduction (15 functions tracked in GitHub Issues)

Planned 📅

📅 Integration with additional test frameworks (ServerSpec, Goss)
📅 Visual migration planning and dependency mapping interface
📅 Terraform provider for infrastructure state management
📅 Jenkins/GitLab CI pipeline generation

🙋‍♀️ Support & Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

SousChef - Transforming infrastructure automation, one recipe at a time. ✨ desc 'Ensure package nginx is properly configured' impact 1.0

describe package('nginx') do it { should be_installed } end end

control 'service-nginx' do title 'Verify service nginx' desc 'Ensure service nginx is properly configured' impact 1.0

describe service('nginx') do it { should be_running } it { should be_enabled } end end

control 'template--etc-nginx-nginx.conf' do title 'Verify template /etc/nginx/nginx.conf' desc 'Ensure template /etc/nginx/nginx.conf is properly configured' impact 1.0

describe file('/etc/nginx/nginx.conf') do it { should exist } its('mode') { should cmp '0644' } its('owner') { should eq 'root' } its('group') { should eq 'root' } end end


#### Testinfra Integration

Convert to Python tests for CI/CD pipelines:

```bash
souschef-cli inspec-convert validation-controls.rb --format testinfra

import pytest

def test_package_nginx(host):
    """Ensure package nginx is properly configured"""
    pkg = host.package("nginx")
    assert pkg.is_installed

def test_service_nginx(host):
    """Ensure service nginx is properly configured"""
    svc = host.service("nginx")
    assert svc.is_running
    assert svc.is_enabled

def test_template_etc_nginx_nginx_conf(host):
    """Ensure template /etc/nginx/nginx.conf is properly configured"""
    f = host.file("/etc/nginx/nginx.conf")
    assert f.exists
    assert oct(f.mode) == "0644"
    assert f.user == "root"
    assert f.group == "root"

Ansible Assert Integration

For Ansible playbook validation:

souschef-cli inspec-convert validation-controls.rb --format ansible_assert

---
# Validation tasks converted from InSpec

- name: Verify package nginx
  ansible.builtin.assert:
    that:
      - ansible_facts.packages['nginx'] is defined
    fail_msg: "Ensure package nginx is properly configured validation failed"

- name: Verify service nginx
  ansible.builtin.assert:
    that:
      - services['nginx'].state == 'running'
      - services['nginx'].status == 'enabled'
    fail_msg: "Ensure service nginx is properly configured validation failed"

Benefits

Consistency Validation - Ensure Chef and Ansible produce identical infrastructure state
AI Context Enhancement - InSpec profiles help AI understand infrastructure intent
Automated Testing - Generate tests automatically from Chef recipes
Multiple Test Formats - Support for InSpec, Testinfra, and Ansible assert
CI/CD Integration - Easy integration with existing test pipelines

As an MCP Server

SousChef is designed to be used as an MCP server with AI assistants that support the Model Context Protocol.

Configure with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "souschef": {
      "command": "poetry",
      "args": [
        "-C",
        "/path/to/souschef",
        "run",
        "souschef"
      ]
    }
  }
}

Available Tools

`list_directory(path: str)`

List the contents of a directory.

Example:

list_directory("/path/to/cookbooks")
# Returns: ['nginx', 'apache2', 'mysql']

`read_file(path: str)`

Read the contents of a file.

Example:

read_file("/path/to/cookbook/recipes/default.rb")
# Returns: file contents as string

`read_cookbook_metadata(path: str)`

Parse Chef cookbook metadata.rb file.

Example:

read_cookbook_metadata("/path/to/cookbook/metadata.rb")
# Returns:
# name: nginx
# maintainer: Chef Software, Inc.
# version: 8.0.0
# depends: logrotate, iptables

`parse_recipe(path: str)`

Parse a Chef recipe file and extract resources.

Example:

parse_recipe("/path/to/cookbook/recipes/default.rb")
# Returns:
# Resource 1:
#   Type: package
#   Name: nginx
#   Action: install

`parse_attributes(path: str, resolve_precedence: bool = True)`

Parse a Chef attributes file and extract attribute definitions with precedence analysis.

Chef Attribute Precedence (lowest to highest):

default - Normal default value
force_default - Forced default, higher than regular default
normal - Normal attribute set by cookbook
override - Override values
force_override - Forced override, cannot be overridden
automatic - Automatically detected by Ohai (highest precedence)

When multiple attributes with the same path exist at different precedence levels, the highest precedence wins. The tool automatically resolves conflicts and reports which values were overridden.

Parameters:

path: Path to the attributes (.rb) file
resolve_precedence: If True (default), resolves conflicts and shows only winning values. If False, shows all attributes.

Example:

# With precedence resolution (default)
parse_attributes("/path/to/cookbook/attributes/default.rb")
# Returns:
# Resolved Attributes (with precedence):
# ==================================================
#
# Attribute: nginx.port
#   Value: 443
#   Precedence: force_override (level 5)
#     Overridden values: default=80, normal=8080
#
# Attribute: nginx.ssl_port
#   Value: 443
#   Precedence: default (level 1)
#
# ==================================================
# Total attributes: 2
# Attributes with precedence conflicts: 1

# Without precedence resolution (show all)
parse_attributes("/path/to/cookbook/attributes/default.rb", resolve_precedence=False)
# Returns:
# default[nginx.port] = 80
# normal[nginx.port] = 8080
# force_override[nginx.port] = 443
# default[nginx.ssl_port] = 443

Use Cases:

Understanding attribute conflicts in complex cookbooks
Debugging which attributes will actually be applied
Planning attribute migrations to Ansible variables
Identifying force_override attributes that need special handling

`list_cookbook_structure(path: str)`

List the structure of a Chef cookbook directory.

Example:

list_cookbook_structure("/path/to/cookbook")
# Returns:
# recipes/
#   default.rb
#   install.rb
# attributes/
#   default.rb
# metadata/
#   metadata.rb

`parse_template(path: str)`

Parse a Chef ERB template file and convert it to Jinja2 format.

Example:

parse_template("/path/to/cookbook/templates/default/nginx.conf.erb")
# Returns JSON with:
# {
#   "original_file": "/path/to/cookbook/templates/default/nginx.conf.erb",
#   "variables": [
#     "nginx']['port",
#     "nginx']['server_name",
#     "nginx']['ssl_enabled"
#   ],
#   "jinja2_template": "server {\n  listen {{ nginx']['port }};\n  {% if nginx']['ssl_enabled %}\n  ssl on;\n  {% endif %}\n}"
# }

ERB to Jinja2 Conversion:

Variable output: <%= var %> → {{ var }}
Instance variables: <%= @var %> → {{ var }}
Node attributes: <%= node['attr'] %> → {{ attr }}
Conditionals: <% if cond %> → {% if cond %}
Unless: <% unless cond %> → {% if not cond %}
Elsif: <% elsif cond %> → {% elif cond %}
Else: <% else %> → {% else %}
Loops: <% arr.each do |item| %> → {% for item in arr %}
End blocks: <% end %> → {% endif %} or {% endfor %}

`parse_custom_resource(path: str)`

Parse a Chef custom resource or LWRP file and extract properties, attributes, and actions.

Example:

parse_custom_resource("/path/to/cookbook/resources/app_config.rb")
# Returns JSON with:
# {
#   "resource_file": "/path/to/cookbook/resources/app_config.rb",
#   "resource_name": "app_config",
#   "resource_type": "custom_resource",  # or "lwrp"
#   "properties": [
#     {
#       "name": "config_name",
#       "type": "String",
#       "name_property": true
#     },
#     {
#       "name": "port",
#       "type": "Integer",
#       "default": "8080"
#     },
#     {
#       "name": "ssl_enabled",
#       "type": "[true, false]",
#       "default": "false"
#     }
#   ],
#   "actions": ["create", "delete"],
#   "default_action": "create"
# }

Detected Resource Types:

Custom Resource (modern) - Uses property keyword
LWRP (legacy) - Uses attribute keyword with kind_of:

Property/Attribute Fields:

name - Property/attribute name
type - Type constraint (String, Integer, Boolean, Array, Hash, etc.)
name_property - Whether this is the resource's name property (true/false)
default - Default value if specified
required - Whether the property is required (true/false)

Action Extraction:

Modern format: action :name do ... end
LWRP format: actions :create, :delete, :update
Supports both formats and mixed declarations

`convert_resource_to_task(resource_type: str, resource_name: str, action: str = "create", properties: str = "")`

Convert a Chef resource to an Ansible task.

Example:

convert_resource_to_task("package", "nginx", "install")
# Returns:
# - name: Install package nginx
#   ansible.builtin.package:
#     name: "nginx"
#     state: "present"

convert_resource_to_task("service", "nginx", "start")
# Returns:
# - name: Start service nginx
#   ansible.builtin.service:
#     name: "nginx"
#     enabled: true
#     state: "started"

convert_resource_to_task("template", "/etc/nginx/nginx.conf.erb", "create")
# Returns:
# - name: Create template /etc/nginx/nginx.conf.erb
#   ansible.builtin.template:
#     src: "/etc/nginx/nginx.conf.erb"
#     dest: "/etc/nginx/nginx.conf"
#     mode: "0644"

Supported Resource Types:

package → ansible.builtin.package
service → ansible.builtin.service
template → ansible.builtin.template
file → ansible.builtin.file
directory → ansible.builtin.file (with state: directory)
execute → ansible.builtin.command
bash → ansible.builtin.shell
user → ansible.builtin.user
group → ansible.builtin.group
And more...

`parse_habitat_plan(plan_path: str)`

Parse a Chef Habitat plan file (plan.sh) and extract package metadata, dependencies, build/install hooks, and service configuration.

Example:

parse_habitat_plan("/path/to/habitat/plan.sh")
# Returns JSON with:
# {
#   "package": {
#     "name": "nginx",
#     "origin": "core",
#     "version": "1.25.3",
#     "maintainer": "The Habitat Maintainers",
#     "description": "High-performance HTTP server"
#   },
#   "dependencies": {
#     "build": ["core/gcc", "core/make"],
#     "runtime": ["core/glibc", "core/openssl"]
#   },
#   "ports": [
#     {"name": "http", "value": "http.port"},
#     {"name": "https", "value": "http.ssl_port"}
#   ],
#   "binds": [
#     {"name": "database", "value": "postgresql.default"}
#   ],
#   "service": {
#     "run": "nginx -g 'daemon off;'",
#     "user": "nginx"
#   },
#   "callbacks": {
#     "do_build": "./configure --prefix=/usr/local\nmake",
#     "do_install": "make install",
#     "do_init": "mkdir -p /var/lib/nginx"
#   }
# }

Extracted Information:

Package metadata: name, origin, version, maintainer, description
Dependencies: Build-time and runtime package dependencies
Ports: Exported port configurations for service discovery
Binds: Service bindings to other Habitat services
Service configuration: Run command, user, and initialization scripts
Build callbacks: do_build, do_install, do_init, and other lifecycle hooks

Use Cases:

Understanding Habitat application structure before containerization
Extracting dependencies for Docker base image selection
Planning port mappings for docker-compose configurations
Analyzing service dependencies and orchestration needs

`convert_habitat_to_dockerfile(plan_path: str, base_image: str = "ubuntu:22.04")`

Convert a Chef Habitat plan to a production-ready Dockerfile with security validation.

Example:

convert_habitat_to_dockerfile("/path/to/habitat/plan.sh", "ubuntu:22.04")
# Returns:
# # Dockerfile generated from Habitat plan
# # Original plan: plan.sh
# # Package: core/nginx
# # Version: 1.25.3
#
# FROM ubuntu:22.04
#
# LABEL maintainer="The Habitat Maintainers"
# LABEL version="1.25.3"
#
# # Install dependencies
# RUN apt-get update && apt-get install -y --no-install-recommends \
#     gcc \
#     make \
#     libssl-dev \
#     && rm -rf /var/lib/apt/lists/*
#
# # Build steps
# WORKDIR /usr/local/src
# RUN ./configure --prefix=/usr/local && \
#     make
#
# # Install steps
# RUN make install
#
# # Initialization steps
# RUN mkdir -p /var/lib/nginx
#
# # Runtime configuration
# EXPOSE 80
# EXPOSE 443
# USER nginx
# WORKDIR /usr/local
#
# CMD ["nginx", "-g", "daemon off;"]

Parameters:

plan_path: Path to the Habitat plan.sh file
base_image: Docker base image (default: ubuntu:22.04). Validated for security

Features:

Dependency mapping: Converts Habitat dependencies to apt packages
Build optimization: Multi-stage builds when applicable
Security scanning: Detects dangerous patterns (curl|sh, eval, etc.)
Metadata preservation: LABEL instructions for package info
User configuration: Non-root user setup when specified
Port exposure: Automatic EXPOSE directives from plan ports

Security Warnings: The tool processes shell commands from Habitat plans and includes them in the Dockerfile. Only use with trusted Habitat plans from known sources. Review generated Dockerfiles before building images.

`generate_compose_from_habitat(plan_paths: str, network_name: str = "habitat_net")`

Generate docker-compose.yml from multiple Habitat plans for multi-service deployments.

Example:

# Single service
generate_compose_from_habitat("/path/to/nginx/plan.sh", "myapp_network")
# Returns:
# version: '3.8'
# services:
#   nginx:
#     build:
#       context: .
#       dockerfile: Dockerfile.nginx
#     container_name: nginx
#     ports:
#       - "80:80"
#       - "443:443"
#     environment:
#       - HTTP=80
#       - HTTPS=443
#     networks:
#       - myapp_network
#
# networks:
#   myapp_network:
#     driver: bridge

# Multiple services with dependencies
generate_compose_from_habitat(
    "/path/to/backend/plan.sh,/path/to/postgres/plan.sh",
    "app_network"
)
# Returns:
# version: '3.8'
# services:
#   backend:
#     build:
#       context: .
#       dockerfile: Dockerfile.backend
#     container_name: backend
#     ports:
#       - "8080:8080"
#     environment:
#       - PORT=8080
#     depends_on:
#       - postgres
#     networks:
#       - app_network
#
#   postgres:
#     build:
#       context: .
#       dockerfile: Dockerfile.postgres
#     container_name: postgres
#     ports:
#       - "5432:5432"
#     environment:
#       - POSTGRESQL=5432
#     volumes:
#       - postgres_data:/var/lib/app
#     networks:
#       - app_network
#
# networks:
#   app_network:
#     driver: bridge
#
# volumes:
#   postgres_data:

Parameters:

plan_paths: Comma-separated paths to plan.sh files for multiple services
network_name: Docker network name for service communication (default: habitat_net)

Features:

Multi-service orchestration: Combines multiple Habitat plans into one compose file
Automatic dependencies: Creates depends_on from Habitat service binds
Volume detection: Identifies services needing persistent storage from do_init callbacks
Network isolation: Configures bridge networks for service communication
Port management: Maps ports from Habitat exports to Docker compose
Environment variables: Generates environment configuration from port definitions

Use Cases:

Converting multi-service Habitat applications to Docker Compose
Creating development environments from production Habitat plans
Simplifying container orchestration for local testing
Migration path from Habitat to Kubernetes (via docker-compose)

Development

Project Structure

souschef/
├── souschef/
│   ├── __init__.py
│   └── server.py          # MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_server.py     # Comprehensive test suite
├── .devcontainer/         # VS Code dev container config
├── .github/
│   └── copilot-instructions.md  # Copilot development guidelines
├── pyproject.toml         # Project configuration
└── README.md

Development Standards

SousChef uses a modern Python toolchain for code quality:

Ruff: Primary linter and formatter (replaces Black, isort, flake8)

poetry run ruff check .    # Lint code
poetry run ruff format .   # Format code

mypy: Static type checking for CI/CD

poetry run mypy souschef   # Type check source code

Pylance: Real-time VS Code type checking and intellisense
- Configured in .vscode/settings.json
- Provides immediate feedback during development

pytest: Testing framework with coverage reporting

poetry run pytest --cov=souschef --cov-report=term-missing

Quality Requirements:

Zero warnings from all tools (Ruff, mypy, Pylance)
Type hints required for all functions
Google-style docstrings
92% test coverage (exceeds 90% target)

See .github/copilot-instructions.md for detailed development guidelines.

Running Tests

# Run all tests
poetry run pytest

# Run with coverage report
poetry run pytest --cov=souschef --cov-report=term-missing --cov-report=html

# Run specific test suites
poetry run pytest tests/test_server.py              # Core unit tests
poetry run pytest tests/test_cli.py                 # CLI tests
poetry run pytest tests/test_mcp.py                 # MCP protocol tests
poetry run pytest tests/test_integration.py         # Integration tests
poetry run pytest tests/test_integration_accuracy.py # Accuracy validation
poetry run pytest tests/test_enhanced_guards.py     # Guard conversion tests
poetry run pytest tests/test_error_paths.py         # Error handling
poetry run pytest tests/test_error_recovery.py      # Error recovery
poetry run pytest tests/test_real_world_fixtures.py # Real-world cookbooks
poetry run pytest tests/test_property_based.py      # Hypothesis fuzz tests
poetry run pytest tests/test_performance.py         # Performance benchmarks
poetry run pytest tests/test_snapshots.py           # Snapshot regression tests

# Run with benchmarks
poetry run pytest --benchmark-only

# Check code quality
poetry run ruff check .        # Linting
poetry run ruff format .       # Formatting
poetry run mypy souschef       # Type checking

Test Types

The project includes comprehensive test coverage across multiple dimensions:

Unit Tests (test_server.py, test_cli.py, test_mcp.py)
- Mock-based tests for individual functions
- Test error handling and edge cases
- Fast execution, isolated from filesystem
- MCP protocol compliance testing
Integration Tests (test_integration.py, test_integration_accuracy.py)
- Real file operations with test fixtures
- Validate parsing with actual Chef cookbook files
- Parameterized tests for various scenarios
- Accuracy validation for conversions
Property-Based Tests (test_property_based.py)
- Uses Hypothesis for fuzz testing
- Generates random inputs to find edge cases
- Ensures functions handle any input gracefully
Specialized Test Suites
- Enhanced Guards (test_enhanced_guards.py): Complex guard condition conversion
- Error Handling (test_error_paths.py, test_error_recovery.py): Comprehensive error scenarios
- Real-World Fixtures (test_real_world_fixtures.py): Production cookbook patterns
- Performance (test_performance.py): Benchmarking and optimization
- Snapshots (test_snapshots.py): Regression testing for output stability
Test Fixtures
- Sample Chef cookbooks in tests/fixtures/
- Multiple cookbook types: apache2, docker, mysql, nodejs, legacy Chef 12, Habitat plans
- Real-world metadata, recipes, attributes, and resources
- Used across integration and accuracy testing

Test Coverage

The project maintains 92% test coverage, exceeding the 90% target. Run coverage with HTML report:

poetry run pytest --cov=souschef --cov-report=html
open htmlcov/index.html  # View detailed coverage report

Mutation Testing

To verify test quality with mutation testing:

poetry run mutmut run
poetry run mutmut results

VS Code Tasks

The project includes several VS Code tasks:

Run Tests - Execute test suite
Run Tests with Coverage - Generate coverage reports
Lint (Ruff) - Check code quality
Format (Ruff) - Auto-format code
Lint & Test - Run both linting and tests

Contributing

Contributions are welcome! Please ensure:

All tests pass
Code coverage maintained at 90%+
Code passes ruff linting
All functions have type hints and docstrings
Follow the development standards in .github/copilot-instructions.md

License

This project is licensed under the MIT License - see the LICENSE file for details.

SousChef - Ansible automation, one recipe at a time. ✨

souschef

Chef to Ansible migration - SousChef MCP

Overview - Chef to Ansible features

Model Agnostic - Works with Any AI Model

Installation

Core Capabilities

1. Chef Cookbook Analysis & Parsing

2. Chef-to-Ansible Conversion Engine

3. Chef Search & Inventory Integration

4. InSpec Integration & Validation

5. Data Bags & Secrets Management

6. Environment & Configuration Management

7. AWX/Ansible Automation Platform Integration

8. Chef Habitat to Container Conversion

9. Advanced Deployment Patterns & Migration Assessment

10. Conversion Validation Framework

Validation Levels

Validation Categories

Example Usage

Migration Workflow

Phase 1: Discovery & Assessment

Phase 2: Content Conversion

Phase 3: AWX/AAP Integration

Phase 4: Habitat to Container Migration

Phase 5: Validation & Testing

Enterprise Features

Migration Assessment & Reporting

Modern Deployment Patterns

Enterprise Integration

Installation & Setup

Prerequisites

Quick Start

Command Line Interface (CLI)

Development Setup

Dependency Management

Architecture & Design

MCP Protocol Integration

Testing Strategy

Quality Assurance

Documentation

Tool Reference

Migration Guides

🤝 Contributing

📄 License

Roadmap

Completed

In Progress

Planned 📅

🙋‍♀️ Support & Community

Ansible Assert Integration

Benefits

As an MCP Server

Configure with Claude Desktop

Available Tools

list_directory(path: str)

read_file(path: str)

read_cookbook_metadata(path: str)

parse_recipe(path: str)

parse_attributes(path: str, resolve_precedence: bool = True)

list_cookbook_structure(path: str)

parse_template(path: str)

parse_custom_resource(path: str)

convert_resource_to_task(resource_type: str, resource_name: str, action: str = "create", properties: str = "")

parse_habitat_plan(plan_path: str)

convert_habitat_to_dockerfile(plan_path: str, base_image: str = "ubuntu:22.04")

generate_compose_from_habitat(plan_paths: str, network_name: str = "habitat_net")

Development

Project Structure

Development Standards

Running Tests

Test Types

Test Coverage

Mutation Testing

VS Code Tasks

Contributing

License

Reviews

`list_directory(path: str)`

`read_file(path: str)`

`read_cookbook_metadata(path: str)`

`parse_recipe(path: str)`

`parse_attributes(path: str, resolve_precedence: bool = True)`

`list_cookbook_structure(path: str)`

`parse_template(path: str)`

`parse_custom_resource(path: str)`

`convert_resource_to_task(resource_type: str, resource_name: str, action: str = "create", properties: str = "")`

`parse_habitat_plan(plan_path: str)`

`convert_habitat_to_dockerfile(plan_path: str, base_image: str = "ubuntu:22.04")`

`generate_compose_from_habitat(plan_paths: str, network_name: str = "habitat_net")`