企业官网建设流程全解析

• 人工智能
• AI Agent
• 多智能体
• MCP 服务
• 工具调用
• 浏览器控制

本文以 Hive 开源仓库tools目录下的 Razorpay 支付工具为对象，完整讲解该集成如何让 Hive Agent 通过 6 个 MCP 工具对接 Razorpay 支付基础设施，覆盖交易查询、付款链接创建、发票管理与退款处理四大核心场景。读完本文，你将掌握从 API 凭证配置、环境变量与凭证存储双通道认证，到每个工具的参数语义、返回值字段、输入校验与错误码处理的完整使用链路，并了解其底层 HTTP 客户端实现与测试验证方式。

工具概述：Hive Agent 的支付操作入口

Razorpay Tool 是 Hive 的 Aden 工具集中面向在线支付与账单管理的 MCP 集成，其能力边界在 razorpay_tool.py 的模块文档中明确声明：支持 API Key 认证（RAZORPAY_API_KEY+RAZORPAY_API_SECRET），主要使用场景为列出并筛选支付、获取支付详情、创建支付链接、列出与获取发票、创建退款。

整个集成对外暴露6 个 MCP 工具，覆盖支付、发票、退款三条业务线：

在 Hive 的 Aden 工具集中，这 6 个工具被归类为需要凭证（credentials）的稳定工具，在 tools/init.py 的_register_verified（已验证工具）与 tools/init.py 的_register_unverified（新工具/社区工具）两个注册阶段均通过register_razorpay(mcp, credentials=credentials)挂载到 FastMCP 服务器，也就是说无论工具成熟度如何划分，Razorpay 支付能力始终可用。

环境准备与凭证配置

1. 获取 Razorpay API 凭证

接入前需要先获得一对 API 凭证，步骤与官方指引一致：

1. 登录 Razorpay Dashboard；
2. 进入Settings → API Keys；
3. 点击Generate Key（或使用已有的测试/生产 Key）；
4. 复制Key ID与Key Secret。

仓库在 credentials/razorpay.py 的api_key_instructions中内嵌了完全相同的获取步骤，供 CredentialManager 在向用户展示配置指引时直接使用。重要提示：开发阶段务必使用测试 Key（以rzp_test_开头），切勿将生产 Key 提交到版本控制。

2. 配置环境变量

两种凭证通过两个环境变量注入：

export RAZORPAY_API_KEY="rzp_test_your_key_id" export RAZORPAY_API_SECRET="your_key_secret"

3. 凭证的第二种来源：CredentialStoreAdapter

除了环境变量，Razorpay 工具还支持通过 Aden 的凭证存储（CredentialStoreAdapter）读取密钥。在 razorpay_tool.py 的_get_credentials中，凭证解析遵循如下优先级：

1. 若传入credentials适配器，则调用credentials.get("razorpay")与credentials.get("razorpay_secret")读取；
2. 否则回退读取环境变量RAZORPAY_API_KEY/RAZORPAY_API_SECRET；
3. 两者都不可用时，返回包含error与help的提示字典，help会引导用户配置上述两个环境变量。

4. 凭证规格：CredentialSpec 双条目

Razorpay 在凭证注册表中占用了两个条目（Key ID 与 Key Secret 分开管理），见 credentials/razorpay.py：

这里有几个值得注意的实现细节：两个凭证同属razorpay组（credential_group），要求它们必须成对配置；startup_required=False意味着缺失凭证不会阻塞 MCP 服务器启动，而是让每个工具在调用时按需返回"凭证未配置"错误；凭证还内置了健康检查端点，便于系统用一次轻量 GET 请求验证 Key 是否有效。CredentialSpec的完整字段语义可参考 credentials/base.py。

认证机制：HTTP Basic Authentication

Razorpay 官方 API 采用 HTTP Basic 认证，本集成完全遵循该约定：

• 用户名：RAZORPAY_API_KEY（Key ID）
• 密码：RAZORPAY_API_SECRET（Key Secret）

在 razorpay_tool.py 中，内部客户端_RazorpayClient通过_auth属性自动构造认证元组(api_key, api_secret)，所有httpx.get/httpx.post调用都直接透传auth=self._auth，无需在业务代码中手工拼接认证头。测试用例 test_razorpay_tool.py 也验证了认证元组的构造结果。

工具详解与实战用法

以下按工具逐一说明参数、示例与底层实现。所有工具的返回值在成功时为结构化字典，失败时统一为包含error键的错误字典。

razorpay_list_payments：列出与过滤支付

参数：

