ibmi-mcp 1.0.0__tar.gz

ibmi_mcp-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+*.log
+.claude/

ibmi_mcp-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Whitehorn Ltd. Co.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ibmi_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: ibmi-mcp
+Version: 1.0.0
+Summary: MCP server providing 5250 terminal access to IBM i systems
+License: BSD-2-Clause
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# ibmi-mcp
+
+Give your AI Agent terminal access to your IBM i system via TN5250.
+
+ibmi-mcp is an MCP server that lets AI Agents like Claude interact with IBM i the same way a human would through a 5250 green-screen terminal.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install ibmi-mcp
+```
+
+Then register it with Claude Code:
+
+```bash
+claude mcp add ibmi-5250 -- uvx ibmi-mcp
+```
+
+## Configuration
+
+Configure the connection using environment variables:
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `IBMI_HOST` | IBM i hostname or IP | Yes | — |
+| `IBMI_PORT` | TN5250 port | No | 23 |
+| `IBMI_SSL` | Enable TLS | No | false |
+| `IBMI_USER` | Username for auto-signon | No | — |
+| `IBMI_PASSWORD` | Password for auto-signon | No | — |
+| `IBMI_DEVICE_NAME` | Virtual device name | No | — |
+| `IBMI_CODEPAGE` | EBCDIC codepage | No | cp037 |
+| `IBMI_TERMINAL_TYPE` | Terminal type | No | IBM-3179-2 |
+
+When `IBMI_USER` and `IBMI_PASSWORD` are set, ibmi-mcp will automatically sign on when it detects a login screen after connecting.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `connect` | Connect to an IBM i system via TN5250 |
+| `disconnect` | Disconnect the active session |
+| `read_screen` | Read the current screen content and input fields |
+| `send_keys` | Type text into the current input field |
+| `send_key` | Send a function/attention key (Enter, F1-F24, PageUp, PageDown, Tab, etc.) |
+| `set_cursor` | Position the cursor at a specific row and column |
+
+## Features
+
+- **Auto-signon** — Automatically detects sign-on screens and logs in with configured credentials
+- **Full key support** — Enter, F1-F24, PageUp, PageDown, Tab, Backtab, Clear, Help, Print, Attn
+- **Local editing** — Backspace, Delete, Field Exit, Home, and End handled locally for responsive editing
+- **Structured screen data** — Returns screen text, cursor position, and input field metadata
+- **Configurable codepage** — Supports EBCDIC codepage translation (default: CP037)
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE) for details.
+
+## About Whitehorn Ltd. Co.
+
+ibmi-mcp is developed and maintained by Whitehorn Ltd. Co., a legacy system modernization firm. We specialize in IBM i, RPG, COBOL, and midrange platforms. We help our clients protect what they can't afford to break while building a path forward.
+
+Learn more about how Whitehorn Ltd. Co. can help you modernize your IBM midrange systems at [whitehorn.ltd](https://whitehorn.ltd).

ibmi_mcp-1.0.0/README.md

@@ -0,0 +1,65 @@
+# ibmi-mcp
+
+Give your AI Agent terminal access to your IBM i system via TN5250.
+
+ibmi-mcp is an MCP server that lets AI Agents like Claude interact with IBM i the same way a human would through a 5250 green-screen terminal.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install ibmi-mcp
+```
+
+Then register it with Claude Code:
+
+```bash
+claude mcp add ibmi-5250 -- uvx ibmi-mcp
+```
+
+## Configuration
+
+Configure the connection using environment variables:
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `IBMI_HOST` | IBM i hostname or IP | Yes | — |
+| `IBMI_PORT` | TN5250 port | No | 23 |
+| `IBMI_SSL` | Enable TLS | No | false |
+| `IBMI_USER` | Username for auto-signon | No | — |
+| `IBMI_PASSWORD` | Password for auto-signon | No | — |
+| `IBMI_DEVICE_NAME` | Virtual device name | No | — |
+| `IBMI_CODEPAGE` | EBCDIC codepage | No | cp037 |
+| `IBMI_TERMINAL_TYPE` | Terminal type | No | IBM-3179-2 |
+
+When `IBMI_USER` and `IBMI_PASSWORD` are set, ibmi-mcp will automatically sign on when it detects a login screen after connecting.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `connect` | Connect to an IBM i system via TN5250 |
+| `disconnect` | Disconnect the active session |
+| `read_screen` | Read the current screen content and input fields |
+| `send_keys` | Type text into the current input field |
+| `send_key` | Send a function/attention key (Enter, F1-F24, PageUp, PageDown, Tab, etc.) |
+| `set_cursor` | Position the cursor at a specific row and column |
+
+## Features
+
+- **Auto-signon** — Automatically detects sign-on screens and logs in with configured credentials
+- **Full key support** — Enter, F1-F24, PageUp, PageDown, Tab, Backtab, Clear, Help, Print, Attn
+- **Local editing** — Backspace, Delete, Field Exit, Home, and End handled locally for responsive editing
+- **Structured screen data** — Returns screen text, cursor position, and input field metadata
+- **Configurable codepage** — Supports EBCDIC codepage translation (default: CP037)
+
+## License
+
+BSD 2-Clause. See [LICENSE](LICENSE) for details.
+
+## About Whitehorn Ltd. Co.
+
+ibmi-mcp is developed and maintained by Whitehorn Ltd. Co., a legacy system modernization firm. We specialize in IBM i, RPG, COBOL, and midrange platforms. We help our clients protect what they can't afford to break while building a path forward.
+
+Learn more about how Whitehorn Ltd. Co. can help you modernize your IBM midrange systems at [whitehorn.ltd](https://whitehorn.ltd).

ibmi_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ibmi-mcp"
+version = "1.0.0"
+description = "MCP server providing 5250 terminal access to IBM i systems"
+readme = "README.md"
+license = {text = "BSD-2-Clause"}
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.scripts]
+ibmi-mcp = "ibmi_mcp:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ibmi_mcp"]

