yolfi-agent MCP - 智能代理集成工具与AI助手开发框架

探索

Yolfi Agent

#null .JavaScript

评分 : 3分

下载量 : 7.6K

更新时间 : 2026-06-18

打开站点

安装

复制以下命令到你的Client进行配置

{
  "mcpServers": {
    "yolfi-api": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"],
      "env": {
        "YOLFI_API_KEY": "..."
      }
    },
    "yolfi-knowledge": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

注意：您的密钥属于敏感信息，请勿与任何人分享。

🤖 Yolfi Agent Kit

为加密结账打造的 AI Agent 支付集成方案 — 一款 JSON 优先的 SDK、CLI、Agent Skill 与 MCP 服务器，让 AI 编程智能体能够通过 Yolfi 为应用快速添加稳定币结账、支付链接、支付状态查询、Webhook 验证以及基于 Webhook 的访问控制逻辑。

当 Codex、Claude Code、Cursor、OpenClaw、MCP 宿主或自定义 AI 智能体已经能够构建产品，但仍需要一个可靠的支付 API 来注册 Yolfi 工作区、创建支付链接、配置 Webhook 并验证加密货币支付状态时，请使用 @yolfi/agent —— 无需让用户手动完成控制台配置。

🌐 多语言文档

阅读本包指南的其他语言版本： English, Español, Deutsch, Français, 简体中文, Русский, हिन्दी, Türkçe, 한국어, 日本語。

💡 为什么开发者选择它

可为 SaaS 产品、游戏、市场平台、捐赠页面、数字下载、内部工具以及智能体构建的应用添加 AI Agent 支付能力。
为编程智能体提供安全的支付工作流：检查应用 → 注册或复用工作区 → 询问钱包与价格决策 → 创建支付链接 → 安装结账组件 → 验证 Webhook → 检查支付状态。
用同一个包即可满足 MCP 加密支付、JSON CLI 自动化、JavaScript SDK 调用、Webhook 签名验证以及智能体可读指令等需求。
基于 Yolfi 现有的 API 构建，无需维护第二套只面向智能体的支付 API。
帮助智能体通过 npm、GitHub、MCP 目录、llms.txt、文档、示例以及集成指南发现 Yolfi。

🧩 职责划分

Yolfi 负责：加密货币支付基础设施、托管结账、支付链接、公开支付发票、组织设置、结算钱包配置以及 Webhook 投递。

你的智能体负责：项目检查、代码修改、用户确认以及目标应用集成。

🎁 它可以为应用带来什么

通过 Yolfi 支付链接实现的托管加密货币结账。
面向数字产品、积分、文件、工具或游戏道具的一次性支付链接。
在 Yolfi 账户支持的前提下，可设置循环或订阅式支付链接。
捐赠与创作者支持支付页面。
服务端路由，用于基于支付链接创建公开支付发票。
通过 Yolfi 公开支付接口进行支付状态轮询。
用于验证 X-Yolfi-Signature 的 Webhook 处理器。
基于 Webhook 的权益逻辑，仅在确认支付事件后才解锁访问权限。
适用于 Codex、Claude Code、Cursor、OpenClaw 以及自定义自动化的智能体工作流。

🧠 Agent Skill

本包在 SKILL.md 中包含了 Yolfi Payments Skill。当用户要求添加加密货币支付、支付链接、结账、订阅、捐赠、付费下载、付费访问或基于 Webhook 的权益时，可将其用于编程智能体。

推荐的安全工作流：

inspect app -> check YOLFI_API_KEY -> register if needed -> ask user for wallet and price -> configure organization -> create or reuse paylink -> add checkout -> add webhook verification -> verify status

⚠️ 安全边界

该技能定义了智能体可以自动执行的操作，以及必须由用户决定的事项。智能体绝不能凭空捏造钱包地址、价格、套餐、币种、密钥存储位置或破坏性的支付链接操作。

📦 安装指南

在项目中安装：

npm install @yolfi/agent

或者直接运行而无需安装：

npx -y @yolfi/agent help

启动 stdio MCP 服务器：

npx -y @yolfi/agent mcp

在本仓库内进行本地开发：

node packages/yolfi-agent/src/cli.js help

🔐 身份认证

私有命令需要使用 Yolfi 组织 API 密钥：

export YOLFI_API_KEY="yolfi_..."

CLI 和 MCP 服务器默认使用 Yolfi 生产环境 API 与结账 URL。

如果目标应用尚无 YOLFI_API_KEY，智能体可以通过 agent 注册端点注册工作区：

yolfi auth:agent-register \
  --project-name "Space Shop" \
  --agent-name "Codex" \
  --integration-intent accept_payments \
  --ref npm

⚠️ 重要提示

返回的 API 密钥只展示一次。请将其存储在已被忽略的 env 文件、部署密钥或密钥管理器中。切勿在日志中打印完整密钥、将其提交到仓库，或写入目标项目的 README 文件中。

🚀 快速开始

检查与 API 密钥关联的工作区：

yolfi auth:status

在用户提供钱包地址后配置结算钱包：

yolfi settlement:configure --json examples/organization.settlement.json

配置 Webhook 投递：

yolfi webhooks:configure \
  --url https://example.com/api/yolfi/webhook \
  --adapter STRIPE

在创建新的支付链接前，先列出已存在的支付链接以避免重复：

yolfi paylinks:list --page 1 --rows 10

创建一个一次性支付链接：

yolfi paylinks:create --json examples/paylink.one-time.json

基于支付链接创建公开支付发票：

yolfi payments:create --json examples/payment.create.json

查询支付状态：

yolfi payments:status --id <paymentId>

💡 使用建议

每个 CLI 命令都会输出 JSON，便于智能体直接解析结果，而无需从终端文本中抓取数据。

🛰️ 加密货币支付 MCP 服务器

Yolfi Agent Kit 在同一 npm 包中内置了一个 stdio MCP 服务器：

{
  "mcpServers": {
    "yolfi-api": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"],
      "env": {
        "YOLFI_API_KEY": "..."
      }
    },
    "yolfi-knowledge": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

yolfi_agent_register 调用公开的 agent 注册端点，无需 YOLFI_API_KEY。
私有 yolfi-api 工具需要注册后返回的 API 密钥。
yolfi-knowledge 资源可帮助智能体在尚未持有密钥时理解集成路径。

可用的 MCP 工具：

yolfi_agent_register
yolfi_auth_status
yolfi_organization_get
yolfi_organization_update
yolfi_settlement_configure
yolfi_webhooks_configure
yolfi_paylinks_create
yolfi_paylinks_list
yolfi_paylinks_get
yolfi_paylinks_disable
yolfi_payments_create
yolfi_payments_status
yolfi_webhooks_verify

⚠️ 重要提示

诸如 yolfi_paylinks_disable 这类破坏性工具，必须在用户明确确认后才能运行。

🧾 面向 Agent 的 JSON 工作流

智能体可以编写一个 payload 文件并传给 CLI：

{
  "name": "Premium Download",
  "description": "One-time access to a digital product.",
  "type": "ONE_TIME",
  "price": "19",
  "currency": "USD",
  "collectEmail": true,
  "metadata": {
    "source": "agent",
    "productSlug": "premium-download"
  }
}

然后运行：

yolfi paylinks:create --json ./paylink.json

💡 使用建议

智能体应将返回的支付链接 ID 保存在目标应用的 env/config 中，并使用 Yolfi 公开支付端点为面向客户的结账和状态轮询服务。

🧰 命令一览

yolfi auth:agent-register --project-name "App" --agent-name "Codex" --integration-intent accept_payments
yolfi auth:status
yolfi organization:update --json organization.json
yolfi settlement:configure --json settlement.json
yolfi webhooks:configure --url https://example.com/api/yolfi/webhook --adapter STRIPE
yolfi paylinks:create --json paylink.json
yolfi paylinks:list --page 1 --rows 10
yolfi paylinks:get --id <paylinkId>
yolfi paylinks:disable --id <paylinkId> --confirm
yolfi payments:create --json payment.json
yolfi payments:status --id <paymentId>
yolfi webhooks:verify --payload payload.json --signature <signature>
yolfi mcp

🔌 端点适配器矩阵

Yolfi Agent Kit 不会创建第二套 /api/agent/* API，而是将智能体操作映射到现有的 Yolfi API：

智能体操作	后端端点	认证
注册 Yolfi 工作区	`POST /api/auth/agent/register`	公开；无需 API 密钥
检查账户	`GET /api/private/organization/current`	bearer API 密钥
配置组织、Webhook、结算钱包	`PUT /api/private/organization/current`	bearer API 密钥
获取 API 密钥状态	`GET /api/private/organization/api-key`	bearer API 密钥或 cookie
创建支付链接	`POST /api/private/paylinks/create`	bearer API 密钥
列出支付链接	`GET /api/private/paylinks`	bearer API 密钥
获取支付链接	`GET /api/private/paylinks/:id`	bearer API 密钥
编辑支付链接	`POST /api/private/paylinks/edit`	bearer API 密钥
禁用支付链接	`POST /api/private/paylinks/disable`	bearer API 密钥 + 确认
公开支付链接结账信息	`GET /api/public/paylinks/:id`	公开
创建公开支付发票	`POST /api/public/payments`	公开
支付状态	`GET /api/public/payments/:id`	公开
商户交易记录	`GET /api/private/transactions`	bearer API 密钥

💻 SDK 使用示例

import { YolfiClient } from "@yolfi/agent";

const yolfi = new YolfiClient({
  apiKey: process.env.YOLFI_API_KEY,
});

const account = await yolfi.authStatus();

const paylink = await yolfi.createPaylink({
  name: "Premium Download",
  description: "One-time access to a digital product.",
  type: "ONE_TIME",
  price: "19",
  currency: "USD",
  collectEmail: true,
  metadata: {
    source: "agent",
    productSlug: "premium-download",
  },
});

console.log(account.success);
console.log(paylink.data?.id ?? paylink.id);

🔒 Webhook 验证

Yolfi 使用 X-Yolfi-Signature 对 Webhook payload 进行签名。在解析和信任事件之前，请先验证原始请求体：

import { verifyWebhookSignature } from "@yolfi/agent";

const valid = verifyWebhookSignature(
  rawBody,
  request.headers["x-yolfi-signature"],
  process.env.YOLFI_API_KEY,
);

if (!valid) {
  throw new Error("Invalid Yolfi webhook signature");
}

⚠️ 重要提示

不要把前端的重定向当作支付成功的凭证。请使用经过验证的 Webhook 和 Yolfi 支付状态查询确认支付结果。

🤝 配合 AI 编程智能体使用

Yolfi Agent Kit 专为「智能体驱动的支付工作流」设计 —— 用户只需给出高级指令，例如「add payments」「sell this digital product」「add a donation button」「charge for this game」或「gate this feature behind payment」。

Codex：检查仓库、添加结账路由/组件、配置环境变量，并将经过验证的 Webhook 接入现有权益逻辑。
Claude Code：使用 MCP 服务器和 Agent Skill 添加支付链接、服务端处理器以及状态查询，并在钱包与价格决策上获得用户批准。
Cursor：添加支付 UI 和后端处理器，同时确保 Yolfi 密钥不进入已提交的源代码。
OpenClaw 及自定义智能体：通过 CLI、SDK、MCP 工具和 JSON payload，将产品构建工作流接入 Yolfi。

推荐的智能体路径：

auth:status -> organization:get -> paylinks:list -> user approval -> settlement:configure -> webhooks:configure -> paylinks:create -> install checkout -> verify webhook -> payments:status