mcp-souschef 3.5.2__tar.gz → 4.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. mcp_souschef-3.5.2/README.md → mcp_souschef-4.0.0/PKG-INFO +178 -7
  2. mcp_souschef-3.5.2/PKG-INFO → mcp_souschef-4.0.0/README.md +132 -50
  3. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/pyproject.toml +9 -2
  4. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/ai_schemas.py +6 -1
  5. mcp_souschef-4.0.0/souschef/github/__init__.py +17 -0
  6. mcp_souschef-4.0.0/souschef/github/agent_control.py +459 -0
  7. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/server.py +193 -0
  8. mcp_souschef-4.0.0/souschef/storage/__init__.py +39 -0
  9. mcp_souschef-4.0.0/souschef/storage/blob.py +331 -0
  10. mcp_souschef-4.0.0/souschef/storage/config.py +163 -0
  11. mcp_souschef-4.0.0/souschef/storage/database.py +1182 -0
  12. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/app.py +17 -4
  13. mcp_souschef-4.0.0/souschef/ui/pages/chef_server_settings.py +709 -0
  14. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/pages/cookbook_analysis.py +352 -6
  15. mcp_souschef-4.0.0/souschef/ui/pages/history.py +964 -0
  16. mcp_souschef-3.5.2/souschef/ui/pages/chef_server_settings.py +0 -300
  17. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/LICENSE +0 -0
  18. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/__init__.py +0 -0
  19. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/assessment.py +0 -0
  20. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ci/__init__.py +0 -0
  21. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ci/common.py +0 -0
  22. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ci/github_actions.py +0 -0
  23. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ci/gitlab_ci.py +0 -0
  24. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ci/jenkins_pipeline.py +0 -0
  25. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/cli.py +0 -0
  26. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/__init__.py +0 -0
  27. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/cookbook_specific.py +0 -0
  28. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/habitat.py +0 -0
  29. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/playbook.py +0 -0
  30. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/resource.py +0 -0
  31. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/converters/template.py +0 -0
  32. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/__init__.py +0 -0
  33. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/constants.py +0 -0
  34. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/errors.py +0 -0
  35. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/http_client.py +0 -0
  36. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/logging.py +0 -0
  37. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/metrics.py +0 -0
  38. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/path_utils.py +0 -0
  39. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/ruby_utils.py +0 -0
  40. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/url_validation.py +0 -0
  41. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/core/validation.py +0 -0
  42. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/deployment.py +0 -0
  43. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/filesystem/__init__.py +0 -0
  44. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/filesystem/operations.py +0 -0
  45. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/generators/__init__.py +0 -0
  46. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/generators/repo.py +0 -0
  47. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/__init__.py +0 -0
  48. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/attributes.py +0 -0
  49. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/habitat.py +0 -0
  50. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/inspec.py +0 -0
  51. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/metadata.py +0 -0
  52. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/recipe.py +0 -0
  53. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/resource.py +0 -0
  54. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/parsers/template.py +0 -0
  55. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/profiling.py +0 -0
  56. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/__init__.py +0 -0
  57. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/health_check.py +0 -0
  58. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/pages/ai_settings.py +0 -0
  59. {mcp_souschef-3.5.2 → mcp_souschef-4.0.0}/souschef/ui/pages/validation_reports.py +0 -0
