v0.5.1

[ajshedivy]

IBM i MCP Server v0.5.1

This release consolidates everything shipped on top of v0.4.5 into the first GitHub Release of the 0.5.x line — the v0.5.0 tag was cut but never published as a GitHub Release, so the notes below cover the full v0.4.5...v0.5.1 span.

Overview

• Monorepo split — @ibm/ibmi-cli — The ibmi command-line tool now ships as its own npm package with a stable public API surface on the server
• Row fetch controls (rowsToFetch / fetchAllRows) — per-tool config for explicit page sizes
• JDBC connection options on YAML sources — Pass Mapepire JDBCOptions through per-source YAML (or the DB2i_JDBC_OPTIONS env var) for naming convention, library list, isolation level, and other connection tunables
• SQL security validation on ibmi tool execution — YAML tool runs now flow through the same SqlSecurityValidator as the built-in execute_sql tool, blocking write statements in read-only contexts before they reach the database
• Pagination safety defaults — New IBMI_PAGINATION_DEFAULT_PAGE_SIZE / IBMI_PAGINATION_MAX_ROWS configure the page size and max row ceiling for paginated tools

Documentation | CLI Guide | SQL Tools Reference

---

New Features

Monorepo split — @ibm/ibmi-mcp-server and @ibm/ibmi-cli

The repository is now an npm workspaces monorepo shipping two co-versioned packages. The ibmi binary no longer ships with @ibm/ibmi-mcp-server — install each package for the surface you want:

# The MCP server (unchanged public binary)
npx -y @ibm/ibmi-mcp-server@0.5.1 --transport http --tools ./tools

# The CLI (new separate package)
npm install -g @ibm/ibmi-cli
ibmi sql "SELECT * FROM SAMPLE.EMPLOYEE" --system dev

Documentation: CLI Guide

Reference: #144

JDBC connection options on YAML sources

Source definitions now accept a passthrough jdbc-options block mapped directly to Mapepire's JDBCOptions. Customize the underlying JDBC connection (naming convention, library list, transaction isolation, date format, or any other JDBC tunable) without forking the pool.

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    jdbc-options:
      naming: system               
      libraries: [MYLIB, SAMPLE]
      "transaction isolation": none
      "date format": iso

For containerized deployments that can't ship YAML, the same options can be supplied via the DB2i_JDBC_OPTIONS environment variable as a JSON object. The env var merges into each source on a per-key basis, with YAML taking precedence when both set the same key.

DB2i_JDBC_OPTIONS={"naming":"system","libraries":["MYLIB"]}

Documentation: Sources configuration

Reference: #141

Row fetch controls: rowsToFetch and fetchAllRows

Tool authors can now decide per-tool whether a query runs with an explicit page size, streams every matching row, or combines both for custom paginated streaming. The two fields compose instead of colliding — fetchAllRows: true is the pagination policy, and when rowsToFetch is also set it becomes the per-fetch page size.

tools:
  list_active_jobs:
    source: ibmi-system
    rowsToFetch: 100               # cap at 100 rows — one fetch
    statement: |
      SELECT JOB_NAME, JOB_USER
      FROM TABLE(QSYS2.ACTIVE_JOB_INFO())

  export_active_jobs:
    source: ibmi-system
    fetchAllRows: true             # stream every matching row
    statement: |
      SELECT JOB_NAME, JOB_USER
      FROM TABLE(QSYS2.ACTIVE_JOB_INFO())
      WHERE JOB_STATUS = 'RUN'

  paginated_export:
    source: ibmi-system
    fetchAllRows: true             # stream everything...
    rowsToFetch: 500               # ...in 500-row pages
    statement: |
      SELECT JOB_NAME, JOB_USER
      FROM TABLE(QSYS2.ACTIVE_JOB_INFO())

Both fields are optional and can be omitted for the pool default. Streaming is bounded by the new pagination ceiling (below), so fetchAllRows: true can't accidentally pull an unbounded result set.

Documentation: Tools parameter reference

Reference: #142, #146

Pagination safety ceiling and tunables

Paginated tools now terminate at a row-based ceiling rather than a fixed iteration count. Previously the internal loop stopped after 100 fetchMore calls, so a larger per-fetch page size implicitly granted a proportionally larger cap. The ceiling is now measured in accumulated rows, so behavior is deterministic regardless of page size. Two new env vars let developers tune both values:

# Rows per fetchMore call when a tool paginates without specifying rowsToFetch
IBMI_PAGINATION_DEFAULT_PAGE_SIZE=1000

# Hard upper bound on total rows returned from a paginated call
IBMI_PAGINATION_MAX_ROWS=30000

When a result hits the ceiling, the server logs a warning, flags the response with truncated: true, and the CLI footer shows (result capped — raise IBMI_PAGINATION_MAX_ROWS or narrow the query) so callers know output was clipped. The built-in execute_sql tool now inherits the same ceiling — previously it hard-coded a 1000-row page size with an effective ~100,000-row cap, inconsistent with YAML tools.

Reference: #146

SQL security validation on ibmi tool execution

YAML tool runs now flow through the same SqlSecurityValidator used by the built-in execute_sql tool. Write statements in read-only contexts are rejected before they reach the database — an additional safety layer on top of existing readOnlyHint tool configuration.

No action required for existing YAML tools. Tools declared with readOnlyHint: true (or run under the CLI's --read-only flag) are validated automatically.

Reference: #136

---

Breaking Changes

ibmi binary moved to @ibm/ibmi-cli

The CLI no longer ships with @ibm/ibmi-mcp-server. Upgrading from 0.4.x requires installing @ibm/ibmi-cli separately. Runtime MCP server usage via npx -y @ibm/ibmi-mcp-server@latest ... is unchanged — only local CLI installs are affected.

Migration:

# Before (v0.4.x) — one install, both binaries
npm i -g @ibm/ibmi-mcp-server

# After (v0.5.x) — separate packages
npm i -g @ibm/ibmi-mcp-server        # provides `ibmi-mcp-server`
npm i -g @ibm/ibmi-cli                # provides `ibmi`

The two packages co-version on every release — installing @ibm/ibmi-cli@0.5.1 always pulls in @ibm/ibmi-mcp-server@0.5.1.

---

What's Changed

• feat(cli)!: split ibmi CLI into @ibm/ibmi-cli package (closes Split ibmi CLI into separate @ibm/ibmi-cli package with version-synced releases #143) by @ajshedivy in feat(cli)!: split ibmi CLI into @ibm/ibmi-cli package (closes #143) #144
• fix(cli): enforce read-only security validation for YAML tool execution by @ajshedivy in fix(cli): enforce read-only security validation for YAML tool execution #136
• feat(config): general-purpose jdbc-options field (supersedes feat(config): add library list selection for multi-environment support #138) by @ajshedivy in feat(config): general-purpose jdbc-options field (supersedes #138) #141
• feat(yaml): add rowsToFetch and fetchAllRows per-tool config by @ajshedivy in feat(yaml): add rowsToFetch and fetchAllRows per-tool config #142
• fix(yaml): reverse rowsToFetch / fetchAllRows precedence by @ajshedivy in fix(yaml): reverse rowsToFetch / fetchAllRows precedence #145
• feat: compose rowsToFetch and fetchAllRows, centralize pagination limits by @ajshedivy in feat: compose rowsToFetch and fetchAllRows, centralize pagination limits #146

Full Changelog: v0.4.5...v0.5.1

---

This discussion was created from the release v0.5.1: fix(docker): build from repo root for npm workspaces layout.