Algovoi Mcp Server

AlgoVoi MCP Server

一个 MCP（Model Context Protocol） 服务，将 AlgoVoi 的支付基础设施作为工具提供，供任何 MCP 客户端调用，包括 Claude Desktop、Claude Code、Cursor、Windsurf 或任何其他兼容 MCP 的助手。

提供 两个软件包：

软件包	安装方式	命令
TypeScript	npm i -g @algovoi/mcp-server	npx -y @algovoi/mcp-server
Python	pip install algovoi-mcp	uvx algovoi-mcp 或 algovoi-mcp

两个软件包现在都提供全部 21 个工具（13 个 Tier 1 工具 + 8 个 Tier 2 持续授权周期性工具，二者均随 v1.3.0 发布）。根据 MCP 客户端 / 部署技术栈的偏好选择运行时即可——工具接口相同、JSON Schema 定义相同，并采用 Pydantic 严格验证 / 禁止额外字段。

---

工具

支付工具

#	工具	功能
1	create_payment_link	为指定金额 + 链生成托管式结账 URL
2	verify_payment	验证结账令牌（可选使用 tx_id）
3	prepare_extension_payment	页面内钱包流程参数（Algorand / VOI）
4	verify_webhook	验证 AlgoVoi Webhook 的 HMAC-SHA256 签名
5	list_networks	支持的链 + 资产 ID（离线，无需 API 调用）

协议质询工具

#	工具	功能
6	generate_mpp_challenge	IETF MPP 402 WWW-Authenticate 标头 + challenge_id
7	verify_mpp_receipt	验证 MPP 链上收据（直接查询索引器，无需 API 调用）
8	verify_x402_proof	验证 x402 base64 支付证明（直接查询索引器）
9	generate_x402_challenge	x402 X-Payment-Required 402 标头 + 负载
10	generate_ap2_mandate	为 AI Agent 支付流程生成 AP2 v0.1 PaymentMandate
11	verify_ap2_payment	验证 AP2 授权的支付收据（直接查询索引器）

A2A Agent 工具 (v1.2.0 新增)

#	工具	功能
12	fetch_agent_card	GET {agent_url}/.well-known/agent.json — 在调用 A2A Agent 前发现其能力和支付要求
13	send_a2a_message	POST {agent_url}/message:send — 调用需要付费的 A2A v1.0 Agent；成功时返回任务结果（200），或在状态码为 402 时返回 challenge_headers，以便 Claude 完成支付后重试

A2A 先支付后调用流程

1. fetch_agent_card("https://agent.example.com")
   → see agent costs $0.01, accepts MPP on Algorand

2. send_a2a_message(agent_url, "What is the price of ALGO?")
   → payment_required: true, challenge_headers: {WWW-Authenticate: ...}

3. generate_mpp_challenge(...)   ← use tool #6
   → user pays on-chain

4. send_a2a_message(agent_url, text, payment_proof="<proof>")
   → task result returned

支持的网络：Algorand、VOI、Hedera、Stellar（四者均支持 USDC + 原生 ALGO/VOI/HBAR/XLM）。

Tier 2 — 持续授权周期性工具 (v1.3.0 新增 — TypeScript 和 Python 均支持)

Tier 2 采用 “客户只签名一次，AlgoVoi 每个周期自动扣款” 模式——适用于订阅 / Agent 绑定支出。每条链都使用其原生授权机制（商户侧无需自定义托管合约）：

#	工具	功能
14	create_recurring_authority	开启新的持续授权。返回特定于链的 customer_signing_payload，供客户的钱包签名
15	get_authority	读取当前状态（status、cycles_pulled、cap_remaining 等）
16	list_authorities	列出此租户的所有授权；可按 status / subscription_id 筛选
17	confirm_authority	在链上交易落地后标记为活跃（大多数流程会跳过此步骤，由 Webhook 完成）
18	revoke_authority	在链上撤销授权（客户的钱包对撤销交易签名）
19	pause_authority	在链下暂停（无需链上操作）
20	resume_authority	在链下恢复
21	manual_pull	由租户发起的补扣 / 按比例扣款

各链的授权机制

链	机制
Algorand / VOI	SpendingCapVault（6 步操作的原子组）
Base / Tempo	ERC-20 approve（单笔交易）
Solana	SPL Token Approve + facilitator 代理权限
Hedera	HTS AccountAllowanceApproveTransaction
Stellar	Soroban auth_entry（智能合约授权）

订阅流程