@@ -1,3 +1,48 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcp-souschef
3
+ Version: 4.0.0
4
+ Summary: AI-powered MCP server for Chef to Ansible conversion
5
+ License: MIT
6
+ License-File: LICENSE
7
+ Keywords: chef,ansible,migration,infrastructure,automation,mcp,ai,conversion
8
+ Author: SousChef Contributors
9
+ Requires-Python: >=3.10,<4.0
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: System Administrators
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Classifier: Topic :: System :: Systems Administration
23
+ Classifier: Topic :: Utilities
24
+ Provides-Extra: ai
25
+ Provides-Extra: all
26
+ Provides-Extra: storage
27
+ Provides-Extra: ui
28
+ Requires-Dist: anthropic (>=0.75.0) ; extra == "ai" or extra == "all"
29
+ Requires-Dist: boto3 (>=1.26.0) ; extra == "storage" or extra == "all"
30
+ Requires-Dist: click (>=8.1.0)
31
+ Requires-Dist: mcp (>=1.25.0)
32
+ Requires-Dist: openai (>=1.0.0) ; extra == "ai" or extra == "all"
33
+ Requires-Dist: pandas (>=2.0.0) ; extra == "ui" or extra == "all"
34
+ Requires-Dist: plotly (>=5.17.0,<7.0) ; extra == "ui" or extra == "all"
35
+ Requires-Dist: psycopg[binary] (>=3.1.19) ; extra == "storage" or extra == "all"
36
+ Requires-Dist: pydantic (>=2.0.0)
37
+ Requires-Dist: python-dotenv (>=1.2.1)
38
+ Requires-Dist: pyyaml (>=6.0.0)
39
+ Requires-Dist: requests (>=2.31.0)
40
+ Requires-Dist: streamlit (>=1.28.0) ; extra == "ui" or extra == "all"
41
+ Project-URL: Documentation, https://kpeacocke.github.io/souschef/
42
+ Project-URL: Homepage, https://github.com/kpeacocke/souschef
43
+ Project-URL: Repository, https://github.com/kpeacocke/souschef
44
+ Description-Content-Type: text/markdown
45
+
1
46
  # Chef to Ansible migration - SousChef MCP
2
47
 
3
48
  An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities for enterprise infrastructure transformation.
@@ -14,17 +59,17 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
14
59
 
15
60
  ## Overview - Chef to Ansible features
16
61
 
17
- SousChef is a complete enterprise-grade migration platform with **35 primary MCP tools** organised across **11 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, and CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.
62
+ SousChef is a complete enterprise-grade migration platform with **40 primary MCP tools** organised across **12 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, CI/CD pipeline generation, and GitHub Copilot agent control, SousChef provides everything needed for a successful infrastructure automation migration.
18
63
 
19
64
  ### About Tool Counts
20
65
 
21
- **Why 35 tools in the documentation but more in the server?**
66
+ **Why 40 tools in the documentation but more in the server?**
22
67
 
23
- The MCP server provides **38 total tools**. This documentation focuses on the **35 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations used internally by the main tools.
68
+ The MCP server provides **43 total tools**. This documentation focuses on the **40 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations used internally by the main tools.
24
69
 
25
70
  As a user, you'll primarily interact with the documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.
26
71
 
27
- > **For developers:** See `souschef/server.py` for the complete list of all 38 registered tools.
72
+ > **For developers:** See `souschef/server.py` for the complete list of all 43 registered tools.
28
73
 
29
74
  ## Model Agnostic - Works with Any AI Model
30
75
 
@@ -45,6 +90,7 @@ As a user, you'll primarily interact with the documented tools. Your AI assistan
45
90
 
46
91
  - **[Terraform Provider](terraform-provider/README.md)** - Manage migrations with infrastructure-as-code
47
92
  - **[User Guide](docs/user-guide/)** - Complete documentation
93
+ - **[Data Persistence Guide](docs/user-guide/data-persistence.md)** - History, caching, and storage backends
48
94
  - **[API Reference](docs/api-reference/)** - Detailed tool documentation
49
95
  - **[Migration Guide](docs/migration-guide/)** - Step-by-step migration process
50
96
 
@@ -184,7 +230,27 @@ Automatically detects and converts:
184
230
  - **Cookstyle/Foodcritic** → Lint stages
185
231
  - Multiple test suites → Parallel execution strategies
186
232
 