ibmi_mcp-1.0.0/src/ibmi_mcp/__init__.py

@@ -0,0 +1,10 @@
+# ========================================================================
+#   Copyright (c) 2026 Whitehorn Ltd. Co.
+#   https://whitehorn.ltd
+# ========================================================================
+
+from ibmi_mcp.server import mcp
+
+
+def main():
+    mcp.run(transport="stdio")

ibmi_mcp-1.0.0/src/ibmi_mcp/__main__.py

@@ -0,0 +1,8 @@
+# ========================================================================
+#   Copyright (c) 2026 Whitehorn Ltd. Co.
+#   https://whitehorn.ltd
+# ========================================================================
+
+from ibmi_mcp import main
+
+main()

ibmi_mcp-1.0.0/src/ibmi_mcp/config.py

@@ -0,0 +1,19 @@
+# ========================================================================
+#   Copyright (c) 2026 Whitehorn Ltd. Co.
+#   https://whitehorn.ltd
+# ========================================================================
+
+from pydantic_settings import BaseSettings
+
+
+class IBMiConfig(BaseSettings):
+    model_config = {"env_prefix": "IBMI_"}
+
+    host: str = ""
+    port: int = 23
+    ssl: bool = False
+    user: str = ""
+    password: str = ""
+    device_name: str = ""
+    codepage: str = "cp037"
+    terminal_type: str = "IBM-3179-2"

ibmi_mcp-1.0.0/src/ibmi_mcp/server.py

