W3Ship MCP Server

Instructions

Implementation Reference

• src/index.ts:1031-1084 (handler)

  The implementation of the search_listings tool, which calls the W3Ship API to perform the search.

  case 'search_listings': {
      const { category: searchCat, keyword: searchKw, limit: searchLimit } = args as any;
  
      try {
          const params = new URLSearchParams();
          if (searchCat) params.set('category', searchCat.toLowerCase());
          if (searchKw) params.set('keyword', searchKw);
          if (searchLimit) params.set('limit', searchLimit.toString());
  
          const searchRes = await fetch(`${W3SHIP_API}/api/listing?${params.toString()}`);
          const searchData = await searchRes.json() as any;
          if (!searchRes.ok) {
              return { content: [{ type: 'text', text: `Error searching: ${searchData.error}` }], isError: true };
          }
  
          const listings = searchData.listings || [];
          if (listings.length === 0) {
              return {
                  content: [{
                      type: 'text',
                      text: JSON.stringify({
                          results: [],
                          message: searchCat
                              ? `No active listings in category "${searchCat}". Try: electronics, clothing, collectibles, home, sports, gifts, books, other.`
                              : searchKw
                                  ? `No listings matching "${searchKw}".`
                                  : 'No active listings yet. Be the first — use create_listing to sell something!',
                      }, null, 2)
                  }]
              };
          }
  
          const results = listings.map((l: any) => ({
              id: l.id, title: l.title,
              price: l.isPromo ? `FREE (shipping: ${l.shippingCost || 0} ${l.currency})` : `${l.price} ${l.currency}`,
              category: l.category, condition: l.condition,
              seller: l.sellerName || (l.sellerAddress?.substring(0, 10) + '...'),
              shipsTo: l.shipsTo, quantity: l.quantity,
              ...(l.isPromo ? { promo: true, remaining: l.promoQuantity ? l.promoQuantity - (l.promoClaimed || 0) : undefined } : {}),
          }));
  
          return {
              content: [{
                  type: 'text',
                  text: JSON.stringify({
                      results, total: results.length,
                      message: `Found ${results.length} listing(s). Use get_listing with the ID for full details, or add_item with productOffering.id to add to cart.`,
                  }, null, 2)
              }]
          };
      } catch (e: any) {
          return { content: [{ type: 'text', text: `Error searching listings: ${e.message}` }], isError: true };
      }
  }