• count（int，默认 10）— 拉取的支付数量，合法范围 1-100；
• skip（int，默认 0）— 分页跳过的记录数；
• from_timestamp（int，可选）— Unix 时间戳，过滤该时间点之后的支付；
• to_timestamp（int，可选）— Unix 时间戳，过滤该时间点之前的支付。

示例：

# 列出最近 20 笔支付 razorpay_list_payments(count=20) # 按时间范围过滤 razorpay_list_payments(count=50, from_timestamp=1640995200, to_timestamp=1643673600)

实现要点：内部调用GET https://api.razorpay.com/v1/payments，查询参数为count、skip，时间过滤会映射为 Razorpay 约定的from与to参数（见 razorpay_tool.py）。count在工具入口会被强制钳制到 1-100（razorpay_tool.py），底层客户端同样用min(count, 100)兜底。返回结果只保留精简字段，每笔支付包含id、amount、currency、status、method、email、contact、created_at、description、order_id。测试 test_razorpay_tool.py 验证了过滤参数的正确透传与 count 上限钳制。

razorpay_get_payment：获取支付详情

参数：

• payment_id（str，必填）— Razorpay 支付 ID，以pay_开头。

示例：

razorpay_get_payment(payment_id="pay_AbcDefGhijkLmn")

实现要点：调用GET https://api.razorpay.com/v1/payments/{payment_id}。入口处用正则^pay_[A-Za-z0-9]+$校验 ID 格式，非法 ID 直接返回Invalid payment_id. Must match pattern: pay_[A-Za-z0-9]+错误（razorpay_tool.py）。成功返回的字段比列表更丰富：额外包含error_code、error_description、captured、fee、tax、refund_status、amount_refunded，便于 Agent 判断支付是否已捕获、手续费与税费以及退款状态（razorpay_tool.py）。

razorpay_create_payment_link：创建一次性支付链接

参数：

• amount（int，必填）— 金额，使用货币最小单位（INR 为派萨 paise）；
• currency（str，必填）— ISO 4217 三位货币代码，如"INR"、"USD"；
• description（str，必填）— 支付说明；
• customer_name（str，可选）— 客户姓名；
• customer_email（str，可选）— 客户邮箱；
• customer_contact（str，可选）— 客户电话。

示例：

