使用说明

W3Ship商务MCP服务器

让AI为你购物——没有密码，没有登录，只有加密身份。

W3Ship是第一个用于 人工智能驱动的商业它为Claude、Cursor和VS Code Copilot等AI代理提供了创建购物车、下订单、跟踪货物、预订会话、， 通过Uniswap交换代币, P2P销售商品，以及 通过店内取货方式分发促销品 --所有这些都使用加密身份（SLH-DSA/ECDSA）而不是密码。

基于TMF开放API标准（TMF663、TMF622、TMF621）构建，以实现互操作性。

⚡ 快速开始

通过npx安装（推荐）

无需安装——只需配置您的AI客户端：

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "w3ship": {
      "command": "npx",
      "args": ["-y", "w3ship-mcp-server"],
      "env": {
        "VALKEY_HOST": "localhost",
        "VALKEY_PORT": "6379"
      }
    }
  }
}

光标 (.cursor/mcp.json):

{
  "mcpServers": {
    "w3ship": {
      "command": "npx",
      "args": ["-y", "w3ship-mcp-server"],
      "env": {
        "VALKEY_HOST": "localhost",
        "VALKEY_PORT": "6379"
      }
    }
  }
}

VS Code (.vscode/mcp.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等）

🛠️ 工具（共22个）

🛒 购物车（TMF663）

工具	说明
`create_cart`	创建购物车。用途 `W3SHIP_PUBLIC_KEY` 如果已配置，则自动
`get_cart`	通过其公钥ID检索购物车
`add_item`	将商品（产品供应+数量）添加到购物车
`delete_cart`	删除购物车

📦 订单（TMF622）

工具	说明
`create_order`	将购物车转换为确认订单并开始履行
`get_order`	按订单ID检索订单详细信息

🚚 发货跟踪（TMF621）

工具	说明
`track_shipment`	通过模拟实时更新跟踪交付状态

📅 会议预订

工具	说明
`get_available_slots`	按地点和日期获取可用的会话时间段（VR、健身、餐饮、沙龙等）
`hold_slot`	预留一个会话时段（在等待付款期间保持10分钟）
`list_bookings`	列出已确认的预订，可选择按地点/日期过滤

🔐 身份查找

工具	说明
`ship_address`	使用公钥+定时签名检索物理收货地址

标识查找被转发到集中式W3Ship API(w3ship.com/api/identity).签名验证和数据库访问发生在服务器端——您端不需要AWS凭据。

🧪 设置和演示

工具	说明
`generate_demo_key`	生成一个演示ECDSA密钥对进行测试——尝试没有钱包的商业流程
`get_identity`	显示当前配置的标识或如何设置标识的说明

🔄 Uniswap交换（v1.3.0中的新功能）

工具	说明
`get_swap_quote`	从Uniswap获取掉期报价——返回输出量、天然气估算、价格影响和路由路径。支持V2、V3、V4和UniswapX。默认链：基础（8453）。
`check_token_approval`	检查是否批准在Uniswap上交换令牌。如果需要，返回审批交易数据。

需要 UNISWAP_API_KEY --免费获取 developers.uniswap.org基础链的内置代币地址：ETH、USDC、USDT、DAI、WETH。为其他代币传递任何ERC-20合约地址。

🏪 P2P市场（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_promo(listingId: "...", fulfillmentChoice: "pickup", pickupLocationId: "qbm")
AI返回取货地点、时间和指令。领取索赔不需要地址注册，只需要钱包身份。

🔐 加密身份

W3Ship使用 加密身份 --没有用户名，没有密码，没有帐户。支持三种身份类型：

方案	密钥大小	用例
EVM地址	20字节（40个十六进制字符）	MetaMask/任何以太坊钱包
ECDSA（P-256）	33字节（压缩）/65字节（未压缩）	标准web3钱包
SLH-DSA	32字节（64个十六进制字符）	后量子安全身份（Dah.mx）

您的钱包地址或公钥就是您的购物车ID。无需注册。

⚙️ 配置

环境变量

变量	必填	默认	描述
`W3SHIP_PUBLIC_KEY`	否	--	您的钱包地址或公钥（十六进制）。设置一次，所有工具都会自动使用它
`UNISWAP_API_KEY`	没有交换报价的	-	Uniswap Trading API密钥。获取你的 developers.uniswap.org
`VALKEY_HOST`	没有	`localhost`	Redis/Valkey主机
`VALKEY_PORT`	没有	`6379`	Redis/Valkey端口
`VALKEY_PASSWORD`	否	--	Redis/Valkey密码（如果启用了auth）
`W3SHIP_API_URL`	没有	`https://w3ship.com`	W3Ship API的基本URL（标识、会话预订）

获取您的密钥

MetaMask用户：只需复制您的以太坊地址（例如。 0x1234...abcd)--它直接工作
Dah.mx用户：设置→ AI助手设置→ 复制密钥
演示/测试：不要设置密钥--使用 generate_demo_key 在你的AI助手中

