mcp-for-i 0.1.13 → 0.3.0

package/README.md

@@ -50,6 +50,8 @@ From an npm install or a git checkout build, these commands are the supported co
 ```bash
 mcp-for-i control
 mcp-for-i control status
+mcp-for-i control stop
+mcp-for-i control restart
 mcp-for-i control enable
 mcp-for-i control disable
 ```
@@ -59,11 +61,15 @@ Equivalent direct control-plane binary commands:
 ```bash
 mcp-for-i-control open
 mcp-for-i-control status
+mcp-for-i-control stop
+mcp-for-i-control restart
 mcp-for-i-control enable
 mcp-for-i-control disable
 mcp-for-i-control serve
 ```
 
+`stop` shuts down the running control plane (it works for one started by `control`, `serve` or the background service). If the background service is enabled, the control plane starts again at the next login; `disable` turns that off. `restart` stops it and starts it again in the background.
+
 Behavior by environment:
 - Windows: `enable` registers a Startup entry.
 - macOS: `enable` registers a LaunchAgent.
@@ -199,6 +205,27 @@ OTP is only needed when the npm account has two-factor authentication enabled fo
 - 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.
 
+## Fast Source Investigation
+
+The existing member tools remain compatible: an unchanged `ibmi.qsys.members.list` call still returns an array, and an unchanged `ibmi.qsys.members.read` call still returns source text. New callers can opt into faster, bounded workflows:
+
+- `ibmi.session.bootstrap` returns connection, release, library-list, policy, transport, and capability information in one call.
+- `ibmi.source.resolve` finds an exact member across likely source files without returning an entire source-file inventory.
+- `ibmi.source.inspect` performs up to eight metadata, outline, search, range-read, and dependency operations over one consistent member snapshot.
+- `ibmi.qsys.members.list` supports exact/prefix/contains/source-type/change-time filtering and keyset paging with `responseFormat: "page"`.
+- `ibmi.qsys.members.read` supports ranges, context, metadata, SHA-256, and version checks with `responseFormat: "structured"`.
+- `ibmi.qsys.members.write` accepts `expectedVersion` or `expectedSha256` to prevent a stale analysis from overwriting newer source.
+
+Source-date reads use an ephemeral `QTEMP` alias in the same database job. If that path is unavailable, the server falls back to a complete UTF-8 `CPYTOSTMF` read; it never reconstructs a member from search matches.
+
+## 5250 Green Screen
+
+`ibmi.tn5250.*` gives the assistant a real 5250 session (a built-in TN5250 client, nothing to install on the IBM i). While a session is open the MCP server also serves a live view on `http://127.0.0.1:3981` (the link, with its token, is in every screen result and on the control plane's Runtime tab): you watch the screen the assistant is driving and can type and click in it yourself. Clients that support MCP Apps draw the same screen inside the chat. See [docs/tools.md](docs/tools.md#tn5250-notes).
+
+## IBM i Documentation
+
+`ibmi.docs.search` and `ibmi.docs.open` provide a release-aware, cached catalog of allowlisted official IBM documentation. The same catalog and topic content are exposed as MCP resources under `ibmi-docs://`. Documentation results include their official canonical URL, content version/checksum, and observation time. When local coverage is insufficient, search results explicitly recommend a web fallback instead of presenting cached material as exhaustive.
+
 ## Links
 
 - Main repo: [ashishthomas2202/mcp-for-i](https://github.com/ashishthomas2202/mcp-for-i)

package/dist/config/store.js

@@ -1,7 +1,10 @@
 import fs from "fs/promises";
+import { constants as fsConstants } from "fs";
 import path from "path";
 import os from "os";
 import { setPassword } from "../security/credentialStore.js";
+import { readFileWithRetry, sleep, writeFileAtomic } from "../util/atomicWrite.js";
+import { withFileLock } from "../util/fileLock.js";
 const defaultSettings = {
     readOnlyMode: false,
     tempLibrary: "ILEDITOR",
@@ -22,138 +25,236 @@ const defaultSettings = {
     sessionPingSeconds: 15,
     sessionReconnectAttempts: 2
 };
+export class ConfigCorruptError extends Error {
+    configPath;
+    backupPath;
+    detail;
+    constructor(configPath, backupPath, detail) {
+        super(`Config file ${configPath} could not be parsed (${detail}). ` +
+            (backupPath ? `A copy was saved to ${backupPath}. ` : "") +
+            "The file was left unchanged; fix or remove it and try again.");
+        this.configPath = configPath;
+        this.backupPath = backupPath;
+        this.detail = detail;
+        this.name = "ConfigCorruptError";
+    }
+}
+// configPath -> { raw content already backed up, backup path }
+const backedUpCorruptContent = new Map();
+const plaintextWarnings = new Set();
 export class ConfigStore {
     configDir;
     configPath;
+    lockPath;
     data = null;
-    saveQueue = Promise.resolve();
-    constructor() {
-        this.configDir = getConfigDir();
+    constructor(options = {}) {
+        this.configDir = options.configDir || getConfigDir();
         this.configPath = path.join(this.configDir, "config.json");
+        this.lockPath = `${this.configPath}.lock`;
     }
+    getConfigPath() {
+        return this.configPath;
+    }
+    /**
+     * Reads the config from disk. Defaults are created only when the file does not
+     * exist. A file that exists but cannot be read or parsed is never overwritten:
+     * a backup copy is made and ConfigCorruptError is thrown.
+     */
     async load() {
-        await ensureDir(this.configDir);
-        let loadedFromDisk = true;
-        try {
-            const raw = await fs.readFile(this.configPath, "utf8");
-            this.data = JSON.parse(raw);
-        }
-        catch {
-            loadedFromDisk = false;
-            this.data = { connections: [], settings: defaultSettings, actions: [] };
-        }
-        const migrated = await migrateConfigFile(this.data);
-        this.data = migrated.config;
-        if (!loadedFromDisk || migrated.changed) {
-            await this.save();
+        const disk = await this.readFromDisk();
+        if (disk.exists) {
+            const migrated = await migrateConfigFile(disk.parsed);
+            if (!migrated.changed) {
+                this.data = migrated.config;
+                return this.data;
+            }
         }
+        // Missing file or a migration is needed: redo the read under the lock so a
+        // concurrent writer's changes are not overwritten.
+        await this.mutate(() => undefined);
         return this.data;
     }
+    /**
+     * Writes the in-memory config as-is (last writer wins). Prefer the specific
+     * update methods or mutate(), which re-read the file under the lock first.
+     */
     async save() {
         if (!this.data)
             await this.load();
-        const payload = JSON.stringify(this.data, null, 2);
-        await this.enqueueSave(async () => {
-            const tempPath = `${this.configPath}.${process.pid}.${Date.now()}.tmp`;
-            await writeFileWithRetry(tempPath, payload);
-            try {
-                await fs.rename(tempPath, this.configPath);
-            }
-            catch {
-                await writeFileWithRetry(this.configPath, payload);
-                await fs.rm(tempPath, { force: true });
-            }
-        });
+        const payload = serializeConfig(this.data);
+        await withFileLock(this.lockPath, () => this.writePayload(payload));
     }
     async listConnections() {
         const cfg = await this.load();
-        return cfg.connections;
+        return cfg.connections.map(publicConnection);
     }
     async getConnection(name) {
         const cfg = await this.load();
-        return cfg.connections.find(c => c.name === name);
+        const found = cfg.connections.find(c => c.name === name);
+        return found ? publicConnection(found) : undefined;
     }
     async upsertConnection(connection) {
-        const cfg = await this.load();
-        const sanitized = await sanitizeConnection(connection);
-        const idx = cfg.connections.findIndex(c => c.name === sanitized.name);
-        if (idx >= 0) {
-            cfg.connections[idx] = { ...cfg.connections[idx], ...sanitized };
-        }
-        else {
-            cfg.connections.push(sanitized);
-        }
-        await this.save();
+        const { sanitized, password, persisted } = await sanitizeConnection(connection);
+        await this.mutate(cfg => {
+            const idx = cfg.connections.findIndex(c => c.name === sanitized.name);
+            if (idx >= 0) {
+                const merged = { ...cfg.connections[idx], ...sanitized };
+                // A legacy plaintext password stays only while it is still the password in
+                // use and the keychain could not take it.
+                if (password !== undefined && (persisted || merged.password !== password)) {
+                    delete merged.password;
+                }
+                cfg.connections[idx] = merged;
+            }
+            else {
+                cfg.connections.push(sanitized);
+            }
+        });
     }
     async deleteConnection(name) {
-        const cfg = await this.load();
-        cfg.connections = cfg.connections.filter(c => c.name !== name);
-        await this.save();
+        await this.mutate(cfg => {
+            cfg.connections = cfg.connections.filter(c => c.name !== name);
+        });
     }
     async getSettings() {
         const cfg = await this.load();
         return cfg.settings;
     }
     async updateSettings(update) {
-        const cfg = await this.load();
-        cfg.settings = { ...cfg.settings, ...update };
-        await this.save();
+        await this.mutate(cfg => {
+            cfg.settings = { ...cfg.settings, ...update };
+        });
     }
     async listActions() {
         const cfg = await this.load();
         return cfg.actions || [];
     }
     async upsertAction(action) {
-        const cfg = await this.load();
-        const idx = cfg.actions.findIndex(a => a.name === action.name);
-        if (idx >= 0)
-            cfg.actions[idx] = action;
-        else
-            cfg.actions.push(action);
-        await this.save();
+        await this.mutate(cfg => {
+            const idx = cfg.actions.findIndex(a => a.name === action.name);
+            if (idx >= 0)
+                cfg.actions[idx] = action;
+            else
+                cfg.actions.push(action);
+        });
     }
     async deleteAction(name) {
-        const cfg = await this.load();
-        cfg.actions = cfg.actions.filter(a => a.name !== name);
-        await this.save();
+        await this.mutate(cfg => {
+            cfg.actions = cfg.actions.filter(a => a.name !== name);
+        });
     }
     async listProfiles(connectionName) {
         const conn = await this.getConnection(connectionName);
         return conn?.profiles || [];
     }
     async saveProfile(connectionName, profile) {
-        const conn = await this.getConnection(connectionName);
-        if (!conn)
-            throw new Error(`Connection ${connectionName} not found`);
-        const profiles = conn.profiles || [];
-        const idx = profiles.findIndex(p => p.name === profile.name);
-        if (idx >= 0)
-            profiles[idx] = profile;
-        else
-            profiles.push(profile);
-        conn.profiles = profiles;
-        await this.upsertConnection(conn);
+        await this.mutateConnection(connectionName, conn => {
+            const profiles = conn.profiles || [];
+            const idx = profiles.findIndex(p => p.name === profile.name);
+            if (idx >= 0)
+                profiles[idx] = profile;
+            else
+                profiles.push(profile);
+            conn.profiles = profiles;
+        });
     }
     async deleteProfile(connectionName, profileName) {
-        const conn = await this.getConnection(connectionName);
-        if (!conn)
-            throw new Error(`Connection ${connectionName} not found`);
-        conn.profiles = (conn.profiles || []).filter(p => p.name !== profileName);
-        if (conn.currentProfile === profileName) {
-            conn.currentProfile = undefined;
-        }
-        await this.upsertConnection(conn);
+        await this.mutateConnection(connectionName, conn => {
+            conn.profiles = (conn.profiles || []).filter(p => p.name !== profileName);
+            if (conn.currentProfile === profileName) {
+                conn.currentProfile = undefined;
+            }
+        });
     }
     async setCurrentProfile(connectionName, profileName) {
-        const conn = await this.getConnection(connectionName);
-        if (!conn)
-            throw new Error(`Connection ${connectionName} not found`);
-        conn.currentProfile = profileName;
-        await this.upsertConnection(conn);
+        await this.mutateConnection(connectionName, conn => {
+            conn.currentProfile = profileName;
+        });
+    }
+    /**
+     * Read-modify-write under the cross-process lock: the file is re-read (and
+     * migrated) while the lock is held, `fn` changes it, and the result is written
+     * atomically. Concurrent callers in this and other processes are serialized,
+     * so no update is lost. `fn` must not call other ConfigStore update methods.
+     */
+    async mutate(fn) {
+        return withFileLock(this.lockPath, async () => {
+            const disk = await this.readFromDisk();
+            const migrated = await migrateConfigFile(disk.exists ? disk.parsed : undefined);
+            const cfg = migrated.config;
+            const result = await fn(cfg);
+            const payload = serializeConfig(cfg);
+            if (!disk.exists || payload !== disk.raw) {
+                await this.writePayload(payload);
+            }
+            this.data = cfg;
+            return result;
+        });
     }
-    enqueueSave(operation) {
-        this.saveQueue = this.saveQueue.then(operation, operation);
-        return this.saveQueue;
+    async mutateConnection(connectionName, fn) {
+        await this.mutate(cfg => {
+            const conn = cfg.connections.find(c => c.name === connectionName);
+            if (!conn)
+                throw new Error(`Connection ${connectionName} not found`);
+            fn(conn);
+        });
+    }
+    async readFromDisk() {
+        let raw;
+        try {
+            raw = await readFileWithRetry(this.configPath);
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return { exists: false };
+            throw new Error(`Config file ${this.configPath} could not be read (${err?.code || err?.message || String(err)}); it was left unchanged.`);
+        }
+        if (raw.trim().length === 0) {
+            // An empty file holds nothing that could be lost; treat it like a missing one.
+            return { exists: false };
+        }
+        try {
+            return { exists: true, raw, parsed: JSON.parse(stripBom(raw)) };
+        }
+        catch {
+            // A writer that does not use atomic renames (an older version) may be mid-write.
+            await sleep(50);
+        }
+        try {
+            raw = await readFileWithRetry(this.configPath);
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return { exists: false };
+            throw err;
+        }
+        try {
+            return { exists: true, raw, parsed: JSON.parse(stripBom(raw)) };
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const backupPath = await this.backupCorruptFile(raw);
+            throw new ConfigCorruptError(this.configPath, backupPath, detail);
+        }
+    }
+    async backupCorruptFile(raw) {
+        const previous = backedUpCorruptContent.get(this.configPath);
+        if (previous && previous.raw === raw)
+            return previous.backupPath;
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const backupPath = `${this.configPath}.corrupt-${stamp}`;
+        try {
+            await fs.copyFile(this.configPath, backupPath, fsConstants.COPYFILE_EXCL);
+            backedUpCorruptContent.set(this.configPath, { raw, backupPath });
+            return backupPath;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async writePayload(payload) {
+        await fs.mkdir(this.configDir, { recursive: true });
+        await writeFileAtomic(this.configPath, payload, { mode: 0o600 });
     }
 }
 export function getConfigDir() {
@@ -166,6 +267,16 @@ export function getConfigDir() {
     }
     return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "mcp-for-i");
 }
+function serializeConfig(cfg) {
+    return JSON.stringify(cfg, null, 2);
+}
+function stripBom(raw) {
+    return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+}
+function publicConnection(connection) {
+    const { password: _password, ...rest } = connection;
+    return rest;
+}
 async function migrateConfigFile(input) {
     let changed = false;
     const root = isPlainObject(input) ? input : {};
@@ -218,9 +329,24 @@ async function normalizeConnections(value) {
             changed = true;
         seenNames.add(uniqueName);
         const password = toNonEmptyString(entry.password);
+        let keepPlaintext = false;
         if (password) {
-            await setPassword(uniqueName, password);
-            changed = true;
+            // The plaintext is dropped only once the keychain confirms it holds the password.
+            let persistent = false;
+            let reason;
+            try {
+                persistent = (await setPassword(uniqueName, password, { keepExistingSessionValue: true })).persistent;
+            }
+            catch (err) {
+                reason = err instanceof Error ? err.message : String(err);
+            }
+            if (persistent) {
+                changed = true;
+            }
+            else {
+                keepPlaintext = true;
+                warnPlaintextKept(uniqueName, reason);
+            }
         }
         const host = toNonEmptyString(entry.host) || "";
         const username = toNonEmptyString(entry.username) || "";
@@ -255,6 +381,8 @@ async function normalizeConnections(value) {
             normalized.readyTimeout = readyTimeout;
         if (sshDebug !== undefined)
             normalized.sshDebug = sshDebug;
+        if (keepPlaintext)
+            normalized.password = password;
         if (JSON.stringify(normalized) !== JSON.stringify(entry)) {
             changed = true;
         }
@@ -262,6 +390,14 @@ async function normalizeConnections(value) {
     }
     return { connections, changed };
 }
+function warnPlaintextKept(connectionName, reason) {
+    if (plaintextWarnings.has(connectionName))
+        return;
+    plaintextWarnings.add(connectionName);
+    process.stderr.write(`[mcp-for-i] warning: no persistent keychain is available, so the plaintext password for connection ` +
+        `"${connectionName}" was left in config.json${reason ? ` (${reason})` : ""}. ` +
+        "It will be moved to the keychain once one is available.\n");
+}
 function normalizeSettings(value) {
     if (!isPlainObject(value)) {
         return { value: { ...defaultSettings }, changed: true };
@@ -298,19 +434,23 @@ function normalizePolicy(value) {
         delete policy.allowPaths;
     if (!Array.isArray(policy.denyPaths))
         delete policy.denyPaths;
+    if (policy.approvalMode !== "prompt" && policy.approvalMode !== "agent")
+        delete policy.approvalMode;
     return policy;
 }
 async function sanitizeConnection(connection) {
     const raw = connection;
     const password = toNonEmptyString(raw.password);
+    let persisted = false;
     if (password) {
-        await setPassword(connection.name, password);
+        persisted = (await setPassword(connection.name, password)).persistent;
     }
     const { password: _password, storePassword: _storePassword, ...rest } = raw;
     const normalizedPort = normalizePort(rest.port);
     return {
-        ...rest,
-        port: normalizedPort
+        sanitized: { ...rest, port: normalizedPort },
+        password,
+        persisted
     };
 }
 function uniqueConnectionName(baseName, seen) {
@@ -346,23 +486,3 @@ function toNonEmptyString(value) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-async function ensureDir(dir) {
-    await fs.mkdir(dir, { recursive: true });
-}
-async function writeFileWithRetry(filePath, content, retries = 5, delayMs = 40) {
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        try {
-            await fs.writeFile(filePath, content, "utf8");
-            return;
-        }
-        catch (err) {
-            const transient = err?.code === "EBUSY" || err?.code === "EPERM";
-            if (!transient || attempt === retries)
-                throw err;
-            await wait(delayMs * (attempt + 1));
-        }
-    }
-}
-async function wait(ms) {
-    await new Promise(resolve => setTimeout(resolve, ms));
-}

package/dist/controlplane/auth.js

@@ -0,0 +1,128 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { getConfigDir } from "../config/store.js";
+/** Header the Web UI and the CLI send with every control-plane API call. */
+export const CONTROL_TOKEN_HEADER = "X-MCP-For-I-Token";
+const TOKEN_FILE = "controlplane.token";
+const TOKEN_PATTERN = /^[a-f0-9]{64}$/;
+export function getControlTokenPath(configDir = getConfigDir()) {
+    return path.join(configDir, TOKEN_FILE);
+}
+/** Reads the per-install token, or returns undefined when none exists yet. */
+export function readControlToken(configDir = getConfigDir()) {
+    try {
+        const raw = fs.readFileSync(getControlTokenPath(configDir), "utf8").trim();
+        return TOKEN_PATTERN.test(raw) ? raw : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Returns the per-install token, creating it on first use. The file is written
+ * with mode 0600 (owner only) where the platform supports it.
+ */
+export function ensureControlToken(configDir = getConfigDir()) {
+    const existing = readControlToken(configDir);
+    if (existing)
+        return existing;
+    fs.mkdirSync(configDir, { recursive: true });
+    const tokenPath = getControlTokenPath(configDir);
+    const token = crypto.randomBytes(32).toString("hex");
+    try {
+        fs.writeFileSync(tokenPath, `${token}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        return token;
+    }
+    catch (err) {
+        if (err?.code !== "EEXIST")
+            throw err;
+    }
+    // Another process created it first, or the existing file is unreadable/invalid.
+    const raced = readControlToken(configDir);
+    if (raced)
+        return raced;
+    fs.writeFileSync(tokenPath, `${token}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        fs.chmodSync(tokenPath, 0o600);
+    }
+    catch {
+        // best effort on platforms without POSIX modes
+    }
+    return token;
+}
+/** Constant-time token comparison. */
+export function tokensMatch(expected, provided) {
+    if (typeof provided !== "string" || !provided)
+        return false;
+    const a = Buffer.from(expected, "utf8");
+    const b = Buffer.from(provided.trim(), "utf8");
+    if (a.length !== b.length)
+        return false;
+    return crypto.timingSafeEqual(a, b);
+}
+/** Hostnames the control plane answers to (blocks DNS rebinding). */
+export function isAllowedHostHeader(hostHeader, port, extraHosts = []) {
+    if (!hostHeader)
+        return false;
+    const parsed = parseHostPort(hostHeader.trim().toLowerCase());
+    if (!parsed)
+        return false;
+    const allowed = new Set(["localhost", "127.0.0.1", "[::1]", ...extraHosts.map(normalizeHostName)]);
+    if (!allowed.has(parsed.host))
+        return false;
+    const effectivePort = parsed.port ?? 80;
+    return effectivePort === port;
+}
+/** An Origin header, when present, must point at this same local server. */
+export function isAllowedOrigin(origin, port, extraHosts = []) {
+    if (origin === undefined)
+        return true;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "http:")
+        return false;
+    const host = url.port ? `${url.hostname}:${url.port}` : url.hostname;
+    return isAllowedHostHeader(host, port, extraHosts);
+}
+function parseHostPort(value) {
+    let host;
+    let portText;
+    if (value.startsWith("[")) {
+        const end = value.indexOf("]");
+        if (end < 0)
+            return undefined;
+        host = value.slice(0, end + 1);
+        const rest = value.slice(end + 1);
+        if (rest) {
+            if (!rest.startsWith(":"))
+                return undefined;
+            portText = rest.slice(1);
+        }
+    }
+    else {
+        const parts = value.split(":");
+        if (parts.length > 2)
+            return undefined;
+        host = parts[0];
+        portText = parts[1];
+    }
+    if (!host)
+        return undefined;
+    if (portText === undefined)
+        return { host };
+    if (!/^\d{1,5}$/.test(portText))
+        return undefined;
+    return { host, port: Number(portText) };
+}
+function normalizeHostName(host) {
+    const lower = host.trim().toLowerCase();
+    if (lower.includes(":") && !lower.startsWith("["))
+        return `[${lower}]`;
+    return lower;
+}