内容
# Interswitch MCP 服务器
一款 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器，使 AI 助手能够与 [Interswitch API](https://docs.interswitchgroup.com/docs/home) 进行交互，用于支付、转账、VAS、无卡支付、交易查询、Card 360、贷款、结算、代理银行和金融科技卡处理实用程序。
> [!WARNING]
> **公共预览版：** 此 MCP 服务器目前处于公共预览阶段。它支持 Interswitch 沙盒和生产环境，因此请谨慎使用，首先以只读模式启动，并报告您遇到的任何问题。
## 快速入门
通过 npm 安装并运行（推荐）：
```bash
npx interswitch-mcp-server
```
或全局安装：
```bash
npm install -g interswitch-mcp-server
interswitch-mcp-server
```
或用于本地开发，克隆并构建：
```bash
git clone https://github.com/Dairus01/Interswitch-mcp-server.git
cd Interswitch-mcp-server
npm install
npm run build
```
然后配置您的 MCP 客户端以使用服务器（参见 [客户端集成](#客户端集成)）。
## 要求
- Node.js v18+
- npm 或 yarn
- 您要使用的域的 Interswitch API 凭证
- 您的用例所需的 Interswitch 商户、可支付、发起实体、终端或特定于域的标识符
## 配置选项
| 环境变量 | 用途 |
| -------------------- | ------- |
| `INTERSWITCH_CLIENT_ID` | 支付、转账、VAS、无卡、贷款、转账服务和结算的核心 OAuth2 客户端 ID |
| `INTERSWITCH_CLIENT_SECRET` | 核心 OAuth2 客户端密钥 |
| `INTERSWITCH_ENV` | API 环境：`sandbox` 或 `production`；默认为 `sandbox` |
| `INTERSWITCH_READ_ONLY` | 设置为 `true` 以阻止任何 API 调用前的写入工具；默认为 `false` |
| `INTERSWITCH_REQUIRE_CONFIRMATION` | 兼容性设置。工具确认由工具模式和风险强制执行。 |
| `INTERSWITCH_MERCHANT_CODE` | 需要它的支付操作的商户代码 |
| `INTERSWITCH_PAYABLE_CODE` | 需要它的支付操作的支付代码 |
| `INTERSWITCH_INITIATING_ENTITY_CODE` | 转账操作的发起实体代码 |
| `INTERSWITCH_TERMINAL_ID` | 需要终端识别的操作的终端 ID |
| `CARD360_CLIENT_ID` | 单独的 Card 360 客户端 ID |
| `CARD360_CLIENT_SECRET` | 单独的 Card 360 客户端密钥 |
| `CARD360_RSA_PUBLIC_KEY` | 用于本地加密 Card 360 PIN 有效载荷的 RSA 公钥 |
| `TRANSACTION_SEARCH_CLIENT_ID` | 单独的交易查询客户端 ID |
| `TRANSACTION_SEARCH_CLIENT_SECRET` | 单独的交易查询客户端密钥 |
| `INTERSWITCH_AGENCY_MERCHANT_ID` | 代理银行商户标识符 |
| `INTERSWITCH_AGENCY_TERMINAL_ID` | 代理银行终端标识符 |
| `INTERSWITCH_LEGACY_AUTH_ENABLED` | 在支持的情況下启用旧的 InterswitchAuth 流程 |
| `DEBUG` | 启用调试日志。避免在生产环境中使用此功能。 |
您可以使用 `INTERSWITCH_ENV` 选择 API 环境：
1. **沙盒（默认）：** `INTERSWITCH_ENV=sandbox`
2. **生产环境：** `INTERSWITCH_ENV=production`
> **安全注意：** 生产环境模式使用真正的 Interswitch 生产环境端点。如果 `INTERSWITCH_ENV=production`，有效的生产环境凭证已配置，`INTERSWITCH_READ_ONLY=false`，并且写入工具以 `confirm: true` 调用，服务器可以进行真正的生产环境 API 调用。
为了更安全的首次设置，请在只读模式下启动：
```bash
INTERSWITCH_ENV=production \
INTERSWITCH_READ_ONLY=true \
INTERSWITCH_CLIENT_ID=您的生产客户端ID \
INTERSWITCH_CLIENT_SECRET=您的生产客户端密钥 \
interswitch-mcp-server
```
当您授权并准备好允许实时写入时，请设置：
```bash
INTERSWITCH_READ_ONLY=false
```
## 客户端集成
Interswitch MCP 服务器与任何兼容 MCP 的客户端配合使用。以下是大多数客户端使用的标准配置模式（Claude Desktop、ChatGPT Desktop、Cursor、Windsurf、VS Code、Claude Code 等）。
### 使用 npm（推荐）
对于通过 npm 安装的服务器：
```json
{
"mcpServers": {
"interswitch": {
"command": "npx",
"args": ["-y", "interswitch-mcp-server"],
"env": {
"INTERSWITCH_ENV": "sandbox",
"INTERSWITCH_READ_ONLY": "true",
"INTERSWITCH_CLIENT_ID": "您的客户端ID",
"INTERSWITCH_CLIENT_SECRET": "您的客户端密钥",
"INTERSWITCH_MERCHANT_CODE": "您的商户代码",
"INTERSWITCH_PAYABLE_CODE": "您的支付代码",
"INTERSWITCH_INITIATING_ENTITY_CODE": "您的实体代码"
}
}
}
}
```
对于生产环境，请有意更改环境值：
```json
{
"mcpServers": {
"interswitch": {
"command": "npx",
"args": ["-y", "interswitch-mcp-server"],
"env": {
"INTERSWITCH_ENV": "production",
"INTERSWITCH_READ_ONLY": "true",
"INTERSWITCH_CLIENT_ID": "您的生产客户端ID",
"INTERSWITCH_CLIENT_SECRET": "您的生产客户端密钥",
"INTERSWITCH_MERCHANT_CODE": "您的生产商户代码",
"INTERSWITCH_PAYABLE_CODE": "您的生产支付代码",
"INTERSWITCH_INITIATING_ENTITY_CODE": "您的生产实体代码"
}
}
}
}
```
### 使用本地构建
如果您在本地克隆并构建了服务器：
```json
{
"mcpServers": {
"interswitch": {
"command": "node",
"args": ["/path/to/Interswitch-mcp-server/dist/index.js"],
"env": {
"INTERSWITCH_ENV": "sandbox",
"INTERSWITCH_READ_ONLY": "true",
"INTERSWITCH_CLIENT_ID": "您的客户端ID",
"INTERSWITCH_CLIENT_SECRET": "您的客户端密钥"
}
}
}
}
```
> [!IMPORTANT]
> 设置 `command: "node"` 时，您应该确保使用 Node v18+。如果您使用包管理器，您可能需要通过在 CLI 中运行以下命令来获取 Node 二进制文件的路径：
>
> ### Linux 和 MacOS
>
> ```sh
> which node
> ```
>
> ### Windows
>
> ```sh
> where node
> ```
>
> 一旦您有了路径，请将其用作 MCP 服务器命令的 JSON 配置中的值。 例如，`command: "path/to/installation/bin/node"`
### 添加此配置的位置
| 客户端 | 配置文件位置 |
| ------ | -------------------- |
| VS Code | `.vscode/mcp.json` |
| Claude Desktop | `claude_desktop_config.json` |
| ChatGPT Desktop | 应用偏好设置中的 MCP 设置 |
| Cursor | `.cursor/mcp.json` 或全局 MCP 设置 |
| Windsurf | 设置中的 MCP 配置 |
| Claude Code | `~/.claude/mcp.json` 或项目级 `.mcp.json` |
## 工作原理
Interswitch MCP 服务器通过专用 MCP 工具将 Interswitch API 域暴露给 AI 助手。服务器在运行时不解析 OpenAPI 文件；相反，它为支持的 Interswitch 域提供精选的、类型化的工具。
### 架构图
```mermaid
graph TD
subgraph MCP Server
A[Interswitch MCP Server]
B[工具注册表]
C[资源注册表]
end
subgraph 认证层
D[OAuth2 Passport 管理器]
E[Card 360 令牌管理器]
F[交易搜索管理器]
G[代理银行令牌管理器]
H[旧身份验证管理器]
end
subgraph 核心服务
I[支付服务]
J[VAS 服务]
K[转账服务]
L[无卡服务]
M[交易搜索服务]
N[Card 360 服务]
O[贷款服务]
P[转账服务]
Q[结算服务]
R[代理服务]
S[金融科技实用程序]
end
subgraph 安全层
J1[确认门]
J2[只读模式]
J3[数据删除系统]
J4[审计日志]
end
A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
A --> H
B --> I
B --> J
B --> K
B --> L
B --> M
B --> N
B --> O
B --> P
B --> Q
B --> R
B --> S
I --> J1
J --> J1
K --> J1
L --> J1
M --> J1
N --> J1
O --> J1
P --> J1
Q --> J1
R --> J1
S --> J1
J1 --> J2
J2 --> J3
J3 --> J4
J4 --> Z[外部 API]
style MCP Server fill:#f0f8ff,stroke:#333,stroke-width:2px
style 认证层 fill:#e6f7e6,stroke:#333,stroke-width:1px
style 核心服务 fill:#f9f9f9,stroke:#666,stroke-width:1px
style 安全层 fill:#fff0f0,stroke:#c33,stroke-width:1px
style Z fill:#d4d4d4,stroke:#999,stroke-dasharray: 5 5
```
每个工具：
1. 使用严格的模式验证其输入
2. 应用确认和只读安全门
3. 选择配置的沙盒或生产环境基准 URL
4. 为域使用正确的身份验证系统
5. 仅在调用工具时调用 Interswitch API
6. 从返回的数据中删除敏感字段
7. 返回标准化的 MCP 响应
### 身份验证系统
| 身份验证系统 | 用于 |
| ----------- | -------- |
| OAuth2 Passport | 核心支付、转账、VAS、无卡、贷款、转账服务和结算 |
| Card 360 令牌管理器 | Card 360 操作 |
| 交易搜索令牌管理器 | 交易搜索 API |
| 旧 InterswitchAuth | 在启用时支持旧签名请求流程 |
| 代理银行令牌管理器 | 代理银行 SOAP/XML 令牌流程 |
### 可用工具
| 工具 | 描述 |
| ---- | ----------- |
| `isw_initialize_payment` | 初始化支付请求 |
| `isw_get_transaction_status` | 检查交易状态 |
| `isw_get_transaction_by_reference` | 按引用获取交易 |
| `isw_create_payment_link` | 创建支付链接 |
| `isw_initiate_refund` | 发起退款；高风险写入 |
| `isw_get_refund_status` | 检查退款状态 |
| `isw_pay_bill` | 支付账单 |
| `isw_get_billers` | 列出账单者 |
| `isw_get_biller_packages` | 列出账单者的套餐 |
| `isw_get_billers_by_category` | 按类别列出账单者 |
| `isw_get_biller_details` | 获取账单者详情 |
| `isw_validate_customer` | 验证账单者客户 |
| `isw_pay_vas_bill` | 支付 VAS 账单 |
| `isw_airtime_recharge` | 充值话费 |
| `isw_get_airtime_epins` | 请求话费 ePIN |
| `isw_single_transfer` | 发送单笔银行转账；高风险写入 |
| `isw_bulk_transfer` | 发送批量转账；高风险写入；最多 100 笔交易 |
| `isw_resolve_bank_account` | 解析银行账户详情 |
| `isw_get_bank_codes` | 列出支持的银行代码 |
| `isw_agency_banking_cashout` | 发起代理现金提取；高风险写入 |
| `isw_create_paycode` | 创建无卡支付代码 |
| `isw_create_bulk_paycodes` | 创建批量无卡支付代码；高风险写入；最多 100 个支付代码 |
| `isw_get_paycode_status` | 检查支付代码状态 |
| `isw_deactivate_paycode` | 停用支付代码 |
| `isw_transaction_search_quick_search` | 按快速搜索字段搜索交易 |
| `isw_transaction_search_reference_search` | 按交易引用搜索 |
| `isw_transaction_search_bulk_search` | 搜索多个交易 |
| `isw_get_transaction_details` | 获取交易详情 |
| `isw_create_card` | 创建卡；高风险写入 |
| `isw_retry_card_creation` | 重试卡创建 |
| `isw_initiate_card_data_prep` | 启动卡数据准备 |
| `isw_fetch_data_prep_request` | 获取数据准备请求 |
| `isw_fetch_prepared_cards` | 获取准备好的卡 |
| `isw_bulk_card_production` | 启动批量卡生产；高风险写入 |
| `isw_reissue_card_pin` | 重新发行卡 PIN；高风险写入 |
| `isw_change_card_pin` | 更改卡 PIN；高风险写入 |
| `isw_get_pin` | 在支持的情况下检索 PIN 相关响应；高风险读取 |
| `isw_block_card` | 阻止卡；高风险写入 |
| `isw_unblock_card` | 解锁卡；高风险写入 |
| `isw_block_prepaid_card` | 阻止预付费卡；高风险写入 |
| `isw_unblock_prepaid_card` | 解锁预付费卡；高风险写入 |
| `isw_link_card_to_account` | 将卡链接到账户；高风险写入 |
| `isw_check_prepaid_balance` | 检查预付费卡余额 |
| `isw_check_debit_balance` | 检查借记卡余额 |
| `isw_confirm_prepaid_sufficient` | 确认预付费卡余额充足 |
| `isw_confirm_debit_sufficient` | 确认借记卡余额充足 |
| `isw_fetch_cards_by_issuer` | 按发行商获取卡 |
| `isw_fetch_single_card_by_pan` | 按 PAN 获取单个卡并进行数据删除 |
| `isw_fetch_cards_by_account` | 按账户获取卡 |
| `isw_fetch_customer_card_details` | 获取客户卡详情 |
| `isw_fetch_request_logs` | 获取 Card 360 请求日志 |
| `isw_validate_card` | 验证卡数据 |
| `isw_request_nano_loan` | 请求纳米贷款；高风险写入 |
| `isw_salary_lending` | 启动薪水贷款流程；高风险写入 |
| `isw_value_financing` | 启动价值融资流程；高风险写入 |
| `isw_get_customer_demographics` | 获取客户人口统计数据 |
| `isw_get_financial_history` | 获取客户财务历史 |
| `isw_get_financial_history_average` | 获取财务历史平均值 |
| `isw_get_financial_habits` | 获取客户财务习惯 |
| `isw_credit_inquiry` | 运行信用查询 |
| `isw_complete_credit` | 使用 OTP 完成信用；高风险写入 |
| `isw_requery_transfer` | 查询转账状态 |
| `isw_get_receiving_institutions` | 获取结算接收机构 |
| `isw_get_payout_channels` | 获取结算通道 |
| `isw_agency_get_token` | 获取/缓存代理银行令牌 |
| `isw_fintech_validate_debit_payload` | 验证借记有效载荷结构 |
| `isw_fintech_validate_reversal_payload` | 验证反转有效载荷结构 |
| `isw_fintech_validate_enquiry_payload` | 验证查询有效载荷结构 |
| `isw_fintech_validate_place_lien_payload` | 验证放置联络有效载荷结构 |
| `isw_fintech_validate_debit_lien_payload` | 验证借记联络有效载荷结构 |
| `isw_fintech_compute_mac` | 计算 MAC；高风险因为它接受秘密 |
| `isw_fintech_build_response` | 构建金融科技响应有效载荷；当提供秘密时为高风险 |
### 可用资源
| 资源 | URI | 描述 |
| -------- | --- | ----------- |
| `response_codes` | `isw://response-codes` | 公共 Interswitch 响应代码参考 |
| `config_summary` | `isw://config-summary` | 安全的运行时配置摘要；仅返回凭证存在情况，不返回机密 |
### 示例
当您向 AI 助手提出类似 _"使用 Interswitch 初始化对 customer@example.com 的 5000 奈拉付款"_ 的问题时，幕后会发生以下情况：
1. 助手选择 `isw_initialize_payment`
2. 它传递显式货币输入，例如 `amountNaira: 5000`
3. 对于写入操作，它必须包含 `confirm: true`
4. 服务器验证请求，安全地转换金额（如果需要），验证身份，调用配置的沙盒或生产端点
5. 您获得标准化的响应，其中原始数据已删除
### 提示建议
要获得使用此 MCP 服务器的最佳结果，请在提示中具体说明，并在请求中始终包含“Interswitch”。
**好提示：**
- “为 user@example.com 初始化 Interswitch 支付 50000 奈拉。”
- “检查参考订单-1001 的 Interswitch 交易状态。”
- “解析 Interswitch 银行账户 0123456789 的银行代码。”
- “使用确认 true 发送单笔 Interswitch 转账 1000 奈拉。”
- “读取 Interswitch 响应代码资源。”
**效果较差的提示：**
- “列出我的交易”（不明确使用哪个服务和参考标准/搜索条件）
- “发送钱”（缺少受益人、银行、金额和确认详情）
- “支付账单”（缺少账单人、套餐、客户和金额详情）
明确表达确保 LLM 快速缩小到正确的工具，减少歧义。
## 生产安全
此服务器可以在设置 `INTERSWITCH_ENV=production` 时路由到生产环境 Interswitch 端点。生产环境就绪取决于正确的凭证、Interswitch 账户权限和贵组织的运营控制。
服务器内置的安全行为：
- 写入工具需要 `confirm: true`
- 高风险敏感读取工具需要 `confirm: true`
- `INTERSWITCH_READ_ONLY=true` 在任何外部 API 调用之前阻止所有写入
- 低风险读取不需要确认
- 原始响应在返回前会进行数据删除
- 令牌和机密永远不会在工具输出中故意返回
- 当配置了所需的 RSA 公钥时，PIN 有效载荷会进行本地加密
- 生产环境启动警告信息会写入 stderr 而不是静默隐藏有风险的配置
推荐的生产环境部署：
1. 配置生产环境凭证但保持 `INTERSWITCH_READ_ONLY=true`
2. 验证启动警告和配置摘要
3. 首先测试安全的只读工具
4. 确认您打算使用的工具的域凭证
5. 仅当授权实时写入时，切换 `INTERSWITCH_READ_ONLY=false`
6. 需要 `confirm: true` 的提示需要人工审核
## 开发
### 在本地运行（无需构建）
在本地开发和测试期间，您可以直接运行 TypeScript 源代码：
```bash
npm run dev
```
### 使用 MCP 检视器运行
```bash
npm run inspect
```
### 构建
```bash
npm run build
```
### 运行测试
```bash
npm test
```
### 类型检查
```bash
npm run lint
```
### 预览 npm 包内容
```bash
npm pack --dry-run
```
## 故障排除
| 问题 | 解决方案 |
| ----- | -------- |
| 服务器启动时无声退出 | 从终端运行它并检查 stderr；验证 Node v18+ 和有效环境变量 |
| 出现生产环境警告 | 添加缺失的凭证组，设置 `INTERSWITCH_READ_ONLY=true` 或根据警告禁用 `DEBUG` |
| 客户端中未显示工具 | 确保服务器正在运行且客户端配置路径正确 |
| 写入工具被阻止 | 传送 `confirm: true`；如果仍然被阻止，请检查 `INTERSWITCH_READ_ONLY` |
| 高风险读取被阻止 | 传送 `confirm: true` |
| 支付工具失败 | 在需要时配置 `INTERSWITCH_MERCHANT_CODE` 和 `INTERSWITCH_PAYABLE_CODE` |
| 转账工具失败 | 在需要时配置 `INTERSWITCH_INITIATING_ENTITY_CODE` |
| Card 360 工具失败 | 配置 `CARD360_CLIENT_ID` 和 `CARD360_CLIENT_SECRET` |
| PIN 操作失败 | 配置有效的 `CARD360_RSA_PUBLIC_KEY` |
| 交易搜索失败 | 配置 `TRANSACTION_SEARCH_CLIENT_ID` 和 `TRANSACTION_SEARCH_CLIENT_SECRET` |
| 代理工具失败 | 配置 `INTERSWITCH_AGENCY_MERCHANT_ID` 和 `INTERSWITCH_AGENCY_TERMINAL_ID` |
| 请求超时 | 检查到配置的 Interswitch 环境的网络连接 |
## 贡献
欢迎提交拉取请求。对于较大的更改，请先打开一个问题，讨论您想要更改的内容。
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取更多详细信息。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器