{"id":47806107,"url":"https://github.com/zowe/zowe-mcp","last_synced_at":"2026-04-03T17:38:41.554Z","repository":{"id":343101595,"uuid":"1166717866","full_name":"zowe/zowe-mcp","owner":"zowe","description":"Zowe MCP Server","archived":false,"fork":false,"pushed_at":"2026-03-30T21:56:08.000Z","size":29608,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-30T22:09:25.544Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zowe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-25T14:29:34.000Z","updated_at":"2026-03-26T17:07:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zowe/zowe-mcp","commit_stats":null,"previous_names":["zowe/zowe-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zowe/zowe-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fzowe-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fzowe-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fzowe-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fzowe-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zowe","download_url":"https://codeload.github.com/zowe/zowe-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zowe%2Fzowe-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31366371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:13:05.644Z","status":"ssl_error","status_checked_at":"2026-04-03T17:13:04.413Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-03T17:38:39.838Z","updated_at":"2026-04-03T17:38:41.052Z","avatar_url":"https://github.com/zowe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"packages/zowe-mcp-vscode/resources/icon.svg\" alt=\"Zowe MCP\" style=\"height:1.2em; vertical-align: text-top;\" /\u003e Zowe MCP\n\nModel Context Protocol (MCP) server and VS Code extension that gives AI\nassistants tools for working with z/OS systems -- data sets, jobs, and UNIX\nSystem Services.\n\n## Use case examples\n\nThe AI can combine multiple tools and reason over results to:\n\n- **AI-assisted development** — Browse, search, read, and open data sets and USS in natural language; get explanations and open in editor.\n- **Job failure diagnostics** — \"Why did this job fail?\" The assistant fetches status and spool, finds errors/ABENDs, and explains cause and next steps.\n- **Search and trace** — Find where a program, copybook, or string is used or defined across libraries; get a short report and suggested next reads.\n\nSee [Use cases](docs/use-cases.md) for the full list and more detail.\n\n## Repository layout\n\n```text\nzowe-mcp/                       # npm workspaces monorepo\n  packages/\n    zowe-mcp-server/            # Standalone MCP server (ESM)\n    zowe-mcp-vscode/            # VS Code extension (CommonJS)\n    zowe-mcp-evals/             # AI evaluations (LLM agent + MCP tools)\n```\n\n## Prerequisites\n\n- **Node.js** \u003e= 22 (LTS recommended)\n- **npm** \u003e= 10 (ships with Node 22+)\n- **VS Code** \u003e= 1.101 (for the extension)\n- **GitHub Copilot Chat** extension installed in VS Code\n\n## Quick start\n\n```bash\n# 1. Install dependencies (both packages are linked automatically)\nnpm install\n\n# 2. Build everything\nnpm run build\n\n# 3. Generate mock z/OS data\nnpx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data\n\n# 4. Build and install the VS Code extension\nnpm run build-and-install\n```\n\nAfter step 4, reload VS Code and the Zowe MCP tools will be available in\nGitHub Copilot Chat.\n\n## Building\n\n### Full build (all packages)\n\n```bash\nnpm run build\n```\n\nThis compiles both `zowe-mcp-server` and `zowe-mcp-vscode`. The server must\nbe built first because the extension imports types from it.\n\n### Server only\n\n```bash\nnpm run build -w packages/zowe-mcp-server\n```\n\n### Extension only\n\nThe extension build has two stages: it bundles the server dist into a\n`server/` directory, then compiles the extension TypeScript.\n\n```bash\n# Build server + bundle + compile extension\nnpm run build:all -w packages/zowe-mcp-vscode\n```\n\n### Watch mode (development)\n\n```bash\n# Server — recompiles on file changes\nnpm run dev -w packages/zowe-mcp-server\n\n# Extension — recompiles on file changes (in a second terminal)\nnpm run dev -w packages/zowe-mcp-vscode\n```\n\n## Mock mode\n\nThe server includes a filesystem-backed mock z/OS backend so you can develop\nand test without a real mainframe.\n\n### Generating mock data\n\n```bash\n# Default preset (2 systems, 2 users each, ~8 datasets per user)\nnpx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data\n\n# Minimal (1 system, 1 user, 5 datasets)\nnpx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data --preset minimal\n\n# Large (5 systems, 3 users each, 20 datasets per user)\nnpx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data --preset large\n\n# Custom scale\nnpx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data \\\n  --systems 3 --users-per-system 2 --datasets-per-user 10 --members-per-pds 8\n```\n\nThe generated directory looks like:\n\n```text\nzowe-mcp-mock-data/\n  systems.json                          # System definitions + credentials\n  mainframe-dev.example.com/            # One directory per system\n    USER/                            # HLQ directory\n      SRC.COBOL/                        # PDS — directory with members\n        HELLO.cbl                       # Member file\n        _meta.json                      # Dataset attributes\n      LOAD.JCL                          # Sequential dataset — plain file\n```\n\n### Running the server standalone with mock data\n\n```bash\n# Via CLI flag\nnpx zowe-mcp-server --stdio --mock ./zowe-mcp-mock-data\n\n# Via environment variable\nZOWE_MCP_MOCK_DIR=./zowe-mcp-mock-data npx zowe-mcp-server --stdio\n```\n\n## Native (SSH) backend\n\nThe server can connect to real z/OS systems over SSH using the Zowe Native Proto\nSDK. The native backend implements the full set of z/OS operations: data set\nCRUD (list, read, write, create, delete, copy, rename, restore, search,\nattributes), USS file operations (list, read, write, create, delete, chmod,\nchown, chtag, copy), TSO and console commands, and job management (submit,\nstatus, list, output, cancel, hold, release, delete).\n\nConnection format is `user@hostname` or `user@hostname:port` (default port 22),\nsame as SSH.\n\n### Standalone mode\n\nSystems come from a config file or CLI:\n\n```bash\n# Config file (JSON with \"systems\" array)\nnpx zowe-mcp-server --stdio --native --config ./native-config.json\n\n# CLI (repeatable)\nnpx zowe-mcp-server --stdio --native --system USERID@sys1.example.com\n```\n\nConfig file format:\n\n```json\n{\n  \"systems\": [\n    \"user1@host1.example.com\",\n    \"user2@host2.example.com:22\"\n  ]\n}\n```\n\nPasswords are read from environment variables:\n`ZOWE_MCP_PASSWORD_\u003cUSER\u003e_\u003cHOST\u003e` (user and host uppercase, dots in host\nreplaced by `_`). Example for `USERID@sys1.example.com`:\n\n```bash\nexport ZOWE_MCP_PASSWORD_USERID_SYS1_EXAMPLE_COM=password\nnpx zowe-mcp-server --stdio --native --system USERID@sys1.example.com\n```\n\nIf a password is invalid, the server will not retry it for the rest of the\nprocess.\n\n### VS Code extension\n\n1. Open Settings and search for **Zowe MCP**\n2. Set **Native connections** to an array of SSH connection specs, e.g.\n   `[\"USERID@sys1.example.com\"]`. Each entry is one connection (user@host or user@host:port); you can have multiple connections to the same z/OS system (e.g. different user IDs).\n3. Reload the window so the MCP server restarts with `--native`\n\nWhen the server needs a password it sends a request to the extension; the\nextension prompts (or reads from VS Code Secret Storage) and sends the password\nback. Passwords are stored under the shared Zowe OSS key\n`zowe.ssh.password.\u003cuser\u003e.\u003chostNormalized\u003e` so other Zowe extensions can reuse\nthem. If a password is invalid the extension deletes it from storage.\n\nServer and extension logs include a **passwordHash** (first 16 hex characters of\nSHA-256 of the password in UTF-8) so you can correlate log lines without\nexposing the password. To verify or reproduce the hash from the command line\n(use `-n` so no newline is included):\n\n```bash\necho -n 'YOUR_EXACT_PASSWORD' | sha256sum\n```\n\nTake the first 16 characters of the output; they should match the `passwordHash`\nin the logs when the same password is used.\n\nYou cannot use both mock mode and native mode; if both are configured, native\nwins.\n\n## Configuring VS Code Copilot\n\n**New to Zowe MCP?** See **[Copilot setup guide](docs/COPILOT-SETUP.md)** for installing the extension from a VSIX, configuring Gemini (e.g. for Broadcom), defining `user@host`, and Copilot/MCP tips (list servers, restart, view output).\n\nThere are two ways to use Zowe MCP with GitHub Copilot in VS Code:\n\n### Option A: Install the VS Code extension (recommended)\n\nThe extension automatically registers the MCP server with Copilot. It also\nprovides a bidirectional communication channel for log forwarding and dynamic\nconfiguration.\n\n```bash\n# Build and install in one step\nnpm run build-and-install\n\n# Or, to install into Cursor / VS Code Insiders / Codium:\nVSCODE_CLONE=cursor npm run build-and-install\n```\n\nAfter installation, reload VS Code. The extension activates on startup and\nregisters a \"Zowe\" MCP server provider.\n\n#### Enabling mock mode in the extension\n\nBy default the extension starts the server without a z/OS backend, so only\nthe `info` tool is available. A warning notification will appear with buttons\nto help you configure mock data.\n\nUse the built-in command (easiest):\n\n1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)\n2. Run **Zowe MCP: Generate Mock Data**\n3. Select a folder where mock data should be created\n4. The command generates the data, configures the setting, and offers to\n   reload the window\n\nOr point at an existing mock data directory:\n\n1. Open VS Code Settings (Ctrl+, / Cmd+,)\n2. Search for **Zowe MCP**\n3. Set **Mock Data Dir** to the absolute path of your mock data directory\n4. Restart the MCP server (reload VS Code or run the\n   \"MCP: List Servers\" command and restart \"Zowe\")\n\nOr add this to your `settings.json`:\n\n```jsonc\n{\n  \"zoweMCP.mockDataDirectory\": \"/absolute/path/to/zowe-mcp-mock-data\"\n}\n```\n\nOnce configured, the server starts with the full set of tools (dataset\nlisting, reading, writing, context management, etc.).\n\n### Option B: Configure as a standalone MCP server in VS Code\n\nThis approach lets you pass the `--mock` flag directly. Create or edit\n`.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"zowe\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/zowe-mcp/packages/zowe-mcp-server/dist/index.js\",\n        \"--stdio\",\n        \"--mock\",\n        \"/absolute/path/to/zowe-mcp/zowe-mcp-mock-data\"\n      ]\n    }\n  }\n}\n```\n\nReplace the paths with the actual absolute paths on your machine. For\nexample, if you cloned the repo to `~/workspace/zowe-mcp` and generated mock\ndata in `~/workspace/zowe-mcp/zowe-mcp-mock-data`:\n\n```jsonc\n{\n  \"github.copilot.chat.mcp.servers\": {\n    \"zowe\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/Users/me/workspace/zowe-mcp/packages/zowe-mcp-server/dist/index.js\",\n        \"--stdio\",\n        \"--mock\",\n        \"/Users/me/workspace/zowe-mcp/zowe-mcp-mock-data\"\n      ]\n    }\n  }\n}\n```\n\nYou can also use the environment variable form:\n\n```jsonc\n{\n  \"github.copilot.chat.mcp.servers\": {\n    \"zowe\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/zowe-mcp/packages/zowe-mcp-server/dist/index.js\",\n        \"--stdio\"\n      ],\n      \"env\": {\n        \"ZOWE_MCP_MOCK_DIR\": \"/absolute/path/to/zowe-mcp/zowe-mcp-mock-data\"\n      }\n    }\n  }\n}\n```\n\nAfter saving `settings.json`, reload VS Code. The MCP server will appear in\nCopilot's tool list.\n\n### Verifying the setup\n\nOpen GitHub Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I) and try:\n\n```text\nUse the info tool to show the Zowe MCP server version.\n```\n\nIf mock mode is active, you can also try:\n\n```text\nList the available z/OS systems.\n```\n\n```text\nSet the active system to mainframe-dev.example.com and list datasets matching USER.**\n```\n\nTool names use camelCase; in Copilot they appear prefixed with `mcp_zowe_` (e.g.\n`mcp_zowe_info`, `mcp_zowe_listDatasets`, `mcp_zowe_setSystem`).\n\n## Testing\n\n```bash\n# Server unit tests (Vitest)\nnpm test\n\n# All tests (server + VS Code extension)\nnpm run test:all\n\n# VS Code extension tests only (launches a real VS Code instance)\nnpm run test:vscode\n```\n\n### Quick tool testing from the CLI\n\nBuild the server first (`npm run build`), then use `npx zowe-mcp-server call-tool`. For usage, options, and examples see the script source: [`packages/zowe-mcp-server/src/scripts/call-tool.ts`](packages/zowe-mcp-server/src/scripts/call-tool.ts).\n\n### MCP Inspector\n\nThe [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\nprovides a web UI for interacting with the server (opens at \u003chttp://localhost:6274\u003e).\nUse the script that matches how you want to run the server:\n\n| Script | Backend | Use when |\n| --- | --- | --- |\n| `npm run inspector` | None | Quick check: only core tools (e.g. `info`) are available; no z/OS systems. |\n| `npm run inspector:mock` | Mock (filesystem) | Try dataset tools without a real z/OS: uses `./zowe-mcp-mock-data`. Generate mock data first with `npx zowe-mcp-server init-mock --output ./zowe-mcp-mock-data`. |\n| `npm run inspector:native` | Native (SSH) | Connect to real z/OS via SSH. Needs `native-config.json` (systems) and `.env` (passwords). Copy `native-config.example.json` → `native-config.json` and `.env.example` → `.env`, then set `ZOWE_MCP_PASSWORD_\u003cUSER\u003e_\u003cHOST\u003e` (see [Standalone mode](#standalone-mode)). |\n\n```bash\nnpm run inspector          # no backend\nnpm run inspector:mock     # mock data in ./zowe-mcp-mock-data\nnpm run inspector:native   # SSH via native-config.json + .env\n```\n\n## Evaluations\n\nThe **evals** package runs an LLM agent against the MCP server (mock or native) and checks that tool calls and answers match expectations. Use it to validate that AI assistants use the Zowe MCP tools correctly.\n\n1. **Config** (at repo root): copy `evals.config.example.json` to `evals.config.json` and set your LLM provider (vLLM, Gemini, or LM Studio). See [packages/zowe-mcp-evals/README.md](packages/zowe-mcp-evals/README.md).\n2. **Run** from repo root:\n\n```bash\nnpm run evals                    # all question sets\nnpm run evals -- --set datasets  # one set\nnpm run evals -- --set datasets --number 1   # one question\n```\n\nReports are written to `evals-report/report.md` and `evals-report/failures.md`.\n\n## Linting and formatting\n\n```bash\nnpm run lint          # Check all ESLint rules\nnpm run lint:fix      # Auto-fix ESLint issues\nnpm run format        # Format all TS/JS/JSON files with Prettier\nnpm run check-format  # Check formatting without modifying files\n```\n\n## Scripts reference\n\nTo publish a VSIX to GitHub Releases from your machine (no GitHub Actions): run `npm run release-vsix` (tag defaults to `v` + extension version) or `npm run release-vsix -- v0.1.0`. Or run `./scripts/release-vsix.sh [TAG]` directly. Requires [GitHub CLI](https://cli.github.com/) (`gh`) and `gh auth login`. Builds the extension, creates/updates the release for the tag, and uploads the VSIX.\n\n| Script | Description |\n| --- | --- |\n| `npm run build` | Build all packages |\n| `npm test` | Run server tests (Vitest) |\n| `npm run test:all` | Run all tests (server + VS Code extension) |\n| `npm run test:vscode` | Run VS Code extension tests |\n| `npm run build-and-install` | Package and install the VS Code extension |\n| `npm run inspector` | Launch MCP Inspector (no backend) |\n| `npm run inspector:mock` | Launch MCP Inspector with mock data (`./zowe-mcp-mock-data`) |\n| `npm run inspector:native` | Launch MCP Inspector with native SSH (`native-config.json` + `.env`) |\n| `npm run evals` | Run AI evals (builds server + evals first). Pass options after `--`: `--set`, `--number`, `--id`, `--filter`. Requires `evals.config.json` at root. |\n| `npm run lint` | Run ESLint |\n| `npm run lint:fix` | Auto-fix ESLint issues |\n| `npm run format` | Format all files with Prettier |\n| `npx zowe-mcp-server init-mock --output \u003cdir\u003e` | Generate mock data |\n| `npx zowe-mcp-server call-tool [--mock=\u003cdir\u003e] [\u003ctool-name\u003e [key=value ...]]` | Call a tool from the CLI |\n| `npm run release-vsix [-- TAG]` | Build VSIX and create/update GitHub Release (requires `gh`). Optional tag after `--`, e.g. `v0.1.0`; default from extension version. |\n\n## License\n\n[Eclipse Public License v2.0](https://www.eclipse.org/legal/epl-v20.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzowe%2Fzowe-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzowe%2Fzowe-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzowe%2Fzowe-mcp/lists"}