Ibmi MCP Server

🚀 ibmi-mcp-server

ibmi-mcp-server 是一款專為 IBM i 設計的 MCP 服務器，它提供了與 IBM i 系統交互的功能，支持多種開發場景和客戶端集成，具備模塊化架構、即時監控等特性，可幫助開發者更高效地進行系統管理和自動化操作。

🚀 快速開始

1. 安裝

克隆倉庫並安裝依賴：

git clone https://github.com/IBM/ibmi-mcp-server.git
cd ibmi-mcp-server/
npm install

2. 構建項目

npm run build
# 或者使用 'npm run rebuild' 進行全新安裝

3. 創建服務器 .env 文件

cp .env.example .env

在 .env 文件中填寫 Db2 for i 的連接詳細信息：

# IBM i DB2 for i 連接設置
# YAML SQL 工具連接 IBM i 系統所需
DB2i_HOST=
DB2i_USER=
DB2i_PASS=
DB2i_PORT=8076
DB2i_IGNORE_UNAUTHORIZED=true

更多配置選項請參考 配置 部分。

4. 運行服務器

• 通過 Stdio（默認）：

npm run start:stdio

• 通過可流式傳輸的 HTTP：

npm run start:http

默認情況下，服務器會註冊存儲在 prebuiltconfigs 目錄中的 SQL 工具。此路徑在 .env 文件（TOOLS_YAML_PATH）中設置。你可以使用 CLI 覆蓋 SQL 工具路徑：

• CLI 選項：--tools <path>

npm run start:http -- --tools <path>

• 傳輸選項：--transport <type>

npm run start:http -- --transport http # 或 stdio

5. 運行示例代理

確保服務器以 http 模式運行：

npm run start:http

在另一個終端中，導航到 tests/agents 目錄，並按照 README 中的設置說明進行操作。

運行示例代理

cd tests/agents
export OPENAI_API_KEY=your_open_ai_key
uv run agent.py -p "What is my system status?"

運行示例腳本

cd tests/agents

# 查看已配置工具的列表
uv run test_tool_annotations.py

# 查看服務器資源列表
uv run test_toolset_resources.py

注意：test_tool_annotations.py 和 run test_toolset_resources.py 不需要 OpenAI API 密鑰。

6. 運行測試

本模板使用 Vitest 進行測試，重點強調 集成測試，以確保所有組件能正確協同工作。

• 一次性運行所有測試：

npm test

• 以監聽模式運行測試：

npm run test:watch

• 運行測試並生成覆蓋率報告：

npm run test:coverage

✨ 主要特性

• 功能豐富的 MCP 服務器：具備示例工具和資源，支持 stdio 和基於 Hono 構建的 可流式傳輸的 HTTP 傳輸。
• 強大的可觀測性：內置 OpenTelemetry 用於分佈式跟蹤和指標收集，對核心模塊進行自動檢測，並對所有工具執行進行自定義跟蹤。
• 實用的生產工具：提供日誌記錄、錯誤處理、ID 生成、速率限制、請求上下文跟蹤和輸入清理等功能。
• 高度的類型安全和安全性：通過 TypeScript 進行強類型檢查和 Zod 驗證，內置安全實用工具（清理、HTTP 身份驗證中間件）。
• 統一的錯誤處理：採用一致的錯誤分類（BaseErrorCode），詳細記錄日誌，並進行集中處理（ErrorHandler）。
• 全面的文檔：包含詳盡的 README.md、結構化的 JSDoc 註釋和 API 參考。
• 詳細的交互日誌：將所有外部 LLM 提供商交互的原始請求和響應捕獲到專用的 interactions.log 文件中，實現完全可追溯性。
• 支持智能代理：包含為 LLM 編碼代理量身定製的 .clinerules 開發速查表。
• 便捷的實用腳本：提供用於清理構建、設置可執行權限、生成目錄樹和獲取 OpenAPI 規範的腳本。
• 可複用的服務模塊：提供用於 LLM（OpenRouter）和數據存儲（DuckDB）集成的可複用模塊及示例。
• 高效的集成測試：與 Vitest 集成，實現快速可靠的集成測試，包含核心邏輯的示例測試和覆蓋率報告。
• 精準的性能指標：內置實用工具，自動測量和記錄每個工具調用的執行時間和有效負載大小。

