mcp-for-i 0.1.11 → 0.1.12

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+`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
 
@@ -17,15 +17,19 @@ 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. Start the local control plane:
+1. Open the local control plane:
 
 ```bash
-mcp-for-i-control serve
+mcp-for-i control
 ```
 
-2. Open the UI at:
+`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
@@ -33,25 +37,45 @@ 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)
+## Control Commands
 
-Enable startup at login:
+From an npm install or a git checkout build, these commands are the supported control entrypoints:
 
 ```bash
-mcp-for-i-control setup
+mcp-for-i control
+mcp-for-i control status
+mcp-for-i control enable
+mcp-for-i control disable
 ```
 
-Check status:
+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
 ```
 
-Disable startup:
+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.
 
-```bash
-mcp-for-i-control remove
-```
+## 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
 
@@ -79,19 +103,18 @@ Check current installed version:
 mcp-for-i --version
 ```
 
-## Control Plane Runtime Actions
+## Control Plane Updates
 
-In the UI, runtime buttons behave as follows:
+The control plane intentionally stays narrow:
 
-- `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.
+  - 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/clones the configured skills repository and branch into the local `skills` directory.
+  - 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)
 
@@ -104,6 +127,14 @@ 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`.

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);
+}

package/dist/controlplane/commands.js

@@ -0,0 +1,109 @@
+import { startControlPlaneServer } from "./server.js";
+import { openUrl } from "./platform.js";
+import { getControlPlaneUrl } from "./serverShared.js";
+import { disableBackgroundService, enableBackgroundService, ensureControlPlaneRunning, getServiceStatus } from "./serviceManager.js";
+export async function runControlCommand(args, options) {
+    const stderr = options.stderr || process.stderr;
+    const command = normalizeCommand(args, options.defaultCommand || "serve");
+    const scriptPath = options.scriptPath;
+    const nodePath = options.nodePath || process.execPath;
+    switch (command) {
+        case "serve":
+            await serve(stderr);
+            return;
+        case "status":
+            await printStatus(stderr, scriptPath, nodePath);
+            return;
+        case "open":
+            await openControlUi(stderr, scriptPath, nodePath);
+            return;
+        case "enable":
+            await enableService(stderr, scriptPath, nodePath);
+            return;
+        case "disable":
+            await disableService(stderr, scriptPath, nodePath);
+            return;
+        case "help":
+        default:
+            printHelp(stderr);
+            return;
+    }
+}
+async function serve(stderr) {
+    try {
+        const server = await startControlPlaneServer();
+        stderr.write(`mcp-for-i control plane running at http://${server.host}:${server.port}\n`);
+        const shutdown = async () => {
+            await server.close();
+            process.exit(0);
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    }
+    catch (err) {
+        if (err?.code === "EADDRINUSE") {
+            const url = getControlPlaneUrl();
+            stderr.write(`mcp-for-i control plane already running at ${url}\n`);
+            process.exit(0);
+        }
+        throw err;
+    }
+}
+async function printStatus(stderr, scriptPath, nodePath) {
+    const url = getControlPlaneUrl();
+    const status = await getServiceStatus(scriptPath, nodePath);
+    stderr.write(`Control plane URL: ${url}\n`);
+    stderr.write(`Platform: ${status.label} (${status.arch})\n`);
+    stderr.write(`Running: ${status.running ? "yes" : "no"}\n`);
+    stderr.write(`Background service: ${status.enabled ? "enabled" : "disabled"} via ${status.managedBy}\n`);
+    if (status.target)
+        stderr.write(`Target: ${status.target}\n`);
+    if (status.detail)
+        stderr.write(`Detail: ${status.detail}\n`);
+}
+async function openControlUi(stderr, scriptPath, nodePath) {
+    const url = getControlPlaneUrl();
+    const result = await ensureControlPlaneRunning(scriptPath, nodePath);
+    if (result.started) {
+        stderr.write(`Started control plane at ${url}\n`);
+    }
+    try {
+        await openUrl(url);
+        stderr.write(`Opening ${url}\n`);
+    }
+    catch {
+        stderr.write(`Control plane is running at ${url}\n`);
+    }
+}
+async function enableService(stderr, scriptPath, nodePath) {
+    const status = await enableBackgroundService(scriptPath, nodePath);
+    await ensureControlPlaneRunning(scriptPath, nodePath);
+    stderr.write(`Enabled background service via ${status.managedBy}\n`);
+    if (status.target)
+        stderr.write(`Target: ${status.target}\n`);
+    if (status.detail)
+        stderr.write(`Detail: ${status.detail}\n`);
+}
+async function disableService(stderr, scriptPath, nodePath) {
+    const status = await disableBackgroundService(scriptPath, nodePath);
+    stderr.write(`Disabled background service (${status.managedBy})\n`);
+    if (status.target)
+        stderr.write(`Target: ${status.target}\n`);
+}
+function printHelp(stderr) {
+    stderr.write(`mcp-for-i-control commands:\n`);
+    stderr.write(`  serve      Start control plane server in the foreground\n`);
+    stderr.write(`  open       Start control plane in the background if needed, then open UI\n`);
+    stderr.write(`  status     Show running and background-service status\n`);
+    stderr.write(`  enable     Enable background service for this platform\n`);
+    stderr.write(`  disable    Disable background service for this platform\n`);
+    stderr.write(`  help       Show this help text\n`);
+}
+function normalizeCommand(args, fallback) {
+    const first = (args[0] || fallback).toLowerCase();
+    if (!first || first === "start")
+        return fallback;
+    if (first === "--help" || first === "-h")
+        return "help";
+    return first;
+}

package/dist/controlplane/index.js

@@ -1,120 +1,7 @@
 #!/usr/bin/env node
-import { startControlPlaneServer } from "./server.js";
-import { spawn } from "child_process";
 import { fileURLToPath } from "url";
-import { AUTOSTART_TASK_NAME, configureWindowsAutostart, getControlPlaneUrl, getWindowsAutostartStatus, isControlPlaneRunning, removeWindowsAutostart } from "./autostart.js";
-const command = normalizeCommand(process.argv.slice(2));
-switch (command) {
-    case "serve":
-        await serve();
-        break;
-    case "setup":
-        await setupAutostart();
-        break;
-    case "status":
-        await printStatus();
-        break;
-    case "remove":
-    case "uninstall":
-        await removeAutostart();
-        break;
-    case "open":
-        await openUi();
-        break;
-    case "help":
-    default:
-        printHelp();
-        break;
-}
-async function serve() {
-    try {
-        const server = await startControlPlaneServer();
-        process.stderr.write(`mcp-for-i control plane running at http://${server.host}:${server.port}\n`);
-        const shutdown = async () => {
-            await server.close();
-            process.exit(0);
-        };
-        process.on("SIGINT", shutdown);
-        process.on("SIGTERM", shutdown);
-    }
-    catch (err) {
-        if (err?.code === "EADDRINUSE") {
-            const url = getControlPlaneUrl();
-            process.stderr.write(`mcp-for-i control plane already running at ${url}\n`);
-            process.exit(0);
-        }
-        throw err;
-    }
-}
-async function setupAutostart() {
-    if (process.platform !== "win32") {
-        process.stderr.write("Autostart setup is currently implemented for Windows only.\n");
-        process.stderr.write(`Run manually with: mcp-for-i-control serve\n`);
-        return;
-    }
-    const scriptPath = fileURLToPath(import.meta.url);
-    await configureWindowsAutostart(scriptPath, process.execPath);
-    process.stderr.write(`Autostart configured (${AUTOSTART_TASK_NAME}).\n`);
-    process.stderr.write(`Control plane URL: ${getControlPlaneUrl()}\n`);
-}
-async function removeAutostart() {
-    if (process.platform !== "win32") {
-        process.stderr.write("Autostart removal is currently implemented for Windows only.\n");
-        return;
-    }
-    try {
-        await removeWindowsAutostart();
-        process.stderr.write(`Autostart removed (${AUTOSTART_TASK_NAME}).\n`);
-    }
-    catch (err) {
-        const msg = err?.message || String(err);
-        if (msg.includes("cannot find the file specified") || msg.includes("ERROR: The system cannot find")) {
-            process.stderr.write(`Autostart task not found (${AUTOSTART_TASK_NAME}).\n`);
-            return;
-        }
-        throw err;
-    }
-}
-async function printStatus() {
-    const url = getControlPlaneUrl();
-    const running = await isControlPlaneRunning(url);
-    process.stderr.write(`Control plane URL: ${url}\n`);
-    process.stderr.write(`Running: ${running ? "yes" : "no"}\n`);
-    if (process.platform === "win32") {
-        const auto = await getWindowsAutostartStatus();
-        process.stderr.write(`Autostart task: ${auto.installed ? "installed" : "not installed"}\n`);
-        if (auto.state) {
-            process.stderr.write(`Autostart state: ${auto.state}\n`);
-        }
-    }
-    else {
-        process.stderr.write("Autostart task: platform not managed by this command\n");
-    }
-}
-async function openUi() {
-    const url = getControlPlaneUrl();
-    if (process.platform === "win32") {
-        spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" }).unref();
-    }
-    else if (process.platform === "darwin") {
-        spawn("open", [url], { detached: true, stdio: "ignore" }).unref();
-    }
-    else {
-        spawn("xdg-open", [url], { detached: true, stdio: "ignore" }).unref();
-    }
-    process.stderr.write(`Opening ${url}\n`);
-}
-function printHelp() {
-    process.stderr.write(`mcp-for-i-control commands:\n`);
-    process.stderr.write(`  serve      Start control plane server (foreground)\n`);
-    process.stderr.write(`  setup      Configure autostart at login and launch now\n`);
-    process.stderr.write(`  status     Show running/autostart status\n`);
-    process.stderr.write(`  remove     Remove autostart configuration\n`);
-    process.stderr.write(`  open       Open UI URL in default browser\n`);
-}
-function normalizeCommand(args) {
-    const first = (args[0] || "serve").toLowerCase();
-    if (!first || first === "start")
-        return "serve";
-    return first;
-}
+import { runControlCommand } from "./commands.js";
+await runControlCommand(process.argv.slice(2), {
+    defaultCommand: "serve",
+    scriptPath: fileURLToPath(import.meta.url)
+});