search_all_items

Instructions

Implementation Reference

• src/mcp.ts:122-191 (registration)

  Tool 'search_all_items' registered in the TOOLS array with its name, description, and inputSchema (including maxItems and maxPages params).

    {
      name: 'search_all_items',
      description: 'Search Vinted listings and automatically paginate through all results, returning up to maxItems items in a single call. Use this instead of search_items when you need comprehensive results — e.g. "find all Nike shoes under €30" or "list every item in size M from this brand". Pages are fetched concurrently for speed. Returns the same item fields as search_items.',
      inputSchema: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search keywords' },
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to search' },
          priceMin: { type: 'number', description: 'Minimum price in local currency' },
          priceMax: { type: 'number', description: 'Maximum price in local currency' },
          brandIds: { type: 'array', items: { type: 'integer' }, description: 'Numeric brand IDs from search_brands' },
          brand: { type: 'array', items: { type: 'string' }, description: 'Brand names; automatically resolved to IDs' },
          categoryId: { type: 'integer', description: 'Category ID from get_categories' },
          sizeIds: { type: 'array', items: { type: 'integer' }, description: 'Size IDs to filter by' },
          colorIds: { type: 'array', items: { type: 'integer' }, description: 'Color IDs to filter by. Use get_colors to discover all available color IDs.' },
          condition: { type: 'array', items: { type: 'string', enum: ['new_with_tags', 'new_without_tags', 'very_good', 'good', 'satisfactory'] }, description: 'Item condition filter' },
          sortBy: { type: 'string', enum: ['relevance', 'price_low_to_high', 'price_high_to_low', 'newest_first'], description: 'Sort order' },
          maxItems: { type: 'integer', default: 200, description: 'Maximum total items to collect across all pages (default 200, max 1000)' },
          maxPages: { type: 'integer', default: 10, description: 'Maximum number of pages to fetch regardless of maxItems' },
        },
        required: ['query'],
      },
    },
    {
      name: 'get_seller_feedback',
      description: 'Fetch paginated buyer and seller feedback reviews for a Vinted user. Each entry includes the review text, star rating (1–5), feedback type (1=negative, 2=neutral, 3=positive), reviewer username, timestamp, and the associated item ID. Use this to assess seller trustworthiness and reliability before making a purchase.',
      inputSchema: {
        type: 'object',
        properties: {
          sellerId: { type: 'integer', description: 'Numeric Vinted user ID (visible in profile URLs: vinted.fr/member/12345-username)' },
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Country site where the seller is registered' },
          limit: { type: 'integer', default: 20, description: 'Reviews per page, 1–100' },
          page: { type: 'integer', default: 1, description: 'Page number starting at 1' },
        },
        required: ['sellerId'],
      },
    },
    {
      name: 'get_colors',
      description: 'Fetch the complete list of Vinted color options available as search filters. Returns every color with its numeric ID, display name, hex color code, short code (e.g. "BLACK"), and sort order. Pass the returned IDs to search_items.colorIds or search_all_items.colorIds to restrict results to specific colors. Results are cached for 1 hour — color catalogues change rarely.',
      inputSchema: {
        type: 'object',
        properties: {
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to query (color catalogues are shared across countries)' },
        },
      },
    },
    {
      name: 'get_size_groups',
      description: 'Fetch all Vinted size groups with their constituent size IDs and labels. Returns a list of size groups (e.g. "Women\'s clothing", "Men\'s shoes", "Kids 2–8 yrs") — each containing the group ID, caption, description, and an array of sizes with numeric IDs and display titles (e.g. "XS", "42", "12 UK"). Pass individual size IDs from the sizes array to search_items.sizeIds or search_all_items.sizeIds to filter listings to an exact size. Results are cached for 1 hour.',
      inputSchema: {
        type: 'object',
        properties: {
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to query (size catalogues are shared across countries)' },
        },
      },
    },
    {
      name: 'get_trending',
      description: 'Fetch the newest and trending items on Vinted for a given country, ordered by recency. Optionally scoped to a specific category. Useful for discovering what\'s currently popular, monitoring new arrivals, or finding deals as they are listed.',
      inputSchema: {
        type: 'object',
        properties: {
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to fetch trending items from' },
          categoryId: { type: 'integer', description: 'Optional category ID from get_categories to restrict results to a specific department' },
          limit: { type: 'integer', default: 20, description: 'Number of trending items to return, 1–96' },
        },
      },
    },
  ];

