W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:1220-1290 (handler)

  The handler implementation for the 'claim_promo' MCP tool, which performs an identity-verified promotional claim by calling the W3Ship API.

  case 'claim_promo': {
      const { listingId: claimListingId, publicKey: claimPK, fulfillmentChoice: claimFulfillment, pickupLocationId: claimPickupId } = args as any;
      const claimKey = claimPK || CONFIGURED_KEY;
  
      if (!claimKey) {
          return {
              content: [{ type: 'text', text: 'Error: Public key required to claim. Set W3SHIP_PUBLIC_KEY or provide publicKey.' }],
              isError: true,
          };
      }
  
      try {
          const claimRes = await fetch(`${W3SHIP_API}/api/listing/claim`, {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({
                  listingId: claimListingId,
                  publicKey: claimKey,
                  ...(claimFulfillment ? { fulfillmentChoice: claimFulfillment } : {}),
                  ...(claimPickupId ? { pickupLocationId: claimPickupId } : {}),
              }),
          });
          const claimData = await claimRes.json() as any;
  
          if (!claimRes.ok) {
              return {
                  content: [{
                      type: 'text',
                      text: JSON.stringify({
                          claimed: false,
                          error: claimData.error || 'Claim failed',
                          alreadyClaimed: claimData.alreadyClaimed || false,
                          ...(claimData.registerUrl ? { registerUrl: claimData.registerUrl } : {}),
                          ...(claimData.pickupLocations ? { availablePickupLocations: claimData.pickupLocations } : {}),
                      }, null, 2)
                  }],
                  isError: true,
              };
          }
  
          // Build response based on fulfillment type
          const isPickup = claimData.fulfillment === 'pickup';
          return {
              content: [{
                  type: 'text',
                  text: JSON.stringify({
                      claimed: true,
                      claimId: claimData.claimId,
                      fulfillment: claimData.fulfillment || 'ship',
                      item: claimData.listing?.title,
                      ...(isPickup ? {
                          pickupLocation: claimData.pickupLocation,
                          instructions: claimData.instructions,
                          cost: 'FREE',
                      } : {
                          shippingCost: claimData.listing?.shippingCost
                              ? `${claimData.listing.shippingCost} ${claimData.listing.currency}`
                              : 'FREE',
                      }),
                      remaining: claimData.listing?.remaining,
                      message: claimData.message,
                      nextStep: isPickup
                          ? `Show your claim ID "${claimData.claimId}" at ${claimData.pickupLocation?.name || 'the pickup location'} to collect your item.`
                          : `Add listing "${claimListingId}" to your cart and create an order. ${claimData.listing?.shippingCost ? `You'll pay ${claimData.listing.shippingCost} ${claimData.listing.currency} for shipping.` : ''}`,
                  }, null, 2)
              }]
          };
      } catch (e: any) {
          return { content: [{ type: 'text', text: `Error claiming promo: ${e.message}` }], isError: true };
      }
  }

• src/index.ts:354-366 (registration)

  The registration of the 'claim_promo' tool in the ListToolsRequestSchema handler.

      name: 'claim_promo',
      description: 'Claim a FREE promotional listing. Items are $0. For shipping promos you pay shipping only; for pickup promos it is completely free. One claim per wallet. Must have a registered W3Ship/Dah.mx identity (address required for shipping, wallet-only for pickup).',
      inputSchema: {
          type: 'object',
          properties: {
              listingId: { type: 'string', description: 'The promotional listing ID to claim' },
              publicKey: { type: 'string', description: 'Your public key / wallet address for identity verification. Uses W3SHIP_PUBLIC_KEY if not provided.' },
              fulfillmentChoice: { type: 'string', description: 'How to receive the item: "ship" (mailed to your address — may have shipping cost) or "pickup" (free, collect at pickup location). Defaults based on listing configuration.' },
              pickupLocationId: { type: 'string', description: 'ID of the pickup location (required when multiple pickup locations exist and fulfillmentChoice is "pickup")' },
          },
          required: ['listingId'],
      },
  },