@@ -0,0 +1,195 @@
+# ========================================================================
+#   Copyright (c) 2026 Whitehorn Ltd. Co.
+#   https://whitehorn.ltd
+# ========================================================================
+
+from mcp.server.fastmcp import FastMCP
+
+from ibmi_mcp.config import IBMiConfig
+from ibmi_mcp.tn5250.session import Tn5250Session
+
+mcp = FastMCP("ibmi-5250")
+
+_session: Tn5250Session | None = None
+_config = IBMiConfig()
+
+
+def _screen_response() -> dict:
+    data = _session.screen.get_screen_data()
+    if _session.timed_out:
+        data["warning"] = "Host did not respond within timeout — screen may be incomplete"
+    return data
+
+
+@mcp.tool()
+async def connect(host: str = "", port: int = 0, use_ssl: bool | None = None) -> dict:
+    """Connect to an IBM i system via TN5250.
+
+    Args:
+        host: IBM i hostname or IP. Defaults to IBMI_HOST env var.
+        port: TN5250 port. Defaults to IBMI_PORT env var or 23.
+        use_ssl: Enable TLS. Defaults to IBMI_SSL env var.
+
+    Returns the initial screen after connection.
+    """
+    global _session
+
+    if _session is not None and _session.state.value != "disconnected":
+        await _session.disconnect()
+
+    resolved_host = host or _config.host
+    if not resolved_host:
+        return {"error": "No host specified. Set IBMI_HOST or pass host parameter."}
+
+    resolved_port = port or _config.port
+    resolved_ssl = use_ssl if use_ssl is not None else _config.ssl
+
+    _session = Tn5250Session(
+        host=resolved_host,
+        port=resolved_port,
+        use_ssl=resolved_ssl,
+        terminal_type=_config.terminal_type,
+        device_name=_config.device_name,
+        codepage=_config.codepage,
+        username=_config.user,
+        password=_config.password,
+    )
+
+    try:
+        await _session.connect()
+    except Exception as e:
+        _session = None
+        return {"error": f"Connection failed: {e}"}
+
+    return _screen_response()
+
+
+@mcp.tool()
+async def disconnect() -> dict:
+    """Disconnect the active TN5250 session."""
+    global _session
+
+    if _session is None:
+        return {"status": "already disconnected"}
+
+    await _session.disconnect()
+    _session = None
+    return {"status": "disconnected"}
+
+
+@mcp.tool()
+async def read_screen() -> dict:
+    """Read the current 5250 screen content.
+
+    Returns structured data with:
+    - screen: list of text rows (the visible display)
+    - cursor: current cursor position {row, col} (1-based)
+    - fields: list of input fields with position, length, value, and type
+    - dimensions: screen size {rows, cols}
+    """
+    if _session is None:
+        return {"error": "Not connected. Call connect() first."}
+
+    return _session.screen.get_screen_data()
+
+
+@mcp.tool()
+async def send_keys(text: str) -> dict:
+    """Type text into the current input field at the cursor position.
+
+    Args:
+        text: The text to type.
+
+    Returns the updated screen state.
+    """
+    if _session is None:
+        return {"error": "Not connected. Call connect() first."}
+
+    try:
+        await _session.type_keys(text)
+    except RuntimeError as e:
+        return {"error": str(e)}
+
+    return _screen_response()
+
+
+@mcp.tool()
+async def send_key(key: str) -> dict:
+    """Send an attention/function key and wait for the host response.
+
+    Args:
+        key: Key name. Valid values: Enter, F1-F24, PageUp, PageDown,
+             Tab, Backtab, Clear, Help, Print, Attn.
+
+    Returns the updated screen after the host processes the key.
+    """
+    if _session is None:
+        return {"error": "Not connected. Call connect() first."}
+
+    key_lower = key.lower().strip()
+
+    if key_lower == "attn":
+        await _session.send_attention()
+    elif key_lower == "tab":
+        _move_to_next_field(forward=True)
+    elif key_lower in ("backtab", "btab", "shift+tab"):
+        _move_to_next_field(forward=False)
+    elif _session.handle_local_key(key_lower):
+        pass  # Handled as local editing key
+    else:
+        try:
+            await _session.send_aid(key_lower)
+        except ValueError as e:
+            return {"error": str(e)}
+
+    return _screen_response()
+
+
+@mcp.tool()
+async def set_cursor(row: int, col: int) -> dict:
+    """Position the cursor at the specified location.
+
+    Args:
+        row: Row number (1-based, top row is 1).
+        col: Column number (1-based, leftmost column is 1).
+
+    Returns the updated screen state.
+    """
+    if _session is None:
+        return {"error": "Not connected. Call connect() first."}
+
+    if row < 1 or row > _session.screen.rows:
+        return {"error": f"Row must be between 1 and {_session.screen.rows}"}
+    if col < 1 or col > _session.screen.cols:
+        return {"error": f"Col must be between 1 and {_session.screen.cols}"}
+
+    _session.move_cursor(row, col)
+    return _session.screen.get_screen_data()
+
+
+def _move_to_next_field(forward: bool = True) -> None:
+    """Move cursor to the next/previous input field (Tab/Backtab behavior)."""
+    if _session is None:
+        return
+
+    fields = _session.screen.get_input_fields()
+    if not fields:
+        return
+
+    cursor_pos = _session.screen.cursor_pos()
+    cols = _session.screen.cols
+
+    if forward:
+        for f in fields:
+            field_start = f.row * cols + f.col
+            if field_start > cursor_pos:
+                _session.screen.set_cursor(f.row, f.col)
+                return
+        _session.screen.set_cursor(fields[0].row, fields[0].col)
+    else:
+        for f in reversed(fields):
+            field_start = f.row * cols + f.col
+            if field_start < cursor_pos:
+                _session.screen.set_cursor(f.row, f.col)
+                return
+        _session.screen.set_cursor(fields[-1].row, fields[-1].col)

ibmi_mcp-1.0.0/src/ibmi_mcp/tn5250/__init__.py

@@ -0,0 +1,8 @@
+# ========================================================================
+#   Copyright (c) 2026 Whitehorn Ltd. Co.
+#   https://whitehorn.ltd
+# ========================================================================
+
+from ibmi_mcp.tn5250.session import Tn5250Session
+
+__all__ = ["Tn5250Session"]