📦 安裝指南

本地安裝前提條件

對於本地開發，使用 npm link 全局安裝服務器：

# 從 ibmi-mcp-server 目錄執行
npm install
npm run build
npm link

這將使 ibmi-mcp-server 命令在你的機器上全局可用。鏈接完成後，你可以在任何客戶端配置中使用 npx ibmi-mcp-server。

注意：TOOLS_YAML_PATH 必須是工具配置目錄的 絕對路徑（例如，/full/path/to/prebuiltconfigs）。

遠程服務器設置

對於 HTTP 遠程連接，你需要：

1. 啟動啟用 IBM i 身份驗證的服務器：

# 確保你的 .env 文件包含以下設置
MCP_AUTH_MODE=ibmi
IBMI_HTTP_AUTH_ENABLED=true
IBMI_AUTH_ALLOW_HTTP=true  # 僅用於開發！

npm run start:http

2. 獲取訪問令牌：

# 使用令牌腳本進行身份驗證
node get-access-token.js --verbose

# 或者直接在環境中設置
export IBMI_MCP_ACCESS_TOKEN="your-token-here"

詳細的身份驗證設置請參考 IBM i HTTP 身份驗證。 3. 使用服務器 URL 和 Bearer 令牌配置你的客戶端（示例如下）。

⚠️ 生產環境注意事項：將 http://localhost:3010 替換為你的生產端點 URL，並確保啟用 HTTPS（IBMI_AUTH_ALLOW_HTTP=false）。

客戶端配置

# 添加本地 stdio 服務器
claude mcp add ibmi-mcp \
  --env DB2i_HOST=your-ibmi-host.com \
  --env DB2i_USER=your-username \
  --env DB2i_PASS=your-password \
  --env DB2i_PORT=8076 \
  --env MCP_TRANSPORT_TYPE=stdio \
  -- npx ibmi-mcp-server --tools /absolute/path/to/prebuiltconfigs

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio",
        "NODE_OPTIONS": "--no-deprecation"
      }
    }
  }
}

# 添加帶有身份驗證的遠程 HTTP 服務器
claude mcp add --transport http ibmi-mcp http://localhost:3010/mcp \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "${IBMI_TOOLS_PATH}"],
      "env": {
        "DB2i_HOST": "${DB2i_HOST}",
        "DB2i_USER": "${DB2i_USER}",
        "DB2i_PASS": "${DB2i_PASS}",
        "DB2i_PORT": "${DB2i_PORT:-8076}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

# 列出已配置的服務器
claude mcp list

# 獲取服務器詳細信息
claude mcp get ibmi-mcp

# 刪除服務器
claude mcp remove ibmi-mcp

# 在 Claude Code 中檢查服務器狀態
/mcp

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

# 添加本地 stdio 服務器
code --add-mcp '{
  "name": "ibmiMcp",
  "type": "stdio",
  "command": "npx",
  "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
  "env": {
    "DB2i_HOST": "your-ibmi-host.com",
    "DB2i_USER": "your-username",
    "DB2i_PASS": "your-password",
    "DB2i_PORT": "8076",
    "MCP_TRANSPORT_TYPE": "stdio"
  }
}'

{
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

# 添加遠程 HTTP 服務器
code --add-mcp '{
  "name": "ibmiMcp",
  "type": "http",
  "url": "http://localhost:3010/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
  }
}'

