mcp-souschef 2.0.1__py3-none-any.whl

mcp_souschef-2.0.1.dist-info/METADATA

@@ -0,0 +1,849 @@
+Metadata-Version: 2.4
+Name: mcp-souschef
+Version: 2.0.1
+Summary: AI-powered MCP server for Chef to Ansible conversion
+License: MIT
+License-File: LICENSE
+Author: SousChef Contributors
+Requires-Python: >=3.14,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: anthropic (>=0.75.0)
+Requires-Dist: click (>=8.1.0)
+Requires-Dist: mcp (>=1.25.0)
+Requires-Dist: python-dotenv (>=1.2.1)
+Requires-Dist: zod (>=0.8.0)
+Description-Content-Type: text/markdown
+
+# 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.
+
+[![PyPI version](https://img.shields.io/pypi/v/mcp-souschef.svg)](https://pypi.org/project/mcp-souschef/)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Test Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](htmlcov/index.html)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![Type Checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=kpeacocke_souschef&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=kpeacocke_souschef)
+
+## Overview - Chef to Ansible features
+
+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.
+
+## 📦 Installation
+
+```bash
+# 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](#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 (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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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+
+- [Poetry](https://python-poetry.org/) for dependency management
+- MCP-compatible client (Claude Desktop, VS Code with MCP extension, etc.)
+
+### Quick Start
+
+1. **Install SousChef**:
+   ```bash
+   pip install mcp-souschef
+   ```
+
+2. **Configure MCP Client**:
+
+   **🎯 Quick Setup - Use Pre-configured Files:**
+   ```bash
+   # Claude Desktop (macOS)
+   cp config/claude-desktop.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
+
+   # VS Code Copilot (macOS/Linux)
+   mkdir -p ~/.config/Code/User/globalStorage/github.copilot-chat
+   cp config/vscode-copilot.json ~/.config/Code/User/globalStorage/github.copilot-chat/mcp.json
+   ```
+
+   See [config/README.md](config/README.md) for detailed setup instructions, development configs, and troubleshooting.
+
+3. **Start using SousChef**:
+   - **Claude Desktop**: Restart Claude, then ask: "What tools does souschef provide?"
+   - **VS Code Copilot**: Reload window, then use: `@souschef analyze this cookbook`
+
+### Command Line Interface (CLI)
+
+SousChef includes a standalone CLI for direct cookbook parsing and conversion:
+
+```bash
+# 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
+
+```bash
+# 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**:
+
+```bash
+# 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](CONTRIBUTING.md#-managing-dependencies) 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:
+
+- **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)
+- **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](docs/enterprise-migration.md)** - Complete methodology for large-scale migrations
+- **[AWX Integration Guide](docs/awx-integration.md)** - Step-by-step AWX/AAP setup and configuration
+- **[Testing Strategy Guide](docs/testing-strategy.md)** - Validation and testing approaches
+- **[Best Practices](docs/best-practices.md)** - Recommended patterns and approaches
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](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](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 improvements
+- 🔄 Documentation website and interactive examples
+- 🔄 Performance optimizations for large-scale enterprise migrations
+- 🔄 Technical debt reduction (15 functions tracked in [GitHub Issues](https://github.com/kpeacocke/souschef/issues?q=is%3Aissue+is%3Aopen+label%3Atechnical-debt))
+
+### 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
+- 📅 Advanced Chef guard handling (only_if, not_if conditions)
+- 📅 Complex attribute precedence and merging logic
+- 📅 Conversion validation and testing framework
+
+## 🙋‍♀️ Support & Community
+
+- **Issues**: [GitHub Issues](https://github.com/kpeacocke/souschef/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/kpeacocke/souschef/discussions)
+- **Documentation**: [Wiki](https://github.com/kpeacocke/souschef/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
+```
+
+```python
+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:
+
+```bash
+souschef-cli inspec-convert validation-controls.rb --format ansible_assert
+```
+
+```yaml
+---
+# 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):
+
+```json
+{
+  "mcpServers": {
+    "souschef": {
+      "command": "poetry",
+      "args": [
+        "-C",
+        "/path/to/souschef",
+        "run",
+        "souschef"
+      ]
+    }
+  }
+}
+```
+
+### Available Tools
+
+#### `list_directory(path: str)`
+List the contents of a directory.
+
+**Example:**
+```python
+list_directory("/path/to/cookbooks")
+# Returns: ['nginx', 'apache2', 'mysql']
+```
+
+#### `read_file(path: str)`
+Read the contents of a file.
+
+**Example:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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:**
+```python
+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
+
+SousChef uses a modern Python toolchain for code quality:
+
+- **Ruff**: Primary linter and formatter (replaces Black, isort, flake8)
+  ```bash
+  poetry run ruff check .    # Lint code
+  poetry run ruff format .   # Format code
+  ```
+
+- **mypy**: Static type checking for CI/CD
+  ```bash
+  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
+  ```bash
+  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](.github/copilot-instructions.md) for detailed development guidelines.
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage report
+poetry run pytest --cov=souschef --cov-report=term-missing --cov-report=html
+
+# Run only unit tests (mocked)
+poetry run pytest tests/test_server.py
+
+# Run only integration tests (real files)
+poetry run pytest tests/test_integration.py
+
+# Run property-based tests
+poetry run pytest tests/test_property_based.py
+
+# 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 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 92% test coverage, exceeding the 90% target. Run coverage with HTML report:
+
+```bash
+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:
+
+```bash
+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:
+1. All tests pass
+2. Code coverage maintained at 90%+
+3. Code passes ruff linting
+4. All functions have type hints and docstrings
+5. Follow the development standards in `.github/copilot-instructions.md`
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+**SousChef** - *Ansible automation, one recipe at a time.* 🍳✨
+