w3ship-mcp-server

# W3Ship Commerce MCP Server > **Let AI shop for you — with no passwords, no logins, just cryptographic identity.** W3Ship is the first MCP (Model Context Protocol) server for **AI-powered commerce**. It gives AI agents like Claude, Cursor, and VS Code Copilot the ability to create shopping carts, place orders, track shipments, book sessions, **swap tokens via Uniswap**, **sell items P2P**, and **distribute promotional items with in-store pickup** — all using cryptographic identity (SLH-DSA / ECDSA) instead of passwords. Built on TMF Open API standards (TMF663, TMF622, TMF621) for interoperability. --- ## ⚡ Quick Start ### Install via npx (recommended) No installation required — just configure your AI client: **Claude Desktop** (`claude_desktop_config.json`): ```json { "mcpServers": { "w3ship": { "command": "npx", "args": ["-y", "w3ship-mcp-server"], "env": { "VALKEY_HOST": "localhost", "VALKEY_PORT": "6379" } } } } ``` **Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "w3ship": { "command": "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" } } } } ``` ### Prerequisites - **Node.js** 18+ - **Redis / Valkey** instance (for cart, order, and shipment storage) - Local: `docker run -p 6379:6379 redis:latest` - Or any Redis-compatible service (AWS ElastiCache, Upstash, etc.) --- ## 🛠️ Tools (22 total) ### 🛒 Shopping Cart (TMF663) | Tool | Description | |:---|:---| | `create_cart` | Create a shopping cart. Uses `W3SHIP_PUBLIC_KEY` automatically if configured | | `get_cart` | Retrieve a cart by its public key ID | | `add_item` | Add an item (product offering + quantity) to a cart | | `delete_cart` | Delete a shopping cart | ### 📦 Orders (TMF622) | Tool | Description | |:---|:---| | `create_order` | Convert a cart into a confirmed order and initiate fulfillment | | `get_order` | Retrieve order details by order ID | ### 🚚 Shipment Tracking (TMF621) | Tool | Description | |:---|:---| | `track_shipment` | Track delivery status with simulated real-time updates | ### 📅 Session Booking | Tool | Description | |:---|:---| | `get_available_slots` | Get available session time slots by location and date (VR, fitness, dining, salon, etc.) | | `hold_slot` | Reserve a session slot (held for 10 minutes pending payment) | | `list_bookings` | List confirmed bookings, optionally filtered by location/date | ### 🔐 Identity Lookup | Tool | Description | |:---|:---| | `ship_address` | Retrieve a physical shipping address using a public key + timed signature | > Identity lookups are forwarded to the centralized W3Ship API (`w3ship.com/api/identity`). Signature verification and database access happen server-side — no AWS credentials needed on your end. ### 🧪 Setup & Demo | Tool | Description | |:---|:---| | `generate_demo_key` | Generate a demo ECDSA key pair for testing — try the commerce flow without a wallet | | `get_identity` | Show the currently configured identity or instructions on how to set one up | ### 🔄 Uniswap Swap (NEW in v1.3.0) | Tool | Description | |:---|:---| | `get_swap_quote` | Get a swap quote from Uniswap — returns output amount, gas estimate, price impact, and routing path. Supports V2, V3, V4, and UniswapX. Default chain: Base (8453). | | `check_token_approval` | Check if a token is approved for swapping on Uniswap. Returns approval transaction data if needed. | > Requires `UNISWAP_API_KEY` — get yours free at [developers.uniswap.org](https://developers.uniswap.org). Built-in token addresses for Base chain: ETH, USDC, USDT, DAI, WETH. Pass any ERC-20 contract address for other tokens. ### 🏪 P2P Marketplace (NEW in v1.4.0) | Tool | Description | |:---|:---| | `create_listing` | Sell anything — no merchant onboarding needed. Set title, price, currency, and your wallet address for payment. Listings expire after 30 days by default. | | `search_listings` | Browse active listings by category (electronics, gifts, clothing, etc.) or keyword search. | | `get_listing` | Get full details of a listing: description, price, seller, payment address, shipping regions. | | `remove_listing` | Remove your own listing. Seller address must match. | > Categories: `electronics`, `clothing`, `collectibles`, `home`, `sports`, `gifts`, `books`, `other`. Anyone with a wallet address is a merchant. ### 💳 Payment & Fulfillment (NEW in v1.4.0) | Tool | Description | |:---|:---| | `confirm_payment` | Submit an on-chain transaction hash to verify payment. Supports Base (8453) and Tempo chains. Updates order to "paid". | | `add_tracking` | Seller provides real carrier tracking (UPS, FedEx, USPS, DHL, etc.) after shipping the item. | > P2P orders auto-detect listing items (LST-* prefix), fill in seller wallet address, and set payment status to `awaiting_payment`. After payment, sellers use `add_tracking` to provide shipping info. ### 🎁 Promotional Items & Pickup (Updated in v1.6.0) | Tool | Description | |:---|:---| | `claim_promo` | Claim a FREE promotional listing. Supports **shipping** or **in-store pickup**. One per wallet. | > **New in v1.6.0: In-Store Pickup** > > Promo listings now support three fulfillment modes: > > | Mode | How It Works | > |:---|:---| > | `ship` | Customer pays shipping, item mailed (original flow) | > | `pickup` | Customer picks up at a physical location — **zero cost** | > | `both` | Customer chooses shipping or pickup | > > Create a pickup promo: > ``` > 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 with pickup: > ``` > claim_promo(listingId: "...", fulfillmentChoice: "pickup", pickupLocationId: "qbm") > ``` > > The AI returns the pickup location, hours, and instructions. No address registration needed for pickup claims — only wallet identity is required. --- ## 🔐 Cryptographic Identity W3Ship uses **cryptographic identity** — no usernames, no passwords, no accounts. Three identity types are supported: | Scheme | Key Size | Use Case | |:---|:---|:---| | **EVM Address** | 20 bytes (40 hex chars) | MetaMask / any Ethereum wallet | | **ECDSA (P-256)** | 33 bytes (compressed) / 65 bytes (uncompressed) | Standard web3 wallets | | **SLH-DSA** | 32 bytes (64 hex chars) | Post-quantum secure identity (Dah.mx) | Your wallet address or public key IS your cart ID. No sign-up required. --- ## ⚙️ Configuration ### Environment Variables | Variable | Required | Default | Description | |:---|:---|:---|:---| | `W3SHIP_PUBLIC_KEY` | No | — | Your wallet address or public key (hex). Set once and all tools use it automatically | | `UNISWAP_API_KEY` | No | — | Uniswap Trading API key for swap quotes. Get yours at [developers.uniswap.org](https://developers.uniswap.org) | | `VALKEY_HOST` | No | `localhost` | Redis/Valkey host | | `VALKEY_PORT` | No | `6379` | Redis/Valkey port | | `VALKEY_PASSWORD` | No | — | Redis/Valkey password (if auth enabled) | | `W3SHIP_API_URL` | No | `https://w3ship.com` | Base URL for the W3Ship API (identity, session booking) | ### Getting Your Key - **MetaMask users**: Just copy your Ethereum address (e.g. `0x1234...abcd`) — it works directly - **Dah.mx users**: Settings → AI Assistant Setup → Copy key - **Demo/Testing**: Don't set a key — use `generate_demo_key` in your AI assistant instead --- ## 🏗️ Architecture The MCP server is a **thin client** that combines local cart/order storage with centralized W3Ship services: ``` ┌─────────────────────────────────────────────┐ │ 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 │ │ │ └──────────────┘ └─────────────────────┘ │ └──────────────────────────────────────────────┘ ``` - **Commerce** (cart, order, shipment) → stored locally in your Redis - **Identity** (address lookup) → forwarded to `w3ship.com` API - **Session Booking** → forwarded to `w3ship.com` API - **No AWS credentials** needed. No cloud config required. --- ## 💡 Example Conversations ### Shopping & Booking ``` 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" ``` ### Claiming a Promo with Pickup (NEW in 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." ``` > **Tip:** For production use, set your real wallet key via `W3SHIP_PUBLIC_KEY` in your MCP config. See [Getting Your Public Key](#getting-your-public-key) above. --- ## 📰 Press - **TechBullion**: [How W3Ship Works: The MCP Server That Turns Any AI Into a Merchant](https://techbullion.com/how-w3ship-works-the-mcp-server-that-turns-any-ai-into-a-merchant/) - **Digital Journal**: [Quantum-Resistant Commerce Token Launches via Uniswap CCA on Unichain](https://www.digitaljournal.com/pr/news/vehement-media/quantum-resistant-commerce-token-launches-via-1883892375.html) - Syndicated across **500+ outlets** — [full coverage →](https://w3ship.com/press) --- ## 🔗 Links - **Website**: [w3ship.com](https://w3ship.com) - **Press**: [w3ship.com/press](https://w3ship.com/press) - **GitHub**: [github.com/baskcart/w3ship](https://github.com/baskcart/w3ship) - **W3SH Token**: [Uniswap CCA Auction](https://app.uniswap.org) --- ## 📄 License MIT — see [LICENSE](./LICENSE)