{
  "servers": {
    "ibmiMcp": {
      "type": "http",
      "url": "http://localhost:3010/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "db2iHost",
      "type": "promptString",
      "description": "IBM i DB2 host address"
    },
    {
      "id": "db2iUser",
      "type": "promptString",
      "description": "IBM i username"
    },
    {
      "id": "db2iPass",
      "type": "promptString",
      "description": "IBM i password",
      "password": true
    }
  ],
  "servers": {
    "ibmiMcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "${input:db2iHost}",
        "DB2i_USER": "${input:db2iUser}",
        "DB2i_PASS": "${input:db2iPass}",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio",
        "NODE_OPTIONS": "--no-deprecation"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ibmi-mcp": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "environment": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      },
      "enabled": true
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ibmi-mcp": {
      "type": "remote",
      "enabled": true,
      "url": "http://localhost:3010/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["ibmi-mcp-server", "--tools", "/absolute/path/to/prebuiltconfigs"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "ibmi-mcp": {
      "url": "http://localhost:3010/mcp",
      "type": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

import asyncio
import os
from agno.agent import Agent
from agno.tools.mcp import MCPTools, StreamableHTTPClientParams

# 從環境中獲取訪問令牌
token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
if not token:
    raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")

url = "http://localhost:3010/mcp"
server_params = StreamableHTTPClientParams(
    url=url,
    headers={"Authorization": f"Bearer {token}"}
)

async def main():
    async with MCPTools(
        url=url,
        server_params=server_params,
        transport="streamable-http"
    ) as tools:
        # 列出可用工具
        result = await tools.session.list_tools()
        print(f"Available tools: {[t.name for t in result.tools]}")

        # 創建代理
        agent = Agent(
            model="openai:gpt-4o",  # 或你喜歡的模型
            tools=[tools],
            name="ibmi-agent",
            show_tool_calls=True
        )

        # 運行查詢
        await agent.aprint_response("What is the system status?")

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
    if not token:
        raise ValueError("IBMI_MCP_ACCESS_TOKEN not set")

    headers = {"Authorization": f"Bearer {token}"}

    async with streamablehttp_client(
        "http://localhost:3010/mcp",
        headers=headers
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # 列出工具
            tools = await session.list_tools()
            print(f"Tools: {[t.name for t in tools.tools]}")

            # 執行工具
            result = await session.call_tool("system_status", {})
            print(result)

if __name__ == "__main__":
    asyncio.run(main())

故障排除

連接問題：

• 驗證 npm link 是否成功：which ibmi-mcp-server
• 檢查 TOOLS_YAML_PATH 是否為絕對路徑
• 確保 IBM i 憑據正確

身份驗證失敗（遠程）：

• 確認服務器以 IBMI_HTTP_AUTH_ENABLED=true 運行
• 驗證令牌是否有效：echo $IBMI_MCP_ACCESS_TOKEN
• 檢查服務器日誌中的身份驗證錯誤

工具加載錯誤：

• 驗證 YAML 配置：npm run validate -- --config prebuiltconfigs
• 檢查工具目錄的文件權限
• 查看服務器啟動日誌中的解析錯誤

🤖 IBM i 代理

IBM i 代理是專門設計用於與 IBM i 系統交互的組件，提供監控、管理和自動化等功能。

關鍵特性

• 與 IBM i 集成：與 IBM i 系統 API 和工具無縫集成。
• 模塊化架構：易於擴展和定製，以適應特定用例。
• 即時監控：持續監控系統性能和健康狀況。

開始使用

導航到 agents 目錄，並按照 README 中的設置說明進行操作。這包括配置、運行代理和示例的詳細信息。大多數代理示例要求 MCP 服務器以 HTTP 模式運行。請閱讀每個代理示例的文檔以獲取詳細信息。

⚙️ 配置

使用以下環境變量（或 .env 文件）配置服務器：

要設置服務器環境變量，請在項目根目錄下創建一個 .env 文件：

cp .env.example .env
code .env

然後在 .env 文件中編輯你的 IBM i 連接詳細信息。

🔐 IBM i HTTP 身份驗證（Beta）

服務器支持 IBM i HTTP 身份驗證，允許客戶端獲取訪問令牌以執行經過身份驗證的 SQL 工具。這實現了按用戶連接池和對 IBM i 資源的安全訪問。

身份驗證流程

1. 客戶端身份驗證：客戶端通過 HTTP 基本身份驗證使用 IBM i 憑據進行身份驗證。
2. 令牌生成：服務器創建一個安全的 Bearer 令牌，並建立專用連接池。
3. 工具執行：後續工具調用使用 Bearer 令牌進行身份驗證執行。
4. 池管理：每個令牌維護自己的連接池，以實現隔離和安全。

配置

要啟用 IBM i HTTP 身份驗證，我們需要設置加密密鑰並配置服務器環境。為了在傳輸過程中保護 IBM i 憑據，身份驗證流程使用 RSA 和 AES 加密。你需要為服務器生成一個 RSA 密鑰對：

mkdir -p secrets
openssl genpkey -algorithm RSA -out secrets/private.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in secrets/private.pem -out secrets/public.pem

在 .env 文件中創建或更新以下設置：

# 啟用 IBM i 身份驗證系統
IBMI_HTTP_AUTH_ENABLED=true
MCP_AUTH_MODE=ibmi

# IBM i 身份驗證設置
IBMI_AUTH_KEY_ID=development
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# 安全設置
IBMI_AUTH_ALLOW_HTTP=true          # 僅用於開發 - 生產環境使用 HTTPS
IBMI_AUTH_TOKEN_EXPIRY_SECONDS=3600 # 令牌有效期（1 小時）

# 資源管理
IBMI_AUTH_MAX_CONCURRENT_SESSIONS=100
IBMI_AUTH_CLEANUP_INTERVAL_SECONDS=300

# IBM i 連接詳細信息
DB2i_HOST=your-ibmi-host
DB2i_USER=your-username
DB2i_PASS=your-password

獲取訪問令牌

選項 1：使用令牌腳本（推薦）

使用包含的 get-access-token.js 腳本來獲取身份驗證令牌：

# 使用 .env 文件中的憑據
node get-access-token.js --verbose

# 使用 CLI 參數（覆蓋 .env）
node get-access-token.js --user myuser --password mypass --host my-ibmi-host

# 靜默模式，用於 shell 評估
eval $(node get-access-token.js --quiet)
echo $IBMI_MCP_ACCESS_TOKEN

該腳本自動執行以下操作：

• 從 .env 加載 IBM i 憑據，支持 CLI 回退
• 獲取服務器的公鑰
• 在客戶端加密憑據
• 請求訪問令牌
• 設置 IBMI_MCP_ACCESS_TOKEN 環境變量
• 提供可複製粘貼的導出命令

序列概述

sequenceDiagram
    participant CLI as Client CLI
    participant Auth as MCP Server (/api/v1/auth)
    participant IBM as IBM i

    CLI->>Auth: GET /api/v1/auth/public-key
    Auth-->>CLI: { keyId, publicKey }

    CLI->>CLI: Generate AES-256-GCM session key + IV
    CLI->>CLI: Encrypt credentials + request body with session key
    CLI->>CLI: Encrypt session key with server public key (RSA-OAEP)

    CLI->>Auth: POST /api/v1/auth { keyId, encryptedSessionKey, iv, authTag, ciphertext }
    Auth->>Auth: Look up keyId, decrypt session key with private key
    Auth->>Auth: Decrypt ciphertext, validate GCM tag, validate payload

    Auth->>IBM: Authenticate against IBM i with decrypted credentials
    IBM-->>Auth: Success/Failure

    Auth->>Auth: Generate access token, provision pool session
    Auth-->>CLI: 201 JSON { access_token, expires_in, ... }

客戶端集成

獲得令牌後，在 MCP 客戶端中使用它來對請求進行身份驗證：

import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    # 從環境中獲取訪問令牌
    token = os.environ.get('IBMI_MCP_ACCESS_TOKEN')
    if not token:
        raise ValueError("IBMI_MCP_ACCESS_TOKEN environment variable not set")

    # 設置身份驗證頭
    headers = {"Authorization": f"Bearer {token}"}

    # 連接到經過身份驗證的 IBM i MCP 服務器
    async with streamablehttp_client(
        "http://localhost:3010/mcp",
        headers=headers
    ) as (read_stream, write_stream, _):
        # 使用經過身份驗證的流創建會話
        async with ClientSession(read_stream, write_stream) as session:
            # 初始化連接
            await session.initialize()

            # 列出可用工具（現在使用你的 IBM i 憑據進行身份驗證）
            tools = await session.list_tools()
            print(f"Available tools: {[tool.name for tool in tools.tools]}")

            # 執行經過身份驗證的 IBM i 訪問工具
            result = await session.call_tool("system_status", {})
            print(f"System status result: {result}")

if __name__ == "__main__":
    asyncio.run(main())

安全考慮

開發環境：

• IBMI_AUTH_ALLOW_HTTP=true 允許 HTTP 進行測試
• 僅使用本地主機/受信任的網絡
• 縮短令牌有效期進行測試

生產環境：

• IBMI_AUTH_ALLOW_HTTP=false 強制使用 HTTPS
• 使用適當的 TLS 證書
• 延長令牌有效期以確保穩定性
• 進行網絡安全和訪問控制
• 監控 IBMI_AUTH_MAX_CONCURRENT_SESSIONS 以瞭解資源使用情況

身份驗證端點

啟用（IBMI_HTTP_AUTH_ENABLED=true）時，服務器提供以下端點：

🧩 SQL 工具配置

配置此 MCP 服務器使用的工具的主要方法是通過 tools.yaml 文件（請參閱 prebuiltconfigs/ 中的示例）。每個 yaml 文件有 3 個主要部分：sources、tools 和 toolsets。以下是每個部分的詳細說明。

數據源

tools.yaml 的 sources 部分定義了 MCP 服務器可以訪問的數據源。

sources:
  ibmi-system:
    host: ${DB2i_HOST}
    user: ${DB2i_USER}
    password: ${DB2i_PASS}
    port: 8076
    ignore-unauthorized: true

[!NOTE] 環境變量 DB2i_HOST、DB2i_USER、DB2i_PASS 和 DB2i_PORT 可以在服務器 .env 文件中設置。請參閱 配置。

工具

tools.yaml 的 tools 部分定義了代理可以執行的操作：工具類型、影響的數據源、使用的參數等。

tools:
  system_status:
    source: ibmi-system
    description: "Overall system performance statistics with CPU, memory, and I/O metrics"
    parameters: []
    statement: |
      SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=>'YES',DETAILED_INFO=>'ALL')) X

工具集

tools.yaml 的 toolsets 部分允許你定義可以一起加載的工具組。這對於為不同的代理或應用程序定義不同的工具集很有用。

toolsets:
  performance:
    tools:
      - system_status
      - system_activity
      - remote_connections
      - memory_pools
      - temp_storage_buckets
      - unnamed_temp_storage
      - http_server
      - system_values
      - collection_services
      - collection_categories
      - active_job_info

更多關於 SQL 工具的文檔即將推出！

🚀 運行服務器（開發）

服務器支持多種傳輸模式和會話配置，以適應不同的開發場景。根據你的需求使用相應的啟動命令。

傳輸模式

HTTP 傳輸（開發推薦）

# 基本 HTTP 服務器
npm run start:http

# 帶有自定義工具路徑的 HTTP
npm run start:http -- --tools ./my-configs

# 帶有特定工具集的 HTTP
npm run start:http -- --toolsets performance,monitoring

Stdio 傳輸（用於 CLI 工具和 MCP 檢查器）

# 基本 stdio 傳輸
npm run start:stdio

# 帶有自定義工具路徑的 stdio
npm run start:stdio -- --tools ./my-custom-tools

會話模式（僅 HTTP）

MCP_SESSION_MODE 環境變量控制 HTTP 服務器如何處理客戶端會話：

• auto（默認）：自動檢測客戶端功能並使用最佳會話模式。
• stateful：維護具有連接狀態的持久會話。
• stateless：每個請求都是獨立的，不維護會話狀態。

# 通過環境變量設置會話模式
MCP_SESSION_MODE=stateful npm run start:http

# 或者在 .env 文件中設置
echo "MCP_SESSION_MODE=stateful" >> .env
npm run start:http

CLI 選項

兩種傳輸模式都支持以下命令行選項：

注意：提供 CLI 參數時，將覆蓋 .env 文件中的相應設置。 | 選項 | 短選項 | 描述 | 示例 | | ---- | ---- | ---- | ---- | | --tools <path> | | 覆蓋 YAML 工具配置路徑（覆蓋 TOOLS_YAML_PATH） | --tools ./custom-configs | | --toolsets <list> | -ts | 僅加載特定的工具集（用逗號分隔）（覆蓋 SELECTED_TOOLSETS） | --toolsets performance,security | | --transport <type> | -t | 強制傳輸類型（http 或 stdio）（覆蓋 MCP_TRANSPORT_TYPE） | --transport http | | --help | -h | 顯示幫助信息 | --help | | --list-toolsets | | 列出 YAML 配置中可用的工具集 | --list-toolsets |

常見開發場景

1. 標準開發服務器

npm run start:http
# 服務器：http://localhost:3010/mcp
# 工具：prebuiltconfigs/（來自 .env）
# 會話：自動檢測

2. 自定義工具路徑

npm run start:http -- --tools ./my-tools
# 服務器：http://localhost:3010/mcp（端口來自 .env 或默認值）
# 工具：./my-tools

3. 僅加載特定工具集

npm run start:http -- --toolsets performance,monitoring
# 僅加載 'performance' 和 'monitoring' 工具集中的工具

開發提示

• 熱重載：在 .env 中啟用 YAML_AUTO_RELOAD=true 以自動更新工具配置。
• 詳細日誌記錄：設置 MCP_LOG_LEVEL=debug 以獲取詳細的操作日誌。
• CORS：為基於 Web 的客戶端配置 MCP_ALLOWED_ORIGINS。
• 身份驗證：使用 MCP_AUTH_MODE=ibmi 和 IBM i HTTP 身份驗證進行基於令牌的訪問。

故障排除

端口已被使用

# 在 .env 文件中配置端口
echo "MCP_HTTP_PORT=3011" >> .env
npm run start:http

工具未加載

# 檢查工具路徑
npm run start:http -- --tools ./prebuiltconfigs

# 先列出可用的工具集
npm run start:http -- --list-toolsets --tools ./prebuiltconfigs

# 獲取幫助
npm run start:http -- --help

🕵️‍♂️ MCP 檢查器

MCP 檢查器是一個用於探索和調試 MCP 服務器功能的工具。它提供了一個用戶友好的界面，用於與服務器交互、查看可用工具和測試查詢。

以下是運行 MCP 檢查器的步驟：

1. 確保構建服務器

cd ibmi-mcp-server/
npm run build

2. 創建 mcp.json 文件

cp template_mcp.json mcp.json

在 mcp.json 中填寫與你的 IBM i 系統信息的連接詳細信息。你應該使用與 .env 文件中相同的憑據：

{
  "mcpServers": {
    "default-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "TOOLS_YAML_PATH": "prebuiltconfigs",
        "NODE_OPTIONS": "--no-deprecation",
        "DB2i_HOST": "<DB2i_HOST>",
        "DB2i_USER": "<DB2i_USER>",
        "DB2i_PASS": "<DB2i_PASS>",
        "DB2i_PORT": "<DB2i_PORT>",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

3. 啟動 MCP 檢查器

npm run mcp-inspector

4. 點擊終端中顯示的 URL，在瀏覽器中打開 MCP 檢查器

Starting MCP inspector...
⚙️ Proxy server listening on 127.0.0.1:6277
🔑 Session token: EXAMPLE_TOKEN
Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth

🔗 Open inspector with token pre-filled:
  http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=EXAMPLE_TOKEN

🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

5. 使用 MCP 檢查器探索和測試 MCP 服務器的功能

• 查看可用工具及其參數
• 對服務器進行測試查詢
• 調試工具執行問題

Docker & Podman 部署

項目包含一個全面的 docker-compose.yml，用於設置完整的 MCP 網關和 IBM i MCP 服務器。

ContextForge MCP 網關是一個功能豐富的網關、代理和 MCP 註冊表，它聯合了 MCP 和 REST 服務 - 將發現、身份驗證、速率限制、可觀測性、虛擬服務器、多傳輸協議和可選的管理 UI 統一到一個簡潔的端點，供你的 AI 客戶端使用。

更多信息請閱讀 此處。

前提條件

選擇以下容器平臺之一：

Docker

• Docker Desktop（macOS/Windows）：在此下載
• Docker Engine（Linux）：安裝指南

Podman（Docker 的替代方案）

• Podman Desktop（macOS/Windows）：在此下載
• Podman CLI（Linux）：安裝指南
• podman-compose：pip install podman-compose

構建 MCP 網關鏡像

docker-compose.yml 使用 MCP 網關鏡像的本地構建。要構建它，請克隆 MCP 網關存儲庫並構建鏡像：

git clone https://github.com/IBM/mcp-context-forge.git
cd mcp-context-forge

# 使用 Docker 構建鏡像
make docker-prod

# 或者使用 Podman 構建鏡像
make podman-prod

這將創建一個名為 localhost/mcpgateway/mcpgateway 的本地鏡像，docker-compose.yml 可以使用該鏡像。有關構建 MCP 網關鏡像的更多詳細信息，請參閱 MCP 網關文檔。

配置 MCP 環境

在 ibmi-mcp-server 目錄中創建一個 .env 文件，並填寫你的 IBM i 連接詳細信息：

cd ibmi-mcp-server/
cp .env.example .env
# 編輯 .env 文件，填寫你的 IBM i 連接詳細信息
code .env

確保在 .env 文件中設置以下變量：

# IBM i 連接詳細信息
DB2i_HOST="your_host"
DB2i_USER="your_user"
DB2i_PASS="your_pass"

# MCP 身份驗證模式
MCP_AUTH_MODE=ibmi

# IBM i HTTP 身份驗證設置
IBMI_AUTH_KEY_ID=development
IBMI_AUTH_PRIVATE_KEY_PATH=secrets/private.pem
IBMI_AUTH_PUBLIC_KEY_PATH=secrets/public.pem

# 啟用 IBM i HTTP 身份驗證端點（需要 MCP_AUTH_MODE=ibmi）
IBMI_HTTP_AUTH_ENABLED=true

# 允許 HTTP 請求進行身份驗證（僅用於開發，生產環境使用 HTTPS）
IBMI_AUTH_ALLOW_HTTP=true

注意：如果你尚未為服務器生成 RSA 密鑰對，則需要進行生成。有關說明，請參閱 IBM i HTTP 身份驗證 部分。

配置好 .env 文件後，你可以使用 Docker 或 Podman 啟動完整的堆棧。

使用 Docker 快速啟動

1. 啟動完整堆棧：

# 在後臺啟動所有服務
docker-compose up -d

# 或者啟動特定服務
docker-compose up -d gateway ibmi-mcp-server postgres redis

2. 驗證服務是否正在運行：

docker-compose ps

使用 Podman 快速啟動

1. 啟動完整堆棧：

# 在後臺啟動所有服務
podman compose up -d

# 或者啟動特定服務
podman compose up -d gateway ibmi-mcp-server postgres redis

2. 驗證服務是否正在運行：

podman compose ps

容器架構

docker-compose 設置包括以下服務：

🔧 服務管理

啟動服務

# Docker
docker-compose up -d                    # 啟動所有服務
docker-compose up -d gateway            # 啟動特定服務
docker-compose up --no-deps gateway     # 不啟動依賴項啟動服務

# Podman
podman compose up -d                    # 啟動所有服務
podman compose up -d gateway            # 啟動特定服務
podman compose up --no-deps gateway     # 不啟動依賴項啟動服務

停止服務

# Docker
docker-compose down                     # 停止所有服務
docker-compose stop gateway             # 停止特定服務

# Podman
podman compose down                     # 停止所有服務
podman compose stop gateway             # 停止特定服務

查看日誌

# Docker
docker-compose logs -f gateway          # 跟蹤網關日誌
docker-compose logs --tail=100 ibmi-mcp-server

# Podman
podman compose logs -f gateway          # 跟蹤網關日誌
podman compose logs --tail=100 ibmi-mcp-server

重建服務

# Docker
docker-compose build ibmi-mcp-server    # 重建特定服務
docker-compose up --build -d            # 重建並重啟所有服務

# Podman
podman compose build ibmi-mcp-server    # 重建特定服務
podman compose up --build -d            # 重建並重啟所有服務

MCP 網關 UI

容器啟動並運行後，你可以在 http://localhost:4444 訪問 MCP Context Forge UI。

輸入演示憑據：

• 用戶：admin
• 密碼：changeme

要在管理 UI 中配置 IBM i MCP 服務器，請導航到 "Gateways/MCP Servers" 選項卡，並輸入 mcp 服務器端點：

• IBM i mcp 服務器端點：http://ibmi-mcp-server:3010 MCP 服務器連接成功後，你可以管理服務器提供的工具：

虛擬服務器目錄演示（即將推出！！）

架構概述

本模板基於一組架構原則構建，以確保模塊化、可測試性和操作清晰性。

• 核心服務器 (src/mcp-server/server.ts)：工具和資源註冊的中心點。它使用 ManagedMcpServer 包裝器提供增強的自省功能。其行為與原生 McpServer 相同，但具有自省和增強的錯誤處理等額外功能。
• 傳輸層 (src/mcp-server/transports/)：傳輸層將核心服務器連接到外部世界。它支持 stdio 用於直接進程通信和基於 Hono 的可流式傳輸 http 服務器。
• “邏輯拋出，處理程序捕獲”：這是我們錯誤處理策略的不變基石。
  • 核心邏輯 (logic.ts)：該層負責純粹的、自包含的業務邏輯。在任何失敗時，它 拋出 一個結構化的 McpError。
  • 處理程序 (registration.ts)：該層與服務器接口，調用核心邏輯，並 捕獲 任何錯誤。它是處理和格式化錯誤為最終響應的唯一位置。
• 結構化、可跟蹤的操作：每個操作通過 RequestContext 從啟動到完成進行跟蹤，該上下文貫穿整個調用棧，確保全面和結構化的日誌記錄。

關鍵特性

項目結構

• src/mcp-server/：包含核心 MCP 服務器、工具、資源和傳輸處理程序。
• src/config/：處理環境變量的加載和驗證。
• src/services/：提供用於集成外部服務（DuckDB、OpenRouter）的可複用模塊。
• src/types-global/：定義共享的 TypeScript 接口和類型定義。
• src/utils/：核心實用工具（日誌記錄、錯誤處理、安全等）。
• src/index.ts：初始化並啟動服務器的主入口點。

自行探索完整結構： 查看 docs/tree.md 中的當前文件樹，或動態生成它：

npm run tree

擴展系統

模板強制執行嚴格的模塊化模式，用於添加新工具和資源，這是 架構標準 所要求的。echoTool (src/mcp-server/tools/echoTool/) 是標準示例。

“邏輯拋出，處理程序捕獲” 模式

這是架構的基石：

1. logic.ts：此文件包含純粹的業務邏輯。

• 它定義輸入和輸出的 Zod 模式，作為工具數據契約的唯一真相來源。
• 核心邏輯函數是純粹的：它接受經過驗證的參數和請求上下文，並在失敗時 拋出 一個結構化的 McpError。
• 它 從不 包含用於格式化最終響應的 try...catch 塊。

2. registration.ts：此文件是將邏輯連接到 MCP 服務器的 “處理程序”。

• 它從 logic.ts 導入模式和邏輯函數。
• 它調用 server.registerTool()，提供工具的元數據和運行時處理程序。
• 運行時處理程序 始終 將對邏輯函數的調用包裝在 try...catch 塊中。這是 唯一 捕獲、由 ErrorHandler 處理並將錯誤格式化為標準化錯誤響應的位置。

這種模式確保核心邏輯保持解耦、純粹且易於測試，而註冊層處理所有傳輸級別的問題、副作用和響應格式化。

📄 許可證

本項目根據 Apache 許可證 2.0 授權。詳情請參閱 LICENSE 文件。