mcp-for-i 0.1.13 → 0.3.0

package/dist/ibmi/tn5250/telnet.js

@@ -0,0 +1,186 @@
+/**
+ * Telnet layer for TN5250 (RFC 854, RFC 1205, RFC 2877, RFC 4777).
+ *
+ * TelnetParser turns raw socket bytes into negotiation events and complete
+ * 5250 records (data between IAC EOR markers, with IAC IAC unescaped).
+ */
+export const IAC = 255;
+export const DONT = 254;
+export const DO = 253;
+export const WONT = 252;
+export const WILL = 251;
+export const SB = 250;
+export const SE = 240;
+export const EOR = 239;
+export const OPT_BINARY = 0;
+export const OPT_TERMINAL_TYPE = 24;
+export const OPT_EOR = 25;
+export const OPT_NEW_ENVIRON = 39;
+// Subnegotiation codes
+export const TT_IS = 0;
+export const TT_SEND = 1;
+export const ENV_IS = 0;
+export const ENV_SEND = 1;
+export const ENV_INFO = 2;
+export const ENV_VAR = 0;
+export const ENV_VALUE = 1;
+export const ENV_ESC = 2;
+export const ENV_USERVAR = 3;
+export class TelnetParser {
+    state = "data";
+    command = 0;
+    record = [];
+    sb = [];
+    /** Feed socket bytes; returns the events completed by this chunk. */
+    push(chunk) {
+        const events = [];
+        for (const byte of chunk) {
+            switch (this.state) {
+                case "data":
+                    if (byte === IAC)
+                        this.state = "iac";
+                    else
+                        this.record.push(byte);
+                    break;
+                case "iac":
+                    if (byte === IAC) {
+                        this.record.push(IAC);
+                        this.state = "data";
+                    }
+                    else if (byte === EOR) {
+                        events.push({ type: "record", data: Buffer.from(this.record) });
+                        this.record = [];
+                        this.state = "data";
+                    }
+                    else if (byte === DO || byte === DONT || byte === WILL || byte === WONT) {
+                        this.command = byte;
+                        this.state = "option";
+                    }
+                    else if (byte === SB) {
+                        this.sb = [];
+                        this.state = "sb";
+                    }
+                    else {
+                        // NOP, GA and other two-byte commands carry nothing we need.
+                        this.state = "data";
+                    }
+                    break;
+                case "option":
+                    events.push({ type: "command", command: this.command, option: byte });
+                    this.state = "data";
+                    break;
+                case "sb":
+                    if (byte === IAC)
+                        this.state = "sb-iac";
+                    else
+                        this.sb.push(byte);
+                    break;
+                case "sb-iac":
+                    if (byte === SE) {
+                        const [option, ...rest] = this.sb;
+                        events.push({ type: "subnegotiation", option: option ?? -1, data: Buffer.from(rest) });
+                        this.sb = [];
+                        this.state = "data";
+                    }
+                    else {
+                        // IAC IAC inside a subnegotiation is a literal 0xFF.
+                        this.sb.push(byte);
+                        this.state = "sb";
+                    }
+                    break;
+            }
+        }
+        return events;
+    }
+}
+export function telnetCommand(command, option) {
+    return Buffer.from([IAC, command, option]);
+}
+/** Wrap a 5250 record for sending: double IAC bytes and append IAC EOR. */
+export function frameRecord(record) {
+    const out = [];
+    for (const byte of record) {
+        out.push(byte);
+        if (byte === IAC)
+            out.push(IAC);
+    }
+    out.push(IAC, EOR);
+    return Buffer.from(out);
+}
+export function subnegotiation(option, payload) {
+    const out = [IAC, SB, option];
+    for (const byte of payload) {
+        out.push(byte);
+        if (byte === IAC)
+            out.push(IAC);
+    }
+    out.push(IAC, SE);
+    return Buffer.from(out);
+}
+export function terminalTypeIs(terminalType) {
+    return subnegotiation(OPT_TERMINAL_TYPE, Buffer.concat([Buffer.from([TT_IS]), Buffer.from(terminalType, "ascii")]));
+}
+/** Parse the body of a NEW-ENVIRON SEND (after the SEND byte). */
+export function parseEnvSend(data) {
+    const requested = [];
+    let serverSeed;
+    let i = 0;
+    while (i < data.length) {
+        const kindByte = data[i];
+        if (kindByte !== ENV_VAR && kindByte !== ENV_USERVAR) {
+            i += 1;
+            continue;
+        }
+        i += 1;
+        // RFC 4777: the server's seed follows the IBMRSEED name directly
+        // (optionally after VALUE) and is 8 raw bytes.
+        if (data.subarray(i, i + 8).toString("ascii") === "IBMRSEED") {
+            i += 8;
+            if (data[i] === ENV_VALUE)
+                i += 1;
+            const seed = data.subarray(i, Math.min(i + 8, data.length));
+            if (seed.length > 0)
+                serverSeed = Buffer.from(seed);
+            i += seed.length;
+            requested.push({ kind: kindByte === ENV_VAR ? "var" : "uservar", name: "IBMRSEED" });
+            continue;
+        }
+        const name = [];
+        let inValue = false;
+        while (i < data.length && data[i] !== ENV_VAR && data[i] !== ENV_USERVAR) {
+            if (data[i] === ENV_VALUE) {
+                inValue = true;
+                i += 1;
+                continue;
+            }
+            if (data[i] === ENV_ESC && i + 1 < data.length)
+                i += 1;
+            if (!inValue)
+                name.push(data[i]);
+            i += 1;
+        }
+        // An empty name means "send all variables of this kind".
+        requested.push({ kind: kindByte === ENV_VAR ? "var" : "uservar", name: Buffer.from(name).toString("ascii") });
+    }
+    return { requested, serverSeed };
+}
+function escapeEnv(bytes) {
+    const out = [];
+    for (const byte of bytes) {
+        if (byte === ENV_VAR || byte === ENV_VALUE || byte === ENV_ESC || byte === ENV_USERVAR)
+            out.push(ENV_ESC);
+        out.push(byte);
+    }
+    return out;
+}
+/** Build IAC SB NEW-ENVIRON IS ... IAC SE. */
+export function envIs(values) {
+    const out = [ENV_IS];
+    for (const entry of values) {
+        out.push(entry.kind === "var" ? ENV_VAR : ENV_USERVAR);
+        out.push(...escapeEnv(Buffer.from(entry.name, "ascii")));
+        out.push(ENV_VALUE);
+        out.push(...escapeEnv(entry.value));
+    }
+    return subnegotiation(OPT_NEW_ENVIRON, Buffer.from(out));
+}