• src/ops/search.ts:10-61 (handler)

  Main handler function opSearchAll that auto-paginates through Vinted search results concurrently, deduplicating items by ID up to maxItems/maxPages limits.

  export async function opSearchAll(
    client: VintedClient,
    p: SearchParams & { maxItems?: number; maxPages?: number },
  ): Promise<SearchResult> {
    if (!p.query?.trim()) throw new Error('query is required');
    const perPage = Math.min(p.perPage ?? 96, 100);
    const maxItems = p.maxItems ?? 1000;
    const maxPages = p.maxPages ?? 25;
    const PREFETCH = 3; // pages to keep in-flight concurrently
  
    const seen = new Set<number>();
    const items: SearchResult['items'] = [];
    let nextPage = p.page ?? 1;
    let totalCount = 0;
  
    // Sliding window of in-flight page requests
    const pending: Array<Promise<SearchResult>> = [];
  
    const enqueue = () => {
      while (pending.length < PREFETCH && nextPage <= maxPages && items.length < maxItems) {
        pending.push(searchItems(client, { ...p, perPage, page: nextPage++ }));
      }
    };
  
    enqueue();
  
    while (pending.length > 0) {
      const r = await pending.shift()!;
      if (r.totalCount > totalCount) totalCount = r.totalCount;
      if (!r.items.length) {
        pending.length = 0; // drain: no point fetching further pages
        break;
      }
  
      let added = 0;
      for (const it of r.items) {
        if (seen.has(it.id)) continue;
        seen.add(it.id);
        items.push(it);
        added++;
        if (items.length >= maxItems) break;
      }
      if (items.length >= maxItems || added === 0) {
        pending.length = 0; // hit limit or end of stream — discard remaining in-flight
        break;
      }
  
      enqueue(); // top up the window
    }
  
    return { totalCount: totalCount || items.length, page: 1, items };
  }

• src/mcp.ts:125-143 (schema)

  Input schema definition for search_all_items, accepting query, country, priceMin/Max, brandIds/brand, categoryId, sizeIds, colorIds, condition, sortBy, maxItems, maxPages.

  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search keywords' },
      country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to search' },
      priceMin: { type: 'number', description: 'Minimum price in local currency' },
      priceMax: { type: 'number', description: 'Maximum price in local currency' },
      brandIds: { type: 'array', items: { type: 'integer' }, description: 'Numeric brand IDs from search_brands' },
      brand: { type: 'array', items: { type: 'string' }, description: 'Brand names; automatically resolved to IDs' },
      categoryId: { type: 'integer', description: 'Category ID from get_categories' },
      sizeIds: { type: 'array', items: { type: 'integer' }, description: 'Size IDs to filter by' },
      colorIds: { type: 'array', items: { type: 'integer' }, description: 'Color IDs to filter by. Use get_colors to discover all available color IDs.' },
      condition: { type: 'array', items: { type: 'string', enum: ['new_with_tags', 'new_without_tags', 'very_good', 'good', 'satisfactory'] }, description: 'Item condition filter' },
      sortBy: { type: 'string', enum: ['relevance', 'price_low_to_high', 'price_high_to_low', 'newest_first'], description: 'Sort order' },
      maxItems: { type: 'integer', default: 200, description: 'Maximum total items to collect across all pages (default 200, max 1000)' },
      maxPages: { type: 'integer', default: 10, description: 'Maximum number of pages to fetch regardless of maxItems' },
    },
    required: ['query'],
  },

• src/mcp.ts:226-234 (handler)

  Registration handler case in CallToolRequestSchema that resolves brand names to IDs and delegates to opSearchAll.

  case 'search_all_items': {
    const args = a as any;
    if (!args.brandIds && Array.isArray(args.brand) && args.brand.length) {
      const r = await resolveBrandIds(c, args.brand, args.country);
      args.brandIds = r.ids.length ? r.ids : undefined;
    }
    result = await opSearchAll(c, { ...args, maxItems: args.maxItems ?? 200 });
    break;
  }