# bezouwenr/ibmi-mcp-server architecture

> Architecture diagram of the GitHub repository bezouwenr/ibmi-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bezouwenr/ibmi-mcp-server
- Repository: https://github.com/bezouwenr/ibmi-mcp-server

## Overview

This repository provides an IBM i MCP server and a sibling CLI for AI-driven and direct SQL access to Db2 for i, alongside agent integrations and an example AgentOS chat application. The main workflow is a client request reaching the server over MCP, invoking a registered SQL tool, and returning results from IBM i via Mapepire; the CLI offers a terminal-first route through the shared YAML tool engine. The graph includes documented CLI, agent, and UI capabilities, but their internal wiring is only shown where supported by the tree or sampled source.

Main entry points: [`packages/server/src/mcp-server/transports`](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/mcp-server/transports) (MCP transports), [`packages/server/src/ibmi-mcp-server/services/connectionPool.ts`](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/services/connectionPool.ts) (Connection pools), [`app/app/main.py`](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/app/main.py) (AgentOS application), [`packages/server/src/ibmi-mcp-server/tools`](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/ibmi-mcp-server/tools) (SQL operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP server"]
  node_server_entry["Server lifecycle<br/>[server.ts]"]
  node_transport["MCP transports"]
  node_auth["Authentication"]
  node_tool_registry["Tool registration<br/>[index.ts]"]
  node_toolsets["YAML toolsets<br/>[toolsetManager.ts]"]
  node_sql_tools["SQL operations"]
  node_query_validation["Query validation"]
  node_connection_pool["Connection pools<br/>[connectionPool.ts]"]
  node_auth_pool["Token pools"]
end

subgraph group_cli["IBM i CLI"]
  node_cli_entry["CLI commands"]
  node_cli_connection["CLI connections<br/>[connection.ts]"]
end

subgraph group_agents["Agent integrations"]
  node_agent_frameworks["Framework agents"]
  node_agent_sdk["Agent SDK"]
  node_agent_client["Python clients"]
end

subgraph group_demo["AgentOS demo"]
  node_agent_ui["Chat interface"]
  node_chat_stream["Chat streaming"]
  node_session_loader["Session loading"]
  node_agentos_app["AgentOS application<br/>[main.py]"]
  node_agent_config["Agent configuration<br/>[config_manager.py]"]
  node_agno_agents["IBM i agents<br/>[ibmi_agents.py]"]
end

node_mcp_client(("AI client"))
node_mapepire["Mapepire"]
node_db2[("Db2 for i")]
node_cli_user(("Terminal user"))
node_chat_user(("Chat user"))

node_mcp_client -->|"sends MCP requests"| node_transport
node_server_entry -->|"registers tools"| node_tool_registry
node_server_entry -->|"starts transport"| node_transport
node_transport -.->|"authenticates requests"| node_auth
node_tool_registry -->|"registers SQL tools"| node_sql_tools
node_toolsets -->|"organizes tools"| node_sql_tools
node_sql_tools -->|"executes queries"| node_connection_pool
node_query_validation -->|"checks SQL metadata"| node_connection_pool
node_auth_pool -->|"manages token pools"| node_connection_pool
node_connection_pool -->|"queries through"| node_mapepire
node_mapepire -->|"accesses"| node_db2
node_cli_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"uses connections"| node_cli_connection
node_cli_connection -->|"queries through"| node_mapepire
node_agent_frameworks -.->|"uses SDK integrations"| node_agent_sdk
node_agent_client -.->|"connects to"| node_transport
node_chat_user -->|"sends chat"| node_agent_ui
node_agent_ui -->|"streams runs"| node_chat_stream
node_session_loader -->|"loads sessions"| node_agent_ui
node_chat_stream -->|"calls AgentOS API"| node_agentos_app
node_agentos_app -->|"loads configuration"| node_agent_config
node_agentos_app -->|"registers agents"| node_agno_agents
node_agno_agents -.->|"uses agent SDK"| node_agent_sdk

click node_server_entry "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/mcp-server/server.ts"
click node_transport "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/mcp-server/transports"
click node_auth "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/ibmi-mcp-server/auth"
click node_tool_registry "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/tools/index.ts"
click node_toolsets "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/utils/config/toolsetManager.ts"
click node_sql_tools "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/ibmi-mcp-server/tools"
click node_query_validation "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/tools/validateQuery.tool.ts"
click node_connection_pool "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/services/connectionPool.ts"
click node_auth_pool "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/services/authenticatedPoolManager.ts"
click node_cli_entry "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/cli/src/commands"
click node_cli_connection "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/cli/src/utils/connection.ts"
click node_agent_frameworks "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/agents/frameworks"
click node_agent_sdk "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/agents/packages/ibmi-agent-sdk/src"
click node_agent_client "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/client"
click node_agent_ui "https://github.com/bezouwenr/ibmi-mcp-server/tree/main/app/agent-ui/src/components/chat"
click node_chat_stream "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agent-ui/src/hooks/useAIStreamHandler.tsx"
click node_session_loader "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agent-ui/src/hooks/useSessionLoader.tsx"
click node_agentos_app "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/app/main.py"
click node_agent_config "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/infra/config_manager.py"
click node_agno_agents "https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agents/ibmi_agents.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_transport,node_auth,node_tool_registry,node_toolsets,node_sql_tools,node_query_validation,node_connection_pool,node_auth_pool,node_mcp_client,node_cli_user,node_chat_user toneBlue
class node_cli_entry,node_cli_connection,node_db2 toneAmber
class node_agent_frameworks,node_agent_sdk,node_agent_client toneMint
class node_agent_ui,node_chat_stream,node_session_loader,node_agentos_app,node_agent_config,node_agno_agents toneRose
class node_mapepire toneIndigo
```

## Components

### MCP server

- [Server lifecycle](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/mcp-server/server.ts): `packages/server/src/mcp-server/server.ts`
- [MCP transports](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/mcp-server/transports): `packages/server/src/mcp-server/transports`
- [Authentication](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/ibmi-mcp-server/auth): `packages/server/src/ibmi-mcp-server/auth`
- [Tool registration](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/tools/index.ts): `packages/server/src/ibmi-mcp-server/tools/index.ts`
- [YAML toolsets](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/utils/config/toolsetManager.ts): `packages/server/src/ibmi-mcp-server/utils/config/toolsetManager.ts`
- [SQL operations](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/server/src/ibmi-mcp-server/tools): `packages/server/src/ibmi-mcp-server/tools`
- [Query validation](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/tools/validateQuery.tool.ts): `packages/server/src/ibmi-mcp-server/tools/validateQuery.tool.ts`
- [Connection pools](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/services/connectionPool.ts): `packages/server/src/ibmi-mcp-server/services/connectionPool.ts`
- [Token pools](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/server/src/ibmi-mcp-server/services/authenticatedPoolManager.ts): `packages/server/src/ibmi-mcp-server/services/authenticatedPoolManager.ts`

### IBM i CLI

- [CLI commands](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/packages/cli/src/commands): `packages/cli/src/commands`
- [CLI connections](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/packages/cli/src/utils/connection.ts): `packages/cli/src/utils/connection.ts`

### Agent integrations

- [Framework agents](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/agents/frameworks): `agents/frameworks`
- [Agent SDK](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/agents/packages/ibmi-agent-sdk/src): `agents/packages/ibmi-agent-sdk/src`
- [Python clients](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/client): `client`

### AgentOS demo

- [Chat interface](https://github.com/bezouwenr/ibmi-mcp-server/tree/main/app/agent-ui/src/components/chat): `app/agent-ui/src/components/chat`
- [Chat streaming](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agent-ui/src/hooks/useAIStreamHandler.tsx): `app/agent-ui/src/hooks/useAIStreamHandler.tsx`
- [Session loading](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agent-ui/src/hooks/useSessionLoader.tsx): `app/agent-ui/src/hooks/useSessionLoader.tsx`
- [AgentOS application](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/app/main.py): `app/app/main.py`
- [Agent configuration](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/infra/config_manager.py): `app/infra/config_manager.py`
- [IBM i agents](https://github.com/bezouwenr/ibmi-mcp-server/blob/main/app/agents/ibmi_agents.py): `app/agents/ibmi_agents.py`

### Other components

- **AI client**
- **Mapepire**
- **Db2 for i**
- **Terminal user**
- **Chat user**

## Connections

- AI client → MCP transports: sends MCP requests
- Server lifecycle → Tool registration: registers tools
- Server lifecycle → MCP transports: starts transport
- MCP transports → Authentication: authenticates requests
- Tool registration → SQL operations: registers SQL tools
- YAML toolsets → SQL operations: organizes tools
- SQL operations → Connection pools: executes queries
- Query validation → Connection pools: checks SQL metadata
- Token pools → Connection pools: manages token pools
- Connection pools → Mapepire: queries through
- Mapepire → Db2 for i: accesses
- Terminal user → CLI commands: runs commands
- CLI commands → CLI connections: uses connections
- CLI connections → Mapepire: queries through
- Framework agents → Agent SDK: uses SDK integrations
- Python clients → MCP transports: connects to
- Chat user → Chat interface: sends chat
- Chat interface → Chat streaming: streams runs
- Session loading → Chat interface: loads sessions
- Chat streaming → AgentOS application: calls AgentOS API
- AgentOS application → Agent configuration: loads configuration
- AgentOS application → IBM i agents: registers agents
- IBM i agents → Agent SDK: uses agent SDK