package/dist/ibmi/variables.js

@@ -31,14 +31,25 @@ export class Variables extends Map {
             super.set(key, this.expand(value, [key]));
         }
     }
+    /**
+     * Replace every variable in one pass. Longer names are tried first and a
+     * name that ends in a letter or digit only matches when the next character
+     * is not part of a name, so `&EXT` never replaces the start of `&EXTL` and
+     * `&OPENLIB` never replaces the start of `&OPENLIBL`.
+     */
     expand(input, keysToOmit = []) {
-        for (const [key, value] of this.entries()) {
-            if (!keysToOmit.includes(key)) {
-                const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-                input = input.replace(new RegExp(escapedKey, `g`), value);
-            }
-        }
-        return input;
+        const keys = Array.from(this.keys())
+            .filter(key => key.length > 0 && !keysToOmit.includes(key))
+            .sort((a, b) => b.length - a.length);
+        if (keys.length === 0)
+            return input;
+        const pattern = keys
+            .map(key => {
+            const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            return /[A-Za-z0-9_#@$]$/.test(key) ? `${escaped}(?![A-Za-z0-9_#@$])` : escaped;
+        })
+            .join("|");
+        return input.replace(new RegExp(pattern, "g"), match => this.get(match) ?? match);
     }
     toPaseVariables() {
         const variables = {};

package/dist/index.js

@@ -4,13 +4,18 @@ import fs from "fs";
 import { fileURLToPath } from "url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { getTools, handleTool } from "./mcp/tools.js";
 import { McpContext } from "./mcp/context.js";
+import { createElicitationConfirm } from "./mcp/confirm.js";
 import { log } from "./mcp/logger.js";
+import { redactSecrets, redactSecretsInText } from "./security/redact.js";
 import { validateToolInput } from "./mcp/validation.js";
 import { appendAuditRecord } from "./mcp/audit.js";
+import { redactModuleArgs } from "./mcp/modules/index.js";
 import { runControlCommand } from "./controlplane/commands.js";
+import { ibmDocs } from "./ibmi/IbmDocs.js";
+import { MCP_APP_MIME_TYPE, TN5250_APP_TOOLS, TN5250_APP_URI, renderTn5250App } from "./mcp/modules/tn5250App.js";
 const argv = process.argv.slice(2);
 const firstArg = (argv[0] || "").toLowerCase();
 const packageVersion = readPackageVersion();
@@ -29,17 +34,64 @@ if (firstArg === "--help" || firstArg === "-h" || firstArg === "help") {
     printHelp();
     process.exit(0);
 }
-const server = new Server({ name: "mcp-for-i", version: packageVersion }, { capabilities: { tools: {} } });
+const server = new Server({ name: "mcp-for-i", version: packageVersion }, { capabilities: { tools: {}, resources: {} } });
 const ctx = new McpContext();
-const tools = getTools();
+ctx.confirm = createElicitationConfirm(server);
+// 5250 tools point MCP Apps clients at the screen view; other clients ignore _meta.
+const tools = getTools().map(tool => (TN5250_APP_TOOLS.has(tool.name)
+    ? { ...tool, _meta: { ...(tool._meta || {}), ui: { resourceUri: TN5250_APP_URI } } }
+    : tool));
 const toolMap = new Map(tools.map(tool => [tool.name, tool]));
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools
 }));
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+        {
+            uri: "ibmi-docs://catalog",
+            name: "IBM i documentation catalog",
+            description: "Release-aware allowlist of official IBM i documentation available through mcp-for-i.",
+            mimeType: "application/json"
+        },
+        {
+            uri: TN5250_APP_URI,
+            name: "5250 screen view",
+            description: "Interactive 5250 screen for MCP Apps clients (used by the ibmi.tn5250 tools).",
+            mimeType: MCP_APP_MIME_TYPE
+        },
+        ...ibmDocs.listResources()
+    ]
+}));
+server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: [{
+            uriTemplate: "ibmi-docs://topic/{ref}",
+            name: "Official IBM i documentation topic",
+            description: "Open a versioned official IBM i documentation topic using a ref from ibmi.docs.search.",
+            mimeType: "text/markdown"
+        }]
+}));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    if (uri === TN5250_APP_URI) {
+        return {
+            contents: [{ uri, mimeType: MCP_APP_MIME_TYPE, text: renderTn5250App(packageVersion), _meta: { ui: { prefersBorder: false } } }]
+        };
+    }
+    const text = await ibmDocs.readResource(uri);
+    return {
+        contents: [{
+                uri,
+                mimeType: uri === "ibmi-docs://catalog" ? "application/json" : "text/markdown",
+                text
+            }]
+    };
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const correlationId = crypto.randomUUID();
     const startedAt = Date.now();
