W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:1216-1291 (handler)

  The handler for the 'get_identity' tool which returns information about the currently configured identity (W3SHIP_PUBLIC_KEY).

          return { content: [{ type: 'text', text: `Error adding tracking: ${e.message}` }], isError: true };
      }
  }
  
  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:213-219 (registration)

  Registration of the 'get_identity' tool in the ListToolsRequestSchema handler.

      name: 'get_identity',
      description: 'Show the currently configured identity (W3SHIP_PUBLIC_KEY). Returns the public key and its type if set, or instructions on how to configure one.',
      inputSchema: {
          type: 'object',
          properties: {},
      },
  },