mcp-for-i 0.1.13 → 0.3.0

package/docs/tools.md

@@ -1,188 +1,367 @@
-# 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`
-
-### Deploy Notes
-- `ibmi.deploy.compare` returns richer drift data: `onlyLocal`, `onlyRemote`, `identical`, `changed`, `unresolved`, and a `summary`.
-- `ibmi.deploy.sync` supports `overwrite`, `dryRun`, and `deleteExtraRemote`.
-- `ibmi.deploy.sync` returns execution mapping (`planned`, `applied`, `errors`) for safer automation.
-
-## 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`
-
-### SQL / CL Notes
-- `ibmi.sql.query` supports cursor paging (`cursor`), `pageSize`, `maxRows`, `timeoutMs`, and optional `includeMetadata`.
-- `ibmi.sql.execute` supports guarded writes with `approve=true` and optional `timeoutMs`.
-- `ibmi.cl.run` supports `ile`, `qsh`, or `pase` execution with optional `timeoutMs`.
-- Tool responses include structured envelopes (`structuredContent`) for machine-safe agent parsing.
-
-## Diagnostics / Ops
-- `ibmi.diagnostics.parseEvfevent`
-- `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`
-
-### Diagnostics Notes
-- Diagnostics tools return normalized records suitable for downstream agents (`source`, normalized severity/status fields, and preserved raw fields).
-- `ibmi.actions.run` now returns mapped execution status (`ok`, `status`) and parsed command diagnostics alongside raw command output.
-- Spool controls now support hold/release/delete and output-queue move operations for targeted spool entries.
-- Job and subsystem controls support both observability (`list`/`status`) and lifecycle actions (hold/release/end/start).
-- Message queue tooling supports operational reads plus explicit send/reply workflows.
-- Lock and authority tools are useful preflight checks before risky writes.
-- Data queue and data area tooling covers common IBM i operational integration surfaces.
-
-## Audit
-- `ibmi.audit.list`
-- `ibmi.audit.verify`
-- `ibmi.audit.export`
-- `ibmi.audit.purge`
-
-### Audit Notes
-- Tool calls are recorded in a tamper-evident local audit chain.
-- `ibmi.audit.verify` validates hash continuity and head hash state.
-- `ibmi.audit.export` supports `jsonl`, `json`, and `csv` output.
-- `ibmi.audit.purge` supports `dryRun`; destructive purge requires `approve=true`.
-
-## 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`
-
-### Journaling Notes
-- `ibmi.journal.entries.query` supports advanced filters (`journalCode`, `entryType`, `userName`, `jobName`, `programName`) and normalizes key fields.
-- `ibmi.qaudjrn.events.query` targets `QSYS/QAUDJRN` for security/compliance event review.
-- `ibmi.journal.receivers.retention` supports `dryRun`; destructive cleanup requires `approve=true`.
-
-## Compliance
-- `ibmi.compliance.report.generate`
-
-### Compliance Notes
-- Generates preset compliance snapshots with audit-chain verification + QAUDJRN summaries.
-- Optional evidence-bundle signing writes `<outputPath>.sig` and `<outputPath>.sha256`.
-
-## TN5250
-- `ibmi.tn5250.connect`
-- `ibmi.tn5250.readScreen`
-- `ibmi.tn5250.setField`
-- `ibmi.tn5250.sendKeys`
-- `ibmi.tn5250.waitFor`
-- `ibmi.tn5250.snapshot`
-- `ibmi.tn5250.disconnect`
-
-### TN5250 Notes
-- Sessions are stateful per IBM i connection.
-- `setField` supports `fieldId: "command"` (or `"1"` alias), then `sendKeys: "Enter"` to execute.
-- `sendKeys` supports guardrails through policy checks and optional `approve=true` for guarded operations.
+# Tools
+
+Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so MCP clients can auto-approve read-only tools and ask before destructive ones. Only the IBM Docs tools reach the internet (`openWorldHint: true`).
+
+## Connection
+- `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 / 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`
+
+### Source performance and compatibility notes
+
+- Existing `members.list` calls keep the legacy array response. Set `responseFormat: "page"`, provide a filter, or provide paging arguments to receive a bounded structured page.
+- Existing `members.read` calls keep the legacy text response. Set `responseFormat: "structured"` or request ranges, context, metadata, or a version check to receive the structured snapshot envelope.
+- `members.write` supports optional optimistic-concurrency checks through `expectedVersion` and `expectedSha256`.
+- `members.read` uses a job-local alias for source-date reads and a complete `CPYTOSTMF` fallback if the SQL path is unavailable.
+- Both read paths normalize content the same way before hashing (LF line endings, trailing blanks trimmed from every line), so `sha256` and `version` do not change when a read falls back from SQL to `CPYTOSTMF`.
+- Cached snapshots are only served after a cheap re-check of the member's `LAST_SOURCE_UPDATE_TIMESTAMP` and row count, so edits made outside this server are seen immediately. Cache hits report `cacheStatus: "hit"` and `validatedAt`.
+- Full reads are capped by the `sourceReadMaxBytes` / `sourceReadMaxLines` settings (defaults 2,000,000 bytes and 50,000 lines). Larger members return a `SOURCE_TOO_LARGE` error with the size and version; read them with `startLine`/`endLine` or `ranges`, or locate code with `ibmi.search.members` / `ibmi.source.inspect`.
+- `startLine` without `endLine` reads to the end of the member. Ranges past the end return no lines and a warning. Range responses are limited to 2,000 lines; when cut, the response has `truncated: true` and `nextLine`.
+- `metadataOnly: true` does not download content. It returns `changeMarker` and catalog metadata, plus `sha256`/`version` only when a validated cached snapshot exists.
+- A version mismatch (`expectedVersion` / `expectedSha256`) on read, inspect or write is a tool error with `code: "VERSION_CONFLICT"`, `currentVersion` and `currentSha256`; nothing is modified.
+- A successful `members.write` reads the member back and returns `version`, `sha256`, `lineCount` and `previousVersion` (as JSON when a version check or `responseFormat: "structured"` is used; otherwise the text stays `OK` and the details are in `structuredContent`). The version check and the write are separate host operations, so a change made in the instant between them is not detected.
+
+## 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`
+
+`ibmi.search.members` accepts either `term` or up to 20 `terms` in one remote request.
+
+- Terms are matched literally (`-F`) and sent over stdin (`-f -`), never through the shell.
+- `maxMatches` defaults to 100 (maximum 1,000). The limit is applied on the host while the grep runs (`-m` per member plus a bounded output pipe), not after downloading everything.
+- The response includes `matchCount`, `maxMatches`, `truncated` and, when truncated, `truncatedReason` (`max-matches` or `output-limit`). When `truncated` is true, narrow the search (members filter, more specific terms) rather than raising the limit.
+- With `before`/`after` (0 to 50), each returned line has `kind: "match"` or `kind: "context"`.
+- `pfgrep` is used when installed at `/QOpenSys/pkgs/bin/pfgrep`; otherwise grep is used.
+
+## Composite Source Inspection
+
+- `ibmi.source.resolve`
+- `ibmi.source.inspect`
+
+`ibmi.source.inspect` batches metadata, outline, search, range-read, and dependency extraction over one versioned source snapshot.
+
+Outline and dependency extraction follow the member source type: RPG (fully free, fixed and mixed: procedures, subroutines, prototypes, data structures, `dcl-f`/F-spec files, `EXTPGM`/`EXTPROC`, `CALL`/`CALLB`/`CALLP`, `/COPY`/`/INCLUDE` and embedded SQL tables), CL (`CALL`, `CALLPRC`, `DCLF`, `OVRDBF TOFILE`, `INCLUDE`, `RUNSQL`, `SBMJOB CMD(CALL ...)`, labels, subroutines), SQL (created objects; tables from `FROM`, `JOIN`, `INSERT`/`MERGE INTO`, `UPDATE`, `DELETE FROM`, `REFERENCES`; `CALL`), and DDS PF/LF/DSPF/PRTF (record formats, keys, fields; `REF`, `REFFLD`, `PFILE`, `JFILE`). Results include the detected `language`.
+
+## Official IBM i Documentation
+
+- `ibmi.docs.search`
+- `ibmi.docs.open`
+
+The documentation catalog is also exposed through MCP resources: `ibmi-docs://catalog` and `ibmi-docs://topic/{ref}`.
+
+- `ibmi.docs.open` accepts a `ref` from search or any `https://www.ibm.com/docs/...` URL (for example a single CL command or API page). The URL must be https, host exactly `www.ibm.com`, path under `/docs/`, with no user information or port. Redirects are followed only within `www.ibm.com/docs/`, at most 3.
+- Pages are capped at 12 MiB while downloading, HTML tables become Markdown tables, and pages that were opened become searchable.
+- Cached pages expire after 7 days (`MCP_FOR_I_IBM_DOCS_CACHE_TTL_DAYS`). `cacheStatus` is `hit`, `miss`, `refreshed` or `stale` (expired copy served because the refresh failed).
+- The search catalog covers IBM i 7.2 to 7.6. Asking for an older release returns a warning saying IBM Docs has no collection for it.
+
+## 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`
+- `ibmi.libl.move`
+- `ibmi.libl.prune`
+- `ibmi.libl.runProfileCommand`
+
+## 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`
+
+### Deploy Notes
+- `ibmi.deploy.compare` returns richer drift data: `onlyLocal`, `onlyRemote`, `identical`, `changed`, `unresolved`, and a `summary`.
+- `ibmi.deploy.sync` supports `overwrite`, `dryRun`, and `deleteExtraRemote`.
+- `ibmi.deploy.sync` returns execution mapping (`planned`, `applied`, `errors`) for safer automation, plus a `summary` with `planned`, `uploaded`, `unchanged`, `skipped`, `deleted` and `failed` counts.
+- `ibmi.deploy.sync` takes `method`:
+  - `all` (default): original behavior. Uploads files missing remotely; with `overwrite`, also files whose size differs or is unknown.
+  - `changed`: compares SHA-256 hashes of files present on both sides (local with node crypto, remote with `sha256sum` or `openssl dgst -sha256` in batched calls) and uploads only missing or different files. Fails with a clear error when the IBM i has neither tool.
+  - `gitChanged`: uploads the staged, unstaged and untracked files under `localPath` reported by `git status --porcelain -z` (run without a shell). Deleted files are listed in `planned.gitDeleted`, never removed remotely.
+  - `selection`: uploads the paths listed in `files` (relative to `localPath`; absolute paths and `..` are refused).
+- `deleteExtraRemote` works only with `all` and `changed`.
+- `ibmi.deploy.compare` takes `method: "changed"` to compare by SHA-256 instead of size (`comparedBy: "sha256"`).
+
+## 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`
+
+### SQL / CL Notes
+- `ibmi.sql.query` supports cursor paging (`cursor`), `pageSize`, `maxRows`, `timeoutMs`, and optional `includeMetadata`.
+- `ibmi.sql.execute` asks the user before writes under the guarded policy and supports optional `timeoutMs`.
+- `ibmi.cl.run` supports `ile`, `qsh`, or `pase` execution with optional `timeoutMs`.
+- Tool responses include structured envelopes (`structuredContent`) for machine-safe agent parsing.
+
+## Diagnostics / Ops
+- `ibmi.diagnostics.parseEvfevent`
+- `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`
+
+### Diagnostics Notes
+- Diagnostics tools return normalized records suitable for downstream agents (`source`, normalized severity/status fields, and preserved raw fields).
+- `ibmi.actions.run` now returns mapped execution status (`ok`, `status`) and parsed command diagnostics alongside raw command output.
+- Spool controls now support hold/release/delete and output-queue move operations for targeted spool entries.
+- Job and subsystem controls support both observability (`list`/`status`) and lifecycle actions (hold/release/end/start).
+- Message queue tooling supports operational reads plus explicit send/reply workflows.
+- Lock and authority tools are useful preflight checks before risky writes.
+- Data queue and data area tooling covers common IBM i operational integration surfaces.
+
+## Audit
+- `ibmi.audit.list`
+- `ibmi.audit.verify`
+- `ibmi.audit.export`
+- `ibmi.audit.purge`
+
+### Audit Notes
+- Tool calls are recorded in a tamper-evident local audit chain.
+- `ibmi.audit.verify` validates hash continuity and head hash state.
+- `ibmi.audit.export` supports `jsonl`, `json`, and `csv` output.
+- `ibmi.audit.purge` supports `dryRun`; destructive purge asks the user under guarded (other profiles: `approve=true`).
+
+## 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`
+
+### Journaling Notes
+- `ibmi.journal.entries.query` supports advanced filters (`journalCode`, `entryType`, `userName`, `jobName`, `programName`) and normalizes key fields.
+- `ibmi.qaudjrn.events.query` targets `QSYS/QAUDJRN` for security/compliance event review.
+- `ibmi.journal.receivers.retention` supports `dryRun`; destructive cleanup asks the user under guarded (other profiles: `approve=true`).
+
+## Compliance
+- `ibmi.compliance.report.generate`
+
+### Compliance Notes
+- Generates preset compliance snapshots with audit-chain verification + QAUDJRN summaries.
+- Optional evidence-bundle signing writes `<outputPath>.sig` and `<outputPath>.sha256`.
+
+## TN5250
+- `ibmi.tn5250.connect`
+- `ibmi.tn5250.readScreen`
+- `ibmi.tn5250.setField`
+- `ibmi.tn5250.sendKeys`
+- `ibmi.tn5250.click`
+- `ibmi.tn5250.waitFor`
+- `ibmi.tn5250.snapshot`
+- `ibmi.tn5250.disconnect`
+
+### 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). `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` (`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 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`.
+- `ibmi.objects.move` - `MOVOBJ` to `toLibrary`.
+- `ibmi.objects.rename` - `RNMOBJ` to `newObject`.
+- `ibmi.objects.delete` - runs the delete command for the type (`DLTPGM`, `DLTSRVPGM`, `DLTF`, `DLTDTAARA`, ...). `objectType: "*LIB"` deletes the library named in `library` with `DLTLIB` and needs `confirmName` repeating the library name; under guarded the user confirms every library delete (other profiles: `approve=true`).
+- `ibmi.objects.changeDescription` - `CHGOBJD TEXT(...)`; an empty `text` sets `*BLANK`.
+- `ibmi.libraries.copy` - `CPYLIB FROMLIB TOLIB CRTLIB(*YES|*NO) DATA(*YES|*NO)`; `createLibrary` and `data` default to true; `timeoutMs` defaults to 10 minutes.
+- `ibmi.qsys.members.copy` - `CPYSRCF ... MBROPT(*REPLACE)` to `toLibrary`/`toSourceFile`/`toMember` (each defaults to the source value). Refuses an existing target member unless `replace=true`.
+- `ibmi.qsys.members.changeText` - `CHGPFM TEXT(...)`.
+- `ibmi.qsys.members.changeType` - `CHGPFM SRCTYPE(...)`.
+- `ibmi.ifs.copy` - `cp`, or `cp -R` with `recursive=true`.
+- `ibmi.ifs.move` - `mv`.
+
+### Object, Member and IFS Operation Notes
+- All of these tools change the system: they are refused in read-only mode and by the read-only policy profile, and ask the user first when the guarded profile lists their operation (`qsys.write`; IFS tools use `ifs.write` or `qsys.write` for the destination, and `ibmi.ifs.move` also `ifs.delete`).
+- Supported object types: `*PGM`, `*SRVPGM`, `*MODULE`, `*FILE`, `*DTAARA`, `*DTAQ`, `*CMD`, `*MSGF`, `*MENU`, `*PNLGRP`, `*BNDDIR`, `*JOBD`, `*OUTQ`, `*USRSPC`, `*USRIDX`, `*USRQ`, `*SQLPKG`, `*QRYDFN`, `*JRN`, `*JRNRCV`, `*SBSD`, `*CLS`, `*TBL` (plus `*LIB` for delete).
+- Names are validated and uppercased; text is limited to 50 characters, quoted for CL, and may not contain control characters.
+- Objects in IBM system libraries (`QSYS*`, `QUSRSYS`, `QRECOVERY`, `QSPL`, `QRPLOBJ`, `QHLPSYS`, `QDOC`, `QSRV`, `SYSIBM`, `SYSIBMADM`, `SYSPROC`, `SYSTOOLS`, `SYSCAT`, `SYSFUN`, `SYSSTAT`, `#*`) are never changed, moved, deleted or copied into. Deleting a library and copying into a library (`CPYLIB` target) also refuse every `Q*` name, including `QGPL` and `QTEMP`.
+- The built CL command is checked against `allowCommands`/`denyCommands`, and every library involved against `allowLibraries`/`denyLibraries`. A failing command returns a tool error with the IBM i message.
+- Member copy and attribute changes drop the cached member snapshot for the affected member.
+- IFS copy/move check both paths against `allowPaths`/`denyPaths`. The destination (and the source of a move or recursive copy) gets the same guard as `ibmi.ifs.delete`: no root, top-level directory, `/QSYS.LIB/<lib>.LIB`, second-level `/QOpenSys` or `/QIBM` directory, IBM product directory, `..` or wildcards. The destination may not equal or sit inside the source. An existing destination is refused unless `overwrite=true`; an existing directory then receives the copied or moved entry inside it.
+
+## Bulk Members
+- `ibmi.members.downloadAll`
+- `ibmi.members.uploadChanged`
+
+### Bulk Members Notes
+- `downloadAll` copies every member of `sourceFile` (or `sourceFiles`, or every source file in `library` when neither is given) to `localPath/LIB/FILE/MEMBER.ext`. The extension is the lowercased member type (`mbr` when the type is blank). `memberPrefix` and `sourceTypes` narrow the set; `maxMembers` (default 500, max 5000) caps it and the result reports `truncated`.
+- A manifest `.mcp-for-i-members.json` in `localPath` records each member's source type, `version`, `sha256` and last-change timestamp.
+- Re-running `downloadAll` keeps local files edited since the last download (reported in `skipped`) unless `overwrite: true`.
+- `uploadChanged` walks the tree under `localPath` (filter with `library`, `sourceFile`, `members`). Files whose content still matches the manifest are skipped without contacting the IBM i. A member that changed on the IBM i since download, or exists remotely without a manifest entry, is reported in `conflicts` and not written unless `force: true`. Missing members are created with SRCTYPE from the manifest or the file extension (`createMissing`, default true).
+- `uploadChanged` honors the write gate (read-only mode, policy, user confirmation), `denyLibraries`/`allowLibraries` for every library in the tree, and `dryRun`. Written members are dropped from the member snapshot cache and the manifest is updated with their new version.
+- Line endings are normalized to LF before hashing and upload.
+
+## Compare
+- `ibmi.compare.text`
+
+### Compare Notes
+- Compares any two of: a source member (`{ "type": "member", "library", "sourceFile", "member" }`), an IFS stream file (`{ "type": "ifs", "path" }`) or a local file (`{ "type": "local", "path" }`). Member and IFS sides may name their own `connectionName`, so the same member can be compared across two systems.
+- Returns a unified diff plus `stats` (`hunks`, `added`, `removed`), `identical`, and size/line count/SHA-256 for each side.
+- Options: `context` (default 3), `ignoreTrailingWhitespace` (default true), `ignoreCase` (default false), `maxBytes` per side (default 2 MB, max 16 MB), `maxDiffLines` (default 2000; counts always cover the whole diff and `truncated` says when the text was cut).
+- Members are read through the member snapshot reader: only the source text is compared (no sequence numbers or source dates) and the record padding is trimmed. A missing final newline is not reported as a difference.
+- Local files must be inside the allowed local roots. IFS and local files must be UTF-8 text. Library and IFS path policies are checked for each side.
+
+## Inspection
+- `ibmi.objects.describe`
+- `ibmi.members.describe`
+- `ibmi.ifs.stat`
+- `ibmi.programs.info`
+- `ibmi.objects.whereUsed`
+- `ibmi.tables.describe`
+- `ibmi.routines.describe`
+
+### Inspection Notes
+- All inspection tools are read-only, cap their queries with `FETCH FIRST`, and upper-case and validate every name.
+- `ibmi.objects.describe` reads `QSYS2.OBJECT_STATISTICS` (owner, size, text, attribute, created/changed/last-used/save dates and source file information when recorded). `objectType` defaults to `*ALL`. If the system rejects the `OBJECT_NAME` argument, the library listing is filtered by name instead. `attributes` holds every non-empty column the service returned.
+- `ibmi.members.describe` reads `QSYS2.SYSPARTITIONSTAT` (source type, text, records, data size, created/changed/source-changed/last-used dates) plus the record length and the `SRCDTA` CCSID.
+- `ibmi.ifs.stat` reads `QSYS2.IFS_OBJECT_STATISTICS` (type, CCSID, owner, size, dates). On releases without that service it falls back to `ls -ldL` (no CCSID) and adds a warning.
+- `ibmi.programs.info` reads `QSYS2.PROGRAM_INFO` for a `*PGM` or `*SRVPGM` (program type, activation group, adopted authority, source location, target release), bound modules from `QSYS2.BOUND_MODULE_INFO`, bound service programs from `QSYS2.BOUND_SRVPGM_INFO`, and exports/imports from `QSYS2.PROGRAM_EXPORT_IMPORT_INFO`. For a service program it returns `binderSource` (`STRPGMEXP PGMLVL(*CURRENT) SIGNATURE(*GEN)` with one `EXPORT` per exported symbol). Check the export order against `DSPSRVPGM DETAIL(*SIGNATURE)` before binding with it. Missing optional services become `warnings`.
+- `ibmi.objects.whereUsed` runs `DSPPGMREF` into a uniquely named QTEMP outfile and reads it in the same SQL job. `direction: "uses"` lists what a program references (`library`, `program`, optional `programType`). `direction: "usedBy"` scans every program, service program and module in `library` and returns the references to `object` (optional `objectLibrary`, which also matches `*LIBL` references, and `objectType`), plus a de-duplicated `programs` list. Scanning a large library can take a while.
+- `ibmi.tables.describe` accepts system or SQL names and returns the table row from `QSYS2.SYSTABLES`, columns from `QSYS2.SYSCOLUMNS`, constraints with key columns (`SYSCST`/`SYSKEYCST`) and SQL indexes with their keys (`SYSINDEXES`/`SYSKEYS`). Keys of DDS keyed files and logical files are not included.
+- `ibmi.routines.describe` returns every overload from `QSYS2.SYSROUTINES` with parameters from `QSYS2.SYSPARMS` and a readable `signature`. `includeDefinition` adds the SQL routine body (capped at 64 KB).
+
+## Compile and errors
+- `ibmi.actions.run` (compile against a member or streamfile)
+- `ibmi.compile.listing`
+- `ibmi.diagnostics.parseEvfevent`
+
+### Compile Notes
+- Member targets: pass `targetType: "member"` and `targetPath: "LIB/FILE/MEMBER[.TYPE]"` (or `library`, `sourceFile`, `member`). The action gets `&OPENLIB`, `&OPENSPF`, `&OPENMBR` (and lowercase `&OPENLIBL`, `&OPENSPFL`, `&OPENMBRL`), `&EXT` (member type, looked up when not given), `&EXTL`, `&NAME`, `&NAMEL`, `&BASENAME`, `&SRCFILE` (`LIB/FILE`), `&SRCLIB`, `&SRCPF`.
+- Streamfile targets: `targetPath` is an absolute IFS path. The action gets `&FULLPATH`, `&RELATIVEPATH` (relative to the working directory), `&FILEDIR`, `&PARENT`, `&BASENAME`, `&NAME`, `&NAMEL`, `&EXT`, `&EXTL`. The working directory is `cwd`, else `remoteWorkspace`, else the home directory.
+- Built-in actions are typed `member` or `streamfile`; running one against the other kind of target is refused, and so is any command that still contains a target variable the target did not set (for example `&RELATIVEPATH` on a member).
+- Longer variable names are substituted first and a name only matches as a whole word, so `&EXT` does not corrupt `&EXTL`.
+- When the command uses `OPTION(*EVENTF)`, the EVFEVENT member is read from the library and name of the object the command creates (`PGM(`, `MODULE(`, `OBJ(`, `SRVPGM(`, `CMD(`, `FILE(` ...; `*CURLIB`/`*LIBL` resolve to the current library). Override with `evfeventLibrary` / `evfeventMember`. The result has `errors` (grouped by source file, each with `line`, `column`, `endLine`, `endColumn`, `severity`, `severityLevel`, `msgid`, `text`) and `errorSummary`.
+- `deployFirst`: with `localWorkspace` and `remoteWorkspace`, the workspace is pushed with `ibmi.deploy.sync` (`overwrite: true`) before the command runs. Without a local workspace the deploy is reported as skipped.
+- `postDownload`: listed paths (relative to the working directory, or absolute) are downloaded to `downloadTo` (default `localWorkspace`). Downloaded `.evfevent` files are parsed and merged into `errors`.
+- `outputToFile`: the command, exit code, stdout and stderr are written to this local path. `&LOCAL` or a relative path resolves against `localWorkspace`.
+- `includeListing: true` returns the compile listing: the newest spooled file named after the object (else `QSYSPRT`, else `QPJOBLOG`) owned by the user and created since the command started.
+- A failed command is returned as a tool error that names the first EVFEVENT error.
+- `ibmi.compile.listing` (read-only) fetches the same listing on its own: `objectName`, optional `userName`, `since` (IBM i timestamp) and `maxLines`.
+- `ibmi.diagnostics.parseEvfevent` parses EVFEVENT text (TIMESTAMP, PROCESSOR, FILEID, FILEEND, EXPANSION, ERROR records). Errors that the compiler reports against a temporary file such as `QTEMP/QSQLTEMP1` are mapped back to the original source line through the precompiler's EXPANSION records.
+
+## System Information
+- `ibmi.system.info` (read-only)
+
+Returns, in one call:
+- `os`: release (from `SYSIBMADM.ENV_SYS_INFO`), host name, CPUs, memory, plus partition and ASP figures from `QSYS2.SYSTEM_STATUS_INFO`.
+- `ptfGroups`: one row per PTF group from `QSYS2.GROUP_PTF_INFO` with the latest level known, its status and the latest installed level. Capped by `ptfGroupLimit` (default 100, max 1000) with `truncated`.
+- `authorities`: the current user's class, special authorities, group profiles and limited capabilities from `QSYS2.USER_INFO`.
+- `systemValues`: an allow-listed set of system values from `QSYS2.SYSTEM_VALUE_INFO` (security, national language, date/time, library list, model). `systemValues` picks a subset; names outside the allow-list are rejected.
+- `pase` and `tools`: `uname`, a few environment variables (PATH, HOME, SHELL, LANG, LC_ALL, TZ, QIBM_CCSID, QIBM_PASE_CCSID) and where pfgrep, openssl, git, bash, python3, node, java and mapepire-server are installed, gathered by one PASE command (`command -v`, then `/QOpenSys/pkgs/bin`).
+
+Pick parts with `sections` (`os`, `ptfGroups`, `authorities`, `systemValues`, `pase`, `tools`). A section that fails is reported under `errors` and the others are still returned.
+
+## Search by Change Date
+- `ibmi.search.changedLines` (read-only)
+
+Finds source lines whose `SRCDAT` falls between `from` and `to` (inclusive, `YYYY-MM-DD`; `to` defaults to today). `member` is a member name or a generic name with `*` (`ORD*`, `*ALL`, the default); `memberType` narrows a generic search. Each hit has the member, line number, sequence number, date and text.
+
+- `SRCDAT` stores `YYMMDD`. Years 40-99 are read as 1940-1999 and 00-39 as 2000-2039 (the IBM i two-digit year window). Lines with no date are never returned.
+- Each member is read with a `QTEMP` alias created in the same SQL job as the query.
+- `maxLines` (default 500, max 5000) and `maxMembers` (default 50, max 500) cap the work; `truncated` and `truncatedReason` say when either was hit. For a generic search, a member that cannot be read is listed under `errors`.
+
+## Library List Tidying
+- `ibmi.libl.move`: move a library to a 1-based `position`, or `direction` `up`/`down` by `steps` (default 1), or `top`/`bottom`.
+- `ibmi.libl.prune`: remove libraries that no longer exist (checked with `QSYS2.OBJECT_STATISTICS`). `dryRun` only reports. A missing current library is reported, not changed.
+- `ibmi.libl.runProfileCommand`: run a profile's `setLibraryListCommand` (the active profile by default, or `profileName`) and store the user library list and current library it produces, read back from `QSYS2.LIBRARY_LIST_INFO` in the same SQL job. `saveToProfile` also stores the result in the profile. Set the command with `ibmi.profiles.save` (`profile.setLibraryListCommand`). The command is checked against the CL command policy.
+
+All three update the stored connection settings the same way `ibmi.libl.set` does, need a writable connection, ask the user first under guarded policies, and run `CHGLIBL`/`CHGCURLIB` when `applyToJob` is true.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-for-i",
-  "version": "0.1.13",
+  "version": "0.3.0",
   "private": false,
   "description": "Local MCP server and control plane for IBM i workflows",
   "type": "module",
@@ -28,7 +28,7 @@
     "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/sql.parse.test.mjs test/audit.chain.test.mjs test/controlplane.platform.test.mjs test/controlplane.service.test.mjs test/credential.environment.test.mjs",
+    "test": "npm run build && node scripts/run-unit-tests.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",
@@ -38,14 +38,17 @@
     "release:major": "node scripts/release-auto.mjs major"
   },
   "dependencies": {
+    "@ibm/mapepire-js": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.25.3",
     "diff": "^5.2.0",
     "keytar": "^7.9.0",
     "node-ssh": "^13.1.0",
+    "ws": "^8.22.0",
     "zod-to-json-schema": "^3.23.2"
   },
   "devDependencies": {
     "@types/diff": "^7.0.2",
+    "@types/ws": "^8.18.2",
     "dotenv": "^17.2.3",
     "ts-node": "^10.9.0",
     "typescript": "^5.4.0"