+    // Computed before the call: module redaction depends on the state the call starts from.
+    let redactedArgs;
     try {
         const toolDef = toolMap.get(name);
         if (!toolDef)
@@ -48,7 +100,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (errors.length > 0) {
             throw new Error(`Invalid arguments: ${errors.join("; ")}`);
         }
-        const redactedArgs = redactSensitive(args || {});
+        redactedArgs = redactSensitive(redactModuleArgs(ctx, name, args || {}));
         log("info", "tool.call", { name, correlationId, args: redactedArgs });
         const result = await handleTool(ctx, name, args || {});
         const durationMs = Date.now() - startedAt;
@@ -72,12 +124,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         await safeAppendAudit({
             tool: name,
             status: "error",
-            args: redactSensitive(args || {}),
+            args: redactedArgs ?? redactSensitive(redactModuleArgs(ctx, name, args || {})),
             connectionName: resolveConnectionName(name, args || {}, ctx.activeName),
             approve: Boolean(args && typeof args === "object" && args.approve),
             durationMs,
             correlationId,
-            error: errorMessage
+            error: redactSecretsInText(errorMessage)
         });
         return {
             isError: true,
@@ -88,30 +140,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 function redactSensitive(input) {
-    const secrets = new Set(["password", "passphrase", "secret", "token", "apikey", "apiKey", "authorization"]);
-    if (Array.isArray(input)) {
-        return input.map(redactSensitive);
-    }
-    if (typeof input === "object" && input !== null) {
-        const out = {};
-        for (const [key, value] of Object.entries(input)) {
-            if (secrets.has(key)) {
-                out[key] = "***REDACTED***";
-            }
-            else {
-                out[key] = redactSensitive(value);
-            }
-        }
-        return out;
-    }
-    return input;
+    return redactSecrets(input);
 }
 function summarizeResult(result) {
     const contentCount = Array.isArray(result?.content) ? result.content.length : 0;
     return {
         isError: Boolean(result?.isError),
         contentCount,
-        hasStructuredContent: typeof result?.structuredContent !== "undefined"
+        hasStructuredContent: typeof result?.structuredContent !== "undefined",
+        ...summarizeScreen(result?.structuredContent)
+    };
+}
+/** For 5250 results: the screen's first text line and state, so the audit shows where a session went. */
+function summarizeScreen(structured) {
+    const content = structured?.data ?? structured;
+    const screen = content && Array.isArray(content.text) ? content : content?.screen;
+    if (!screen || !Array.isArray(screen.text) || typeof screen.version !== "number")
+        return {};
+    const title = String(screen.text.find((line) => typeof line === "string" && line.trim()) || "").trim().substring(0, 80);
+    return {
+        screen: {
+            title: redactSecretsInText(title),
+            keyboardLocked: Boolean(screen.keyboardLocked),
+            ...(screen.errorLine ? { errorLine: redactSecretsInText(String(screen.errorLine).substring(0, 80)) } : {}),
+            ...(typeof content.sent === "string" ? { sent: content.sent } : {})
+        }
     };
 }
 function resolveConnectionName(tool, args, activeName) {
@@ -136,6 +189,8 @@ function printHelp() {
     process.stderr.write(`  mcp-for-i                 Start MCP stdio server\n`);
     process.stderr.write(`  mcp-for-i control         Start/open control plane UI\n`);
     process.stderr.write(`  mcp-for-i control status  Show control plane and background-service status\n`);
+    process.stderr.write(`  mcp-for-i control stop    Stop the running control plane\n`);
+    process.stderr.write(`  mcp-for-i control restart Stop the control plane and start it again\n`);
     process.stderr.write(`  mcp-for-i control enable  Enable background service for this platform\n`);
     process.stderr.write(`  mcp-for-i control disable Disable background service for this platform\n`);
     process.stderr.write(`  mcp-for-i --version       Print package version\n`);

package/dist/mcp/annotations.js

@@ -0,0 +1,155 @@
+// Tools that only read from the IBM i, the local config or the audit log.
+const READ_ONLY = new Set([
+    "ibmi.session.list",
+    "ibmi.session.status",
+    "ibmi.session.keepalive",
+    "ibmi.session.bootstrap",
+    "ibmi.connections.list",
+    "ibmi.qsys.libraries.list",
+    "ibmi.qsys.objects.list",
+    "ibmi.qsys.sourcefiles.list",
+    "ibmi.qsys.members.list",
+    "ibmi.qsys.members.read",
+    "ibmi.ifs.list",
+    "ibmi.ifs.read",
+    "ibmi.search.members",
+    "ibmi.source.resolve",
+    "ibmi.source.inspect",
+    "ibmi.search.ifs",
+    "ibmi.find.ifs",
+    "ibmi.actions.list",
+    "ibmi.libl.get",
+    "ibmi.libl.validate",
+    "ibmi.profiles.list",
+    "ibmi.resolve.path",
+    "ibmi.filters.list",
+    "ibmi.ifs.shortcuts.list",
+    "ibmi.debug.status",
+    "ibmi.deploy.compare",
+    "ibmi.sql.query",
+    "ibmi.diagnostics.parseEvfevent",
+    "ibmi.joblog.get",
+    "ibmi.spool.list",
+    "ibmi.spool.read",
+    "ibmi.jobs.list",
+    "ibmi.subsystems.list",
+    "ibmi.subsystems.status",
+    "ibmi.msgq.read",
+    "ibmi.locks.list",
+    "ibmi.authority.object.get",
+    "ibmi.dataarea.read",
+    "ibmi.audit.list",
+    "ibmi.audit.verify",
+    "ibmi.journal.objects.list",
+    "ibmi.journal.entries.query",
+    "ibmi.qaudjrn.events.query",
+    "ibmi.tn5250.readScreen",
+    "ibmi.tn5250.waitFor",
+    "ibmi.tn5250.snapshot"
+]);
+// Read-only tools that reach outside the IBM i and the local machine.
+const OPEN_WORLD = new Set(["ibmi.docs.search", "ibmi.docs.open"]);
+// Tools that can delete or overwrite data, end work, or run arbitrary commands.
+const DESTRUCTIVE = new Set([
+    "ibmi.connections.delete",
+    "ibmi.qsys.members.write",
+    "ibmi.qsys.members.delete",
+    "ibmi.qsys.members.rename",
+    "ibmi.ifs.write",
+    "ibmi.ifs.delete",
+    "ibmi.ifs.upload",
+    "ibmi.ifs.download",
+    "ibmi.actions.run",
+    "ibmi.actions.delete",
+    "ibmi.profiles.delete",
+    "ibmi.filters.delete",
+    "ibmi.ifs.shortcuts.delete",
+    "ibmi.deploy.uploadDirectory",
+    "ibmi.deploy.uploadFiles",
+    "ibmi.deploy.sync",
+    "ibmi.sql.execute",
+    "ibmi.cl.run",
+    "ibmi.spool.delete",
+    "ibmi.jobs.end",
+    "ibmi.subsystems.end",
+    "ibmi.dataqueue.receive",
+    "ibmi.dataarea.write",
+    "ibmi.audit.export",
+    "ibmi.audit.purge",
+    "ibmi.journal.endPf",
+    "ibmi.journal.endIfs",
+    "ibmi.journal.receivers.retention",
+    "ibmi.compliance.report.generate",
+    "ibmi.tn5250.sendKeys"
+]);
+// Writes that leave the same end state when repeated with the same arguments.
+const IDEMPOTENT_WRITES = new Set([
+    "ibmi.connect",
+    "ibmi.disconnect",
+    "ibmi.session.terminate",
+    "ibmi.connections.update",
+    "ibmi.qsys.members.write",
+    "ibmi.ifs.write",
+    "ibmi.ifs.mkdir",
+    "ibmi.ifs.upload",
+    "ibmi.ifs.download",
+    "ibmi.libl.set",
+    "ibmi.libl.setCurrent",
+    "ibmi.profiles.save",
+    "ibmi.profiles.activate",
+    "ibmi.actions.save",
+    "ibmi.filters.save",
+    "ibmi.deploy.setCcsid",
+    "ibmi.spool.hold",
+    "ibmi.spool.release",
+    "ibmi.jobs.hold",
+    "ibmi.jobs.release",
+    "ibmi.dataarea.write",
+    "ibmi.audit.export",
+    "ibmi.tn5250.connect",
+    "ibmi.tn5250.setField",
+    "ibmi.tn5250.disconnect"
+]);
+export function annotationsFor(name) {
+    if (READ_ONLY.has(name)) {
+        return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+    }
+    if (OPEN_WORLD.has(name)) {
+        return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+    }
+    // Anything not listed is treated as a write; unknown tools default to destructive.
+    return {
+        readOnlyHint: false,
+        destructiveHint: DESTRUCTIVE.has(name) || !IDEMPOTENT_WRITES.has(name) && !isKnownNonDestructiveWrite(name),
+        idempotentHint: IDEMPOTENT_WRITES.has(name),
+        openWorldHint: false
+    };
+}
+function isKnownNonDestructiveWrite(name) {
+    return [
+        "ibmi.connections.add",
+        "ibmi.qsys.members.create",
+        "ibmi.qsys.sourcefiles.create",
+        "ibmi.qsys.libraries.create",
+        "ibmi.libl.add",
+        "ibmi.libl.remove",
+        "ibmi.ifs.shortcuts.add",
+        "ibmi.debug.startService",
+        "ibmi.debug.stopService",
+        "ibmi.spool.move",
+        "ibmi.subsystems.start",
+        "ibmi.msgq.send",
+        "ibmi.msgq.reply",
+        "ibmi.dataqueue.send",
+        "ibmi.journal.receiver.create",
+        "ibmi.journal.create",
+        "ibmi.journal.receiver.change",
+        "ibmi.journal.startPf",
+        "ibmi.journal.startIfs"
+    ].includes(name);
+}
+export function withAnnotations(tool) {
+    if (tool.annotations)
+        return tool;
+    return { ...tool, annotations: annotationsFor(tool.name) };
+}