1. create_recurring_authority(subscription_id, chain, customer_wallet,
                              cap_amount_minor, cap_period_seconds,
                              per_cycle_amount_minor)
   → customer_signing_payload returned

2. Hand template to wallet (Pera / Defly / MetaMask / Phantom /
   HashPack / Freighter / etc.)
   → customer signs the chain-native authorisation tx

3. confirm_authority(authority_id, on_chain_address)
   → status: 'pending' → 'active'

4. AlgoVoi cycle reaper auto-pulls per cap_period_seconds.
   Each pull emits subscription.charged or subscription.payment_failed
   webhooks (verify with verify_webhook).

5. Lifecycle: revoke_authority / pause_authority / resume_authority /
   manual_pull as needed.

各链的钱包端集成：每条链的客户端流程请参阅 ../Recurr/<chain>/README.md。

支持的网络：全部 14 个（7 个主网 + 7 个测试网）——Algorand、VOI、 Base、Tempo、Solana、Hedera、Stellar。

---

两种连接方式

选项 A — AlgoVoi Cloud（推荐）

AlgoVoi Cloud 是所有集成的控制平面——WooCommerce、Zapier、n8n 和 MCP 都集中在同一个仪表板中。将 ALGOVOI_API_BASE 指向 https://cloud.algovoi.co.uk，你的单个 algv_... API 密钥即可用于所有集成——无需租户 ID 或收款地址（它们都存储在仪表板中）。

{
  "mcpServers": {
    "algovoi": {
      "command": "npx",
      "args": ["-y", "@algovoi/mcp-server"],
      "env": {
        "ALGOVOI_API_KEY": "algv_...",
        "ALGOVOI_API_BASE": "https://cloud.algovoi.co.uk"
      }
    }
  }
}

Claude 创建的每笔付款都会显示在你的 Cloud 仪表板中，并与其他所有平台的付款一同列出。所有信息尽在一处。

在 dash.algovoi.co.uk 免费注册。

---

选项 B — AlgoVoi 直连

使用你的 algv_... 密钥和租户 ID，直接连接 AlgoVoi API。

两个软件包读取相同的环境变量：

变量	必需	用途
ALGOVOI_API_KEY	✅	AlgoVoi 仪表板中的 algv_... API 密钥
ALGOVOI_TENANT_ID	✅	AlgoVoi 仪表板中的租户 UUID
ALGOVOI_PAYOUT_ALGORAND	✅*	Algorand 收款钱包地址
ALGOVOI_PAYOUT_VOI	✅*	VOI 收款钱包地址
ALGOVOI_PAYOUT_HEDERA	✅*	Hedera 收款账户（例如 0.0.123456）
ALGOVOI_PAYOUT_STELLAR	✅*	Stellar 收款地址（G...）
ALGOVOI_PAYOUT_ADDRESS	—	未设置各链变量时使用的通用备用地址
ALGOVOI_WEBHOOK_SECRET	—	用于 verify_webhook
ALGOVOI_API_BASE	—	覆盖 AlgoVoi API 基础 URL（默认值：https://cloud.algovoi.co.uk）

* 至少需要一个各链地址（或用作备用地址的 ALGOVOI_PAYOUT_ADDRESS）。

仅通过环境变量进行身份验证。 密钥不会通过工具参数传递——MCP 客户端永远不会看到 API 密钥。

在 www.algovoi.co.uk 注册以获取 API 密钥和租户 ID。

{
  "mcpServers": {
    "algovoi": {
      "command": "npx",
      "args": ["-y", "@algovoi/mcp-server"],
      "env": {
        "ALGOVOI_API_KEY": "algv_...",
        "ALGOVOI_TENANT_ID": "...",
        "ALGOVOI_PAYOUT_ALGORAND": "<your-algorand-address>",
        "ALGOVOI_PAYOUT_VOI":      "<your-voi-address>",
        "ALGOVOI_PAYOUT_HEDERA":   "0.0.<your-account>",
        "ALGOVOI_PAYOUT_STELLAR":  "G<your-stellar-address>"
      }
    }
  }
}

对于 Python 软件包，将 "command": "uvx", "args": ["algovoi-mcp"] 替换为相应配置。

配置文件位置：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、%APPDATA%\Claude\claude_desktop_config.json（Windows）
• Claude Code：~/.claude.json
• Cursor：~/.cursor/mcp.json

---

测试

# TypeScript unit tests (77/77)
cd typescript && npm test

# Python unit tests (85/85)
cd python && pytest

# Stdio integration smoke — boots both servers and confirms all 13 tools list
python smoke_stdio.py

---

基于 Business Source License 1.1 授权。