内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/mcp-bridge</h1>
<p align="center"><strong>一款可以支付开放网络上任意 x402 付费端点的 MCP 服务器 — 面向 AI 代理的通用 x402 支付方。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/mcp-bridge"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/mcp-bridge?logo=npm&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@three-ws/mcp-bridge"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/mcp-bridge?color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/mcp-bridge?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/mcp-bridge?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#安全性和支出控制">安全性</a> ·
<a href="#暴露的工具">工具</a> ·
<a href="#环境">环境</a> ·
<a href="https://three.ws">three.ws</a>
</p>
---
> 一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，可以支付开放网络上任意 x402 付费端点。将您的代理指向一个返回 `402 Payment Required` 的 URL；桥接器会签名、支付、重试并返回响应和结算收据 — EVM 精确、EVM 批量结算和 Solana 精确，均在严格的支出上限后。
## 快速开始
克劳德代码：
```bash
claude mcp add x402-bridge -e MCP_BRIDGE_SVM_PRIVATE_KEY=... -- npx -y @three-ws/mcp-bridge
```
使用 `-e MCP_BRIDGE_EVM_PRIVATE_KEY=0x...` 代替（或同时）支付 Base 和其他 EVM 链。至少需要一个密钥。
克劳德桌面版（`claude_desktop_config.json`）或光标（`~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"x402-bridge": {
"command": "npx",
"args": ["-y", "@three-ws/mcp-bridge"],
"env": {
"MCP_BRIDGE_EVM_PRIVATE_KEY": "0x…买方密钥…",
"MCP_BRIDGE_SVM_PRIVATE_KEY": "…base58 64字节密钥…",
"MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC": "100000",
"MCP_BRIDGE_DISCOVER_LIMIT": "20"
}
}
}
}
```
重启客户端并请求类似“在 Base 上支付 0.01 美元以获取天气报告” — 模型会选择一个匹配的 Bazaar 工具（或 `call_paid_endpoint`），桥接器会自动通过 x402 支付。
## 安全性和支出控制
**此服务器持有私钥并支付真实的 USDC。** 在配置之前请阅读本节。
- **使用专用的低余额钱包。** `MCP_BRIDGE_EVM_PRIVATE_KEY` / `MCP_BRIDGE_SVM_PRIVATE_KEY` 绝不能是主钱包。仅用您愿意让代理花费的金额资助它。
- **每次调用的上限。** 任何超过 `MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC`（默认 `100000` = 0.10 美元 USDC）的付款在签名有效载荷之前都会被拒绝，并附有错误名称、网络和上限。
- **会话上限。** 每个进程的累计支出由 `MCP_BRIDGE_MAX_TOTAL_ATOMIC`（默认 `1000000` = 1.00 美元 USDC）限制。这限制了循环或提示注入代理的损害；一旦达到上限，每次进一步付款都会中止，直到重启。累加器会原子性地预留，因此并发调用不能共同超过它。
- **收款人白名单。** 设置 `MCP_BRIDGE_ALLOWED_PAYTO`（逗号分隔的地址）以拒绝向您未明确信任的任何收款人付款。
- **SSRF 防护。** 每个出站可付费 URL（无论是由模型还是由 Bazaar 列表提供）都会经过一个检查点，该检查点强制执行仅 https 的方案策略，解析主机名，如果 **任何** 解析的地址是私有、环回、链路本地（包括 `169.254.169.254` 云元数据）、CGNAT、ULA 或未指定，则拒绝请求。直接检查字面 IP 主机；绝不会遵循重定向（公共主机不能将桥接器 3xx 进入内部基础设施）。仅在显式 `MCP_BRIDGE_ALLOW_HTTP=1` 开发选项卡下，才允许 `http://`。
- **主机白名单。** 设置 `MCP_BRIDGE_ALLOWED_HOSTS`（逗号分隔的主机名）以启用严格模式：仅列出的主机才能被支付。
- **存款上限。** 批量结算通道存款由 `MCP_BRIDGE_MAX_DEPOSIT_ATOMIC`（默认 5.00 美元）限制，无论服务器请求多少。
- **诚实注解。** 每个支付工具都注解了 `readOnlyHint: false`、`idempotentHint: false`、`openWorldHint: true`，因此 MCP 主机应用其最严格的确认策略。重试付费调用是一种新的收费。
## 暴露的工具
桥接器启动时注册：
| 工具 | 功能 |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `call_paid_endpoint` | 通用回退：点击任意 URL，如果返回 402，则自动支付。返回响应 + 解析结算。 |
| `list_bazaar_tools` | 返回缓存的 Bazaar 发现工具列表（名称、资源、接受的付款条款）。免费。 |
| `refresh_bazaar` | 重新查询 x402 Bazaar 并重新注册动态工具，无需重启。免费。 |
| `paid_<derived>` … | 每个发现的 Bazaar 资源（最多 `MCP_BRIDGE_DISCOVER_LIMIT`）的工具，具有该端点的架构。 |
价格超过每次调用上限的工具在发现时会被过滤掉，因此模型永远不会看到它负担不起的工具。
### 工具注解
每个工具都带有 MCP `ToolAnnotations`，以便主机应用正确的确认策略：
- `call_paid_endpoint` 和每个动态 `paid_*` 工具：`readOnlyHint: false`、`destructiveHint: false`、`idempotentHint: false`、`openWorldHint: true`。**这些会支付真实的 USDC** — 每次调用都会结算付款（上限为 `MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC`），重试是一种新的收费。它们永远不会删除或覆盖调用者状态，因此不是破坏性的。
- `list_bazaar_tools`：`readOnlyHint: true`、`idempotentHint: true`、`openWorldHint: false`。纯粹的过程缓存读取；免费，无网络。
- `refresh_bazaar`：`readOnlyHint: false`、`destructiveHint: false`、`idempotentHint: false`、`openWorldHint: true`。免费（无付款），但它会根据实时 Bazaar 馈送修改注册的工具集，因此重复调用可能不同。
工具结果为纯对象，返回为 JSON `text` 块（向后兼容）和 `structuredContent` 以供类型化客户端使用。
### 支付方案
买方客户端上注册的支付路径：
- `eip155:*` → `BatchSettlementEvmScheme`（如果服务器宣传，则优先使用；基于凭证，无需每次调用 gas）
- `eip155:*` → `ExactEvmScheme`（如果服务器宣传 `scheme: "exact"`）
- `solana:*` → `ExactSvmScheme`（USDC SPL 转账由宣传的费用支付方共同签署）
批量结算通道状态持久化到 `~/.x402-mcp-bridge/channels/client/`，因此客户端重启不会在下一次调用时重新存款。
## 环境
| 变量 | 必需 | 默认 | 备注 |
| -------------------------------------- | ----------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `MCP_BRIDGE_EVM_PRIVATE_KEY` | EVM/SVM 之一必填 | — | 0x 前缀 32 字节十六进制。资助 Base、Arbitrum 等 USDC 付款。 |
| `MCP_BRIDGE_SVM_PRIVATE_KEY` | EVM/SVM 之一必填 | — | base58 64 字节密钥（Phantom/solana-keygen 格式）**或** 64-int JSON 数组。 |
| `MCP_BRIDGE_MAX_PRICE_PER_CALL_ATOMIC` | 否 | `100000` (= 0.10 美元 USDC，6 个小数位) | 每次调用的支出上限。付款超过此金额时，会中止并附带明确原因。 |
| `MCP_BRIDGE_MAX_TOTAL_ATOMIC` | 否 | `1000000` (= 1.00 美元 USDC) | 累计会话支出上限。达到上限后，进一步付款会中止。 |
| `MCP_BRIDGE_ALLOWED_PAYTO` | 否 | — （任何收款人） | 逗号分隔的收款人白名单。设置后，未列出的 `payTo` 地址将被拒绝。 |
| `MCP_BRIDGE_ALLOWED_HOSTS` | 否 | — （任何公共主机） | 逗号分隔的主机名白名单，用于出站付费请求。 |
| `MCP_BRIDGE_ALLOW_HTTP` | 否 | `0` | 设置 `1` 以允许 `http://` 目标。仅限本地开发。 |
| `MCP_BRIDGE_DISCOVER_LIMIT` | 否 | `20` | 动态注册的 Bazaar 工具的最大数量。设为 `0` 以禁用发现。 |
| `MCP_BRIDGE_BAZAAR_URL` | 否 | `https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources` | 覆盖以指向自托管或替代 Bazaar。 |
| `MCP_BRIDGE_BATCH_DEPOSIT_MULTIPLIER` | 否 | `5` | 打开批量通道时一次性存入的请求金额倍数。 |
| `MCP_BRIDGE_MAX_DEPOSIT_ATOMIC` | 否 | `5000000` (= 5.00 美元 USDC) | 通道打开/充值时存款金额的硬上限。 |
| `X402_MCP_BRIDGE_CHANNELS_DIR` | 否 | `~/.x402-mcp-bridge/channels` | 覆盖 `FileClientChannelStorage` 使用的目录。 |
| `RPC_URL_<chainId>` | 否 | viem 默认公共 RPC | 每链 RPC 覆盖。示例：`RPC_URL_8453=https://mainnet.base.org`. |
如果您已经设置了 `MCP_BRIDGE_*` 密钥变量，也会回退到 `EVM_PRIVATE_KEY` / `SVM_PRIVATE_KEY`。
## 支出上限行为
预付款钩子检查所选的 `accepts` 条目，如果金额超过每次调用上限、收款人不在白名单中或会话上限将被突破，则中止有效载荷创建。然后，工具结果会带有明确的错误消息，说明所达到的网络、资产和限制 — 有助于模型决定是否要求您提高限制。
## 无客户端检查
```bash
MCP_BRIDGE_SVM_PRIVATE_KEY=... npx -y @modelcontextprotocol/inspector npx -y @three-ws/mcp-bridge
```
检查器通过 stdio 连接，列出静态工具（`call_paid_endpoint`、`list_bazaar_tools`、`refresh_bazaar`）以及每个发现的 Bazaar 条目的动态工具。
## 程序化使用
任何 Node 模块都可以通过相同的买方客户端使用 x402 端点：
```js
import { buildBuyerAxios } from '@three-ws/mcp-bridge/src/x402-axios-client.js';
const { api } = await buildBuyerAxios();
const res = await api.get('https://api.example.com/some-paid-resource');
```
相同的支出上限、SSRF 防护和通道存储规则适用。空闲批量通道可以通过 `@x402` SDK 的 `client.refund(resourceUrl, { amount })` 进行退款。
## 测试
```bash
npm test # 封闭：URL 防护 SSRF 策略、支出上限钩子、工具命名、stdio 启动
npm run test:smoke # 现场：针对真实 Bazaar 启动并断言上限阻止真实付费调用
```
封闭套件在进程中生成临时密钥对；绝不会涉及真实密钥或资金。
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
本软件是专有软件 - 请参阅 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
