Mainframe Modernization Toolkit
Deterministic tools and agent instructions for migrating a JCL-bounded COBOL workload to Python or PySpark.
The toolkit discovers source relationships, validates configuration and record layouts, extracts SQL and business rules, generates typed boundaries, compiles validated relational IR to PySpark, and compares final outputs with an authoritative Golden Dataset. It does not invent missing source semantics.
Install
Python 3.10 or newer is required.
python -m pip install mainframe-modernization-toolkit
mainframe-toolkit --version
Optional runtime dependencies:
python -m pip install "mainframe-modernization-toolkit[pyspark]"
python -m pip install "mainframe-modernization-toolkit[aws]"
Initialize A Workspace
mainframe-toolkit workspace init . --target vscode
mainframe-toolkit workspace init . --target claude
mainframe-toolkit workspace init . --target all
The initializer adds mainframe-migration.json, JSON schemas, and the selected agent integration without overwriting existing files. Configure source directories, encoding, extensions, known external dependencies, transport profiles, environment facts, and targetCapabilities in mainframe-migration.json.
For Claude Code, verify the project MCP server with claude mcp list or /mcp.
Migration Workflow
A migration starts from one JCL. A compact campaign inventories the job, then processes one program at a time so large jobs do not produce one huge preflight response.
mainframe-toolkit run migration_campaign -- init . --jcl MYJOB --format json
mainframe-toolkit run migration_campaign -- next . --jcl MYJOB --worker local --format json
For each selected program:
- Resolve dependencies, callers, copybooks, impact, and blockers.
- Generate canonical record contracts and readers.
- Extract SQL and business rules.
- Generate one program capsule containing machine-readable I/O and partial IR.
- Implement cohesive business logic and focused tests.
- Validate relational IR and compile PySpark when appropriate.
- Mark the program complete and claim the next one.
After all programs are implemented, compose the JCL pipeline and compare its final output with an authoritative Golden Dataset.
mainframe-toolkit validate-golden . --manifest validation/job-output.json --format json
Intermediate program outputs do not require Golden files when the migrated job passes DataFrames in process. Validate those boundaries with explicit contracts and focused tests.
Core Commands
| Command | Purpose |
|---|---|
migration_preflight |
Validate sources, references, environment, scope, and target capabilities. |
migration_campaign |
Track compact program-at-a-time progress for one JCL. |
dependency_graph |
Build CALL, COPY, and EXEC relationships. |
impact_analysis |
Calculate transitive impact. |
dead_code_finder |
Find unreferenced migration candidates. |
jcl_flow_extractor |
Extract JCL flow and generate a local runner. |
migration_complexity_report |
Order programs by deterministic risk. |
copybook_to_contract |
Generate canonical record contracts. |
copybook_to_dataclass |
Generate Python boundary models. |
generate_copybook_fixtures |
Generate ingestion-only test records. |
generate_file_readers |
Generate contract-based readers. |
sql_extractor |
Extract SQL and host variables. |
business_rule_extractor |
Extract conditional rules with source locations. |
characterization_test_scaffolder |
Generate a starting characterization test. |
generate_program_capsule |
Generate a program manifest, contracts, and partial IR. |
validate_relational_ir |
Validate typed relational IR. |
ir_to_pyspark |
Compile executable IR to PySpark. |
golden_validate |
Compare authoritative expected and actual CSV files. |
Run any command through the stable entry point:
mainframe-toolkit run <command> -- <arguments>
AWS Glue And Local PySpark
Use the aws-glue-pyspark starter profile when creating a new configuration:
mainframe-toolkit run migration_preflight -- . --write-template --profile aws-glue-pyspark
Keep transformations in transform_frames(). Production wrappers can use Glue Catalog, S3, and Iceberg descriptors; local runners can load semicolon-delimited CSV files with explicit schemas and invoke the same transformations.
The toolkit does not provision AWS resources. IAM, Lake Formation, buckets, Glue jobs, Catalog tables, bookmarks, connectors, and Iceberg configuration belong in deployment infrastructure.
Safety Boundaries
- Missing copybooks, PROCs, conflicting sources, parse failures, and unsafe layouts block the affected migration.
- Unknown external programs remain explicit adapter TODOs.
- Synthetic fixtures validate ingestion, not business equivalence.
- Only mainframe output or a verified equivalent implementation is an authoritative Golden Dataset.
- Generated relational IR with TODOs is non-executable.
See docs/JCL-MIGRATION-GUIDE.md for the concise end-to-end procedure.
Metadata
Release files for mainframe-modernization-toolkit 0.1.19
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mainframe_modernization_toolkit-0.1.19.tar.gz | 5.9 MB | Without provenance | Details for mainframe_modernization_toolkit-0.1.19.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mainframe_modernization_toolkit-0.1.19-py3-none-any.whl | Python 3 | none | any | Details for mainframe_modernization_toolkit-0.1.19-py3-none-any.whl |
Total release size: 11.8 MB
Release files / mainframe_modernization_toolkit-0.1.19.tar.gz
| Download URL | mainframe_modernization_toolkit-0.1.19.tar.gz |
|---|---|
| Size | 5.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8134485bd9b1393ec07a3299f4c9a1700953d2ee67af6e4a4b0ca6afc1f308ed
|
|
BLAKE2b-256 checksum How to use checksums |
b7db763cecf8b2233d184c56f31d04cc6ce3f34e128008f8f3cd8a4c7e9805d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / mainframe_modernization_toolkit-0.1.19-py3-none-any.whl
| Download URL | mainframe_modernization_toolkit-0.1.19-py3-none-any.whl |
|---|---|
| Size | 5.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c04c6d0d955f5155d4080e5202cddcfcf8c9c4b02865b6f78b576e88e3089c6a
|
|
BLAKE2b-256 checksum How to use checksums |
3cd5e59351320353a4741d11ac8f4532fd69a3febc09b3d42ab88c67539c65ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for mainframe-modernization-toolkit 0.1.19
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.