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 文件）配置服务器： | 变量 | 描述 | 默认值 | | ---- | ---- | ---- | | MCP_TRANSPORT_TYPE | 服务器传输方式：stdio 或 http。 | stdio | | MCP_SESSION_MODE | HTTP 会话模式：stateless、stateful 或 auto。 | auto | | MCP_HTTP_PORT | HTTP 服务器端口。 | 3010 | | MCP_HTTP_HOST | HTTP 服务器主机地址。 | 127.0.0.1 | | MCP_ALLOWED_ORIGINS | CORS 允许的源，用逗号分隔。 | （无） | | MCP_AUTH_MODE | HTTP 身份验证模式：jwt、oauth、ibmi 或 none。 | none | | MCP_AUTH_SECRET_KEY | jwt 模式必需。用于签署/验证身份验证令牌的密钥（至少 32 个字符）。 | （无 - 生产环境必须设置） | | OAUTH_ISSUER_URL | oauth 模式必需。授权服务器的发行者 URL。 | （无） | | OAUTH_AUDIENCE | oauth 模式必需。此 MCP 服务器的受众标识符。 | （无） | | OPENROUTER_API_KEY | OpenRouter.ai 服务的 API 密钥。 | （无） | | OTEL_ENABLED | 设置为 true 以启用 OpenTelemetry 检测。 | false | | OTEL_EXPORTER_OTLP_TRACES_ENDPOINT | 用于导出跟踪的 OTLP 端点（例如，http://localhost:4318/v1/traces）。 | （无；记录到文件） | | OTEL_EXPORTER_OTLP_METRICS_ENDPOINT | 用于导出指标的 OTLP 端点（例如，http://localhost:4318/v1/metrics）。 | （无） | | TOOLS_YAML_PATH | YAML 工具定义的路径（文件或目录）。支持目录或通配符。 | （无） | | YAML_MERGE_ARRAYS | 合并多个 YAML 文件时，合并数组（true）而不是替换它们。 | false | | YAML_ALLOW_DUPLICATE_TOOLS | 允许合并的 YAML 文件中存在重复的工具名称。 | false | | YAML_ALLOW_DUPLICATE_SOURCES | 允许合并的 YAML 文件中存在重复的源名称。 | false | | YAML_VALIDATE_MERGED | 在使用前验证合并后的 YAML 配置。 | true | | YAML_AUTO_RELOAD | 启用 YAML 工具在配置文件更改时自动重新加载。 | true | | SELECTED_TOOLSETS | 要加载/过滤工具的工具集名称列表，用逗号分隔（覆盖全量加载）。 | （无） | | DB2i_HOST | IBM i Db2 for i 主机（Mapepire 守护程序或网关主机）。 | （无） | | DB2i_USER | IBM i 用户配置文件，用于 Db2 for i 连接。 | （无） | | DB2i_PASS | IBM i 用户配置文件的密码。 | （无） | | DB2i_PORT | 用于 Db2 for i 的 Mapepire 守护程序/网关端口。 | 8076 | | DB2i_IGNORE_UNAUTHORIZED | 如果为 true，则跳过 Mapepire 的 TLS 证书验证（自签名证书等）。 | true | | IBMI_HTTP_AUTH_ENABLED | ibmi 身份验证模式必需。启用 IBM i HTTP 身份验证端点。 | false | | IBMI_AUTH_ALLOW_HTTP | 允许 HTTP 请求进行身份验证（仅用于开发，生产环境使用 HTTPS）。 | false | | IBMI_AUTH_TOKEN_EXPIRY_SECONDS | IBM i 身份验证令牌的默认有效期（秒）。 | 3600（1 小时） | | IBMI_AUTH_CLEANUP_INTERVAL_SECONDS | 清理过期令牌的频率（秒）。 | 300（5 分钟） | | IBMI_AUTH_MAX_CONCURRENT_SESSIONS | 允许的最大并发身份验证会话数。 | 100 |

要设置服务器环境变量，请在项目根目录下创建一个 .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）时，服务器提供以下端点： | 端点 | 方法 | 描述 | | ---- | ---- | ---- | | /api/v1/auth | POST | 使用 IBM i 凭据进行身份验证并接收 Bearer 令牌 |

🧩 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 设置包括以下服务： | 服务 | 端口 | 描述 | 访问 URL | | ---- | ---- | ---- | ---- | | gateway | 4444 | MCP Context Forge 主 API | http://localhost:4444 | | ibmi-mcp-server | 3010 | IBM i SQL 工具 MCP 服务器 | http://localhost:3010 | | postgres | - | PostgreSQL 数据库（内部） | - | | redis | 6379 | 缓存服务 | redis://localhost:6379 | | pgadmin | 5050 | 数据库管理 UI | http://localhost:5050 | | redis_insight | 5540 | 缓存管理 UI | http://localhost:5540 |

🔧 服务管理

启动服务

# 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 从启动到完成进行跟踪，该上下文贯穿整个调用栈，确保全面和结构化的日志记录。

关键特性

| 功能领域 | 描述 | 关键组件/位置 | | ---- | ---- | ---- | | 🔌 MCP 服务器 | 一个具有示例工具和资源的功能服务器。支持 stdio 和使用 Hono 构建的 可流式传输的 HTTP 传输。 | src/mcp-server/, src/mcp-server/transports/ | | 🔭 可观测性 | 内置 OpenTelemetry 用于分布式跟踪和指标收集。对核心模块进行自动检测，并对所有工具执行进行自定义跟踪。 | src/utils/telemetry/ | | 🚀 生产工具 | 提供日志记录、错误处理、ID 生成、速率限制、请求上下文跟踪和输入清理等功能。 | src/utils/ | | 🔒 类型安全/安全性 | 通过 TypeScript 进行强类型检查和 Zod 验证。内置安全实用工具（清理、HTTP 身份验证中间件）。 | 贯穿整个项目，src/utils/security/, src/mcp-server/transports/auth/ | | ⚙️ 错误处理 | 采用一致的错误分类（BaseErrorCode），详细记录日志，并进行集中处理（ErrorHandler）。 | src/utils/internal/errorHandler.ts, src/types-global/ | | 📚 文档 | 包含详尽的 README.md、结构化的 JSDoc 注释和 API 参考。 | README.md, 代码库, tsdoc.json, docs/api-references/ | | 🕵️ 交互日志 | 将所有外部 LLM 提供商交互的原始请求和响应捕获到专用的 interactions.log 文件中，实现完全可追溯性。 | src/utils/internal/logger.ts | | 🤖 支持智能代理 | 包含为 LLM 编码代理量身定制的 .clinerules 开发速查表。 | .clinerules/ | | 🛠️ 实用脚本 | 提供用于清理构建、设置可执行权限、生成目录树和获取 OpenAPI 规范的脚本。 | scripts/ | | 🧩 服务模块 | 提供用于 LLM（OpenRouter）和数据存储（DuckDB）集成的可复用模块及示例。 | src/services/, src/storage/duckdbExample.ts | | 🧪 集成测试 | 与 Vitest 集成，实现快速可靠的集成测试，包含核心逻辑的示例测试和覆盖率报告。 | vitest.config.ts, tests/ | | ⏱️ 性能指标 | 内置实用工具，自动测量和记录每个工具调用的执行时间和有效负载大小。 | src/utils/internal/performance.ts |

项目结构

• 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 文件。