helipay-mcp-server

helipay-mcp-server 实现了 MCP（Model Context Protocol）协议，让 AI 智能体具备调用合利宝支付接口的能力。智能体通过标准工具调用即可完成下单、查询等操作，通信全程使用国密 SM2/SM4 算法加密签名。

1. 简介

在 AI 智能体场景下，用户只需在智能体应用中描述支付需求，智能体即可通过合利宝 MCP Server 自动完成下单、支付、查询等操作，无需人工跳转多个页面或手动填写订单信息，实现端到端的智能支付体验。

核心特性：

• 基于 MCP（Model Context Protocol）标准协议，兼容所有支持 MCP 的客户端
• 采用国密 SM2 非对称加密签名 + SM4 对称加密，符合国家密码算法标准
• 每笔交易独立生成随机 SM4 会话密钥，通过 SM2 公钥加密传输

2. 使用和配置

使用前，欢迎微信进入“合利宝商户管家”公众号，咨询在线客服，入驻成为合利宝商户，获取商户编号、SM2 私钥及合利宝 SM2 公钥。之后，即可在主流支持 MCP 的客户端应用上配置使用。

在 Claude Code 中使用

在项目根目录的 .claude/settings.json 中加入如下配置：

{
  "mcpServers": {
    "helipay-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "helipay-mcp-server"
      ],
      "env": {
        "HP_MERCHANT_NO": "<商户编号，必填>",
        "HP_SM_PRIVATE_KEY_PATH": "<商户 SM2 私钥文件绝对路径，必填>",
        "HP_SM_PRIVATE_KEY_PWD": "<SM2 私钥密码，必填>",
        "HP_SM_PUBLIC_KEY_PATH": "<合利宝 SM2 公钥文件绝对路径，必填>",
        "HP_API_URL": "<合利宝交易地址，选填，默认生产地址，https://域名/trx>",
        "HP_TIME_OUT": "<交易地址超时时间（单位毫秒），选填，默认 5000 毫秒>",
        "HP_LOG_DIR": "<日志打印目录，选填，默认 ~/.helipay-mcp-server/>",
        "HP_AVAILABLE_TOOLS": "<可用工具列表，选填，默认 all，可按需配置工具名称，英文逗号分隔>",
        "HP_UC_SERVER_CALLBACK_URL": "<通用收银台服务器异步通知地址，选填>",
        "HP_UC_FRONT_CALLBACK_URL": "<通用收银台前台跳转地址，选填>"
      }
    }
  }
}

在其他 MCP Client 中使用

在其它支持 MCP 的客户端中，配置 Server 进程启动方式为 npx -y helipay-mcp-server，并按上述方式设置环境变量即可使用。

3. 使用 MCP Inspector 调试

开发人员可使用 MCP Inspector 来调试和了解合利宝 MCP Server 的各项功能，具体操作如下：

1. 通过 export 设置各环境变量：

export HP_MERCHANT_NO="your_merchant_no"
export HP_SM_PRIVATE_KEY_PATH="/path/to/private_key"
export HP_SM_PRIVATE_KEY_PWD="your_password"
export HP_SM_PUBLIC_KEY_PATH="/path/to/public_key"

2. 启动 MCP Inspector：

npx -y @modelcontextprotocol/inspector npx -y helipay-mcp-server

3. 在 MCP Inspector WebUI 中查看工具列表、测试调用参数并验证返回结果。

4. 工具列表

下表列出了当前版本 MCP Server 提供的支付工具。

create_universal_cashier_unified_order

通用收银台支付预下单。创建一笔支付订单，返回预下单结果（含支付跳转链接等）。

参数：

| 参数 | 类型 | 必填 | 说明 | |:--------------|:-------|:--:|:--------------------------------------------| | orderAmount | string | 是 | 订单金额，单位元，最小 0.01 | | orderId | string | 是 | 商户订单号，8-50 位字母数字 | | goodsName | string | 否 | 商品名称，默认：默认商品名称 | | userId | string | 否 | 用户 ID | | period | string | 否 | 订单有效时间数值，需配合 periodUnit 使用 | | periodUnit | enum | 否 | 有效时间单位：second / minute / hour / day |

输出：

| 字段 | 类型 | 说明 | |:----------------------|:-------|:-------------------| | code | string | 状态码，0000 表示成功 | | message | string | 提示信息 | | data.customerNumber | string | 商户号 | | data.orderId | string | 商户订单号 | | data.orderNo | string | 商户业务订单号 | | data.prepayId | string | 预支付标识 | | data.wapUrl | string | 收银台支付链接，引导用户跳转完成支付 |

query_universal_cashier_order

通用收银台订单查询。通过商户订单号查询订单状态和详情。

参数：

| 参数 | 类型 | 必填 | 说明 | |:----------|:-------|:--:|:------| | orderId | string | 是 | 商户订单号 |

输出：

| 字段 | 类型 | 说明 | |:-------------------------|:-------|:-------------------------------------------------------------------------------------------| | code | string | 状态码，0000 表示成功 | | message | string | 提示信息 | | data.customerNumber | string | 商户号 | | data.orderId | string | 商户订单号 | | data.orderNo | string | 商户业务订单号 | | data.serialNumber | string | 合利宝交易流水号 | | data.tradeState | string | 交易状态：INIT（未支付）/ DOING（处理中）/ SUCCESS（已支付）/ FAILED（失败）/ CLOSING（关闭中）/ CLOSE（已关闭） | | data.tradeStateDesc | string | 交易状态描述 | | data.completeTime | string | 交易完成时间 | | data.orderAmount | number | 原订单支付金额，单位元 | | data.onlineCardType | string | 银行卡类型：DEBIT（借记卡）/ CREDIT（贷记卡） | | data.bankId | string | 银行编码 | | data.cardAfterFour | string | 银行卡后四位 | | data.payerName | string | 付款人姓名 | | data.userId | string | 用户 ID | | data.desc | string | 订单备注 | | data.receiverFee | number | 实收手续费，单位元 | | data.offlineFee | number | 后收手续费，单位元 | | data.presetSplitAmount | number | 预设分账金额，单位元 | | data.splittableAmount | number | 可分账金额，单位元 |