内容
<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-server</h1>
<p align="center"><strong>MCP 工具来自 three.ws — 免费文本转 3D，付费文本/图像转 3D，头像，绑定，代理声誉等。付费调用按每次调用结算，单位为 USDC。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/mcp-server"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/mcp-server?logo=npm&color=cb3837"></a>
<a href="https://www.npmjs.com/package/@three-ws/mcp-server"><img alt="downloads" src="https://img.shields.io/npm/dm/@three-ws/mcp-server?color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/mcp-server?color=3b82f6">
<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-7c3aed"></a>
<img alt="node" src="https://img.shields.io/node/v/@three-ws/mcp-server?color=339933&logo=node.js">
<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="#快速开始-30秒">快速开始</a> ·
<a href="#工具列表">工具列表</a> ·
<a href="#环境变量">配置</a> ·
<a href="#编程客户端">编程客户端</a> ·
<a href="#支付流程">支付流程</a> ·
<a href="https://three.ws">three.ws</a>
</p>
---
> 来自 [three.ws](https://three.ws) 的十六种 MCP 工具 — **一种免费** (`forge_free`: 文本提示 → 3D GLB 在免费 NVIDIA NIM / Microsoft TRELLIS 通道上，无需支付和 API 密钥) 和十五种付费：文本/图像 → 3D 网格生成，3D 头像，GLB 自动绑定，姿势种子，pump.fun 快照，ERC-8004 代理声誉，ENS/SNS 解析，代理委托，代币情绪，AgenC 协调读取，aixbt 市场情报和 Solana 别名打磨器。付费调用通过 Solana 主网上的 [x402](https://x402.org) 支付协议以 USDC 结算（`exact` 方案）。无订阅，无 API 密钥 — 按调用付费，失败的调用不会向调用者收费。
---
## 快速开始（30 秒）
### Claude 代码
```bash
claude mcp add 3d-agent -- npx -y @three-ws/mcp-server
```
如果您还需要接收付款（服务器操作员），请将付款地址作为环境变量传递： `claude mcp add 3d-agent -e MCP_SVM_PAYMENT_ADDRESS=您的Solana钱包地址 -- npx -y @three-ws/mcp-server`.
### Claude 桌面版
将以下内容粘贴到您的 **Claude 桌面版** 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上，`%APPDATA%\Claude\claude_desktop_config.json` 在 Windows 上）：
```json
{
"mcpServers": {
"3d-agent": {
"command": "npx",
"args": ["-y", "@three-ws/mcp-server"],
"env": {
"MCP_SVM_PAYMENT_ADDRESS": "您的Solana钱包地址"
}
}
}
}
```
重启 Claude 桌面版。所有工具都会立即出现 — 无需安装步骤。
---
## 工具列表
大多数工具会引用一个固定的 USDC 价格并在 Solana 主网上结算 `exact`（下面的价格直接来自每个工具的源代码）； **`forge_free` 是免费的** — 无需支付，无需钱包，无需 API 密钥。每个工具还会声明 MCP 工具注释（`readOnlyHint`，`destructiveHint`，`idempotentHint`，`openWorldHint`），以便客户端可以正确设置确认提示 — 这些工具都不是破坏性的。
### 3D 生成
| 工具 | 价格 | 返回内容 |
| --- | --- | --- |
| `forge_free` | **免费** | 从**文本提示**生成带有纹理的 3D GLB，零成本。在免费的 NVIDIA NIM（Microsoft TRELLIS）文本 → 3D 通道上驱动 three.ws `/api/forge` 管道 — 与 [`/forge`](https://three.ws/forge) 网页使用的提示草图相同的引擎。无需 x402 支付，无需钱包，无需 API 密钥。选择层级 `draft`（快速，默认），`standard` 或 `high` — 全部免费。返回持久的 `glbUrl`，three.ws 查看器 `preview` 链接，`tier` 和实际运行的 `backend`。仅限文本；对于图像/多视图输入或 Granite 导向的链，请使用 `mesh_forge`。将 `glbUrl` 输入到 `rig_mesh` 以使其动画化。 |
| `mesh_forge` | $0.25 | 从**文本提示或参考图像**生成带有纹理的 3D GLB。文本模式运行一系列专家模型 — IBM Granite “提示导向器” 将提示重写为优化的单主题 3D 规格，FLUX 渲染参考图像，Microsoft TRELLIS / Tencent Hunyuan3D 重建网格。图像模式（`image_url`）直接重建。返回持久的 `glbUrl`，three.ws 查看器 `preview`，`directedPrompt` 和时间。 |
| `rig_mesh` | $0.20 | 将静态 GLB 自动绑定到动画就绪模型 — 人形骨骼 + 每个顶点皮肤权重通过 VAST-AI UniRig。获取 `glb_url`（例如 `mesh_forge` 的输出），返回 `riggedGlbUrl` 和 three.ws pose-studio 链接。 |
| `text_to_avatar` | $0.15 | 从文本提示或参考图像 URL 生成带有纹理的 3D GLB 头像，驱动 Replicate（默认为 Hunyuan-3D 3.1）。返回 GLB URL，模型版本，预测 ID 和时间。 |
| `get_pose_seed` | $0.001 | 三个.ws pose-studio 人偶的确定性种子 + 完整欧拉旋转姿势图（弧度），从存储库预设库中匹配。包括 `https://three.ws/pose?seed=…&preset=…` 处的 `previewUrl`。 |
### Solana 和市场
| 工具 | 价格 | 返回内容 |
| --- | --- | --- |
| `pump_snapshot` | $0.005 | 实时代币快照 — USD 价格（Jupiter），24 小时交易量 + 交易对（Dexscreener），铸造元数据 + 图像（pump.fun frontend-api-v3），以及链上顶级持有者分布（Solana RPC）。如果设置了 `HELIUS_API_KEY`，则添加 Helius DAS 数据。 |
| `sentiment_pulse` | $0.003 | Solana 代币的情绪：使用 three.ws 确定性词典评估最近的 pump.fun 评论（以及调用者提供的可选片段）。返回整体 + 按来源分类的明细，并附有示例。与 `pump_snapshot` 配对使用。 |
| `vanity_grinder` | $0.05 | Solana 密钥对，其 base58 地址以 `prefix`（和可选的 `suffix`）开头。返回完整的 base58 密钥 — 视为秘密。固定价格（使用 `MCP_VANITY_PRICE_USD` 覆盖）；难度守卫拒绝前缀太长而无法在迭代上限内挖掘。 |
| `aixbt_intel` | $0.01 | aixbt 叙事智能馈送 — 加密货币的近期智能项目，包含类别，描述，观察计数，官方来源标志和相关项目/股票代码。可选类别/链过滤。实时 aixbt REST API。 |
| `aixbt_projects` | $0.01 | aixbt 动量扫描 — 按激增/攀升/活跃分数排名的项目，包含股票代码，链，市场指标（价格，市值，24 小时交易量 + 变化）和近期情报。可按名称或链过滤。实时 aixbt REST API。 |
### 代理和身份
| 工具 | 价格 | 返回内容 |
| --- | --- | --- |
| `agent_reputation` | $0.01 | ERC-8004 声誉：`getReputation`，`getTotalStake`，以及来自请求链（默认为 Base）的最新 `ReputationSubmitted` / `ReputationStaked` 事件。从钱包地址自动解析 `agentId`。 |
| `agent_delegate_action` | $0.01 | 向 three.ws 注册的代理发送消息并接收其响应（它使用其配置的 Claude 模型 + 系统提示）。已退出 MCP 委托的代理被拒绝。适用于代理到代理协作和工具组合。 |
| `ens_sns_resolve` | $0.0005 | 跨 **ENS** （`.eth` → 通过 ethers 的以太坊地址）和 **SNS** （`.sol` → 通过 Bonfida 的 Solana 所有者钱包，以及所有者拥有的其他 `.sol` 域名）解析人类可读名称。无后缀的名称同时针对两者尝试。 |
| `agenc_list_tasks` | $0.001 | 列出 Solana 钱包创建的每个公共 AgenC 任务 — 任务 PDA，状态，奖励，截止日期，工作者计数，奖励铸造。AgenC（agenc.tech，Tetsuo Corp）是 Solana 任务协调协议。`cluster` 默认为主网。 |
| `agenc_get_task` | $0.001 | 单个 AgenC 任务的链上状态 + 生命周期时间线。传递 `taskPda` 或 `{creator, taskId}`（十六进制或 UTF-8 标签）。返回状态，奖励，截止日期，工作者计数，生命周期事件，奖励铸造。 |
| `agenc_get_agent` | $0.001 | AgenC 代理的链上注册。传递 `agentPda` 或 `agentId`（十六进制或 UTF-8 标签）。返回权限钱包，功能位掩码，端点 URL，状态，声誉，权益和活动任务计数。 |
---
## 安装
服务器在您的机器上本地运行，并通过 stdio JSON-RPC 进行通信 — 您的 MCP 客户端通过上面的 `npx` 命令自动启动它。您不需要全局安装 `npm install`。
如果您更喜欢全局安装：
```bash
npm install -g @three-ws/mcp-server
```
然后在您的配置文件中将 `"command": "npx", "args": ["-y", "@three-ws/mcp-server"]` 替换为 `"command": "3d-agent-mcp"`。
---
## 环境变量
### 付款（设置此项以接收付款）
| 变量 | 描述 |
| --- | --- |
| `MCP_SVM_PAYMENT_ADDRESS` | Solana USDC 付款地址（base58），工具接收付款。如果未设置，服务器仍会启动并将付费调用的 USDC 路由到 three.ws 平台付款 — 设置此项为 32-44 个字符的 base58 钱包以自行收款。配置但格式错误的地址会快速失败。 |
### 可选参数
| 变量名 | 默认值 | 描述 |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `HELIUS_API_KEY` | 未设置 | 添加 Helius DAS 增强功能到 `pump_snapshot` |
| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | 主要的 Solana RPC 节点，用于 `pump_snapshot` / AgenC 读取 |
| `SOLANA_RPC_URLS` | 内置公共节点集 | **故障转移** — 逗号分隔的 Solana RPC 节点，按顺序尝试；第一个健康的节点响应 |
| `MCP_EVM_RPC_<chainId>` | 内置公共节点集 | **故障转移** — 逗号分隔的 EVM RPC 节点，用于特定链（`agent_reputation`，ENS 使用链 1） |
| `X402_FACILITATOR_URL_SOLANA` | `https://facilitator.payai.network` | 主要的 PayAI Solana 促进者，验证并结算支付 |
| `X402_FACILITATOR_URLS_SOLANA` | 未设置 | **故障转移** — 逗号分隔的促进者；早期条目在初始化时优先，后续节点在故障时覆盖 |
| `X402_FACILITATOR_TOKEN_SOLANA` | 未设置 | Solana 促进者的 Bearer Token（如果需要） |
| `X402_FEE_PAYER_SOLANA` | three.ws 默认 | 结算交易的费用支付方 |
| `MCP_VANITY_PRICE_USD` | `$0.05` | `vanity_grinder` 的固定价格 |
| `FORGE_FREE_API_BASE` | `https://three.ws` | three.ws 源的免费 `forge_free` 工具调用（`/api/forge`） |
| `FORGE_FREE_TIMEOUT_MS` | `180000` | `forge_free` 的超时预算 |
| `FORGE_FREE_POLL_MS` | `3000` | `forge_free` 的轮询间隔 |
| `FORGE_FREE_ATTEMPTS` | `2` | `forge_free` 的最大生成次数，当 NVIDIA 通道降级时优先使用**持久**结果（1-4） |
| `MCP_REVIEW_SECRET` | 未设置 | **评论权限**。当设置后，呈现匹配的 `MCP_REVIEW_MODE` 的调用者运行付费工具时无需费用（连接器评论访问） |
| `MCP_REVIEW_MODE` | 未设置 | 客户端值，必须与服务器的 `MCP_REVIEW_SECRET` 匹配，以激活上述评论权限 |
| `MCP_POSE_PREVIEW_BASE` | `https://three.ws/pose` | `get_pose_seed` 预览链接的基准 URL |
| `MCP_AGENT_REP_RPC_<chainId>` | 公共 RPC | 每链 RPC 重写，用于 `agent_reputation`（在故障转移集之前尝试） |
| `MCP_AGENT_REP_LOG_WINDOW` | `200000` | `agent_reputation` 事件扫描的区块窗口 |
| `X402_ASSET_MINT_SOLANA` | USDC (`EPjFW…Dt1v`) | 结算为支付资产的 SPL 铸造（默认为 Solana USDC） |
| `SOLANA_DEVNET_RPC_URL` | 公共开发网络 | 当 `cluster: "devnet"` 时，AgenC 工具的开发网络 RPC |
| `AGENC_RPC_URL` | 未设置 | 所有 AgenC 读取的单一端点覆盖（胜过集群默认值） |
| `MCP_ENS_RPC_URL` / `MAINNET_RPC_URL` | 故障转移集 | `ens_sns_resolve` 的以太坊主网 RPC 重写 |
| `MESH_FORGE_TIMEOUT_MS` / `MESH_FORGE_POLL_MS` | `180000` / `3000` | `mesh_forge` 重建轮询预算 / 间隔 |
| `MESH_FORGE_DIRECTOR` | `1`（开启） | 将 `0` 设置为跳过 `mesh_forge` 中的 IBM Granite 提示导演阶段 |
| `RIG_MESH_TIMEOUT_MS` / `RIG_MESH_POLL_MS` | `180000` / `3000` | `rig_mesh` 轮询预算 / 间隔 |
### `text_to_avatar`（Replicate）
`text_to_avatar` 工具驱动 Replicate。如果以下两个变量未设置，它将返回 `not_configured` 错误而不是生成 — 其他所有工具无需它们即可正常工作。
| 变量名 | 默认值 | 描述 |
| ------------------------------ | ---------------------- | ----------------------------------------------------------------------- |
| `REPLICATE_API_TOKEN` | 未设置（**必填**） | 用于提交预测的 Replicate API Token |
| `REPLICATE_TEXT_TO_AVATAR_MODEL` | 未设置（**必填**) | 固定的商业可用图像/文本转 3D 版本哈希（例如 Hunyuan-3D 3.1） |
| `MCP_TEXT_TO_AVATAR_TIMEOUT_MS` / `MCP_TEXT_TO_AVATAR_POLL_MS` | `110000` / `2000` | 预测轮询预算 / 间隔 |
| `MCP_TEXT_TO_AVATAR_REHOST` | `0` | 将 `1` 设置为通过 `MCP_REHOST_ENDPOINT` + `MCP_REHOST_KEY` 将 Replicate GLB 重定向到 three.ws R2 |
---
## 编程客户端
使用 `@x402/mcp` 的 `wrapMCPClientWithPayment` 从另一个 Node 服务调用这些工具。包装器自动处理 402 重试：
```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { wrapMCPClientWithPayment } from '@x402/mcp';
import { x402Client } from '@x402/core/client';
import { registerExactSvmScheme } from '@x402/svm/exact/client';
import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';
const transport = new StdioClientTransport({
command: 'npx',
args: ['-y', '@three-ws/mcp-server'],
env: {
// 服务器接收的 USDC 地址。您的客户端从以下 Solana 密钥对中资助支付。
MCP_SVM_PAYMENT_ADDRESS: process.env.MCP_SVM_PAYMENT_ADDRESS,
},
});
const mcp = new Client({ name: 'agent', version: '1.0.0' });
await mcp.connect(transport);
// Solana 主网，`exact` 方案 — 这些工具接受的唯一网络/方案。
const payer = Keypair.fromSecretKey(bs58.decode(process.env.AGENT_SOLANA_SECRET_KEY));
const x402 = new x402Client();
registerExactSvmScheme(x402, { signer: payer });
const paid = wrapMCPClientWithPayment(mcp, x402, { autoPayment: true });
const result = await paid.callTool('get_pose_seed', { prompt: 'warrior stance' });
// 优先使用 MCP 结构化输出；对于较旧的服务器，备用文本镜像。
console.log(result.structuredContent ?? JSON.parse(result.content[0].text));
```
`forge_free` 无需付款人 — 它从不发出 402 — 因此您可以直接在 **裸** MCP 客户端（`wrapMCPClientWithPayment` 之前）调用它：
```javascript
// 免费文本 → 3D — 无钱包，无支付，无 API 密钥。
const free = await mcp.callTool('forge_free', { prompt: 'a glossy white robot mascot', tier: 'draft' });
const out = free.structuredContent ?? JSON.parse(free.content[0].text);
console.log(out.glbUrl, out.preview); // 持久 GLB + 浏览器内查看器链接
```
---
## 游标
在 Cursor 的 MCP 设置（`Cursor > Settings > Features > MCP`）：
```json
{
"mcpServers": {
"3d-agent": {
"command": "npx",
"args": ["-y", "@three-ws/mcp-server"],
"env": {
"MCP_SVM_PAYMENT_ADDRESS": "YourSolanaWallet"
}
}
}
}
```
---
## 从源代码运行
从 monorepo 根目录：
```bash
npm install
node mcp-server/src/index.js
```
交互式检查工具：
```bash
npm run inspect --prefix mcp-server
```
---
## 支付流程
服务器是 x402 **资源服务器**。在每次工具调用时：
1. 客户端发送 `tools/call` 请求（尚未支付）。
2. 服务器返回 `PaymentRequired`（v2 MCP 传输规范），包含 USDC 金额和支付地址。
3. 有支付功能的客户端（或 `wrapMCPClientWithPayment`）签署并提交链上支付。
4. 客户端重试 `tools/call` 并附加 `_meta["x402/payment"]`。
5. 服务器验证并结算通过配置的促进者，运行工具并返回结果，附带 `_meta["x402/payment-response"]`。
每个工具都在 **Solana 主网** 上使用 `exact` 方案（`@x402/svm` 交付 `upto`/计量方案）结算为 USDC。每个工具都引用固定价格；没有后-hoc 计量。
成功的结果包含工具的 JSON，两种形式：`content[0].text`（适用于纯文本客户端）和 `structuredContent`（MCP 2025-06-18 结构化输出 — 一个可直接使用的对象）。工具级错误设置 `isError: true`，x402 包装器 **取消而不是结算** 支付，因此失败的调用不会向调用者收费。
---
## 可靠性和故障转移
每个外部依赖都有一个备份路径，因此单个提供者的故障不会使工具宕机 — 并且没有调用可以无限期地挂起付费请求。
- **每个出站 HTTP 调用** 都通过共享的弹性层运行（`src/lib/resilient-fetch.js`）：每个尝试都有一个硬超时加上抖动的指数退避重试，用于暂时的 `429`/`5xx`/网络错误，遵守 `Retry-After`。默认情况下，重试仅限于幂等读取 — 像 `agent_delegate_action` 这样的非幂等操作不会被静默重放。
- **Solana RPC** （`src/lib/solana-rpc.js`）在有序端点列表（`SOLANA_RPC_URLS`，否则内置公共节点集）中故障转移。限流或关闭的端点会轮换到末尾，下一个端点会响应。
- **EVM RPC** （`src/lib/evm-rpc.js`）对多个端点使用 ethers `FallbackProvider`（仲裁 1）每个链（`MCP_EVM_RPC_<chainId>` 或内置冗余），每个请求都有超时限制。
- **x402 促进者** 接受逗号分隔的 `X402_FACILITATOR_URLS_SOLANA`：早期条目在初始化时优先，后续促进者覆盖 Solana `exact` 类型，如果主要促进者的 `/supported` 不可达。
- **数据故障转移：** `pump_snapshot` 从 Dexscreener 交叉填充其 USD 价格，当 Jupiter 不可用时，以及每个上游故障转移到 `null`/`{ error }` 字段，而不是使整个快照失败。
为了最大化冗余，请设置专用端点而不是依赖公共默认值：
```bash
SOLANA_RPC_URLS="https://your-primary-rpc,https://your-secondary-rpc"
MCP_EVM_RPC_8453="https://your-base-rpc,https://base-rpc.publicnode.com"
X402_FACILITATOR_URLS_SOLANA="https://facilitator.payai.network,https://your-backup-facilitator"
```
---
## 架构
```
┌─────────────────┐ ┌─────────────────────┐ ┌──────────────────────┐
│ Claude Desktop │────▶│ @three-ws/mcp-server │────▶│ x402 促进者 │
│ / 游标 / │ │ （stdio 传输） │ │ （PayAI — Solana │
│ 您的代理 │ │ │ │ USDC，确切） │
└─────────────────┘ └─────────────────────┘ └──────────────────────┘
```
来源：[`mcp-server/`](https://github.com/nirholas/three.ws/tree/main/mcp-server)
---
## 要求
- Node.js **>= 20** （来自 `engines`）。
- `MCP_SVM_PAYMENT_ADDRESS` 中的 Solana USDC 支付地址（或 `X402_PAY_TO_SOLANA` / `X402_PAY_TO`）以结算付费调用 — 参见[环境变量](#environment-variables)。工具注册（名称/方案）不需要环境变量；只有实际的付费调用才需要。
- 支付感知型 MCP 客户端（或 `@x402/mcp` 的 `wrapMCPClientWithPayment`）从 Solana 密钥对资助支付。
## 相关
- [`@three-ws/pumpfun-mcp`](https://www.npmjs.com/package/@three-ws/pumpfun-mcp) — 免费、只读的 pump.fun + Solana MCP（代币发现、链上分析、实时 3D 快照；无需密钥）。
## 链接
- 首页：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>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 参见 [LICENSE](./LICENSE)。除版权所有者的明确书面许可外，不得授予任何权利。
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器