内容
W3Ship Commerce MCP 服务器
> **让 AI 为您购物 — 无需密码，无需登录，只需加密身份。**
W3Ship 是首个适用于 **AI 驱动的商业** 的 MCP（模型上下文协议）服务器。它赋予 Claude、Cursor 和 VS Code Copilot 等 AI 代理创建购物车、下单、跟踪发货、预订会话、**通过 Uniswap 交换代币**、**点对点销售商品** 以及 **店内自取促销商品** 的能力 — 所有这些都使用加密身份（SLH-DSA / ECDSA）而非密码。
该服务器基于 TMF 开放 API 标准（TMF663、TMF622、TMF621）构建，以实现互操作性。
---
## ⚡ 快速入门
### 通过 npx 安装（推荐）
无需安装 — 只需配置您的 AI 客户端：
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"w3ship": {
"command": "npx",
"args": ["-y", "w3ship-mcp-server"],
"env": {
"_HOST": "localhost "VALKEY_PORT": "6379"
}
}
}
}
```
**Cursor** (`.cursor/mcp.json`)：
```json
{
"mcpServers": {
3ship": {
": "npx",
args": ["-y", "w3ship-mcp-server"],
"env": {
"VALKEY_HOST": "localhost",
"VALKEY_PORT": "6379"
}
}
}
}
```
**VS Code** (`.vscode/mcp.json`)：
```json
{
"servers": {
"w3ship": {
"type": "stdio",
"command": "npx",
"args": ["-y", "w3ship-mcp-server"],
"env "VALKEY_HOST": "localhost",
"VALKEY_PORT": "6379"
}
}
}
}
```
### 先决条件
- **Node.js** 18+
- **Redis / Valkey** 实例（用于购物车、订单和发货存储）
- 本地：`docker run -p 6379:6379 redis:latest`
- 或任何 Redis 兼容服务（AWS ElastiCache、Upstash 等）
---
## 🛠️ 工具列表
### 🛒 购物车（TMF663）
| 工具 | 描述 |
|:---|:---|
| `create_cart` | 创建购物车。如果配置了 `W3SHIP_PUBLIC_KEY`，则自动使用 |
| `get_cart` | 通过其公钥 ID 检索购物车 |
| `add_item` | 向购物车添加商品（产品供应 + 数量） |
| `delete_cart` | 删除购物车 |
### 📦 订单（TMF622）
| 工具 | 描述 |
|:---|:---|
|_order` | 将已确认订单并启动履行 |
| `get_order` | 通过订单 ID 检索订单### 🚚 发货TMF621）
工具 | 描述 |
|:| `track` | 跟踪配送状态实时更新 |
### 会话预订
| 工具 | 描述 |
|:---|:---|
| `get_available | 按位置和日期获取可用会话时间段（VR餐饮、沙龙等） |
| `hold_slot` | 预留一个会话时间段（保留 10 分钟，待付款） |
| `list_bookings` |已确认的预订，可选按位置/日期筛选 🔐 身份| 工具 | 描述 |
---|
| `` | 使用公钥 + 计时签名检索物理发货地址 |
> 身份查找被转发到集中式 W3Ship API (`w3ship.comidentity`)。签名验证访问在服务器端需在您这边 凭证。
### 与演示
| 工具 | 描述 |
|:---| `generate_demo | 为测试生成演示 密钥对 — 无尝试商业流程 |
get_identity` | 显示当前配置的身份或设置说明 |
### 🔄 交换（v1.3.0 新增）
| 工具 | 描述 |
|:---|:---|
| `get_swap_quote` | 从 Uniswap 获取交换报价 — 返回输出金额、gas 估计、价格影响和路由路径。支持 V2、V3、V UniswapX。默认Base（8453）。 `check_token_approval` | 检查代币是否已在 Uniswap 上批准交换。如果需要，返回批准交易数据。 `UNISWAP_API_KEY` — 在.uniswap.org](https://developers.uniswap.org) 免费获取。内置代币地址 链：ETH、USDT、DAI、WETH。传递任何 ERC 合约地址以获取其他代币。
### 🏪 点对点市场（v1.4.0 新增）
| 工具 | 描述 |
|:---|:---|
| `create_listing` | 销售任何商品 — 无需商家注册。设置标题、价格、货币和您的钱包地址用于支付。默认情况下，列表在 30 天后过期。 |
| `search_listings` | 按类别（电子产品、礼物、服装等）或关键词搜索浏览活动列表。 |
| `get_listing` | 获取列表的完整详细信息：描述、价格、卖家、支付地址、发货地区。 |
| `remove_listing` | 删除您自己的卖家地址必须匹配。 |
> 类别：`electronics`、`clothing`、`collectibles`、`home`、`sports`、`gifts`、`books`、`other`。任何拥有钱包地址的人都是商家。
### 💳 支付与履行（v1.4.0 新增）
| 工具 | 描述 |
|:---|:---|
| `confirm_payment` | 提交链上交易哈希以验证支付。支持 Base（8453）和 Tempo 链。更新订单为“已支付”。 |
| `add_tracking` | 卖家在发货商品后提供真实的承运商跟踪（UPS、FedEx、USPS、DHL 等）。 |
> P2P 订单自动检测列表项（LST-* 前缀），填写卖家钱包地址，并将支付状态设置为 `awaiting_payment`。支付后，卖家使用 `add_tracking` 提供发货信息。
### 🎁 促销商品与自取（v1.6.0 更新）
| 工具 | 描述 |
|:---|:---|
| `claim_promo` | 领取免费促销列表。支持 **发货** 或 **店内自取**。每个钱包一个。 |
> **v1.6.0 新增：店内自取**
>
> 促销列表现在支持三种履行模式：
>
> | 模式 | 工作原理 |
> |:---|:---|
> | `ship` | 客户支付运费，商品邮寄（原始流程） |
> | `pickup` | 客户在实体地点领取 — **零成本** |
> | `both` | 客户选择发货或自取 |
>
> 创建自取促销：
> ```
> create_listing(
> isPromo: true,
> fulfillmentType: "pickup",
> pickupLocations: [{
> id: "qbm",
> name: "Quaker Bridge Mall",
> address: "3320 Brunswick Pike, Lawrenceville NJ",
> hours: "Mon-Sat 10am-9pm",
> instructions: "Visit the kiosk near the food court. Show your claim ID."
> }]
> )
> ```
>
> 领取自取：
> claim_promoId: "...", fulfillmentChoice: "pickup",Id: "qbm")
> ```
>
> AI取地点、营业时间和说明。自取领取无需注册地址 — 只需钱包身份。
---
## 🔐 加密身份
W3Ship 使用 **加密身份** — 无用户名、无密码、无账户。支持三种身份类型：
| 方案 | 密钥大小 | 用例 |
|:---|:---|:---|
| ** 地址** | 字节（40 个） | MetaMask / 任何以太坊钱包 |
| **ECDSA（P-256）** | 33 字节（压缩）/ 65 字节（未压缩） web3 钱包 |
SLH-DSA32 字节 个十六进制字符） | 抗量子安全身份（Dah.mx） |
您的或公钥是您的。无需注册。
⚙️ 配置
### 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|:---|:---|:---|:---|
| `W3SHIP_PUBLIC_KEY` | 否 | — | 您的钱包地址或公钥（十六进制）。设置一次自动使用 |
| `AP_API_KEY` | 否 | — | 交易 API 密钥，用于交换报价。在 [developers.uniswap.org](https://developers.org) 获取 |
| `VALKEY_HOST` | 否 | `localhost` | Redis/Valkey 主机 `VALKEY_PORT` | `6379 Redis/Valkey |
| `VALKEY_PASSWORD` | 否 | — | Redis/Valkey 密码（如果启用身份验证）W3SHIP` | 否 |://w3ship | W3Ship API（身份、会话预订） |
### 获取您的密钥
- **MetaMask 用户**：只需复制您的以太坊地址（例如 `0x1234...abcd`）— 直接有效
-.mx 用户** AI 助手设置 → 复制密钥
-/测试**：密钥 — 在 AI中使用 `generate_demo_key` 代替
---
🏗️ 架构
是一个 **薄，它将本地购物车/订单存储与集中3Ship 服务相结合：
```
┌────────────────────────────────────────
│ （Claude / Cursor / VS Code） │
│ "创建一个购物车并预订健身会话"──────────────────┘
stdio (MCP)
┌──────────────────▼──────────────────────────┐
│ W3Ship MCP 服务器（您的机器）│ │
│ 存储（Redis/Valkey）： │
│ ┌──────────┐ ┌─────────┐ ┌──────────────┐ │
│ │ 购物车 │ │ 订单 │ │ 发货 │ │
│ │ （TMF663） │ │ （TMF622）│ │ （TMF621） │ │
│ └──────────┘ └─────────┘ └──────────────┘ │
│ │
集中式 API（w3ship.com）： │
│ ┌──────────────┐ ┌─────────────────────┐ │
│ │ 预订 │ │ 身份查找 │ │
│ │ /api/slots │ │ /identity ││ └──────────────┘ └─────────────────────┘ │
└──────────────────────────────────────────────┘
```
- **商业**（购物车、订单、发货）→ 存储在您的 Redis 中
- **身份**（地址查找）→ 转发到 `w3ship.com` API
- **会话预订** → 转发到 `w3ship.com` API
- **无需 AWS 凭证**。无需云配置。
---
## 💡 示例对话
### 购物与预订
```
您： "我想在 W3Ship 上购物"
Claude： get_identity — 未 [调用_key — 创建测试 [调用 create_cart 使用演示密钥]
"您我已为您创建一个购物车。
您？"
您 "为我预的 VR 会aude：[调用 get_available_slots 获取今天的时段]
"今天 Downtown VR 的时段如下：
• 2:00 PM - $45（3 个名额剩余）
• 4:00 PM - $45（5 个名额剩余）
哪个时间合适？"
您： "4 点钟"
Claude：[调用 hold_slot → add_item]
"时段已保留 10 分钟。已添加到您的购物车。"
"下单aude：[调用 create_order]
"订单已确认！跟踪：TRK-8392751046"
```
### 领取具有自取功能的促销（v1.6.0 新增）
```
您： "我哪些免费促销？"
Claude：[调用 search_listings，类别：promotional]
"有一个免费的 VR 体验卡可用！
您可以在 Quaker Bridge Mall 领取。"
您： "我会接受"
Claude：[调用 claim_promofillmentChoice：pick "领取成功您的自取信息：
📍 Quaker Bridge Mall, Lawrenceville NJ
🕐 周一至周六 10am-9pm
🎟️ 领取 ID：CLM-MMB1ZW3W-W98I
在美食广场附近的 VR 售货亭出示您的领取 ID。"
```
提示：**环境中，请通过在 MCP 配置中设置钱包密钥 `W3SHIP_PUBLIC_KEY`。参见获取您的公钥](#获取您的公钥)。
---
## 📰 媒体报道
- **TechBullion**：[W3Ship 如何工作：MCP 服务器让任何 AI 成为商家](https://techbullion.com/how-w3ship-works-the-mcp-server-that-turns-any-ai-into-a-merchant/)
- **Digital Journal**：[抗量子商业代币通过 Unichain 上的 Uniswap CCA 启动](https://www.digitaljournal.com/pr/news/vehement-media/quantum-resistant-commerce-token-launches-via-1883892375.html)
- 联播超过 **500+ 个媒体 outlets** — [完整报道 →](https://w3ship.com/press)
---
## 🔗 链接
- **网站**：[w3ship.com](https://w3ship.com)
- **媒体报道**：[w3ship.com/press](https://w3ship.com/press)
- **GitHub**：[github.com/baskcart/w3ship](https://github.com/baskcart/w3ship)
- **W3SH 代币**：[Uniswap CCA 拍卖](https://app.uniswap.org)
---
## 📄 许可证
MIT — 参见 [LICENSE](./LICENSE)
