Quickstart

1. Connect

Add https://harwell.metaphi.ai/mcp/ to your MCP client and sign in. See Connect an MCP server. You need harwell:runs:write.

2. Write a unit

A unit is a directory in a mainframe codebase’s own shape, plus a run.json that says what to run.

hello/
  Progs/HELLO.cbl
  Procs/HELLOJOB.jcl
  run.json

Progs/HELLO.cbl:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. HELLO.
       PROCEDURE DIVISION.
           DISPLAY 'HELLO FROM THE SANDBOX'.
           STOP RUN.

Procs/HELLOJOB.jcl:

//HELLOJOB JOB
//STEP01   EXEC PGM=HELLO
//SYSOUT   DD SYSOUT=*

run.json:

{"submit": ["HELLOJOB"]}

submit names the deck by its file stem in Procs/. The deck runs program HELLO, found by its PROGRAM-ID.

3. Run it

Ask your agent: “Run the hello unit with Harwell.” It calls run_unit with the directory:

run_unit {"unit_zip_b64": "<the hello directory, zipped and base64-encoded>"}

unit_zip_b64 is the directory as a base64 zip. Hum packs a directory path for you. In any other client, the agent runs:

cd hello && zip -qr - . | base64

4. Read the result

HELLOJOB ok · STEP01 HELLO rc=0
JOB HELLOJOB  [ok]
  STEP01   HELLO   cobol   ran   RC=0   ran; 0 out DD(s)
--- HELLOJOB STEP01 HELLO · DISPLAY ---
HELLO FROM THE SANDBOX

The first line is the verdict. Then comes the job log, one line per step, and what each step displayed. The result also carries:

structuredContent: the same result as JSON: status, verdict, diagnostics, and every job and step with its return code.
Resource links to report.json, every listing and every spool file. Read one with resources/read when the text is not enough.

A step that ran reads ran or ok. Anything else failed, and the call is a tool error.

5. Break it

Change HELLO.cbl to use a name it never declares:

           DISPLAY WS-GREETING.

Run it again. The result opens with the compiler’s first error, at the line in your tree, and the call is a tool error:

Progs/HELLO.cbl:4: error: 'WS-GREETING' is not defined

Fix the line and run again.

Run a batch job: data sets, SORT, and chains of jobs.
Tools: every tool and its parameters.

Get started

Guides

Concepts

Reference

1. Connect

2. Write a unit

3. Run it

4. Read the result

5. Break it

Next

​1. Connect

​2. Write a unit

​3. Run it

​4. Read the result

​5. Break it

​Next

1. Connect

2. Write a unit

3. Run it

4. Read the result

5. Break it

Next