Skip to main content
Glama
kpeacocke

SousChef

by kpeacocke
OverviewInspectSchemaRelated ServersScoreDiscussions
Python
Hybrid

SousChef šŸ³

An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities for enterprise infrastructure transformation.

Overview

SousChef is a complete enterprise-grade migration platform with 34 MCP tools organized across 8 major capability areas to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, SousChef provides everything needed for a successful infrastructure automation migration.

šŸš€ 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 (default, override, normal) with precedence analysis

  • 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

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. 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

  • 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: 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

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+

  • uv for dependency management

  • MCP-compatible client (Claude Desktop, VS Code with MCP extension, etc.)

Quick Start

  1. Clone and setup:

    git clone https://github.com/your-org/souschef cd souschef uv sync

  2. Configure MCP client (Claude Desktop example):

    { \"mcpServers\": { \"souschef\": { \"command\": \"uv\", \"args\": [\"--directory\", \"/path/to/souschef\", \"run\", \"souschef\"], \"env\": {} } } }

  3. Start using SousChef: Ask your MCP client: "Analyze the cookbook at /path/to/my/cookbook" or "Convert this Chef recipe to an Ansible playbook"

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\n\nbash\n# Install dependencies\nuv sync\n\n# Run tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=souschef --cov-report=html\n\n# Lint and format\nuv run ruff check .\nuv run ruff format .\n

šŸ—ļø Architecture & Design

MCP Protocol Integration

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

  • 34 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:

  • Unit Tests: Mock-based testing for individual functions (tests/test_server.py)

  • Integration Tests: Real cookbook testing with fixtures (tests/test_integration.py)

  • Property-Based Tests: Hypothesis fuzz testing for edge cases (tests/test_property_based.py)

  • 82% Coverage: Comprehensive test coverage with goal of 95% 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

šŸ¤ 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

In Progress šŸ”„

  • šŸ”„ Enhanced error handling and user experience

  • šŸ”„ Documentation website and interactive examples

  • šŸ”„ Performance optimizations for large-scale migrations

Planned šŸ“…

  • šŸ“… Chef Habitat to containerized deployment conversion

  • šŸ“… 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

  • šŸ“… Custom resource conversion framework

  • šŸ“… Advanced templating and variable substitution patterns

šŸ™‹ā€ā™€ļø Support & Community

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": "uv", "args": [ "--directory", "/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)

Parse a Chef attributes file and extract attribute definitions.

Example:

parse_attributes("/path/to/cookbook/attributes/default.rb") # Returns: # default[nginx.port] = 80 # default[nginx.ssl_port] = 443

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...

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

  • Code Quality: Zero warnings policy, type hints required, Google-style docstrings

  • Testing: High test coverage (82%) using pytest with goal of 100%

  • Linting: Code must pass ruff check with no violations

  • Formatting: Code must be formatted with ruff format

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

Running Tests

# Run all tests uv run pytest # Run with coverage report uv run pytest --cov=souschef --cov-report=term-missing --cov-report=html # Run only unit tests (mocked) uv run pytest tests/test_server.py # Run only integration tests (real files) uv run pytest tests/test_integration.py # Run property-based tests uv run pytest tests/test_property_based.py # Run with benchmarks uv run pytest --benchmark-only # Run linting uv run ruff check . # Run formatting uv run ruff format .

Test Types

The project includes multiple types of tests:

  1. Unit Tests (test_server.py)

    • Mock-based tests for individual functions

    • Test error handling and edge cases

    • Fast execution, isolated from filesystem

  2. Integration Tests (test_integration.py)

    • Real file operations with test fixtures

    • Validate parsing with actual Chef cookbook files

    • Parameterized tests for various scenarios

    • Performance benchmarks with pytest-benchmark

  3. 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

  4. Test Fixtures

    • Sample Chef cookbook in tests/fixtures/sample_cookbook/

    • Real-world metadata, recipes, and attributes

    • Used for integration testing

Test Coverage

The project maintains 82% test coverage with a goal of 95%+. Run coverage with HTML report:

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

Mutation Testing

To verify test quality with mutation testing:

uv run mutmut run uv 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:

  1. All tests pass

  2. Code coverage remains at 100%

  3. Code passes ruff linting

  4. All functions have type hints and docstrings

  5. Follow the development standards in .github/copilot-instructions.md

License

TBD

Roadmap

  • Add server entry point and runner

  • Implement Chef ā†’ Ansible resource conversion (basic)

  • Support template conversion (ERB ā†’ Jinja2)

  • Parse custom Chef resources/LWRPs

  • Generate complete Ansible playbooks from recipes

  • Handle Chef guards (only_if, not_if) and notifications

  • Support complex attribute precedence and merging

  • Add conversion validation and testing

  • Handle Chef search and data bags

Install Server
A
security ā€“ no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kpeacocke/souschef'

If you have feedback or need assistance with the MCP directory API, please join our Discord server