187
- #### Example Usage
233
+ ### 11. GitHub Copilot Agent Control
234
+
235
+ Manage GitHub Copilot agents working on repository issues with full pause/stop/resume capabilities:
236
+
237
+ - **assign_github_copilot_to_issue** - Assign Copilot agent to implement an issue
238
+ - **pause_github_copilot_agent** - Pause a running agent (can be resumed)
239
+ - **stop_github_copilot_agent** - Stop and cancel an agent assignment
240
+ - **resume_github_copilot_agent** - Resume a paused agent with optional new instructions
241
+ - **check_github_copilot_agent_status** - Check current agent state and activity
242
+
243
+ **Agent lifecycle management:**
244
+
245
+ 1. **Assign** - Start Copilot working on an issue
246
+ 2. **Monitor** - Check status and review progress
247
+ 3. **Pause** - Temporarily pause for review or changes
248
+ 4. **Resume** - Continue with optional new guidance
249
+ 5. **Stop** - Cancel if requirements change
250
+
251
+ State is tracked via issue labels and comments, providing full visibility and control.
252
+
253
+ #### Example Usage - CI/CD Pipelines
188
254
 
189
255
  ```bash
190
256
  # Generate Jenkins Declarative pipeline
@@ -199,12 +265,58 @@ souschef generate-gitlab-ci ./mycookbook
199
265
  # Generate GitHub Actions workflow
200
266
  souschef generate-github-workflow ./mycookbook
201
267
 
202
- # Customize with options
268
+ # Customise with options
203
269
  souschef generate-gitlab-ci ./mycookbook --no-cache --no-artifacts
204
270
  souschef generate-github-workflow ./mycookbook --workflow-name "My CI" --no-cache
205
271
  ```
206
272
 
207
- #### Command Line Usage
273
+ #### Example Usage - GitHub Agent Control
274
+
275
+ ```python
276
+ # From an AI assistant with SousChef MCP
277
+
278
+ # Assign Copilot to work on an issue
279
+ assign_github_copilot_to_issue(
280
+ owner="myorg",
281
+ repo="my-ansible-repo",
282
+ issue_number=42,
283
+ base_ref="main",
284
+ custom_instructions="Focus on idempotency and error handling"
285
+ )
286
+
287
+ # Check agent status
288
+ check_github_copilot_agent_status(
289
+ owner="myorg",
290
+ repo="my-ansible-repo",
291
+ issue_number=42
292
+ )
293
+
294
+ # Pause for review
295
+ pause_github_copilot_agent(
296
+ owner="myorg",
297
+ repo="my-ansible-repo",
298
+ issue_number=42,
299
+ reason="Need to review approach before continuing"
300
+ )
301
+
302
+ # Resume with new guidance
303
+ resume_github_copilot_agent(
304
+ owner="myorg",
305
+ repo="my-ansible-repo",
306
+ issue_number=42,
307
+ additional_instructions="Also add role dependencies"
308
+ )
309
+
310
+ # Stop if no longer needed
311
+ stop_github_copilot_agent(
312
+ owner="myorg",
313
+ repo="my-ansible-repo",
314
+ issue_number=42,
315
+ reason="Requirements changed - manual implementation needed"
316
+ )
317
+ ```
318
+
319
+ #### Command Line Usage - CI/CD Pipelines
208
320
 
209
321
  **MCP Tool Usage:**
210
322
 
@@ -433,6 +545,7 @@ Interactive web-based interface for Chef-to-Ansible migration planning and visua
433
545
  - **Dependency Mapping**: Visual dependency graphs showing cookbook relationships and migration ordering
434
546
  - **Validation Reports**: Conversion validation results with syntax checking and best practice compliance
435
547
  - **Progress Tracking**: Real-time migration progress with completion metrics and bottleneck identification
548
+ - **History and Persistence**: Stored analysis history, cached results, and downloadable artefacts (SQLite or PostgreSQL, plus S3-compatible storage)
436
549
 
437
550
  **Launch the UI:**
438
551
 
@@ -553,8 +666,59 @@ STREAMLIT_SERVER_HEADLESS=true
553
666
  - `SOUSCHEF_AI_MAX_TOKENS` - Maximum tokens to generate (optional, default: 4000)
554
667
  - `SOUSCHEF_ALLOWED_HOSTNAMES` - Comma-separated list of allowed hostnames for outbound API requests (optional)
