search_items

Instructions

Implementation Reference

• src/ops/search.ts:5-8 (handler)

  opSearch: The handler function for the 'search_items' tool. Validates query is present, then delegates to searchItems (from endpoints.ts).

  export async function opSearch(client: VintedClient, p: SearchParams): Promise<SearchResult> {
    if (!p.query?.trim()) throw new Error('query is required');
    return searchItems(client, p);
  }

• src/client/endpoints.ts:27-56 (handler)

  searchItems: Core implementation that builds the Vinted catalog API path, makes the HTTP request via VintedClient.apiGet, maps the raw response items into structured Item objects, and returns SearchResult.

  export async function searchItems(client: VintedClient, p: SearchParams): Promise<SearchResult> {
    const country = p.country ?? 'fr';
    const data = await client.apiGet<{
      items: any[];
      pagination?: { total_entries?: number };
    }>(country, buildSearchPath(p));
  
    const items: Item[] = (data.items ?? []).map((i) => ({
      id: Number(i.id),
      title: String(i.title ?? ''),
      price: String(i.price?.amount ?? i.price ?? ''),
      currency: String(i.price?.currency_code ?? i.currency ?? ''),
      brand: i.brand_title ?? i.brand,
      size: i.size_title ?? i.size,
      condition: i.status,
      url: i.url ?? `https://${DOMAIN[country]}/items/${i.id}`,
      favouriteCount: i.favourite_count,
      photoUrl: i.photo?.url ?? i.photos?.[0]?.url,
      seller: {
        id: Number(i.user?.id ?? 0),
        username: String(i.user?.login ?? i.user?.username ?? ''),
      },
    }));
  
    return {
      totalCount: data.pagination?.total_entries ?? items.length,
      page: p.page ?? 1,
      items,
    };
  }

• src/client/types.ts:37-52 (schema)

  SearchParams: Defines all input parameters accepted by searchItems (query, country, priceMin/Max, brandIds, categoryId, sizeIds, colorIds, condition, sortBy, perPage, page, dateFrom, dateTo).

  export interface SearchParams {
    query: string;
    country?: Country;
    priceMin?: number;
    priceMax?: number;
    brandIds?: number[];
    categoryId?: number;
    sizeIds?: number[];
    colorIds?: number[];
    condition?: Condition[];
    sortBy?: SortBy;
    perPage?: number;
    page?: number;
    dateFrom?: string;  // ISO date e.g. "2024-01-01"
    dateTo?: string;
  }

• src/client/types.ts:68-72 (schema)

  SearchResult: Defines the return type (totalCount, page, items array of Item objects).

  export interface SearchResult {
    totalCount: number;
    page: number;
    items: Item[];
  }

• src/mcp.ts:20-45 (registration)

  Registration of the 'search_items' tool in the MCP TOOLS array with its name, description, and inputSchema defining all accepted parameters.

  const TOOLS = [
    {
      name: 'search_items',
      description: 'Search Vinted second-hand listings with rich filters across 19 country sites. Returns a paginated list of items — each with title, price, currency, brand, size, condition, photo URL, item URL, favourite count, and seller info. Use get_categories to discover valid categoryId values and search_brands to resolve brand names to IDs. For comprehensive multi-page results use search_all_items instead.',
      inputSchema: {
        type: 'object',
        properties: {
          query: { type: 'string', description: 'Search keywords, e.g. "Nike Air Max 90" or "levi 501 jeans"' },
          country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Vinted country site to search (fr, de, uk, pl, es, nl, be, it, pt, cz, sk, hu, ro, lt, lv, ee, fi, at, se)' },
          priceMin: { type: 'number', description: 'Minimum price in the local currency of the selected country' },
          priceMax: { type: 'number', description: 'Maximum price in the local currency of the selected country' },
          brandIds: { type: 'array', items: { type: 'integer' }, description: 'Numeric Vinted brand IDs from search_brands. Prefer the brand[] parameter for name-based lookup.' },
          brand: { type: 'array', items: { type: 'string' }, description: 'Brand names to filter by, e.g. ["Nike", "Adidas"]. Automatically resolved to IDs via search_brands.' },
          categoryId: { type: 'integer', description: 'Category ID from get_categories (e.g. 4 = women\'s clothing, 5 = men\'s clothing, 1231 = women\'s shoes)' },
          sizeIds: { type: 'array', items: { type: 'integer' }, description: 'Size IDs to filter by. Discover valid IDs by inspecting results from a previous search in the same category, or use get_size_groups to browse all size groups.' },
          colorIds: { type: 'array', items: { type: 'integer' }, description: 'Color IDs to filter by (e.g. [1] for black, [3] for white). Use get_colors to discover all available color IDs and their names.' },
          condition: { type: 'array', items: { type: 'string', enum: ['new_with_tags', 'new_without_tags', 'very_good', 'good', 'satisfactory'] }, description: 'Item condition filter; multiple values are OR-ed together' },
          sortBy: { type: 'string', enum: ['relevance', 'price_low_to_high', 'price_high_to_low', 'newest_first'], description: 'Sort order for results. Defaults to relevance.' },
          perPage: { type: 'integer', description: 'Results per page, 1–96. Defaults to 20.' },
          page: { type: 'integer', description: 'Page number starting at 1' },
          dateFrom: { type: 'string', description: 'Return items listed on or after this date. ISO-8601 format, e.g. "2024-01-01"' },
          dateTo: { type: 'string', description: 'Return items listed on or before this date. ISO-8601 format, e.g. "2024-12-31"' },
        },
        required: ['query'],
      },
    },