Bridge

mcp
Guvenlik Denetimi
Basarisiz
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Basarisiz
  • os.homedir — User home directory access in credential-resolver/src/resolver.ts
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

MCP server that gates mainframe z/OS changes behind spec and plan approval

README.md

Zcrafter Bridge

Give AI Agents real access to your mainframe and keep it from changing anything you haven't approved.

Screenshot 2026-09-24 at 11 58 01 PM

What's an MCP server?

MCP is how AI Agents talks to outside systems. An MCP server hands AI a set of tools it can call. Bridge is an MCP server whose tools are your mainframe - datasets, members, z/OS UNIX files, jobs, spool, TSO and the operator console, with an approval gate in front of anything that changes the system.

Install it once, point Claude Code/Codex at it, then just talk to Claude.


Setup

Before you start

  • Python 3.11+ and Node.js 20+
  • Claude Code — install guide
  • A working Zowe CLI profile. Test it: zowe zosmf check status. If that fails, fix Zowe first — Bridge reads the same profile.

1. Get the code

git clone https://github.com/ZcrafterAI/Bridge.git
cd Bridge

2. Install

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cd credential-resolver && npm install && npm run build && cd ..

The credential resolver reads your mainframe password from your OS keychain at run time. No password is stored in this repo.

3. Check it starts

python -m mainframe_workflow_mcp.server

It should start and wait silently. Press Ctrl+C. Errors? See Troubleshooting.

4. Connect Claude Code

From inside the Bridge folder:

claude mcp add mainframe-workflow -- "$(pwd)/.venv/bin/python" -m mainframe_workflow_mcp.server

Windows: use .venv\Scripts\python.exe.

Verify with claude mcp list — you want mainframe-workflow: ✔ Connected.

5. Install the skill

mkdir -p ~/.claude/skills
cp -r .claude/skills/mainframe-workflow ~/.claude/skills/

How the gate works

Reading is free. Listing datasets, reading members, checking jobs, searching spool — no approval needed.

Changing anything is gated. Before an agent can write a member, submit a job, run a command or delete a dataset, it must:

  1. Open a request
  2. Write a spec (what changes and why) and get your yes
  3. Write a plan that lists every change as a step, and get your yes

Only you can say yes. The agent can ask for an approval. It cannot give one. Bridge asks you directly, outside the agent's reach:

  • in your AI client's own prompt, when the client has one, or
  • on a page Bridge opens in your browser, on your machine only, or
  • in a terminal, with python -m mainframe_workflow_mcp.approve, on a machine with no browser.

The page's address carries a one-time token the agent never sees, so an agent that can browse still cannot press Approve.

The approval page: what was asked, the plan, and each change it allows

Your yes covers the listed steps and nothing else. Each step names one tool and its target, for example member.write on PAY.TEST.COBOL(PAYCALC). After approval a change runs only if it matches a step, and each step runs once unless the plan says more. A command step fixes the exact command. A step can also fix the exact content, diff or JCL, and then that is what must be sent.

The agent tries It gets
A change before you approved PLAN_NOT_APPROVED
To approve its own plan WAITING_FOR_PERSON, and you get asked
A change the plan did not list STEP_NOT_IN_PLAN
A change to a protected dataset PROTECTED_DATASET

Editing the spec after approval un-approves the plan too. Every change is logged with its inputs; passwords are redacted, diffs are hashed.


Tools

48 tools. The ones in italics change the system, so they need an approved plan step.

Datasets list, info, read, write, create, create like, delete, rename, copy, recall, migrate
Members list, read, search, write, patch, delete, rename
z/OS UNIX files list, read, write, create, delete, rename, chmod
Jobs list, status, steps, failed jobs, wait, JCL, spool, output, submit, cancel, purge, hold, release, change class
TSO tso.query for read-only commands (LISTCAT, LISTDS, LISTUSER...), tso.command for anything else
Operator console console.command
System list systems, verify connection, list profiles, search the tool catalog

job.steps shows which step of a job failed, and job.failed lists the jobs that ended badly, so an agent can start from the failure instead of reading every log.

Large reads (member.read, dataset.read, job.output, job.spool.read) accept searchText, maxLines and regex — so Claude finds one line in a 40,000-line job log instead of pulling the whole thing into context.


Configuration

Copy .env.example to .env to change defaults.

Variable Default
MAINFRAME_WORKFLOW_ZOWE_PROFILE default Which Zowe profile to use
MAINFRAME_WORKFLOW_DB_PATH ./mainframe_workflow_mcp/state.db Where requests are stored
MAINFRAME_WORKFLOW_IDLE_DAYS 14 Abandon untouched requests after
MAINFRAME_WORKFLOW_RETENTION_DAYS 90 Archive finished requests after
MAINFRAME_WORKFLOW_APIML_BASE_PATH — Set if z/OSMF is behind API ML
MAINFRAME_WORKFLOW_APPROVAL auto How you approve: auto (your AI client's prompt, else a browser page), prompt, browser, terminal
MAINFRAME_WORKFLOW_APPROVAL_WAIT_SECONDS 60 How long one approval call waits for you before telling the agent to ask again
MAINFRAME_WORKFLOW_READ_ONLY false true offers no tool that changes anything
MAINFRAME_WORKFLOW_PROTECTED_DATASETS — Patterns the dataset and member tools may never write to, e.g. SYS1.**,*.PROD.**
MAINFRAME_WORKFLOW_TSO_ACCOUNT ACCT TSO account number, used on z/OSMF without the one-request TSO interface

MAINFRAME_WORKFLOW_APPROVAL=unsafe-agent turns the person off: the agent's own call counts as approval. It exists for automated runs against throwaway systems. Do not use it on a mainframe you care about.


Troubleshooting

Zowe config not found — Bridge reads ~/.zowe/zowe.config.json. Run zowe config list to confirm you have one.

z/OSMF profile "default" not found — your profile has another name. Run zowe config list profiles, then set MAINFRAME_WORKFLOW_ZOWE_PROFILE in .env.

Resolved profile is missing host/user/password — credentials aren't in your OS vault. Re-run zowe config secure.

Claude says a tool isn't allowed — approve it when prompted, or check claude mcp list.

The agent says an approval is waiting but nothing opened — the address is printed in the server's log (stderr), or run python -m mainframe_workflow_mcp.approve in a terminal.

STEP_NOT_IN_PLAN — the agent tried a change you did not approve. It has to write a new plan revision that lists it and ask you again.

tso.command or console.command answers 401 or 403 — your user ID needs TSO or EMCS console authority on the mainframe. Bridge cannot grant it.


Development

pip install -r requirements-dev.txt
pytest                                    # 167 tests
cd credential-resolver && npm test        # 8 tests

Architecture notes: docs/architecture.md. The tool catalog lives in mainframe_workflow_mcp/toolbox/ and the z/OSMF calls in mainframe_workflow_mcp/clients/.


MIT licensed. Contributions welcome — see CONTRIBUTING.md.

Yorumlar (0)

Sonuc bulunamadi