555
668
 
669
+ **Persistent Storage Configuration (Docker Compose):**
670
+
671
+ All persistent storage paths are configurable via environment variables. Add these to your `.env` file to customise where data is stored:
672
+
673
+ ```dotenv
674
+ # Docker Compose Volume Configuration (optional)
675
+ SOUSCHEF_DATA_DIR=./data/souschef # SQLite database and analysis history
676
+ SOUSCHEF_STORAGE_DIR=./data/storage # Generated artefacts and conversions
677
+ POSTGRES_DATA_DIR=./data/postgres # PostgreSQL database files
678
+ MINIO_DATA_DIR=./data/minio # MinIO object storage data
679
+ ```
680
+
681
+ The storage paths default to `./data/` subdirectories (relative to docker-compose.yml) but can be set to any absolute or relative path. This allows you to:
682
+ - Store data on different volumes or network storage
683
+ - Easily backup and restore data by copying directories
684
+ - Share data between development and production environments
685
+
686
+ See [Docker Deployment Guide](docs/docker-deployment.md#persistent-storage-configuration) for detailed configuration options.
687
+
556
688
  **Docker Compose (recommended for development):**
557
689
 
690
+ ```bash
691
+ # Using PostgreSQL (default, production-ready)
692
+ docker compose up
693
+
694
+ # Or if you prefer SQLite (lightweight, local storage only):
695
+ # 1. Set in .env: SOUSCHEF_DB_BACKEND=sqlite
696
+ # 2. Run normally: docker compose up
697
+ ```
698
+
699
+ **Database Options:**
700
+
701
+ - **PostgreSQL** (default):
702
+ - Robust, production-ready database server
703
+ - Recommended for all deployments
704
+ - Better concurrency and performance
705
+ - Data stored in `./data/postgres/`
706
+
707
+ - **SQLite**:
708
+ - Lightweight, embedded database
709
+ - Good for development and testing
710
+ - Set `SOUSCHEF_DB_BACKEND=sqlite` in .env
711
+ - Data stored in `./data/souschef/`
712
+
713
+ **Example with SQLite:**
714
+ ```bash
715
+ # In .env, set:
716
+ SOUSCHEF_DB_BACKEND=sqlite
717
+ # Then start normally:
718
+ docker compose up
719
+ ```
720
+
721
+ **Example with PostgreSQL (default):**
558
722
  ```yaml
559
723
  version: '3.8'
560
724
  services:
@@ -569,6 +733,12 @@ services:
569
733
  - STREAMLIT_SERVER_ADDRESS=0.0.0.0
570
734
  - STREAMLIT_SERVER_PORT=9999
571
735
  - STREAMLIT_SERVER_HEADLESS=true
736
+ - SOUSCHEF_DB_BACKEND=postgres
737
+ - SOUSCHEF_DB_HOST=postgres
738
+ - SOUSCHEF_DB_PORT=5432
739
+ - SOUSCHEF_DB_NAME=souschef
740
+ - SOUSCHEF_DB_USER=souschef
741
+ - SOUSCHEF_DB_PASSWORD=souschef
572
742
  restart: unless-stopped
573
743
  ```
574
744
 
@@ -1272,3 +1442,4 @@ Questions? Check [ARCHITECTURE.md](docs/ARCHITECTURE.md) for module responsibili
1272
1442
  This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
1273
1443
 
1274
1444
  ---
1445
+
@@ -1,45 +1,3 @@
1
- Metadata-Version: 2.4
2
- Name: mcp-souschef
3
- Version: 3.5.2
4
- Summary: AI-powered MCP server for Chef to Ansible conversion
5
- License: MIT
6
- License-File: LICENSE
7
- Keywords: chef,ansible,migration,infrastructure,automation,mcp,ai,conversion
8
- Author: SousChef Contributors
9
- Requires-Python: >=3.10,<4.0
10
- Classifier: Development Status :: 4 - Beta
11
- Classifier: Intended Audience :: Developers
12
- Classifier: Intended Audience :: System Administrators
13
- Classifier: License :: OSI Approved :: MIT License
14
- Classifier: Operating System :: OS Independent
15
- Classifier: Programming Language :: Python :: 3
16
- Classifier: Programming Language :: Python :: 3.10
17
- Classifier: Programming Language :: Python :: 3.11
18
- Classifier: Programming Language :: Python :: 3.12
19
- Classifier: Programming Language :: Python :: 3.13
20
- Classifier: Programming Language :: Python :: 3.14
21
- Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
- Classifier: Topic :: System :: Systems Administration
23
- Classifier: Topic :: Utilities
24
- Provides-Extra: ai
25
- Provides-Extra: all
26
- Provides-Extra: ui
27
- Requires-Dist: anthropic (>=0.75.0) ; extra == "ai" or extra == "all"
28
- Requires-Dist: click (>=8.1.0)
29
- Requires-Dist: mcp (>=1.25.0)
30
- Requires-Dist: openai (>=1.0.0) ; extra == "ai" or extra == "all"
31
- Requires-Dist: pandas (>=2.0.0) ; extra == "ui" or extra == "all"
32
- Requires-Dist: plotly (>=5.17.0,<7.0) ; extra == "ui" or extra == "all"
33
- Requires-Dist: pydantic (>=2.0.0)
34
- Requires-Dist: python-dotenv (>=1.2.1)
35
- Requires-Dist: pyyaml (>=6.0.0)
36
- Requires-Dist: requests (>=2.31.0)
37
- Requires-Dist: streamlit (>=1.28.0) ; extra == "ui" or extra == "all"
38
- Project-URL: Documentation, https://kpeacocke.github.io/souschef/
39
- Project-URL: Homepage, https://github.com/kpeacocke/souschef
40
- Project-URL: Repository, https://github.com/kpeacocke/souschef
41
- Description-Content-Type: text/markdown
42
-
43
1
  # Chef to Ansible migration - SousChef MCP
44
2
 
45
3
  An AI-powered MCP (Model Context Protocol) server that provides comprehensive Chef-to-Ansible migration capabilities for enterprise infrastructure transformation.
@@ -56,17 +14,17 @@ An AI-powered MCP (Model Context Protocol) server that provides comprehensive Ch
56
14
 
57
15
  ## Overview - Chef to Ansible features
58
16
 
59
- SousChef is a complete enterprise-grade migration platform with **35 primary MCP tools** organised across **11 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, and CI/CD pipeline generation, SousChef provides everything needed for a successful infrastructure automation migration.
17
+ SousChef is a complete enterprise-grade migration platform with **40 primary MCP tools** organised across **12 major capability areas** to facilitate Chef-to-Ansible AWX/AAP migrations. From cookbook analysis to deployment pattern conversion, including Chef Habitat to containerised deployments, Chef Server integration, CI/CD pipeline generation, and GitHub Copilot agent control, SousChef provides everything needed for a successful infrastructure automation migration.
60
18
 
61
19
  ### About Tool Counts
62
20
 
63
- **Why 35 tools in the documentation but more in the server?**
21
+ **Why 40 tools in the documentation but more in the server?**
64
22
 
65
- The MCP server provides **38 total tools**. This documentation focuses on the **35 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations used internally by the main tools.
23
+ The MCP server provides **43 total tools**. This documentation focuses on the **40 primary user-facing tools** that cover the main migration capabilities. The remaining 3 tools are low-level filesystem operations used internally by the main tools.
66
24
 
67
25
  As a user, you'll primarily interact with the documented tools. Your AI assistant may use the additional tools automatically when needed, but you don't need to know about them for successful migrations.
68
26
 
69
- > **For developers:** See `souschef/server.py` for the complete list of all 38 registered tools.
27
+ > **For developers:** See `souschef/server.py` for the complete list of all 43 registered tools.
70
28
 
71
29
  ## Model Agnostic - Works with Any AI Model
72
30
 
@@ -87,6 +45,7 @@ As a user, you'll primarily interact with the documented tools. Your AI assistan
87
45
 
88
46
  - **[Terraform Provider](terraform-provider/README.md)** - Manage migrations with infrastructure-as-code
89
47
  - **[User Guide](docs/user-guide/)** - Complete documentation
48
+ - **[Data Persistence Guide](docs/user-guide/data-persistence.md)** - History, caching, and storage backends
90
49
  - **[API Reference](docs/api-reference/)** - Detailed tool documentation
91
50
  - **[Migration Guide](docs/migration-guide/)** - Step-by-step migration process
92
51
 
@@ -226,7 +185,27 @@ Automatically detects and converts:
226
185
  - **Cookstyle/Foodcritic** → Lint stages
227
186
  - Multiple test suites → Parallel execution strategies
228
187
 
229
- #### Example Usage
188
+ ### 11. GitHub Copilot Agent Control
189
+
190
+ Manage GitHub Copilot agents working on repository issues with full pause/stop/resume capabilities:
191
+
192
+ - **assign_github_copilot_to_issue** - Assign Copilot agent to implement an issue
193
+ - **pause_github_copilot_agent** - Pause a running agent (can be resumed)
194
+ - **stop_github_copilot_agent** - Stop and cancel an agent assignment
195
+ - **resume_github_copilot_agent** - Resume a paused agent with optional new instructions
196
+ - **check_github_copilot_agent_status** - Check current agent state and activity
197
+
198
+ **Agent lifecycle management:**
199
+
200
+ 1. **Assign** - Start Copilot working on an issue
201
+ 2. **Monitor** - Check status and review progress
202
+ 3. **Pause** - Temporarily pause for review or changes
203
+ 4. **Resume** - Continue with optional new guidance
204
+ 5. **Stop** - Cancel if requirements change
205
+
206
+ State is tracked via issue labels and comments, providing full visibility and control.
207
+
208
+ #### Example Usage - CI/CD Pipelines
230
209
 
231
210
  ```bash
232
211
  # Generate Jenkins Declarative pipeline
@@ -241,12 +220,58 @@ souschef generate-gitlab-ci ./mycookbook
241
220
  # Generate GitHub Actions workflow
242
221
  souschef generate-github-workflow ./mycookbook
243
222
 
244
- # Customize with options
223
+ # Customise with options
245
224
  souschef generate-gitlab-ci ./mycookbook --no-cache --no-artifacts
246
225
  souschef generate-github-workflow ./mycookbook --workflow-name "My CI" --no-cache
247
226
  ```
248
227
 
249
- #### Command Line Usage
228
+ #### Example Usage - GitHub Agent Control
229
+
230
+ ```python
231
+ # From an AI assistant with SousChef MCP
232
+
233
+ # Assign Copilot to work on an issue
234
+ assign_github_copilot_to_issue(
235
+ owner="myorg",
236
+ repo="my-ansible-repo",
237
+ issue_number=42,
238
+ base_ref="main",
239
+ custom_instructions="Focus on idempotency and error handling"
240
+ )
241
+
242
+ # Check agent status
243
+ check_github_copilot_agent_status(
244
+ owner="myorg",
245
+ repo="my-ansible-repo",
246
+ issue_number=42
247
+ )
248
+
249
+ # Pause for review
250
+ pause_github_copilot_agent(
251
+ owner="myorg",
252
+ repo="my-ansible-repo",
253
+ issue_number=42,
254
+ reason="Need to review approach before continuing"
255
+ )
256
+
257
+ # Resume with new guidance
258
+ resume_github_copilot_agent(
259
+ owner="myorg",
260
+ repo="my-ansible-repo",
261
+ issue_number=42,
262
+ additional_instructions="Also add role dependencies"
263
+ )
264
+
265
+ # Stop if no longer needed
266
+ stop_github_copilot_agent(
267
+ owner="myorg",
268
+ repo="my-ansible-repo",
269
+ issue_number=42,
270
+ reason="Requirements changed - manual implementation needed"
271
+ )
272
+ ```
273
+
274
+ #### Command Line Usage - CI/CD Pipelines
250
275
 
251
276
  **MCP Tool Usage:**
252
277
 
@@ -475,6 +500,7 @@ Interactive web-based interface for Chef-to-Ansible migration planning and visua
475
500
  - **Dependency Mapping**: Visual dependency graphs showing cookbook relationships and migration ordering
476
501
  - **Validation Reports**: Conversion validation results with syntax checking and best practice compliance
477
502
  - **Progress Tracking**: Real-time migration progress with completion metrics and bottleneck identification
503
+ - **History and Persistence**: Stored analysis history, cached results, and downloadable artefacts (SQLite or PostgreSQL, plus S3-compatible storage)
478
504
 
479
505
  **Launch the UI:**
480
506
 
@@ -595,8 +621,59 @@ STREAMLIT_SERVER_HEADLESS=true
595
621
  - `SOUSCHEF_AI_MAX_TOKENS` - Maximum tokens to generate (optional, default: 4000)
596
622
  - `SOUSCHEF_ALLOWED_HOSTNAMES` - Comma-separated list of allowed hostnames for outbound API requests (optional)
597
623
 
624
+ **Persistent Storage Configuration (Docker Compose):**
625
+
626
+ All persistent storage paths are configurable via environment variables. Add these to your `.env` file to customise where data is stored:
627
+
628
+ ```dotenv
629
+ # Docker Compose Volume Configuration (optional)
630
+ SOUSCHEF_DATA_DIR=./data/souschef # SQLite database and analysis history
631
+ SOUSCHEF_STORAGE_DIR=./data/storage # Generated artefacts and conversions
632
+ POSTGRES_DATA_DIR=./data/postgres # PostgreSQL database files
633
+ MINIO_DATA_DIR=./data/minio # MinIO object storage data
634
+ ```
635
+
636
+ The storage paths default to `./data/` subdirectories (relative to docker-compose.yml) but can be set to any absolute or relative path. This allows you to:
637
+ - Store data on different volumes or network storage
638
+ - Easily backup and restore data by copying directories
639
+ - Share data between development and production environments
640
+
641
+ See [Docker Deployment Guide](docs/docker-deployment.md#persistent-storage-configuration) for detailed configuration options.
642
+
598
643
  **Docker Compose (recommended for development):**
599
644
 
645
+ ```bash
646
+ # Using PostgreSQL (default, production-ready)
647
+ docker compose up
648
+
649
+ # Or if you prefer SQLite (lightweight, local storage only):
650
+ # 1. Set in .env: SOUSCHEF_DB_BACKEND=sqlite
651
+ # 2. Run normally: docker compose up
652
+ ```
653
+
654
+ **Database Options:**
655
+
656
+ - **PostgreSQL** (default):
657
+ - Robust, production-ready database server
658
+ - Recommended for all deployments
659
+ - Better concurrency and performance
660
+ - Data stored in `./data/postgres/`
661
+
662
+ - **SQLite**:
663
+ - Lightweight, embedded database
664
+ - Good for development and testing
665
+ - Set `SOUSCHEF_DB_BACKEND=sqlite` in .env
666
+ - Data stored in `./data/souschef/`
667
+
668
+ **Example with SQLite:**
669
+ ```bash
670
+ # In .env, set:
671
+ SOUSCHEF_DB_BACKEND=sqlite
672
+ # Then start normally:
673
+ docker compose up
674
+ ```
675
+
676
+ **Example with PostgreSQL (default):**
600
677
  ```yaml
601
678
  version: '3.8'
602
679
  services:
@@ -611,6 +688,12 @@ services:
611
688
  - STREAMLIT_SERVER_ADDRESS=0.0.0.0
612
689
  - STREAMLIT_SERVER_PORT=9999
613
690
  - STREAMLIT_SERVER_HEADLESS=true
691
+ - SOUSCHEF_DB_BACKEND=postgres
692
+ - SOUSCHEF_DB_HOST=postgres
693
+ - SOUSCHEF_DB_PORT=5432
694
+ - SOUSCHEF_DB_NAME=souschef
695
+ - SOUSCHEF_DB_USER=souschef
696
+ - SOUSCHEF_DB_PASSWORD=souschef
614
697
  restart: unless-stopped
615
698
  ```
616
699
 
@@ -1314,4 +1397,3 @@ Questions? Check [ARCHITECTURE.md](docs/ARCHITECTURE.md) for module responsibili
1314
1397
  This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
1315
1398
 
1316
1399
  ---
1317
-
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "mcp-souschef"
3
- version = "3.5.2"
3
+ version = "4.0.0"
4
4
  description = "AI-powered MCP server for Chef to Ansible conversion"
5
5
  readme = "README.md"
6
6
  homepage = "https://github.com/kpeacocke/souschef"
@@ -28,11 +28,14 @@ openai = {version = ">=1.0.0", optional = true}
28
28
  pandas = {version = ">=2.0.0", optional = true}
29
29
  streamlit = {version = ">=1.28.0", optional = true}
30
30
  plotly = {version = ">=5.17.0,<7.0", optional = true}
31
+ boto3 = {version = ">=1.26.0", optional = true}
32
+ psycopg = {version = ">=3.1.19", extras = ["binary"], optional = true}
31
33
 
32
34
  [tool.poetry.extras]
33
35
  ai = ["anthropic", "openai"]
34
36
  ui = ["pandas", "streamlit", "plotly"]
35
- all = ["anthropic", "openai", "pandas", "streamlit", "plotly"]
37
+ storage = ["boto3", "psycopg"]
38
+ all = ["anthropic", "openai", "pandas", "streamlit", "plotly", "boto3", "psycopg"]
36
39
  [tool.poetry.group.dev.dependencies]
37
40
  pytest = ">=9.0.2"
38
41
  pytest-cov = ">=7.0.0"
@@ -57,6 +60,7 @@ matplotlib = "^3.8.0"
57
60
  types-networkx = "^3.6.1.20251220"
58
61
  types-requests = "^2.32.4.20260107"
59
62
  types-urllib3 = "^1.26.25.14"
63
+ pandas-stubs = "^2.0.0"
60
64
 
61
65
  [tool.poetry.scripts]
62
66
  souschef = "souschef.cli:main"
@@ -90,6 +94,9 @@ ignore = ["D100", "D104", "D105", "D107", "D203", "D212"]
90
94
  [tool.pytest.ini_options]
91
95
  minversion = "6.0"
92
96
  addopts = "-ra -q --cov=souschef --cov-report=term-missing"
97
+ filterwarnings = [
98
+ "ignore::ResourceWarning",
99
+ ]
93
100
  testpaths = [
94
101
  "tests/unit",
95
102
  "tests/integration",
@@ -30,7 +30,12 @@ class AnsibleTask(BaseModel):
30
30
  None, description="List of tags for task categorization"
31
31
  )
32
32
  become: bool | None = Field(None, description="Whether to use privilege escalation")
33
- register: str | None = Field(None, description="Variable name to store task result")
33
+ register_var: str | None = Field(
34
+ None,
35
+ validation_alias="register",
36
+ serialization_alias="register",
37
+ description="Variable name to store task result",
38
+ )
34
39
 
35
40
 
36
41
  class AnsibleHandler(BaseModel):
@@ -0,0 +1,17 @@
1
+ """GitHub integration utilities."""
2
+
3
+ from souschef.github.agent_control import (
4
+ assign_copilot_agent_to_issue,
5
+ check_copilot_agent_status,
6
+ pause_copilot_agent,
7
+ resume_copilot_agent,
8
+ stop_copilot_agent,
9
+ )
10
+
11
+ __all__ = [
12
+ "assign_copilot_agent_to_issue",
13
+ "pause_copilot_agent",
14
+ "stop_copilot_agent",
15
+ "resume_copilot_agent",
16
+ "check_copilot_agent_status",
17
+ ]