🏗️ 建筑

MCP服务器是 瘦客户机 它将本地购物车/订单存储与集中式W3Ship服务相结合：

┌─────────────────────────────────────────────┐
│  AI Client (Claude / Cursor / VS Code)      │
│  "Create a cart and book a fitness session"  │
└──────────────────┬──────────────────────────┘
                   │ stdio (MCP Protocol)
┌──────────────────▼──────────────────────────┐
│  W3Ship MCP Server (your machine)           │
│                                              │
│  Local Storage (Redis/Valkey):               │
│  ┌──────────┐ ┌─────────┐ ┌──────────────┐  │
│  │ Cart     │ │ Orders  │ │ Shipment     │  │
│  │ (TMF663) │ │ (TMF622)│ │ (TMF621)     │  │
│  └──────────┘ └─────────┘ └──────────────┘  │
│                                              │
│  Centralized API (w3ship.com):               │
│  ┌──────────────┐  ┌─────────────────────┐  │
│  │ Booking      │  │ Identity Lookup     │  │
│  │ /api/slots   │  │ /api/identity       │  │
│  └──────────────┘  └─────────────────────┘  │
└──────────────────────────────────────────────┘

商业（购物车、订单、发货）→ 本地存储在Redis中
身份（地址查找）→ 转发给 w3ship.com API
会议预订 → 转发给 w3ship.com API
没有AWS凭据 需要。不需要云配置。

💡 对话示例

购物与预订

You:    "I want to shop on W3Ship"
Claude: [calls get_identity — no key configured]
        [calls generate_demo_key — creates a test identity]
        [calls create_cart with the demo key]
        "You're all set! I've created a shopping cart for you.
         What would you like to buy?"

You:    "Book me a VR session for this afternoon"
Claude: [calls get_available_slots for today]
        "Here are today's sessions at Downtown VR:
         • 2:00 PM - $45 (3 spots left)
         • 4:00 PM - $45 (5 spots left)
         Which time works?"

You:    "4 PM"
Claude: [calls hold_slot → add_item]
        "Slot held for 10 minutes. Added to your cart."

You:    "Place the order"
Claude: [calls create_order]
        "Order confirmed! Tracking: TRK-8392751046"

领取皮卡促销（v1.6.0中的新功能）

You:    "Any free promos I can grab?"
Claude: [calls search_listings with category: promotional]
        "There's a free VR Experience Card available!
         You can pick it up at Quaker Bridge Mall."

You:    "I'll take it"
Claude: [calls claim_promo with fulfillmentChoice: pickup]
        "Claimed! Here's your pickup info:
         📍 Quaker Bridge Mall, Lawrenceville NJ
         🕐 Mon-Sat 10am-9pm
         🎟️ Claim ID: CLM-MMB1ZW3W-W98I
         Show your claim ID at the VR kiosk near the food court."

提示： 对于生产用途，请通过以下方式设置您的真实钱包密钥 W3SHIP_PUBLIC_KEY 在您的MCP配置中。看获取您的公钥上面。

📰 按

TechBullion: W3Ship的工作原理：将任何AI变成商家的MCP服务器
数字期刊: 通过Unichain上的Uniswap CCA推出量子抗性商业代币
跨行业联合 500+个网点 — 全面覆盖→

🔗 链接

网站: w3ship.com
按: w3ship.com/press
GitHub: github/baskcart/w3ship
W3SH代币: Uniswap CCA拍卖

📄 许可证

麻省理工学院——见许可证

模式	工作原理
`ship`	客户支付运费，邮寄物品（原始流程）
`pickup`	客户在实际地点取货-- 零成本
`both`	客户选择发货或提货