mcp-for-i 0.1.11 → 0.1.13

package/README.md

@@ -1,159 +1,207 @@
-# MCP-for-i
-
-`mcp-for-i` is a local MCP server + control plane for IBM i workflows. It provides secure connection onboarding, keychain-backed credentials, runtime update controls, and IBM i tools for agent-driven operations.
-
-## Install
-
-Install globally from npm:
-
-```bash
-npm i -g mcp-for-i
-```
-
-Verify commands:
-
-```bash
-mcp-for-i --help
-mcp-for-i-control help
-```
-
-## Quick Start
-
-1. Start the local control plane:
-
-```bash
-mcp-for-i-control serve
-```
-
-2. Open the UI at:
-
-```text
-http://127.0.0.1:3980
-```
-
-3. Add IBM i connection profiles in the UI. Passwords are stored in the OS keychain, not plain config.
-
-## Background Startup (Windows)
-
-Enable startup at login:
-
-```bash
-mcp-for-i-control setup
-```
-
-Check status:
-
-```bash
-mcp-for-i-control status
-```
-
-Disable startup:
-
-```bash
-mcp-for-i-control remove
-```
-
-## Update and Version Management
-
-Update to latest globally:
-
-```bash
-npm i -g mcp-for-i@latest
-```
-
-Install a specific version:
-
-```bash
-npm i -g mcp-for-i@0.1.1
-```
-
-Rollback example:
-
-```bash
-npm i -g mcp-for-i@0.1.0
-```
-
-Check current installed version:
-
-```bash
-mcp-for-i --version
-```
-
-## Control Plane Runtime Actions
-
-In the UI, runtime buttons behave as follows:
-
-- `Install/Repair MCP`
-  - If running from a git checkout: runs local dependency repair/build.
-  - If running as npm-installed package: runs global npm install/repair for latest package.
-- `Update MCP`
-  - If running from a git checkout: pulls latest changes from `origin/<current-branch>`, then installs/builds.
-  - If running as npm-installed package: upgrades global npm package to latest.
-  - On Windows global installs, update runs in a detached updater and briefly restarts control plane to avoid file-lock (`EBUSY`) errors.
-- `Update Skills`
-  - Pulls/clones the configured skills repository and branch into the local `skills` directory.
-
-## Development (Git Checkout)
-
-For contributors working from source:
-
-```bash
-npm install
-npm run build
-npm test
-npm run start:controlplane
-```
-
-## Automated Release (No Manual Version Bump)
-
-Use the release script instead of raw `npm publish`.
-
-Patch release:
-
-```bash
-npm run release:patch
-```
-
-Minor release:
-
-```bash
-npm run release:minor
-```
-
-Major release:
-
-```bash
-npm run release:major
-```
-
-What it does:
-- Verifies git working tree is clean.
-- Runs `npm test` (unless `--skip-tests` is passed).
-- Checks npm published version.
-- Auto-bumps version only when local version is not ahead.
-- Publishes to npm.
-- Pushes commit/tag to GitHub.
-
-Optional flags:
-
-```bash
-npm run release:patch -- --skip-tests
-npm run release:patch -- --otp=123456
-npm run release:patch -- --no-push
-```
-
-## Security Model
-
-- Credential-bearing direct tool arguments are blocked for connection creation/update flows.
-- Passwords are stored in keychain when available.
-- Control plane is local-first (`127.0.0.1` by default).
-- Guarded policy profile is the default for operational safety.
-- Tool schemas are strict (`additionalProperties: false`) with runtime argument validation, including nested connection/action/filter/profile payloads.
-- QSYS object names and source settings are validated before command execution to reduce interpolation and injection risk.
-
-## Links
-
-- Main repo: [ashishthomas2202/mcp-for-i](https://github.com/ashishthomas2202/mcp-for-i)
-- Skills repo: [ashishthomas2202/mcp-for-i-skills](https://github.com/ashishthomas2202/mcp-for-i-skills)
-- Docs: `docs/`
-- Full capability guide: `docs/capabilities.md`
+# MCP-for-i
+
+`mcp-for-i` is a local MCP server + control plane for IBM i workflows. It provides secure connection onboarding, keychain-backed credentials, cross-platform runtime update controls, and IBM i tools for agent-driven operations.
+
+## Install
+
+The npm package name is `mcp-for-i`.
+
+Install globally from npm:
+
+```bash
+npm i -g mcp-for-i
+```
+
+Verify commands:
+
+```bash
+mcp-for-i --help
+mcp-for-i-control help
+```
+
+Supported shells and terminals include PowerShell, `cmd`, Git Bash, Bash, Zsh, and WSL shells, across Windows, macOS, and Linux.
+
+## Quick Start
+
+1. Open the local control plane:
+
+```bash
+mcp-for-i control
+```
+
+`mcp-for-i control` will start the control server in the background if needed, then open the UI. If a browser cannot be opened in the current environment, it prints the local URL instead.
+
+2. The default local UI URL is:
+
+```text
+http://127.0.0.1:3980
+```
+
+3. Add IBM i connection profiles in the UI. Passwords are stored in the OS keychain, not plain config.
+
+WSL note: persistent password storage requires a working Linux Secret Service inside the WSL distro. WSL does not automatically use Windows Credential Manager; when no keychain is available, MCP-for-i keeps passwords only for the current process and the control plane shows a warning.
+
+Credential storage adapts to the Node runtime: Windows Node from PowerShell, `cmd`, or Git Bash uses Windows Credential Manager; macOS uses Keychain; Linux uses Secret Service; WSL uses the WSL distro's Linux Secret Service.
+
+## Control Commands
+
+From an npm install or a git checkout build, these commands are the supported control entrypoints:
+
+```bash
+mcp-for-i control
+mcp-for-i control status
+mcp-for-i control enable
+mcp-for-i control disable
+```
+
+Equivalent direct control-plane binary commands:
+
+```bash
+mcp-for-i-control open
+mcp-for-i-control status
+mcp-for-i-control enable
+mcp-for-i-control disable
+mcp-for-i-control serve
+```
+
+Behavior by environment:
+- Windows: `enable` registers a Startup entry.
+- macOS: `enable` registers a LaunchAgent.
+- Linux: `enable` uses a user `systemd` service when available.
+- WSL: `enable` installs a guarded `.bashrc` hook that starts the control plane on interactive Bash shell launch.
+
+## Add To Coding Clients
+
+The control-plane UI now includes a `Clients` tab with one-click setup for:
+- `Codex Desktop / CLI`
+- `Claude Code` when the `claude` CLI is installed
+- `VS Code / GitHub Copilot` when the `code` CLI is installed
+
+It also includes manual guidance for:
+- `Project Bob`
+- other MCP clients that use generic JSON/TOML stdio server configuration
+
+The UI writes or invokes the local client-specific setup on the same machine where the control plane is running. If a client CLI is not installed, the UI falls back to showing the exact launch command/snippet to use manually.
+
+## Update and Version Management
+
+Update to latest globally:
+
+```bash
+npm i -g mcp-for-i@latest
+```
+
+Install a specific version:
+
+```bash
+npm i -g mcp-for-i@0.1.1
+```
+
+Rollback example:
+
+```bash
+npm i -g mcp-for-i@0.1.0
+```
+
+Check current installed version:
+
+```bash
+mcp-for-i --version
+```
+
+## Control Plane Updates
+
+The control plane intentionally stays narrow:
+
+- `Update MCP`
+  - If running from a git checkout: pulls latest changes from `origin/<current-branch>`, then installs/builds.
+  - If running as an npm-installed package: upgrades the global npm package to latest.
+  - On Windows global installs, update still runs in a detached updater to avoid file-lock (`EBUSY`) errors during self-update.
+- `Update Skills`
+  - Pulls or clones the configured skills repository and branch into the local `skills` directory.
+
+For npm installs and manual upgrades, prefer standard npm commands such as `npm i -g mcp-for-i@latest`.
+
+## Development (Git Checkout)
+
+For contributors working from source:
+
+```bash
+npm install
+npm run build
+npm test
+npm run start:controlplane
+```
+
+You can also use the built artifacts directly after build:
+
+```bash
+node dist/index.js
+node dist/index.js control
+node dist/controlplane/index.js open
+```
+
+## Automated Release (No Manual Version Bump)
+
+Use the release script instead of raw `npm publish`. The script publishes the `mcp-for-i` npm package.
+
+Before releasing, verify npm auth and the currently published version:
+
+```bash
+npm whoami
+npm view mcp-for-i version
+```
+
+If `npm whoami` fails, run `npm login` first.
+
+Patch release:
+
+```bash
+npm run release:patch
+```
+
+Minor release:
+
+```bash
+npm run release:minor
+```
+
+Major release:
+
+```bash
+npm run release:major
+```
+
+What it does:
+- Verifies git working tree is clean.
+- Runs `npm test` (unless `--skip-tests` is passed).
+- Checks npm published version.
+- Auto-bumps version only when local version is not ahead.
+- Publishes to npm.
+- Pushes commit/tag to GitHub.
+
+Optional flags:
+
+```bash
+npm run release:patch -- --skip-tests
+npm run release:patch -- --otp=123456
+npm run release:patch -- --no-push
+```
+
+OTP is only needed when the npm account has two-factor authentication enabled for publishing. If npm asks for a one-time password, use the current code from the authenticator app or recovery method configured on the npm account, then rerun with `--otp=<code>`. If the account does not have publish-time 2FA enabled, no OTP is needed.
+
+## Security Model
+
+- Credential-bearing direct tool arguments are blocked for connection creation/update flows.
+- Passwords are stored in keychain when available; failed or missing keychain access falls back to process-only session storage with a visible control-plane warning.
+- Control plane is local-first (`127.0.0.1` by default).
+- Guarded policy profile is the default for operational safety.
+- Tool schemas are strict (`additionalProperties: false`) with runtime argument validation, including nested connection/action/filter/profile payloads.
+- QSYS object names and source settings are validated before command execution to reduce interpolation and injection risk.
+
+## Links
+
+- Main repo: [ashishthomas2202/mcp-for-i](https://github.com/ashishthomas2202/mcp-for-i)
+- Skills repo: [ashishthomas2202/mcp-for-i-skills](https://github.com/ashishthomas2202/mcp-for-i-skills)
+- Docs: `docs/`
+- Full capability guide: `docs/capabilities.md`

package/dist/controlplane/clientIntegrationService.js

@@ -0,0 +1,292 @@
+import fs from "fs/promises";
+import os from "os";
+import path from "path";
+import { spawn } from "child_process";
+const SERVER_NAME = "mcp-for-i";
+export class ClientIntegrationService {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    async listTargets() {
+        const launchSpec = this.getLaunchSpec();
+        const [hasCodex, hasClaude, hasCode] = await Promise.all([
+            commandExists("codex"),
+            commandExists("claude"),
+            commandExists("code")
+        ]);
+        const [codexConfigured, claudeConfigured, codeConfigured] = await Promise.all([
+            hasCodex ? this.isCodexConfigured() : false,
+            hasClaude ? this.isClaudeConfigured() : false,
+            hasCode ? this.isCodeConfigured() : false
+        ]);
+        return [
+            {
+                id: "codex",
+                label: "Codex Desktop / CLI",
+                description: "Adds mcp-for-i to Codex using the local Codex MCP command.",
+                available: hasCodex,
+                autoInstall: hasCodex,
+                configured: codexConfigured,
+                details: hasCodex ? undefined : "codex command not found on PATH."
+            },
+            {
+                id: "claude-code",
+                label: "Claude Code",
+                description: "Adds mcp-for-i to Claude Code at user scope.",
+                available: hasClaude,
+                autoInstall: hasClaude,
+                configured: claudeConfigured,
+                details: hasClaude ? undefined : "claude command not found on PATH."
+            },
+            {
+                id: "vscode-copilot",
+                label: "VS Code / GitHub Copilot",
+                description: "Adds mcp-for-i to the current VS Code user profile via the code CLI.",
+                available: hasCode,
+                autoInstall: hasCode,
+                configured: codeConfigured,
+                details: hasCode ? undefined : "code command not found on PATH."
+            },
+            {
+                id: "project-bob",
+                label: "Project Bob",
+                description: "Manual instructions only. No stable local Project Bob automation path is configured here.",
+                available: true,
+                autoInstall: false,
+                configured: false,
+                details: "Use manual instructions until a documented local config or CLI flow is available."
+            },
+            {
+                id: "manual",
+                label: "Other MCP Clients",
+                description: "Show ready-to-copy config snippets for clients not listed above.",
+                available: true,
+                autoInstall: false,
+                configured: false,
+                details: `Launch command: ${launchSpec.command} ${launchSpec.args.join(" ")}`
+            }
+        ];
+    }
+    async installTarget(id) {
+        switch (id) {
+            case "codex":
+                return this.installCodex();
+            case "claude-code":
+                return this.installClaudeCode();
+            case "vscode-copilot":
+                return this.installVsCode();
+            case "project-bob":
+                return this.manualOnly("project-bob", "Project Bob");
+            case "manual":
+                return this.manualOnly("manual", "Other MCP Clients");
+            default:
+                throw new Error(`Unknown client target: ${id}`);
+        }
+    }
+    async installCodex() {
+        if (!await commandExists("codex")) {
+            return {
+                ok: false,
+                id: "codex",
+                label: "Codex Desktop / CLI",
+                message: "codex command was not found. Use the manual instructions below."
+            };
+        }
+        if (await this.isCodexConfigured()) {
+            return {
+                ok: true,
+                id: "codex",
+                label: "Codex Desktop / CLI",
+                message: "mcp-for-i is already configured in Codex."
+            };
+        }
+        const spec = this.getLaunchSpec();
+        const result = await runCommand("codex", ["mcp", "add", SERVER_NAME, "--", spec.command, ...spec.args]);
+        if (!result.ok)
+            throw new Error(result.stderr || result.stdout || "Failed to add mcp-for-i to Codex.");
+        return {
+            ok: true,
+            id: "codex",
+            label: "Codex Desktop / CLI",
+            message: "Added mcp-for-i to Codex.",
+            output: compactOutput(result)
+        };
+    }
+    async installClaudeCode() {
+        if (!await commandExists("claude")) {
+            return {
+                ok: false,
+                id: "claude-code",
+                label: "Claude Code",
+                message: "claude command was not found. Use the manual instructions below."
+            };
+        }
+        if (await this.isClaudeConfigured()) {
+            return {
+                ok: true,
+                id: "claude-code",
+                label: "Claude Code",
+                message: "mcp-for-i is already configured in Claude Code."
+            };
+        }
+        const spec = this.getLaunchSpec();
+        const result = await runCommand("claude", ["mcp", "add", "--scope", "user", "--transport", "stdio", SERVER_NAME, "--", spec.command, ...spec.args]);
+        if (!result.ok)
+            throw new Error(result.stderr || result.stdout || "Failed to add mcp-for-i to Claude Code.");
+        return {
+            ok: true,
+            id: "claude-code",
+            label: "Claude Code",
+            message: "Added mcp-for-i to Claude Code.",
+            output: compactOutput(result)
+        };
+    }
+    async installVsCode() {
+        if (!await commandExists("code")) {
+            return {
+                ok: false,
+                id: "vscode-copilot",
+                label: "VS Code / GitHub Copilot",
+                message: "code command was not found. Use the manual instructions below."
+            };
+        }
+        const spec = this.getLaunchSpec();
+        const payload = JSON.stringify({
+            name: SERVER_NAME,
+            command: spec.command,
+            args: spec.args
+        });
+        const result = await runCommand("code", ["--add-mcp", payload]);
+        if (!result.ok)
+            throw new Error(result.stderr || result.stdout || "Failed to add mcp-for-i to VS Code.");
+        return {
+            ok: true,
+            id: "vscode-copilot",
+            label: "VS Code / GitHub Copilot",
+            message: "Added mcp-for-i to VS Code / GitHub Copilot.",
+            output: compactOutput(result)
+        };
+    }
+    async manualOnly(id, label) {
+        const spec = this.getLaunchSpec();
+        const genericJson = JSON.stringify({
+            mcpServers: {
+                [SERVER_NAME]: {
+                    command: spec.command,
+                    args: spec.args
+                }
+            }
+        }, null, 2);
+        const vscodeJson = JSON.stringify({
+            name: SERVER_NAME,
+            command: spec.command,
+            args: spec.args
+        }, null, 2);
+        const codexToml = [
+            `[mcp_servers.${quoteTomlKey(SERVER_NAME)}]`,
+            `command = ${quoteToml(spec.command)}`,
+            `args = [${spec.args.map(quoteToml).join(", ")}]`
+        ].join("\n");
+        const claudeCommand = `claude mcp add --scope user --transport stdio ${SERVER_NAME} -- ${spec.command} ${spec.args.join(" ")}`;
+        const codexCommand = `codex mcp add ${SERVER_NAME} -- ${spec.command} ${spec.args.join(" ")}`;
+        const vscodeCommand = `code --add-mcp ${JSON.stringify(vscodeJson)}`;
+        return {
+            ok: true,
+            id,
+            label,
+            message: "Manual setup instructions",
+            output: [
+                "Codex:",
+                codexCommand,
+                "",
+                codexToml,
+                "",
+                "Claude Code:",
+                claudeCommand,
+                "",
+                "VS Code / GitHub Copilot:",
+                vscodeCommand,
+                "",
+                vscodeJson,
+                "",
+                "Generic JSON clients:",
+                genericJson,
+                "",
+                "Project Bob:",
+                "Use the generic JSON command/args above unless Project Bob publishes a stable local MCP config or CLI flow."
+            ]
+        };
+    }
+    async isCodexConfigured() {
+        const result = await runCommand("codex", ["mcp", "get", SERVER_NAME]);
+        return result.ok;
+    }
+    async isClaudeConfigured() {
+        const result = await runCommand("claude", ["mcp", "get", SERVER_NAME]);
+        return result.ok;
+    }
+    async isCodeConfigured() {
+        const userConfigPath = getVsCodeUserMcpPath();
+        try {
+            const raw = await fs.readFile(userConfigPath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed?.servers)) {
+                return parsed.servers.some((entry) => entry?.name === SERVER_NAME);
+            }
+            if (parsed?.servers && typeof parsed.servers === "object") {
+                return Object.prototype.hasOwnProperty.call(parsed.servers, SERVER_NAME);
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    getLaunchSpec() {
+        return {
+            command: process.execPath,
+            args: [path.join(this.rootDir, "dist", "index.js")]
+        };
+    }
+}
+function getVsCodeUserMcpPath() {
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "Code", "User", "mcp.json");
+    }
+    if (process.platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "Code", "User", "mcp.json");
+    }
+    return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "Code", "User", "mcp.json");
+}
+async function commandExists(command) {
+    const result = await runCommand(command, ["--help"]);
+    return result.ok;
+}
+async function runCommand(command, args) {
+    return new Promise(resolve => {
+        const child = spawn(command, args, {
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", chunk => stdout.push(String(chunk)));
+        child.stderr.on("data", chunk => stderr.push(String(chunk)));
+        child.on("error", () => resolve({ ok: false, stdout: "", stderr: "" }));
+        child.on("exit", code => resolve({
+            ok: code === 0,
+            stdout: stdout.join("").trim(),
+            stderr: stderr.join("").trim()
+        }));
+    });
+}
+function compactOutput(result) {
+    return [result.stdout, result.stderr].filter(Boolean).flatMap(value => value.split(/\r?\n/)).filter(Boolean);
+}
+function quoteToml(value) {
+    return JSON.stringify(value);
+}
+function quoteTomlKey(value) {
+    return JSON.stringify(value);
+}