内容
# 🔗 NEAR 意图交换 MCP 服务器
[](https://www.npmjs.com/package/@iqai/mcp-near-intent-swaps)
[](https://opensource.org/licenses/MIT)
## 📖 概述
NEAR 意图交换 MCP 服务器通过 [Defuse Protocol 一键 SDK](https://github.com/defuse-protocol/one-click-sdk-typescript) 使 AI 代理能够通过 NEAR 的基于意图的架构执行跨链代币交换。该服务器提供了一个全面的 5 步流程，用于发现代币、获取报价、执行交换和跟踪其状态。
通过实施模型上下文协议（MCP），该服务器允许大型语言模型（LLM）无缝促进跨链交换，弥合了 AI 助手和去中心化跨链基础设施之间的差距。
## ✨ 功能
* **代币发现**：发现 Defuse Protocol 支持的多个区块链上的可用代币。
* **简单报价**：在不需地址的情况下获取基本交换报价 - 适用于汇率检查。
* **完整报价**：获取包含存款地址的完整报价以执行交换。
* **交换执行**：提交存款交易哈希以执行跨链交换。
* **状态跟踪**：实时监控交换进度和完成状态。
## 📦 安装
### 🚀 使用 npx（推荐）
无需全局安装即可使用此服务器：
```bash
npx @iqai/mcp-near-intent-swaps
```
### 🔧 从源码构建
```bash
git clone https://github.com/IQAIcom/mcp-near-intent-swaps.git
cd mcp-near-intent-swaps
pnpm install
pnpm run build
```
## ⚡ 使用 MCP 客户端运行
在您的 MCP 客户端设置中添加以下配置（例如 `claude_desktop_config.json`）。
### 📋 最小配置
```json
{
"mcpServers": {
"near-intent-swaps": {
"command": "npx",
"args": ["-y", "@iqai/mcp-near-intent-swaps"],
"env": {
"NEAR_SWAP_JWT_TOKEN": "您的 jwt token"
}
}
}
}
```
### ⚙️ 高级配置（本地构建）
```json
{
"mcpServers": {
"near-intent-swaps": {
"command": "node",
"args": ["/绝对路径/to/mcp-near-intent-swaps/dist/index.js"],
"env": {
"NEAR_SWAP_JWT_TOKEN": "您的 jwt token",
"NEAR_SWAP_API_URL": "https://1click.chaindefuser.com"
}
}
}
}
```
## 🔐 配置（环境变量）
| 变量 | 是否必需 | 描述 | 默认值 |
| :--- | :--- | :--- | :--- |
| `NEAR_SWAP_JWT_TOKEN` | 是 | Defuse Protocol API 身份验证的 JWT token | - |
| `NEAR_SWAP_API_URL` | 否 | 自定义 API 端点 | `https://1click.chaindefuser.com` |
## 💡 使用示例
### 🔍 代币发现
* "NEAR 上有哪些可用于跨链交换的代币？"
* "显示 Defuse Protocol 中所有支持的代币。"
* "列出我可以从 Arbitrum 交换到 Solana 的可用代币。"
### 📊 获取报价
* "将 100 USDC 从 Arbitrum 交换到 SOL 的汇率是多少？"
* "给我一个在 NEAR 上将 ETH 交换为 USDC 的报价。"
* "1000 USDC 可以兑换多少 SOL？"
### 💱 执行交换
* "我想将 500 USDC 从 Arbitrum 交换到 Solana。"
* "帮助我使用此存款地址执行跨链交换。"
* "我已将资金发送到存款地址，这里是我的交易哈希值。"
### 📈 跟踪状态
* "检查我的交换状态，存款地址为 0xabc..."
* "我的跨链交换是否已完成？"
* "我的待定交换的当前状态是什么？"
## 🛠️ MCP 工具
<!-- AUTO-GENERATED TOOLS START -->
### `CHECK_NEAR_SWAP_STATUS`
[步骤 5] 检查 NEAR 意图交换的当前执行状态。返回交换状态（PENDING_DEPOSIT、PROCESSING、SUCCESS、REFUNDED、FAILED 等）以及详细的 交易信息。使用此功能监控交换进度，并在交换完成后继续轮询。
| 参数 | 类型 | 是否必需 | 描述 |
|-----------|------|----------|-------------|
| `depositAddress` | 字符串 | ✅ | 报价响应中提供的唯一存款地址 - 用于跟踪和检索交换的当前状态 |
### `EXECUTE_NEAR_SWAP`
[步骤 4] 提交存款交易哈希以在将资金发送到存款地址后启动交换。这通知 1Click 服务资金已发送并触发交换执行过程。在用户将资金发送到报价响应中提供的存款地址后使用此功能。
| 参数 | 类型 | 是否必需 | 描述 |
|-----------|------|----------|-------------|
| `txHash` | 字符串 | ✅ | 发送到存款地址的存款交易的 交易哈希 |
| `depositAddress` | 字符串 | ✅ | 报价响应中提供的存款地址 |
### `GET_NEAR_SWAP_FULL_QUOTE`
[步骤 2] 获取 NEAR 意图交换的完整报价，包含存款地址。此功能需要接收地址和退款地址，并返回一个唯一的存款地址，用户可以将资金发送到该地址以启动交换。在用户准备继续交换时使用此功能，之前需要检查简单报价。注意：如果用户提供简单的代币名称（例如“ETH”、“USDC”），请先使用 GET_NEAR_SWAP_TOKENS 发现确切的代币 ID。
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `swapType` | 字符串 | | "EXACT_INPUT" | （可选，默认为 EXACT_INPUT）使用金额作为交换的基础输入或输出：EXACT_INPUT - 请求确切输入的输出金额，EXACT_OUTPUT - 请求确切输出的输出金额。退款地址将始终在交换完成后接收多余的代币。 |
| `originAsset` | 字符串 | ✅ | | 源资产的 ID（例如 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near'） |
| `destinationAsset` | 字符串 | ✅ | | 目标资产的 ID（例如 'nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near'） |
| `amount` | 字符串 | ✅ | | 以指定货币的最小单位表示的交换金额（例如 ETH 的 wei） |
| `recipient` | 字符串 | ✅ | | 接收地址。格式应与 recipientType 匹配。 |
| `recipientType` | 字符串 | | "DESTINATION_CHAIN" | （可选，默认为 DESTINATION_CHAIN）接收地址类型：DESTINATION_CHAIN - 资产将转移到目标链，INTENTS - 资产将转移到意图内的账户 |
| `refundTo` | 字符串 | | | （可选）用户退款地址 |
| `refundType` | 字符串 | | "ORIGIN_CHAIN" | （可选，默认为 ORIGIN_CHAIN）退款地址类型：ORIGIN_CHAIN - 资产将退回到退款地址的源链，INTENTS - 资产将退回到退款地址的意图账户 |
| `slippageTolerance` | 数字 | | 100 | （可选，默认为 100）交换的滑点容忍度。该值以基点表示（1/100 个百分点），例如 100 代表 1% 的滑点。 |
| `dry` | 布尔值 | | false | （可选，默认为 false）指示此请求是否为 dry run。如果为 true，响应中不会包含以下字段：depositAddress、timeWhenInactive、deadline。 |
| `depositType` | 字符串 | | "ORIGIN_CHAIN" | （可选，默认为 ORIGIN_CHAIN）存款地址类型：ORIGIN_CHAIN - 源链上的存款地址，INTENTS - 意图内的账户 ID，应将资产转移到该账户 |
| `deadline` | 字符串 | | "2026-02-10T11:56:58.847Z" | （可选，默认为 1 小时后）ISO 格式的时间戳，用于标识如果交换未在该时间戳之前完成，用户退款将开始。它需要超过存款交易被铸造所需的时间，例如对于比特币，可能需要 ~1 小时，取决于支付的 gas 费用。 |
| `referral` | 字符串 | | | （可选）推荐标识符（仅限小写）。它将反映在链上数据中，并在公共分析平台上显示。 |
| `quoteWaitingTimeMs` | 数字 | | 3000 | （可选，默认为 3000）毫秒数，用户愿意等待从中继获取报价。 |
### `GET_NEAR_SWAP_SIMPLE_QUOTE`
[步骤 1] 获取不同链和资产之间 NEAR 意图交换的简单报价。这是一个 dry run，不需要任何地址 - 适用于用户在承诺交换之前检查交换汇率和费用。在用户想要在不提供接收地址的情况下探索交换选项时使用此功能。注意：如果用户提供简单的代币名称（例如“ETH”、“USDC”），请先使用 GET_NEAR_SWAP_TOKENS 发现确切的代币 ID。
| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|-----------|------|----------|---------|-------------|
| `originAsset` | 字符串 | ✅ | | 源资产的 ID（例如 'nep141:arb-0xaf88d065e77c8cc2239327c5edb3a432268e5831.omft.near'） |
| `destinationAsset` | 字符串 | ✅ | | 目标资产的 ID（例如 'nep141:sol-5ce3bf3a31af18be40ba30f721101b4341690186.omft.near'） |
| `amount` | 字符串 | ✅ | | 以指定货币的最小单位表示的交换金额（例如 ETH 的 wei） |
| `swapType` | 字符串 | | "EXACT_INPUT" | （可选，默认为 EXACT_INPUT）使用金额作为交换的输入或输出 |
| `slippageTolerance` | 数字 | | 100 | （可选，默认为 100）滑点容忍度，以基点表示（100 = 1%） |
| `quoteWaitingTimeMs` | 数字 | | 3000 | （可选，默认为 3000）毫秒数，等待中继的报价 |
### `GET_NEAR_SWAP_TOKENS`
[发现] 获取 NEAR 意图 1Click API 当前支持的代币列表。返回代币元数据，包括区块链、合约地址、当前 USD 价格、符号、十进制和小数更新时间戳。使用此功能帮助用户在请求报价之前发现可用代币。
_无参数_
<!-- AUTO-GENERATED TOOLS END -->
## 👨💻 开发
### 🏗️ 构建项目
```bash
pnpm run build
```
### 👁️ 开发模式（监听）
```bash
pnpm run watch
```
### ✅ 校验和格式化
```bash
pnpm run lint
pnpm run format
```
### 📁 项目结构
* `src/tools/`：单个工具定义
* `src/services/`：API 客户端和业务逻辑
* `src/lib/`：共享实用程序
* `src/index.ts`：服务器入口点
## 📚 资源
* [Defuse Protocol 一键 SDK](https://github.com/defuse-protocol/one-click-sdk-typescript)
* [模型上下文协议（MCP）](https://modelcontextprotocol.io)
* [NEAR 协议](https://near.org)
## ⚠️ 免责声明
该项目与跨链交换基础设施交互。用户在执行交换前应谨慎并验证所有交易详情。跨链交易涉及多个区块链，具有固有的风险。
## 📄 许可证
[MIT](LICENSE)
