W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:466-593 (handler)

  The handler for the create_order tool, which validates the cart, creates an order via orderService, handles P2P payments or simulated shipments, and clears the cart.

  case 'create_order': {
      const { orderService } = await import('./orders/service.js');
      const { shipmentService } = await import('./shipment/service.js');
      const cartId = (args?.cartId as string) || CONFIGURED_KEY;
      if (!cartId) {
          return { content: [{ type: 'text', text: 'Error: No cart ID. Set W3SHIP_PUBLIC_KEY or provide a cartId.' }], isError: true };
      }
  
      // 1. Validate Cart
      const cart = await valkeyService.getCart(cartId);
      if (!cart) {
          return { content: [{ type: 'text', text: `Error: Cart not found: ${cartId}` }], isError: true };
      }
      if (!cart.cartItem || cart.cartItem.length === 0) {
          return { content: [{ type: 'text', text: `Error: Cart is empty.` }], isError: true };
      }
  
      // 2. Check if cart contains P2P listing items
      let merchantWallet: string | undefined;
      let totalPrice = 0;
      let isP2P = false;
      const listingIds: string[] = [];
  
      for (const item of cart.cartItem) {
          const offId = item.productOffering?.id || '';
          if (offId.startsWith('LST-')) {
              isP2P = true;
              listingIds.push(offId);
              // Fetch listing to get seller wallet and price
              try {
                  const lstRes = await fetch(`${W3SHIP_API}/api/listing?id=${encodeURIComponent(offId)}`);
                  const lstData = await lstRes.json() as any;
                  if (lstRes.ok && lstData.listing) {
                      merchantWallet = lstData.listing.sellerAddress;
                      totalPrice += lstData.listing.price * (item.quantity?.amount || 1);
                  }
              } catch { /* continue */ }
          }
      }
  
      // 3. Create Order
      const orderId = `ord_${Math.random().toString(36).substring(2, 10)}`;
      const order: any = {
          id: orderId,
          orderDate: new Date().toISOString(),
          state: isP2P ? 'Pending Payment' : 'Confirmed',
          orderItem: cart.cartItem.map(item => ({
              id: item.id,
              quantity: item.quantity?.amount || 1,
              productOffering: item.productOffering,
              state: isP2P ? 'Pending' : 'Allocated'
          })),
          totalPrice,
          relatedParty: [{ id: cart.id, role: 'Customer' }],
      };
  
      // Add payment fields for P2P orders
      if (isP2P && merchantWallet) {
          order.merchantWallet = merchantWallet;
          order.paymentStatus = 'awaiting_payment';
          order.paymentToken = 'USDC';
          order.paymentChainId = 8453; // Base
          order.paymentAmount = totalPrice;
      }
  
      await orderService.createOrder(order);
  
      // 4. Mark listings as sold
      for (const lstId of listingIds) {
          try {
              await fetch(`${W3SHIP_API}/api/listing`, {
                  method: 'POST',
                  headers: { 'Content-Type': 'application/json' },
                  body: JSON.stringify({ id: lstId, status: 'sold' }),
              });
          } catch { /* best effort */ }
      }
  
      // 5. For non-P2P (demo), create simulated shipment. For P2P, seller adds tracking later.
      let shipmentInfo: any = null;
      if (!isP2P) {
          const shipmentId = `shp_${Math.random().toString(36).substring(2, 10)}`;
          const shipment = {
              id: shipmentId,
              orderId: orderId,
              trackingNumber: `TRK-${Math.random().toString(10).substring(2, 12)}`,
              carrier: 'QuantumLogistics',
              status: 'Label Created',
              origin: { address: 'Distribution Center 1', city: 'Satoshi City', country: 'Digital Nation' },
              destination: { address: 'Customer Address', city: 'Unknown', country: 'Unknown' },
              events: [{ timestamp: new Date().toISOString(), status: 'Label Created', description: 'Shipment info received' }]
          };
          await shipmentService.createShipment(shipment as any);
          shipmentInfo = { shipmentId, trackingNumber: shipment.trackingNumber };
      }
  
      // 6. Clear Cart
      await valkeyService.deleteCart(cartId);
  
      // 7. Return appropriate response
      if (isP2P) {
          return {
              content: [{
                  type: 'text', text: JSON.stringify({
                      success: true,
                      message: `Order created! Send ${totalPrice} USDC to ${merchantWallet} on Base chain, then use confirm_payment with the transaction hash.`,
                      orderId,
                      paymentStatus: 'awaiting_payment',
                      payTo: merchantWallet,
                      amount: `${totalPrice} USDC`,
                      chainId: 8453,
                      nextStep: `After paying, call confirm_payment(orderId: "${orderId}", txHash: "0x...")`,
                  }, null, 2)
              }]
          };
      }
  
      return {
          content: [{
              type: 'text', text: JSON.stringify({
                  success: true,
                  message: "Order confirmed and shipment initiated.",
                  orderId,
                  ...shipmentInfo,
              }, null, 2)
          }]
      };
  }

• src/orders/service.ts:36-38 (handler)

  The implementation of the createOrder function that persists the order data in the Valkey (Redis) database.

  async createOrder(order: Order): Promise<void> {
      await this.getClient().set(`order:${order.id}`, JSON.stringify(order));
  }

• src/index.ts:135-144 (registration)

  The registration of the 'create_order' tool in the ListTools request handler.

      name: 'create_order',
      description: 'Convert a Shopping Cart into a confirmed Order (TMF622) and initiate fulfillment.',
      inputSchema: {
          type: 'object',
          properties: {
              cartId: { type: 'string', description: 'The ID of the shopping cart to convert' },
          },
          required: ['cartId'],
      },
  },