Agent Toolkit 快速入门 - Linkpay API 中文版

MCP Server

EVO Payment MCP server 定义了一套工具，AI agents 可以使用这些工具与EVO支付API进行交互。

使用此 SDK 将 EVO Payment 集成到您的智能体工作流中。由于智能体行为具有不确定性，请在测试环境中使用此 SDK 并运行评估以评估您应用程序的效果。

前置要求

MCP 客户端

确保您有可用的 mcp 客户端，详细的客户端列表可以参考网页 https://modelcontextprotocol.io/clients
确保您已经安装了 uv, 参考文档 https://docs.astral.sh/uv/getting-started/installation/

环境变量

在使用 LinkPay MCP 之前，您需要配置以下环境变量：

环境变量	说明	必填
`EVOCLOUD_BASE_URL`	EvoCloud API 基础 URL(默认使用 uat 服务)	是
`EVOCLOUD_SID`	EvoCloud 商户 ID	是
`EVOCLOUD_SIGN_KEY`	EvoCloud 签名密钥	是
`EVOCLOUD_WEBHOOK_URL`	支付回调 URL	否

MCP 服务器配置

在您的 MCP 客户端配置文件中添加以下配置：

{
  "mcpServers": {
    "linkpay": {
      "command": "uvx",
      "args": ["--from", "evocloud_agent_toolkit", "linkpaymcp", "stdio"],
      "env": {
        "EVOCLOUD_BASE_URL": "https://counter-uat.everonet.com",
        "EVOCLOUD_SID": "您的商户ID",
        "EVOCLOUD_SIGN_KEY": "您的签名密钥",
        "EVOCLOUD_WEBHOOK_URL": "https://example.com/webhook"
      }
    }
  }
}

功能概览

LinkPay MCP 提供以下核心功能：

1. 生成商户订单 ID

功能名称: generate_merchant_order_id
描述: 生成唯一的商户订单 ID
参数:
- prefix (可选): 订单号前缀，默认为 "LINKPAY"

2. 创建支付订单

功能名称: create_linkpay_order
描述: 创建 LinkPay 支付订单
参数:
- merchant_order_id (必填): 商户订单 ID
- currency (必填): 货币代码，如 "USD", "CNY"
- amount (必填): 支付金额
- merchant_order_time (可选): 订单时间
- goods_name (可选): 商品名称
- goods_description (可选): 商品描述
- trade_type (可选): 交易类型
- return_url (可选): 支付完成后的返回地址
- webhook_url (可选): 支付状态回调地址
- enabled_payment_methods (可选): 支持的支付方式列表
- valid_time (可选): 订单有效时间（分钟）

3. 查询订单状态

功能名称: query_linkpay_order
描述: 查询 LinkPay 订单状态
参数:
- merchant_order_id (必填): 商户订单 ID

4. 创建退款

功能名称: create_linkpay_refund
描述: 创建 LinkPay 退款请求
参数:
- original_merchant_order_id (必填): 原始订单 ID
- merchant_trans_id (必填): 退款交易 ID
- currency (必填): 货币代码
- refund_amount (必填): 退款金额
- merchant_trans_time (可选): 退款时间
- reason (可选): 退款原因
- description (可选): 退款描述

5. 查询退款状态

功能名称: query_linkpay_refund
描述: 查询 LinkPay 退款状态
参数:
- merchant_trans_id (必填): 退款交易 ID

使用示例

1. Cursor 配置 LinkPay MCP 服务

配置如下服务:

保存好，在 mcp 工具列表里查看 LinkPay 服务是否正常

2. 创建 LinkPay 交易订单

安全注意事项

密钥安全: 确保 EVOCLOUD_SIGN_KEY 等敏感信息安全存储，不要硬编码在代码中
HTTPS: 生产环境必须使用 HTTPS 协议
签名验证: 回调 webhook 应验证请求签名的有效性
订单幂等: 确保相同的 merchant_order_id 不会重复创建订单
金额验证: 在处理支付前应验证金额的合理性

LangChain Integration

了解如何使用 EVO Payment Agent Toolkit 构建您的 AI agent。

使用此 SDK 将 EVO Payment 集成到您的智能体工作流中。由于智能体行为具有不确定性，请在测试环境中使用此 SDK 并运行评估以评估您应用程序的效果。

1. 安装依赖

pip install evocloud-agent-toolkit langchain langchain-openai

2. 配置环境变量

cp env.example .env
# 编辑 .env 文件，填写实际配置
EVOCLOUD_BASE_URL=https://online-uat.everonet.com
EVOCLOUD_SIGN_KEY=your_sign_key
EVOCLOUD_SID=your_sid
EVOCLOUD_WEBHOOK_URL=https://your-domain.com/webhook  # 可选
OPENAI_API_KEY=your_openai_api_key

3. 集成到 LangChain Agent

from evocloud_agent_toolkit.langchain import EvoCloudToolkit
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI

# 初始化工具和模型
toolkit = EvoCloudToolkit()
tools = toolkit.get_tools()
llm = ChatOpenAI(model="gpt-4", temperature=0)

# 创建提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是专业的支付助手，可以帮助用户处理 LinkPay 相关业务。"),
    ("user", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# 创建和运行 Agent
agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

# 使用自然语言交互
response = agent_executor.invoke({
    "input": "请创建一个订单，订单号ORDER_123，金额99.99美元，商品是Premium服务"
})
print(response["output"])