内容
<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/three-token-mcp</h1>
<p align="center"><strong>首个销毁代币的MCP服务器 - 允许任何AI代理定价、持有和销毁Solana上的$THREE。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/three-token-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/three-token-mcp?logo=npm&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@three-ws/three-token-mcp"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/three-token-mcp?color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/three-token-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/three-token-mcp?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>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为任何AI助手提供三个$THREE基本操作：读取实时美元价格、读取钱包余额和 **销毁$THREE** - 在销毁地址和three.ws金库之间分配，价格通过Jupiter实时获取。作为AI代理的通缩原语：每次`three_burn`调用都是一个真实的、可验证的Solana交易，永久移除$THREE并资助金库。
$THREE是此服务器唯一涉及的代币。合约地址（主网SPL）：`FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump`。
## 为什么与众不同
大多数付费MCP服务器结算使用USDC。而这款服务器使用项目自身的代币，目的地不是硬编码的 - 而是在运行时从 **公共** three.ws代币表面读取（`/api/token/config`，`/api/token/price`），因此铸造、十进制、销毁地址、金库和分割始终跟踪three.ws其余部分使用的规范链上配置。在签名之前，解析的铸造被断言为等于上述规范$THREE地址 - 错误配置或受损的端点不能将销毁重定向到其他代币。
## 安装
```bash
npm install @three-ws/three-token-mcp
```
使用`npx`直接运行（无需安装）：
```bash
SOLANA_SECRET_KEY=<base58> npx @three-ws/three-token-mcp
```
或全局安装`three-token-mcp`二进制文件到您的`PATH`：
```bash
npm install -g @three-ws/three-token-mcp
```
## 快速开始
**Claude 代码**，一行：
```bash
claude mcp add three-token -- npx -y @three-ws/three-token-mcp
```
**Claude 桌面版 / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"three-token": {
"command": "npx",
"args": ["-y", "@three-ws/three-token-mcp"],
"env": {
"SOLANA_SECRET_KEY": "<base58 钱包私钥>",
"SOLANA_RPC_URL": "https://您的RPC提供商"
}
}
}
}
```
`SOLANA_SECRET_KEY`仅在`three_burn`时需要。只读工具（`three_price`，`three_balance`）无需此密钥即可工作。使用MCP检查器检查表面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/three-token-mcp
```
## 工具列表
| 工具 | 类型 | 功能 |
| --------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `three_price` | 只读 | $THREE的实时美元价格（Jupiter优先，Birdeye备用）。传递`usd`以获取代币数量报价。 |
| `three_balance` | 只读 | 任意公钥的$THREE + SOL余额（默认为配置的签名者）。 |
| `three_burn` | **执行** | 在一个Solana交易中销毁以美元计价的$THREE数量，分割到销毁地址和金库。返回签名、明细和Solscan链接。 |
`three_burn`销毁钱包 **已持有的** $THREE。要先获取$THREE，请在任意Solana DEX上兑换SOL → $THREE，然后销毁。
### 安全
所有三个工具都附带 [MCP工具注解](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)：`three_price`和`three_balance`标注`readOnlyHint: true`，可以安全地自动批准；`three_burn`标注`destructiveHint: true`，因此支持注解的MCP客户端（Claude 代码、Claude 桌面版、Cursor）会在运行前提示确认。提示是建议性的 - 在服务器端，每次销毁仍受`MAX_BURN_USD`（默认 $100）限制，由`REQUIRE_CONFIRM`控制（默认开启：调用直到重新发出`confirm: true`才拒绝）。
### 输入参数
**`three_price`** — `usd`（可选正数：美元金额报价为$THREE）。
**`three_balance`** — `pubkey`（可选 base58，32–64 字符；默认为配置的签名者地址）。
**`three_burn`** — `usd`（必填正数：销毁的$THREE美元价值），`burnBps`（0–10000，默认 5000 = 50% 销毁 / 50% 金库；10000 = 销毁全部），`memo`（可选，≤120 字符；附加到链上备注），`secret`（可选 base58 签名者覆盖；默认为`SOLANA_SECRET_KEY`），`confirm`（必须为`true`，当`REQUIRE_CONFIRM`开启时执行不可逆销毁）。
## 示例
```jsonc
// three_price
> { "usd": 5 }
{ "price_usd": 0.0042, "quote": { "usd": 5, "token_amount": 1190.47, "atomics": "1190476190" } }
// three_burn — 不可逆；默认情况下需要confirm:true
> { "usd": 5, "burnBps": 5000, "confirm": true }
{
"ok": true,
"signature": "5x...",
"explorer": "https://solscan.io/tx/5x...",
"usd": 5,
"burned": 595.23,
"legs": [
{ "role": "burn", "amount": 595.23 },
{ "role": "treasury", "amount": 595.23 }
]
}
```
## 销毁构建
`three_burn`镜像three.ws浏览器支付流程：
1. `GET /api/token/config` → 铸造、十进制、销毁地址、金库。
2. `GET /api/token/price?usd=<n>` → 实时Jupiter价格和确切的$THREE原子数。
3. 构建 **一个** 交易：每个腿（销毁 + 金库）的幂等ATA创建 + SPL转账，加上一个在链上标记销毁的备注。
4. 使用您的钱包签名，发送并确认。结果报告链上签名和每个腿的金额。
服务器预先检查您的$THREE余额，如果无法支付销毁费用，则快速失败并显示清晰的错误信息。销毁受`MAX_BURN_USD`（默认 $100）限制，并由`REQUIRE_CONFIRM`控制（默认开启）。
## 需求
- **Node.js >= 20.**
- Solana主网RPC端点（公共集群适用于只读；请自带 - Helius / QuickNode / Triton - 用于销毁流量）。端点必须是`https`（仅`http://localhost`被接受，用于本地开发验证器）。
- 用于销毁：持有$THREE的钱包，以base58 `SOLANA_SECRET_KEY`（或每次调用的`secret`）提供。
### 环境变量
| 变量 | 必需 | 默认 |
| -------------------- | -------------- | ------------------------------------------------- |
| `SOLANA_SECRET_KEY` | 仅销毁需要 | — |
| `SOLANA_RPC_URL` | 否 | `https://api.mainnet-beta.solana.com` |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `MAX_BURN_USD` | 否 | `100` |
| `REQUIRE_CONFIRM` | 否 | `true`（设为`0`/`false`以跳过确认门控） |
| `THREE_BURN_ADDRESS` | 否 | Solana销毁地址 |
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
本软件为专有软件 - 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
