mcp-for-i 0.2.0 → 0.3.0

package/docs/capabilities.md

@@ -1,263 +1,264 @@
-# MCP-for-i Capabilities (Current)
-
-This document summarizes what `mcp-for-i` can do today across the MCP server and local control-plane workflow.
-
-Version context: `0.2.0`.
-
-## 1) Platform Capabilities
-
-### 1.1 Secure Onboarding and Connection Management
-- Local control plane for adding/updating/deleting saved IBM i connections.
-- Credential handling via OS keychain flow (no plaintext password arguments in MCP connection tools).
-- Connection policies per profile (`read-only`, `guarded`, `power-user`).
-- Connection profiles for per-user/per-context library and variable settings.
-
-### 1.2 Runtime Safety and Policy Guardrails
-- Strict tool input schemas (`additionalProperties: false`) with runtime validation.
-- Guarded approval model: the user confirms sensitive operations in the MCP client.
-- Read-only mode enforcement.
-- Validation for critical identifiers (QSYS names, journaling object names, etc.).
-
-### 1.3 Session Lifecycle
-- Multi-session tracking.
-- Session status/list/keepalive/terminate operations.
-- One-call session bootstrap with release, library-list, policy, transports, and supported fast-path capabilities.
-- Sliding inactivity timeout.
-- Heartbeat and reconnect behavior.
-- Persistent SQL job per connection (Mapepire, when installed on the IBM i): SQL, SQL-run CL, library list changes and the job log share one job across calls; falls back to a new QZDFMDB2 job per call when Mapepire is not available. Timed-out statements are cancelled on the IBM i. See [configuration](configuration.md#persistent-sql-job-mapepire) for `sqlTransport` and how to install Mapepire.
-
-### 1.4 Agent-Safe Structured Results
-- Tool responses expose structured payloads for automation.
-- SQL/CL/diagnostic outputs normalized where applicable.
-- TN5250 screens are returned as text rows plus machine-readable fields (position, label, protected/hidden flags); hidden field contents are never returned.
-
-### 1.5 Auditing and Compliance Foundations
-- Tamper-evident hash-chain audit record for tool calls.
-- Audit verification, export, and retention purge controls.
-- Compliance report generation with optional signed evidence bundle.
-
-### 1.6 IBM i Operations Control (Phase 7)
-- Spool lifecycle controls (hold/release/delete/move by job/file/number).
-- Job lifecycle controls (list/hold/release/end).
-- Subsystem lifecycle controls (list/status/start/end).
-- Message queue operations (read/send/reply).
-- Preflight operational visibility (lock contention + object authority lookup).
-- Data queue and data area operations for integration and runbook workflows.
-
-## 2) Complete MCP Tool Catalog
-
-### Connection and Session
-- `ibmi.connect`
-- `ibmi.disconnect`
-- `ibmi.session.list`
-- `ibmi.session.status`
-- `ibmi.session.keepalive`
-- `ibmi.session.terminate`
-- `ibmi.session.bootstrap`
-- `ibmi.connections.list`
-- `ibmi.connections.add`
-- `ibmi.connections.update`
-- `ibmi.connections.delete`
-
-### QSYS and Source Management
-- `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.members.copy`
-- `ibmi.qsys.members.changeText`
-- `ibmi.qsys.members.changeType`
-- `ibmi.qsys.sourcefiles.create`
-- `ibmi.qsys.libraries.create`
-- `ibmi.objects.copy`, `ibmi.objects.move`, `ibmi.objects.rename`, `ibmi.objects.delete`, `ibmi.objects.changeDescription`
-- `ibmi.libraries.copy`
-- Legacy-compatible member list/read responses plus opt-in filtered paging, ranged reads, metadata, version/hash checks, caching, and complete fallback reads.
-
-### IFS Operations
-- `ibmi.ifs.list`
-- `ibmi.ifs.read`
-- `ibmi.ifs.write`
-- `ibmi.ifs.mkdir`
-- `ibmi.ifs.delete`
-- `ibmi.ifs.copy`
-- `ibmi.ifs.move`
-- `ibmi.ifs.upload`
-- `ibmi.ifs.download`
-
-### Search and Resolution
-- `ibmi.search.members`
-- `ibmi.source.resolve`
-- `ibmi.source.inspect`
-- `ibmi.search.ifs`
-- `ibmi.find.ifs`
-- `ibmi.search.changedLines`
-- `ibmi.resolve.path`
-
-### System Information
-- `ibmi.system.info`
-
-### Official IBM i Documentation
-- `ibmi.docs.search`
-- `ibmi.docs.open` (any `https://www.ibm.com/docs/` page)
-- MCP resources at `ibmi-docs://catalog` and `ibmi-docs://topic/{ref}`
-
-### Actions, Filters, Profiles, Library List
-- `ibmi.actions.list`
-- `ibmi.actions.run` (compiles members or streamfiles and returns EVFEVENT errors by file; see docs/tools.md "Compile and errors")
-- `ibmi.actions.save`
-- `ibmi.actions.delete`
-- `ibmi.filters.list`
-- `ibmi.filters.save`
-- `ibmi.filters.delete`
-- `ibmi.profiles.list`
-- `ibmi.profiles.save`
-- `ibmi.profiles.delete`
-- `ibmi.profiles.activate`
-- `ibmi.libl.get`
-- `ibmi.libl.set`
-- `ibmi.libl.add`
-- `ibmi.libl.remove`
-- `ibmi.libl.setCurrent`
-- `ibmi.libl.validate`
-- `ibmi.libl.move`
-- `ibmi.libl.prune`
-- `ibmi.libl.runProfileCommand`
-- `ibmi.ifs.shortcuts.list`
-- `ibmi.ifs.shortcuts.add`
-- `ibmi.ifs.shortcuts.delete`
-
-### Compare and Inspection
-- `ibmi.compare.text`
-- `ibmi.objects.describe`
-- `ibmi.members.describe`
-- `ibmi.ifs.stat`
-- `ibmi.programs.info`
-- `ibmi.objects.whereUsed`
-- `ibmi.tables.describe`
-- `ibmi.routines.describe`
-
-### Deploy and File Sync
-- `ibmi.deploy.compare`
-- `ibmi.deploy.sync`
-- `ibmi.deploy.uploadDirectory`
-- `ibmi.deploy.uploadFiles`
-- `ibmi.deploy.setCcsid`
-- `ibmi.deploy.sync` methods: `all`, `changed` (SHA-256), `gitChanged`, `selection`
-
-### Bulk Source Members
-- `ibmi.members.downloadAll`
-- `ibmi.members.uploadChanged`
-
-### SQL, CL, Diagnostics, Spool, Debug
-- `ibmi.sql.query`
-- `ibmi.sql.execute`
-- `ibmi.cl.run`
-- `ibmi.diagnostics.parseEvfevent`
-- `ibmi.compile.listing`
-- `ibmi.joblog.get`
-- `ibmi.spool.list`
-- `ibmi.spool.read`
-- `ibmi.spool.hold`
-- `ibmi.spool.release`
-- `ibmi.spool.delete`
-- `ibmi.spool.move`
-- `ibmi.jobs.list`
-- `ibmi.jobs.hold`
-- `ibmi.jobs.release`
-- `ibmi.jobs.end`
-- `ibmi.subsystems.list`
-- `ibmi.subsystems.status`
-- `ibmi.subsystems.start`
-- `ibmi.subsystems.end`
-- `ibmi.msgq.read`
-- `ibmi.msgq.send`
-- `ibmi.msgq.reply`
-- `ibmi.locks.list`
-- `ibmi.authority.object.get`
-- `ibmi.dataqueue.send`
-- `ibmi.dataqueue.receive`
-- `ibmi.dataarea.read`
-- `ibmi.dataarea.write`
-- `ibmi.debug.status`
-- `ibmi.debug.startService`
-- `ibmi.debug.stopService`
-
-### Audit and Compliance
-- `ibmi.audit.list`
-- `ibmi.audit.verify`
-- `ibmi.audit.export`
-- `ibmi.audit.purge`
-- `ibmi.compliance.report.generate`
-
-### Journaling
-- `ibmi.journal.objects.list`
-- `ibmi.journal.entries.query`
-- `ibmi.qaudjrn.events.query`
-- `ibmi.journal.receiver.create`
-- `ibmi.journal.create`
-- `ibmi.journal.receiver.change`
-- `ibmi.journal.startPf`
-- `ibmi.journal.endPf`
-- `ibmi.journal.startIfs`
-- `ibmi.journal.endIfs`
-- `ibmi.journal.receivers.retention`
-
-### TN5250 (5250 green-screen sessions)
-A real TN5250 client: connects to the saved connection's host on port 23 (or 992 with TLS), reads the actual screen and fields, fills fields and presses keys (Enter, F1-F24, PageUp/PageDown, Clear, Help, Attn, SysReq). Optional sign-on uses the stored credentials. AID keys go through the write gate: read-only connections cannot press them, and text on a `===>` command line is checked against the command policy. See [tools](tools.md#tn5250-notes) for details and limits.
-
-- `ibmi.tn5250.connect`
-- `ibmi.tn5250.readScreen`
-- `ibmi.tn5250.setField`
-- `ibmi.tn5250.sendKeys`
-- `ibmi.tn5250.waitFor`
-- `ibmi.tn5250.snapshot`
-- `ibmi.tn5250.disconnect`
-
-## 3) High-Value Behaviors Users Often Miss
-
-### 3.1 Guarded Approvals
-- In guarded policy, risky operations wait for the user to confirm them in the MCP client; the agent cannot approve them itself.
-- With `approvalMode: "agent"` (for clients without prompts), `approve=true` from the agent is accepted instead.
-
-### 3.2 Audit Data Lifecycle
-- Verify chain integrity with `ibmi.audit.verify`.
-- Export evidence using `ibmi.audit.export` (`jsonl`, `json`, `csv`).
-- Use `ibmi.audit.purge` for retention cleanup (`dryRun` supported).
-
-### 3.3 Journaling and QAUDJRN
-- PF and IFS journaling lifecycle operations are supported.
-- `ibmi.journal.entries.query` supports advanced filters (`journalCode`, `entryType`, `userName`, `jobName`, `programName`).
-- `ibmi.qaudjrn.events.query` provides normalized QAUDJRN security/compliance event access.
-
-### 3.4 Compliance Report Bundles
-- `ibmi.compliance.report.generate` can return in-memory report payload or write to `outputPath`.
-- Optional signing creates:
-  - `<outputPath>.sig`
-  - `<outputPath>.sha256`
-
-## 4) Useful Local Paths and Env Knobs
-
-### 4.1 Config and Audit Storage
-- Config base directory: from local MCP-for-i config store (`~/.mcp-for-i` on typical setups).
-- Default audit log path:
-  - `<configDir>/audit/tool-audit.jsonl`
-
-### 4.2 Audit Environment Variables
-- `MCP_FOR_I_AUDIT_ENABLED=0` disables audit append.
-- `MCP_FOR_I_AUDIT_LOG_PATH=<path>` overrides default audit file location.
-
-### 4.3 Logging Environment Variables
-- `MCP_FOR_I_LOG_ENABLED`
-- `MCP_FOR_I_LOG_LEVEL`
-- `MCP_FOR_I_LOG`
-- `MCP_FOR_I_LOG_STDERR`
-
-## 5) Current Scope Boundary
-
-Implemented through Phase 7.  
-Next roadmap items begin at Phase 8 (reliability/recovery/change assurance), then autonomy/distribution phases.
+# MCP-for-i Capabilities (Current)
+
+This document summarizes what `mcp-for-i` can do today across the MCP server and local control-plane workflow.
+
+Version context: `0.2.0`.
+
+## 1) Platform Capabilities
+
+### 1.1 Secure Onboarding and Connection Management
+- Local control plane for adding/updating/deleting saved IBM i connections.
+- Credential handling via OS keychain flow (no plaintext password arguments in MCP connection tools).
+- Connection policies per profile (`read-only`, `guarded`, `power-user`).
+- Connection profiles for per-user/per-context library and variable settings.
+
+### 1.2 Runtime Safety and Policy Guardrails
+- Strict tool input schemas (`additionalProperties: false`) with runtime validation.
+- Guarded approval model: the user confirms sensitive operations in the MCP client.
+- Read-only mode enforcement.
+- Validation for critical identifiers (QSYS names, journaling object names, etc.).
+
+### 1.3 Session Lifecycle
+- Multi-session tracking.
+- Session status/list/keepalive/terminate operations.
+- One-call session bootstrap with release, library-list, policy, transports, and supported fast-path capabilities.
+- Sliding inactivity timeout.
+- Heartbeat and reconnect behavior.
+- Persistent SQL job per connection (Mapepire, when installed on the IBM i): SQL, SQL-run CL, library list changes and the job log share one job across calls; falls back to a new QZDFMDB2 job per call when Mapepire is not available. Timed-out statements are cancelled on the IBM i. See [configuration](configuration.md#persistent-sql-job-mapepire) for `sqlTransport` and how to install Mapepire.
+
+### 1.4 Agent-Safe Structured Results
+- Tool responses expose structured payloads for automation.
+- SQL/CL/diagnostic outputs normalized where applicable.
+- TN5250 screens are returned as text rows plus machine-readable fields (position, label, protected/hidden flags); hidden field contents are never returned.
+
+### 1.5 Auditing and Compliance Foundations
+- Tamper-evident hash-chain audit record for tool calls.
+- Audit verification, export, and retention purge controls.
+- Compliance report generation with optional signed evidence bundle.
+
+### 1.6 IBM i Operations Control (Phase 7)
+- Spool lifecycle controls (hold/release/delete/move by job/file/number).
+- Job lifecycle controls (list/hold/release/end).
+- Subsystem lifecycle controls (list/status/start/end).
+- Message queue operations (read/send/reply).
+- Preflight operational visibility (lock contention + object authority lookup).
+- Data queue and data area operations for integration and runbook workflows.
+
+## 2) Complete MCP Tool Catalog
+
+### Connection and Session
+- `ibmi.connect`
+- `ibmi.disconnect`
+- `ibmi.session.list`
+- `ibmi.session.status`
+- `ibmi.session.keepalive`
+- `ibmi.session.terminate`
+- `ibmi.session.bootstrap`
+- `ibmi.connections.list`
+- `ibmi.connections.add`
+- `ibmi.connections.update`
+- `ibmi.connections.delete`
+
+### QSYS and Source Management
+- `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.members.copy`
+- `ibmi.qsys.members.changeText`
+- `ibmi.qsys.members.changeType`
+- `ibmi.qsys.sourcefiles.create`
+- `ibmi.qsys.libraries.create`
+- `ibmi.objects.copy`, `ibmi.objects.move`, `ibmi.objects.rename`, `ibmi.objects.delete`, `ibmi.objects.changeDescription`
+- `ibmi.libraries.copy`
+- Legacy-compatible member list/read responses plus opt-in filtered paging, ranged reads, metadata, version/hash checks, caching, and complete fallback reads.
+
+### IFS Operations
+- `ibmi.ifs.list`
+- `ibmi.ifs.read`
+- `ibmi.ifs.write`
+- `ibmi.ifs.mkdir`
+- `ibmi.ifs.delete`
+- `ibmi.ifs.copy`
+- `ibmi.ifs.move`
+- `ibmi.ifs.upload`
+- `ibmi.ifs.download`
+
+### Search and Resolution
+- `ibmi.search.members`
+- `ibmi.source.resolve`
+- `ibmi.source.inspect`
+- `ibmi.search.ifs`
+- `ibmi.find.ifs`
+- `ibmi.search.changedLines`
+- `ibmi.resolve.path`
+
+### System Information
+- `ibmi.system.info`
+
+### Official IBM i Documentation
+- `ibmi.docs.search`
+- `ibmi.docs.open` (any `https://www.ibm.com/docs/` page)
+- MCP resources at `ibmi-docs://catalog` and `ibmi-docs://topic/{ref}`
+
+### Actions, Filters, Profiles, Library List
+- `ibmi.actions.list`
+- `ibmi.actions.run` (compiles members or streamfiles and returns EVFEVENT errors by file; see docs/tools.md "Compile and errors")
+- `ibmi.actions.save`
+- `ibmi.actions.delete`
+- `ibmi.filters.list`
+- `ibmi.filters.save`
+- `ibmi.filters.delete`
+- `ibmi.profiles.list`
+- `ibmi.profiles.save`
+- `ibmi.profiles.delete`
+- `ibmi.profiles.activate`
+- `ibmi.libl.get`
+- `ibmi.libl.set`
+- `ibmi.libl.add`
+- `ibmi.libl.remove`
+- `ibmi.libl.setCurrent`
+- `ibmi.libl.validate`
+- `ibmi.libl.move`
+- `ibmi.libl.prune`
+- `ibmi.libl.runProfileCommand`
+- `ibmi.ifs.shortcuts.list`
+- `ibmi.ifs.shortcuts.add`
+- `ibmi.ifs.shortcuts.delete`
+
+### Compare and Inspection
+- `ibmi.compare.text`
+- `ibmi.objects.describe`
+- `ibmi.members.describe`
+- `ibmi.ifs.stat`
+- `ibmi.programs.info`
+- `ibmi.objects.whereUsed`
+- `ibmi.tables.describe`
+- `ibmi.routines.describe`
+
+### Deploy and File Sync
+- `ibmi.deploy.compare`
+- `ibmi.deploy.sync`
+- `ibmi.deploy.uploadDirectory`
+- `ibmi.deploy.uploadFiles`
+- `ibmi.deploy.setCcsid`
+- `ibmi.deploy.sync` methods: `all`, `changed` (SHA-256), `gitChanged`, `selection`
+
+### Bulk Source Members
+- `ibmi.members.downloadAll`
+- `ibmi.members.uploadChanged`
+
+### SQL, CL, Diagnostics, Spool, Debug
+- `ibmi.sql.query`
+- `ibmi.sql.execute`
+- `ibmi.cl.run`
+- `ibmi.diagnostics.parseEvfevent`
+- `ibmi.compile.listing`
+- `ibmi.joblog.get`
+- `ibmi.spool.list`
+- `ibmi.spool.read`
+- `ibmi.spool.hold`
+- `ibmi.spool.release`
+- `ibmi.spool.delete`
+- `ibmi.spool.move`
+- `ibmi.jobs.list`
+- `ibmi.jobs.hold`
+- `ibmi.jobs.release`
+- `ibmi.jobs.end`
+- `ibmi.subsystems.list`
+- `ibmi.subsystems.status`
+- `ibmi.subsystems.start`
+- `ibmi.subsystems.end`
+- `ibmi.msgq.read`
+- `ibmi.msgq.send`
+- `ibmi.msgq.reply`
+- `ibmi.locks.list`
+- `ibmi.authority.object.get`
+- `ibmi.dataqueue.send`
+- `ibmi.dataqueue.receive`
+- `ibmi.dataarea.read`
+- `ibmi.dataarea.write`
+- `ibmi.debug.status`
+- `ibmi.debug.startService`
+- `ibmi.debug.stopService`
+
+### Audit and Compliance
+- `ibmi.audit.list`
+- `ibmi.audit.verify`
+- `ibmi.audit.export`
+- `ibmi.audit.purge`
+- `ibmi.compliance.report.generate`
+
+### Journaling
+- `ibmi.journal.objects.list`
+- `ibmi.journal.entries.query`
+- `ibmi.qaudjrn.events.query`
+- `ibmi.journal.receiver.create`
+- `ibmi.journal.create`
+- `ibmi.journal.receiver.change`
+- `ibmi.journal.startPf`
+- `ibmi.journal.endPf`
+- `ibmi.journal.startIfs`
+- `ibmi.journal.endIfs`
+- `ibmi.journal.receivers.retention`
+
+### TN5250 (5250 green-screen sessions)
+A real TN5250 client: connects to the saved connection's host on port 23 (or 992 with TLS), reads the actual screen and fields, fills fields and presses keys (Enter, F1-F24, PageUp/PageDown, Clear, Help, Attn/Esc, SysReq/Shift+Esc, plus local keys such as Field+/-, Dup, Insert and the arrows) and clicks like an emulator mouse. Supports 21 single-byte code pages. A live view on localhost (and an in-chat screen in MCP Apps clients) shows the session the agent drives, and the person can type and click in it at the same time. Optional sign-on uses the stored credentials. AID keys go through the write gate: read-only connections cannot press them, and text on a `===>` command line is checked against the command policy. See [tools](tools.md#tn5250-notes) for details and limits.
+
+- `ibmi.tn5250.connect`
+- `ibmi.tn5250.readScreen`
+- `ibmi.tn5250.setField`
+- `ibmi.tn5250.sendKeys`
+- `ibmi.tn5250.click`
+- `ibmi.tn5250.waitFor`
+- `ibmi.tn5250.snapshot`
+- `ibmi.tn5250.disconnect`
+
+## 3) High-Value Behaviors Users Often Miss
+
+### 3.1 Guarded Approvals
+- In guarded policy, risky operations wait for the user to confirm them in the MCP client; the agent cannot approve them itself.
+- With `approvalMode: "agent"` (for clients without prompts), `approve=true` from the agent is accepted instead.
+
+### 3.2 Audit Data Lifecycle
+- Verify chain integrity with `ibmi.audit.verify`.
+- Export evidence using `ibmi.audit.export` (`jsonl`, `json`, `csv`).
+- Use `ibmi.audit.purge` for retention cleanup (`dryRun` supported).
+
+### 3.3 Journaling and QAUDJRN
+- PF and IFS journaling lifecycle operations are supported.
+- `ibmi.journal.entries.query` supports advanced filters (`journalCode`, `entryType`, `userName`, `jobName`, `programName`).
+- `ibmi.qaudjrn.events.query` provides normalized QAUDJRN security/compliance event access.
+
+### 3.4 Compliance Report Bundles
+- `ibmi.compliance.report.generate` can return in-memory report payload or write to `outputPath`.
+- Optional signing creates:
+  - `<outputPath>.sig`
+  - `<outputPath>.sha256`
+
+## 4) Useful Local Paths and Env Knobs
+
+### 4.1 Config and Audit Storage
+- Config base directory: from local MCP-for-i config store (`~/.mcp-for-i` on typical setups).
+- Default audit log path:
+  - `<configDir>/audit/tool-audit.jsonl`
+
+### 4.2 Audit Environment Variables
+- `MCP_FOR_I_AUDIT_ENABLED=0` disables audit append.
+- `MCP_FOR_I_AUDIT_LOG_PATH=<path>` overrides default audit file location.
+
+### 4.3 Logging Environment Variables
+- `MCP_FOR_I_LOG_ENABLED`
+- `MCP_FOR_I_LOG_LEVEL`
+- `MCP_FOR_I_LOG`
+- `MCP_FOR_I_LOG_STDERR`
+
+## 5) Current Scope Boundary
+
+Implemented through Phase 7.  
+Next roadmap items begin at Phase 8 (reliability/recovery/change assurance), then autonomy/distribution phases.

package/docs/configuration.md

@@ -34,6 +34,10 @@ Default settings (editable in the config file):
 - `tn5250Port`: number. TN5250 telnet port (default 23, or 992 when `tn5250Tls` is true).
 - `tn5250Tls`: boolean. Use TLS for TN5250 (default true when the port is 992).
 - `tn5250DeviceName`: string. Virtual device name requested for TN5250 sessions (1-10 characters).
+- `tn5250LiveView`: boolean. Serve the live 5250 view on localhost while a session is open (default true).
+- `tn5250LiveViewPort`: number. Preferred port for the live 5250 view (default 3981; the next free port when taken, 0 for any).
+- `tn5250AttnWaitMs`: number. How long Attn/SysReq wait for the host before unlocking the keyboard, in milliseconds (default 2000, range 250-15000).
+- `tn5250Ccsid`: number. Single-byte EBCDIC code page for TN5250 screen text (default 37; also 273, 277, 278, 280, 284, 285, 297, 500, 871, 1047, 1140-1149).
 
 `tempLibrary` remains accepted for configuration compatibility. Source member reads and source-date writes now use job-local `QTEMP` objects and do not require a persistent `ILEDITOR` library.
 

package/docs/tools.md

@@ -234,6 +234,7 @@ The documentation catalog is also exposed through MCP resources: `ibmi-docs://ca
 - `ibmi.tn5250.readScreen`
 - `ibmi.tn5250.setField`
 - `ibmi.tn5250.sendKeys`
+- `ibmi.tn5250.click`
 - `ibmi.tn5250.waitFor`
 - `ibmi.tn5250.snapshot`
 - `ibmi.tn5250.disconnect`
@@ -241,16 +242,19 @@ The documentation catalog is also exposed through MCP resources: `ibmi-docs://ca
 ### TN5250 Notes
 These tools drive a real 5250 display session over telnet (RFC 1205 / RFC 2877 / RFC 4777): what you see is the actual green screen, and anything an operator can do there (menus, prompts, interactive programs) can be done here.
 
-- **connect**: opens one session per saved connection. The host is the connection's host; the port and TLS come from the connection (or global) settings `tn5250Port` and `tn5250Tls` (default port 23; port 992 or `tn5250Tls: true` means TLS), and can be overridden with `port` / `tls`. `deviceName` (or the `tn5250DeviceName` setting) requests a virtual device name. `screenSize: "27x132"` announces an IBM-3477-FC display; the default is IBM-3179-2 (24x80). Calling connect again while the session is open returns the current screen with `reused: true`.
+- **connect**: opens one session per saved connection. The host is the connection's host; the port and TLS come from the connection (or global) settings `tn5250Port` and `tn5250Tls` (default port 23; port 992 or `tn5250Tls: true` means TLS), and can be overridden with `port` / `tls`. `deviceName` (or the `tn5250DeviceName` setting) requests a virtual device name. `screenSize: "27x132"` announces an IBM-3477-FC display; the default is IBM-3179-2 (24x80). `ccsid` (or the `tn5250Ccsid` setting) picks the single-byte EBCDIC code page for screen text; the matching `CODEPAGE`, `CHARSET` and `KBDTYPE` are announced to the host. Calling connect again while the session is open returns the current screen with `reused: true`.
 - **Sign-on**: `signOn: true` uses the connection's saved user and password; a password is never accepted as a tool argument. Over TLS the credentials are offered in the telnet negotiation (RFC 4777 auto sign-on, which needs the `QRMTSIGN` system value to allow it). Otherwise, or if the host still shows a sign-on screen, the user and password fields of the sign-on screen are filled and Enter is pressed. The result reports `signOn.method` and `signOn.stillOnSignOnScreen`. On plain telnet (port 23) the password travels unencrypted, exactly as with any 5250 emulator; use TLS.
 - **readScreen** returns `text` (one string per row), `cursor`, `keyboardLocked`, `inputInhibited` (an error message is showing; `errorLine` has it), `readPending` and `fields`. Each field has an `id` such as `r6c53` (row 6, column 53), `index`, `row`, `col`, `length`, a `label` taken from the text to its left, `protected`, `hidden`, `modified`, `numeric` and `commandLine` (labelled `===>`). Hidden (non-display, password-style) fields never include their content, only `hasValue`, and their positions are blank in `text`.
 - **setField** fills a field locally by `fieldId` (id, 1-based index, or `"command"` for the command line) or by `row`/`col`. Nothing is sent until an AID key is pressed. `useStoredPassword: true` fills a hidden field with the connection's saved password (for example a re-sign-on prompt).
-- **sendKeys** types `text` at the cursor (optionally after moving it with `cursorRow`/`cursorCol`), then presses `keys`: local keys `Tab`, `BackTab`, `Home`, `Reset`, `EraseEOF`, `FieldExit`, and at most one AID key, last: `Enter`, `F1`-`F24`, `PageUp`/`PageDown` (Roll Down/Up), `Clear`, `Help`, `Print`, `Attn`, `SysReq`. After an AID key it waits up to `timeoutMs` for the host to unlock the keyboard and returns the new screen with `settled`. If an error message has inhibited input, `Reset` is pressed automatically (`autoReset: true`).
+- **sendKeys** types `text` at the cursor (optionally after moving it with `cursorRow`/`cursorCol`), then presses `keys`: local keys `Tab`, `BackTab` (`Shift+Tab`), `Home`, `End`, `Reset`, `EraseEOF`, `EraseInput`, `FieldExit`, `Field+`, `Field-`, `Dup`, `Insert` (toggles insert mode, shown as `insertMode`), `Delete`, `Up`, `Down`, `Left` (`Backspace`), `Right` and `NewLine`, and at most one host key, last: `Enter`, `F1`-`F24`, `PageUp`/`PageDown` (Roll Down/Up), `Clear`, `Help`, `Print`, `Attn`, `SysReq`. A local key can be repeated with `*N` (`Down*3`). As in IBM emulators, `Esc` (also `Escape`, `Attention`) is `Attn` and `Shift+Esc` (also `SysRq`) is `SysReq`. Attn runs the job's attention program (the "Esc menu"); if the host sends nothing back within 5 seconds (no attention program), the keyboard is unlocked again and the result has a `note`. `Field+`/`Field-` right-adjust numeric fields (Field- marks the value negative), `Field Exit` right-adjusts fields that ask for it, and `Dup` fills a Dup-enabled field with the DUP character (shown as `*`). After an AID key it waits up to `timeoutMs` for the host to unlock the keyboard and returns the new screen with `settled`. If an error message has inhibited input, `Reset` is pressed automatically (`autoReset: true`).
+- **click** works like an emulator mouse: it moves the cursor to `row`/`col`. A click on a function-key legend such as `F3=Exit` presses that key, and on `More...` presses PageDown (`hotspots: false` turns this off); `doubleClick: true` moves the cursor and presses Enter. Keys pressed by a click go through the same checks as sendKeys.
 - **waitFor** waits for `text` to appear on any row and/or for the keyboard to unlock (`keyboardUnlocked`, default true when no text is given). An input-inhibited error state also counts as unlocked, because the host is waiting for the operator.
+- **Live view**: as soon as a session opens, the MCP server serves a live 5250 page on `127.0.0.1` (port 3981, or the next free port; `tn5250LiveViewPort` sets it, `tn5250LiveView: false` turns it off). Every screen result carries `liveViewUrl`; the link holds a per-process token, so only someone with the link can open it. The page shows the session the agent drives and follows it live, and you can type and click in it like an emulator (Esc = Attn, Shift+Esc = SysReq, Ctrl alone = Reset, a click moves the cursor or presses a key legend, a double click presses Enter). While you type, the agent's setField, sendKeys and click calls are refused for a few seconds with a message asking it to wait and re-read the screen; `readScreen` then shows `personTyping: true` and `lastActor: "person"`. Your own keys skip the approval prompt but keep read-only mode, the read-only profile and deny lists. The control plane's Runtime tab lists the open sessions with an Open link. The screen scales to fill the space (fit to width or height), so the page embeds cleanly in a product at any size, including an iframe. The controls are optional: press the **Controls** button (top right), or add `view=screen` to the link, for a screen-only view that fills the whole area; `keys=0`, `header=0`, `hint=0` and `status=0` hide individual parts, and `chrome=full` forces everything on. The choice is remembered per browser, and a URL param always wins.
+- **In-chat screen (MCP Apps)**: clients that support MCP Apps (`io.modelcontextprotocol/ui`) draw the same screen inside the chat after any 5250 tool call; you can type and click there too, and its key presses go through the 5250 tools, so the approval prompts still apply. Clients without that support see the usual text result and can use `liveViewUrl`.
 - **snapshot** returns `plainText` plus the structured screen. **disconnect** closes the session; `ibmi.disconnect` and `ibmi.session.terminate` close it too.
 - **Write gate**: every AID key goes through the write gate. Read-only connections (`readOnlyMode` or the `read-only` policy) refuse all AID keys, including Enter and `signOn`, so they can only open and read the first screen. When a recognised command line (`===>`) holds text, pressing a data-sending AID key is checked as `cl.run` with that text (command policy, and approval under the default guarded policy); any other AID key is checked as `tn5250.sendKeys` (add it to `requireApprovalFor` to ask the user first).
 - Text typed into hidden fields is replaced by `***REDACTED***` in the server log and the audit record.
-- Supported: TN5250 negotiation (TERMINAL-TYPE, BINARY, EOR, NEW-ENVIRON with DEVNAME, KBDTYPE, CODEPAGE and CHARSET), TLS with certificate pinning, Write To Display (SOH, SBA, SF with field format words, IC/MC, RA, EA, TD), Clear Unit (and Alternate for 27x132), Clear Format Table, Write Error Code, Read Input Fields / Read MDT Fields / Read Immediate / Read Screen, Save/Restore Screen, Roll and the 5250 Query. Text uses CCSID 37. Windows, pull-down menus and other Write To Display Structured Field constructs are skipped (their text still shows where the host writes it as plain data); a warning is listed in `warnings`.
+- Supported: TN5250 negotiation (TERMINAL-TYPE, BINARY, EOR, NEW-ENVIRON with DEVNAME, KBDTYPE, CODEPAGE and CHARSET), TLS with certificate pinning, Write To Display (SOH, SBA, SF with field format words, IC/MC, RA, EA, TD), Clear Unit (and Alternate for 27x132), Clear Format Table, Write Error Code, Read Input Fields / Read MDT Fields / Read Immediate / Read Screen, Save/Restore Screen, Roll and the 5250 Query. Text uses one of the single-byte CCSIDs 37, 273, 277, 278, 280, 284, 285, 297, 500, 871, 1047 and 1140-1149; double-byte (DBCS) code pages are not supported. The audit record of each 5250 call keeps the screen's first line, so you can see where a session went. Windows, pull-down menus and other Write To Display Structured Field constructs are skipped (their text still shows where the host writes it as plain data); a warning is listed in `warnings`.
 
 ## Object, Member and IFS Operations
 - `ibmi.objects.copy` - `CRTDUPOBJ` to `toLibrary` (default: same library) as `newObject` (default: same name); `data=true` adds `DATA(*YES)` for `*FILE`.