get_categories
Retrieve the full Vinted category tree for a country. Get numeric IDs, names, and parent IDs to filter search results by department.
Instructions
Fetch the full Vinted category tree for a country. Returns a flat list of all categories and subcategories with their numeric IDs, names, parent IDs, and item counts. Pass a categoryId to search_items or search_all_items to restrict results to a department (e.g. women's clothing, men's shoes, electronics). Results are cached for 1 hour.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| country | No | Country site to fetch categories for (category IDs are consistent across countries) | fr |
| query | No | Optional keyword filter on category name, e.g. "shoes" or "dress" |
Implementation Reference
- src/mcp.ts:111-121 (registration)Tool registration in the TOOLS array with name 'get_categories', description, and inputSchema.
{ name: 'get_categories', description: 'Fetch the full Vinted category tree for a country. Returns a flat list of all categories and subcategories with their numeric IDs, names, parent IDs, and item counts. Pass a categoryId to search_items or search_all_items to restrict results to a department (e.g. women\'s clothing, men\'s shoes, electronics). Results are cached for 1 hour.', inputSchema: { type: 'object', properties: { country: { type: 'string', enum: COUNTRIES, default: 'fr', description: 'Country site to fetch categories for (category IDs are consistent across countries)' }, query: { type: 'string', description: 'Optional keyword filter on category name, e.g. "shoes" or "dress"' }, }, }, }, - src/ops/categories.ts:5-15 (handler)Handler function opCategories that fetches categories and optionally filters by query string.
export async function opCategories( client: VintedClient, args: { country?: Country; query?: string }, ): Promise<CategoryHit[]> { const cats = await getCategories(client, args.country ?? 'fr'); if (args.query) { const q = args.query.toLowerCase(); return cats.filter((c) => c.title.toLowerCase().includes(q)); } return cats; } - src/client/endpoints.ts:237-250 (helper)Client-level getCategories function that calls the Vinted API and returns flattened categories.
const STATIC_TTL_MS = 60 * 60 * 1000; // 1 hour — categories rarely change export async function getCategories( client: VintedClient, country: Country = 'fr', ): Promise<CategoryHit[]> { const data = await client.apiGet<{ dtos?: { catalogs?: any[] } }>( country, `/api/v2/catalog/initializers`, STATIC_TTL_MS, ); const raw = data.dtos?.catalogs ?? []; return flattenCategories(raw); } - src/client/endpoints.ts:252-266 (helper)Helper flattenCategories that recursively flattens the catalog tree into a flat list of CategoryHit objects.
function flattenCategories(nodes: any[], parentId?: number): CategoryHit[] { const result: CategoryHit[] = []; for (const n of nodes) { result.push({ id: Number(n.id), title: String(n.title ?? n.name ?? ''), parentId, itemCount: n.item_count, }); if (Array.isArray(n.catalogs) && n.catalogs.length) { result.push(...flattenCategories(n.catalogs, Number(n.id))); } } return result; } - src/client/types.ts:92-97 (schema)CategoryHit interface defining the shape of a category result: id, title, parentId, itemCount.
export interface CategoryHit { id: number; title: string; parentId?: number; itemCount?: number; }