mcp-for-i 0.1.0

package/dist/mcp/validation.js

@@ -0,0 +1,74 @@
+export function validateToolInput(schema, value) {
+    const errors = [];
+    validateNode(schema, value, "$", errors);
+    return errors;
+}
+function validateNode(schema, value, path, errors) {
+    if (!matchesType(schema.type, value)) {
+        const typeText = Array.isArray(schema.type) ? schema.type.join("|") : schema.type || "unknown";
+        errors.push(`${path} must be ${typeText}`);
+        return;
+    }
+    if (schema.enum && !schema.enum.includes(value)) {
+        errors.push(`${path} must be one of: ${schema.enum.map(v => JSON.stringify(v)).join(", ")}`);
+        return;
+    }
+    if (isObjectSchema(schema, value)) {
+        const obj = value;
+        for (const key of schema.required || []) {
+            if (!(key in obj) || obj[key] === undefined) {
+                errors.push(`${path}.${key} is required`);
+            }
+        }
+        if (schema.additionalProperties === false && schema.properties) {
+            for (const key of Object.keys(obj)) {
+                if (!(key in schema.properties)) {
+                    errors.push(`${path}.${key} is not allowed`);
+                }
+            }
+        }
+        if (schema.properties) {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (obj[key] !== undefined) {
+                    validateNode(propSchema, obj[key], `${path}.${key}`, errors);
+                }
+            }
+        }
+    }
+    if (Array.isArray(value) && schema.items) {
+        value.forEach((entry, idx) => validateNode(schema.items, entry, `${path}[${idx}]`, errors));
+    }
+}
+function isObjectSchema(schema, value) {
+    const types = toTypes(schema.type);
+    return types.includes("object") && isPlainObject(value);
+}
+function matchesType(type, value) {
+    if (!type)
+        return true;
+    const accepted = toTypes(type);
+    return accepted.some(t => isType(t, value));
+}
+function toTypes(type) {
+    if (!type)
+        return [];
+    return Array.isArray(type) ? type : [type];
+}
+function isType(type, value) {
+    if (type === "string")
+        return typeof value === "string";
+    if (type === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    if (type === "boolean")
+        return typeof value === "boolean";
+    if (type === "array")
+        return Array.isArray(value);
+    if (type === "object")
+        return isPlainObject(value);
+    if (type === "null")
+        return value === null;
+    return true;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/security/credentialStore.js

@@ -0,0 +1,42 @@
+const SERVICE = "mcp-for-i";
+const sessionStore = new Map();
+let keytar;
+async function getKeytar() {
+    if (keytar !== undefined)
+        return keytar;
+    try {
+        const mod = await import("keytar");
+        keytar = mod.default || mod;
+    }
+    catch {
+        keytar = null;
+    }
+    return keytar;
+}
+export async function setPassword(connectionName, password) {
+    const kt = await getKeytar();
+    if (kt) {
+        await kt.setPassword(SERVICE, connectionName, password);
+    }
+    else {
+        sessionStore.set(connectionName, password);
+    }
+}
+export async function getPassword(connectionName) {
+    const kt = await getKeytar();
+    if (kt) {
+        return kt.getPassword(SERVICE, connectionName);
+    }
+    return sessionStore.get(connectionName);
+}
+export async function deletePassword(connectionName) {
+    const kt = await getKeytar();
+    if (kt) {
+        await kt.deletePassword(SERVICE, connectionName);
+    }
+    sessionStore.delete(connectionName);
+}
+export async function isKeychainAvailable() {
+    const kt = await getKeytar();
+    return Boolean(kt);
+}

package/docs/configuration.md

@@ -0,0 +1,57 @@
+# Configuration
+
+Config file is stored under the user config directory:
+- Windows: `%APPDATA%\mcp-for-i\config.json`
+- macOS: `~/Library/Application Support/mcp-for-i/config.json`
+- Linux: `${XDG_CONFIG_HOME:-~/.config}/mcp-for-i/config.json`
+
+## Settings
+Default settings (editable in the config file):
+- `readOnlyMode`: boolean
+- `tempLibrary`: string
+- `tempDir`: string
+- `autoClearTempData`: boolean
+- `sourceFileCCSID`: string (default `*FILE`)
+- `enableSourceDates`: boolean (Phase 2+)
+- `homeDirectory`: string
+- `libraryList`: string[]
+- `currentLibrary`: string
+- `customVariables`: list of `{ name, value }`
+
+## Connections
+Connections are stored without passwords. Passwords are stored in OS keychain (or in-session fallback). Each connection can include optional `settings` overrides.
+Connections can also define policy, for example:
+- `read-only`
+- `guarded` (default; approvals required for risky operations)
+- `power-user`
+
+Example:
+```json
+{
+  "connections": [
+    {
+      "name": "DEV400",
+      "host": "dev400.myco.com",
+      "port": 22,
+      "username": "DEVUSER",
+      "privateKeyPath": "C:/keys/id_rsa",
+      "settings": {
+        "readOnlyMode": false
+      },
+      "policy": {
+        "profile": "guarded",
+        "requireApprovalFor": ["sql.write", "cl.run", "deploy.sync"]
+      },
+      "profiles": [
+        {
+          "name": "projectA",
+          "currentLibrary": "PROJALIB",
+          "libraryList": ["QSYS", "QGPL", "PROJALIB"],
+          "customVariables": [{ "name": "ENV", "value": "DEV" }]
+        }
+      ],
+      "currentProfile": "projectA"
+    }
+  ]
+}
+```

package/docs/examples.md

@@ -0,0 +1,73 @@
+# Examples
+
+## Add connection profile
+```json
+{
+  "tool": "ibmi.connections.add",
+  "arguments": {
+    "name": "DEV400",
+    "host": "dev400.myco.com",
+    "port": 22,
+    "username": "DEVUSER",
+    "password": "*****",
+    "storePassword": true,
+    "policy": { "profile": "guarded" }
+  }
+}
+```
+
+## Connect by saved name
+```json
+{
+  "tool": "ibmi.connect",
+  "arguments": { "name": "DEV400" }
+}
+```
+
+## List libraries
+```json
+{
+  "tool": "ibmi.qsys.libraries.list",
+  "arguments": { "filter": "*ALL" }
+}
+```
+
+## Read a member
+```json
+{
+  "tool": "ibmi.qsys.members.read",
+  "arguments": {
+    "library": "MYLIB",
+    "sourceFile": "QRPGLESRC",
+    "member": "MYPGM"
+  }
+}
+```
+
+## Run an action
+```json
+{
+  "tool": "ibmi.actions.run",
+  "arguments": {
+    "actionName": "Create RPGLE Program",
+    "targetType": "member",
+    "targetPath": "MYLIB/QRPGLESRC/MYPGM",
+    "library": "MYLIB",
+    "sourceFile": "QRPGLESRC",
+    "member": "MYPGM",
+    "extension": "RPGLE"
+  }
+}
+```
+
+## Activate a profile
+```json
+{
+  "tool": "ibmi.profiles.activate",
+  "arguments": {
+    "connectionName": "DEV400",
+    "name": "projectA",
+    "applyToJob": true
+  }
+}
+```

package/docs/installation.md

@@ -0,0 +1,61 @@
+# Installation
+
+## Prerequisites
+- Node.js 18+ recommended
+- IBM i SSH access (22)
+- On Linux: `libsecret` (for keychain via `keytar`)
+
+## Install
+1. Clone or copy this repo
+2. Install dependencies:
+   - `npm install`
+3. Build:
+   - `npm run build`
+4. Run:
+   - `node dist/index.js`
+
+## Control Plane UI (Onboarding + Updates)
+Run local control plane:
+
+- `npm run start:controlplane`
+
+Open:
+
+- `http://127.0.0.1:3980`
+
+Use the UI to add/edit/delete/rename connections, manage keychain passwords, and run MCP/skills update actions.
+
+## MCP (stdio) usage
+Configure your MCP client (e.g., Codex CLI) to run `mcp-for-i` via stdio. Example (pseudo-config):
+
+```json
+{
+  "mcpServers": {
+    "mcp-for-i": {
+      "command": "mcp-for-i"
+    }
+  }
+}
+```
+
+If you run from source, use:
+
+```json
+{
+  "command": "node",
+  "args": ["C:/Users/pgmashish/projects/mcp/mcp-for-i/dist/index.js"]
+}
+```
+
+## Logging (opt‑in)
+Logging is **disabled by default**. Enable it via env vars or CLI flags:
+
+- Env flags:
+  - `MCP_FOR_I_LOG_ENABLED=1`
+  - `MCP_FOR_I_LOG` = path to log file
+  - `MCP_FOR_I_LOG_LEVEL` = `error|warn|info|debug` (default `info`)
+  - `MCP_FOR_I_LOG_STDERR=1` to log to stderr (set `0` to disable)
+- CLI flags (when running `node dist/index.js` directly):
+  - `--log` (stderr, info level)
+  - `--log-level=debug`
+  - `--log-file=C:/path/to/log.txt`

package/docs/overview.md

@@ -0,0 +1,14 @@
+# MCP-for-i Overview
+
+MCP-for-i is a local MCP server that exposes IBM i operations as MCP tools. It mirrors the core capabilities of the Code for IBM i VS Code extension but is designed for agent-driven workflows (e.g., Codex CLI) over MCP stdio.
+
+Key capabilities (Phase 1):
+- Connect/disconnect to IBM i
+- Keep multiple sessions warm with inactivity timeout
+- Browse libraries/objects/members
+- Read/write members and IFS files
+- Run compile actions (RPG/COBOL/C/CL/SQL)
+- Search members and IFS
+- Run guarded SQL and CL tools
+
+The server runs locally and connects to IBM i via SSH + QSH/PASE + SQL (QZDFMDB2).

package/docs/security.md

@@ -0,0 +1,8 @@
+# Security
+
+- Credentials are stored in OS keychain via `keytar` (Windows Credential Manager, macOS Keychain, Linux libsecret).
+- If keychain is unavailable, credentials are stored in memory for the current session only.
+- Passwords are never written to the config file.
+- `readOnlyMode` prevents write operations on members/IFS.
+- Connection policies support `read-only`, `guarded`, and `power-user` modes.
+- Guarded mode requires `approve: true` for configured risky operations.

package/docs/tools.md

@@ -0,0 +1,105 @@
+# Tools
+
+## Connection
+- `ibmi.connect`
+- `ibmi.disconnect`
+- `ibmi.session.list`
+- `ibmi.session.status`
+- `ibmi.session.keepalive`
+- `ibmi.session.terminate`
+- `ibmi.connections.list`
+- `ibmi.connections.add`
+- `ibmi.connections.update`
+- `ibmi.connections.delete`
+
+## QSYS / Members
+- `ibmi.qsys.libraries.list`
+- `ibmi.qsys.objects.list`
+- `ibmi.qsys.sourcefiles.list`
+- `ibmi.qsys.members.list`
+- `ibmi.qsys.members.read`
+- `ibmi.qsys.members.write`
+- `ibmi.qsys.members.create`
+- `ibmi.qsys.members.rename`
+- `ibmi.qsys.members.delete`
+- `ibmi.qsys.sourcefiles.create`
+- `ibmi.qsys.libraries.create`
+
+## IFS
+- `ibmi.ifs.list`
+- `ibmi.ifs.read`
+- `ibmi.ifs.write`
+- `ibmi.ifs.mkdir`
+- `ibmi.ifs.delete`
+- `ibmi.ifs.upload`
+- `ibmi.ifs.download`
+
+## Search
+- `ibmi.search.members`
+- `ibmi.search.ifs`
+- `ibmi.find.ifs`
+
+## Actions
+- `ibmi.actions.list`
+- `ibmi.actions.run`
+- `ibmi.actions.save`
+- `ibmi.actions.delete`
+
+## Library List
+- `ibmi.libl.get`
+- `ibmi.libl.set`
+- `ibmi.libl.add`
+- `ibmi.libl.remove`
+- `ibmi.libl.setCurrent`
+- `ibmi.libl.validate`
+
+## Profiles
+- `ibmi.profiles.list`
+- `ibmi.profiles.save`
+- `ibmi.profiles.delete`
+- `ibmi.profiles.activate`
+
+## Resolve
+- `ibmi.resolve.path`
+
+## Deploy
+- `ibmi.deploy.uploadDirectory`
+- `ibmi.deploy.uploadFiles`
+- `ibmi.deploy.setCcsid`
+- `ibmi.deploy.compare`
+- `ibmi.deploy.sync`
+
+## Filters
+- `ibmi.filters.list`
+- `ibmi.filters.save`
+- `ibmi.filters.delete`
+
+## IFS Shortcuts
+- `ibmi.ifs.shortcuts.list`
+- `ibmi.ifs.shortcuts.add`
+- `ibmi.ifs.shortcuts.delete`
+
+## Debug
+- `ibmi.debug.status`
+- `ibmi.debug.startService`
+- `ibmi.debug.stopService`
+
+## SQL / CL
+- `ibmi.sql.query`
+- `ibmi.sql.execute`
+- `ibmi.cl.run`
+
+## Diagnostics / Ops
+- `ibmi.diagnostics.parseEvfevent`
+- `ibmi.joblog.get`
+- `ibmi.spool.list`
+- `ibmi.spool.read`
+
+## TN5250 (Scaffold)
+- `ibmi.tn5250.connect`
+- `ibmi.tn5250.readScreen`
+- `ibmi.tn5250.setField`
+- `ibmi.tn5250.sendKeys`
+- `ibmi.tn5250.waitFor`
+- `ibmi.tn5250.snapshot`
+- `ibmi.tn5250.disconnect`

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mcp-for-i",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Local MCP server and control plane for IBM i workflows",
+  "type": "module",
+  "homepage": "https://github.com/ashishthomas-pcr/mcp-for-i",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashishthomas-pcr/mcp-for-i.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ashishthomas-pcr/mcp-for-i/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "bin": {
+    "mcp-for-i": "dist/index.js",
+    "mcp-for-i-control": "dist/controlplane/index.js"
+  },
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "start:controlplane": "node dist/controlplane/index.js",
+    "dev": "ts-node src/index.ts",
+    "dev:controlplane": "ts-node src/controlplane/index.ts",
+    "test": "npm run build && node --test test/tools.test.mjs test/variables.test.mjs test/validation.test.mjs test/config.migration.test.mjs",
+    "test:all": "npm run build && node --test test/*.mjs",
+    "test:ibmi": "npm run build && node --test test/ibmi.integration.test.mjs",
+    "test:mcp": "npm run build && node --test test/mcp.integration.test.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "diff": "^5.2.0",
+    "keytar": "^7.9.0",
+    "node-ssh": "^13.1.0",
+    "zod-to-json-schema": "^3.23.2"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.2",
+    "dotenv": "^17.2.3",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.4.0"
+  }
+}