razorpay_create_payment_link( amount=50000, # Rs. 500.00 currency="INR", description="Payment for order #123", customer_email="customer@example.com" )

实现要点：调用POST https://api.razorpay.com/v1/payment_links。请求体会按需组装customer对象——只有至少提供了姓名/邮箱/电话之一时才会写入customer字段（razorpay_tool.py），最小化请求可只含amount、currency、description。入口校验包括：amount必须为正数、currency必须恰好为 3 个字母、description不能为空（razorpay_tool.py）。成功后返回id、short_url（可分享短链，如https://rzp.io/rzp/...）、amount、currency、description、status、created_at、customer。测试 test_razorpay_tool.py 专门验证了无客户信息时请求体不含customer键，以及amount=-100、currency="INVALID"、空description三类非法输入均被拦截。

razorpay_list_invoices：列出发票

参数：

• count（int，默认 10）— 拉取数量（1-100）；
• skip（int，默认 0）— 分页偏移；
• type_filter（str，可选）— 按发票类型过滤，如"invoice"、"link"。

示例：

razorpay_list_invoices(count=20, type_filter="invoice")

实现要点：调用GET https://api.razorpay.com/v1/invoices，type_filter映射为查询参数type（razorpay_tool.py）。返回的每张发票含id、amount、currency、status、customer_id、created_at、description、short_url。测试 test_razorpay_tool.py 验证了类型过滤透传。

razorpay_get_invoice：获取发票详情

参数：

• invoice_id（str，必填）— Razorpay 发票 ID，以inv_开头。

示例：

razorpay_get_invoice(invoice_id="inv_AbcDefGhijkLmn")

实现要点：调用GET https://api.razorpay.com/v1/invoices/{invoice_id}，入口以^inv_[A-Za-z0-9]+$校验格式（razorpay_tool.py）。相比列表接口，详情接口额外返回customer_details、line_items（明细行数组）、paid_at、cancelled_at等关键字段（razorpay_tool.py），是核对订单内容与付款时间的核心入口。测试 test_razorpay_tool.py 验证了明细行与paid_at字段。

razorpay_create_refund：创建退款

参数：

• payment_id（str，必填）— Razorpay 支付 ID，以pay_开头；
• amount（int，可选）— 退款金额（最小货币单位），省略则全额退款；
• notes（dict，可选）— 附加退款的键值对信息。

示例：

# 全额退款 razorpay_create_refund(payment_id="pay_AbcDefGhijkLmn") # 带备注的部分退款 razorpay_create_refund( payment_id="pay_AbcDefGhijkLmn", amount=10000, # Rs. 100.00 notes={"reason": "Customer request"} )

实现要点：调用POST https://api.razorpay.com/v1/payments/{payment_id}/refund。请求体按需组装：仅当amount非空时才写入amount，仅当notes非空时才写入notes，全额退款时请求体为空对象（razorpay_tool.py）。入口校验复用pay_正则，并拒绝非正的退款金额（razorpay_tool.py）。成功后返回id、payment_id、amount、currency、status、created_at、notes、speed_processed。测试 test_razorpay_tool.py 同时覆盖了全额（空请求体）与部分（带amount与notes）两种形态。

参数校验与防御式设计

从源码结构看，Razorpay 工具在 MCP 入口层做了完整的输入防御，未命中校验的调用不会发往 Razorpay API，而是直接返回错误字典：

此外，所有工具调用都包裹了httpx.TimeoutException（统一返回Request timed out）与httpx.RequestError（返回Network error: ...）两类网络异常的捕获，确保网络抖动时工具仍以结构化错误返回，不会让异常穿透到 Agent 侧（如 razorpay_tool.py）。每个 HTTP 请求都显式设置了 30 秒超时。

错误处理：统一的错误字典契约

所有 6 个工具在失败时统一返回错误字典，格式如下：

{ "error": "Invalid Razorpay API credentials" }

底层由_RazorpayClient._handle_response统一将 HTTP 状态码翻译为可读错误信息（razorpay_tool.py）：

测试 test_razorpay_tool.py 通过参数化用例逐一断言了 401/403/404/400/429 与通用 500 的错误文案，保证了错误契约的稳定性。

测试与验证：测试模式 + 单元测试

使用 Razorpay 测试模式

为避免真实扣款，开发阶段务必使用测试环境：

1. 生成测试 API Key（以rzp_test_开头）；
2. 使用 Razorpay 官方测试卡文档提供的测试卡号、测试 UPI ID 等测试支付方式完成支付流程模拟。

仓库内置的单元测试

仓库为这套集成提供了完整的单元测试 test_razorpay_tool.py，覆盖范围包括：

• _RazorpayClient六个方法的请求路径、参数与认证透传；
• 错误处理的状态码到错误文案映射（参数化测试）；
• 凭证获取三条路径：无凭证（返回not configured）、CredentialStoreAdapter（按razorpay/razorpay_secret两次读取）、环境变量（验证 auth 元组来自 env）；
• 6 个 MCP 工具函数的成功路径、输入校验与超时/网络异常；
• 凭证规格断言：CREDENTIAL_SPECS中存在razorpay与razorpay_secret两条目、各自关联 6 个工具、健康检查端点为GET https://api.razorpay.com/v1/payments?count=1、aden_supported=False且direct_api_key_supported=True（test_razorpay_tool.py）。

其中test_register_tools_registers_all_tools通过断言mcp.tool.call_count == 6确保工具注册数量不回归（test_razorpay_tool.py）。

在 Hive 工具生态中的位置与扩展入口

如果你要在自己的 Hive 部署中接入或扩展 Razorpay 能力，可以按以下脉络继续深入：

• 工具声明与注册：入口函数register_tools(mcp, credentials=None)定义于 razorpay_tool.py，并通过init.py 导出；统一在 tools/init.py 与 tools/init.py 挂载到 MCP；
• 凭证规格：新增或修改环境变量名、健康检查端点等，编辑 credentials/razorpay.py；
• 凭证基础设施：CredentialSpec的完整字段与 CredentialManager 的读取、校验、热加载逻辑见 credentials/base.py；
• 工具总览：razorpay_*在 Aden 工具清单中的定位可参考 tools/README.md；
• 集成文档：本工具的使用说明原始文档位于 razorpay_tool/README.md。

总结

Razorpay Tool 以 6 个语义清晰的 MCP 工具，为 Hive Agent 提供了从收款到退款的全链路支付操作能力：凭证侧支持环境变量与凭证存储双通道，认证遵循 HTTP Basic 约定；请求侧内置完整的参数校验、30 秒超时与网络异常兜底；响应侧统一为结构化字典并给出精确的错误文案。配合仓库内完整的单元测试与 Razorpay 官方测试模式，开发者可以在不产生真实交易的前提下，安全地把支付、开票与退款管理自动化能力集成进自己的 Agent 工作流中。

• 人工智能
• AI Agent
• 多智能体
• MCP 服务
• 工具调用
• 浏览器控制