FindMine Shopping Stylist

Instructions

Implementation Reference

• src/index.ts:607-683 (handler)

  MCP tool handler for get_visually_similar: validates input parameters, calls findMineService.getVisuallySimilar, processes response products into URIs and JSON output.
  case "get_visually_similar": { try { const args = request.params.arguments as any; // Extract and validate required parameters const productId = args.product_id; if (!productId) { logger.error('Missing required parameter: product_id'); return { error: { message: "Product ID is required", code: "VALIDATION_ERROR" } }; } // Set defaults for optional parameters const limit = args.limit ?? 10; const offset = args.offset ?? 0; const colorId = args.product_color_id; const sessionId = args.session_id; const customerId = args.customer_id; // Don't pass gender by default - this parameter should be explicitly set only when needed const gender = args.customer_gender !== undefined ? args.customer_gender : undefined; const apiVersion = args.api_version; logger.error(`Getting visually similar products for ${productId}, limit: ${limit}, offset: ${offset}`); // Get visually similar products const result = await findMineService.getVisuallySimilar( productId, { colorId, sessionId, customerId, limit, offset, gender, apiVersion, } ); // Process products data const productItems = result.products.map(product => { const productUri = createProductUri(product.id, product.colorId); return { product_id: product.id, name: product.name, uri: productUri, }; }); // Return success response with structured data return { success: true, content: [{ type: "text", text: JSON.stringify({ products: productItems, total: result.total, limit, offset, source_product_id: productId, }, null, 2) }] }; } catch (error) { logger.error(`Error getting visually similar products: ${error instanceof Error ? error.message : String(error)}`, error); return { error: { message: error instanceof Error ? error.message : 'Unknown error occurred while getting visually similar products', code: 'VISUALLY_SIMILAR_ERROR' } }; } }
• src/index.ts:284-327 (schema)

  Input schema definition and tool registration for get_visually_similar in the ListTools response.
  name: "get_visually_similar", description: "Get visually similar products", inputSchema: { type: "object", properties: { product_id: { type: "string", description: "ID of the product" }, product_color_id: { type: "string", description: "Color ID of the product (if applicable)" }, limit: { type: "number", description: "Maximum number of products to return", default: 10 }, offset: { type: "number", description: "Offset for pagination", default: 0 }, customer_id: { type: "string", description: "Customer ID for personalized recommendations" }, customer_gender: { type: "string", enum: ["M", "W", "U"], description: "Customer gender (M = Men, W = Women, U = Unknown)" }, session_id: { type: "string", description: "Session ID for tracking and personalization" }, api_version: { type: "string", description: "API version to use (overrides FINDMINE_API_VERSION env var)" } }, required: ["product_id"] } }
• src/services/findmine-service.ts:173-250 (helper)

  Service layer method: handles caching, calls FindMineClient.getVisuallySimilar, maps API products to internal ProductResource objects.
  async getVisuallySimilar( productId: string, options: { colorId?: string; sessionId?: string; customerId?: string; limit?: number; offset?: number; gender?: 'M' | 'W' | 'U'; useCache?: boolean; apiVersion?: string; } = {} ): Promise<{ products: ProductResource[]; total: number; }> { const sessionId = options.sessionId || config.session.defaultSessionId; const useCache = options.useCache !== false && config.cache.enabled; // Create cache key const cacheKey = Cache.createKey([ 'visuallySimilar', productId, options.colorId || 'default', String(options.limit || 'default'), String(options.offset || 'default') ]); // Try to get from cache let response: VisuallySimilarResponse; if (useCache) { const cached = this.visuallySimilarCache.get(cacheKey); if (cached) { response = cached; } else { response = await this.client.getVisuallySimilar( productId, sessionId, { colorId: options.colorId, customerId: options.customerId, limit: options.limit, offset: options.offset, gender: options.gender, apiVersion: options.apiVersion, } ); // Store in cache this.visuallySimilarCache.set(cacheKey, response); } } else { response = await this.client.getVisuallySimilar( productId, sessionId, { colorId: options.colorId, customerId: options.customerId, limit: options.limit, offset: options.offset, gender: options.gender, apiVersion: options.apiVersion, } ); } // Convert to internal resources const products: ProductResource[] = response.products.map(product => { const productResource = mapProductToResource(product); this.resources.products[productResource.id] = productResource; return productResource; }); return { products, total: response.total, }; }
• src/api/findmine-client.ts:222-254 (helper)

  API client method: constructs HTTP GET request to FindMine API endpoint /api/{version}/visually-similar with query parameters.
  async getVisuallySimilar( productId: string, sessionId: string, options: { colorId?: string; customerId?: string; limit?: number; offset?: number; gender?: 'M' | 'W' | 'U'; apiVersion?: string; } = {} ): Promise<VisuallySimilarResponse> { const apiVersion = options.apiVersion || this.config.apiVersion; // Create request parameters, only including gender if explicitly provided const params: VisuallySimilarRequest = { ...this.createBaseRequest(sessionId, options.customerId), product_id: productId, product_color_id: options.colorId, limit: options.limit, offset: options.offset, }; // Only add gender param if explicitly provided if (options.gender !== undefined) { params.customer_gender = options.gender; } return this.makeRequest<VisuallySimilarResponse>( `/api/${apiVersion}/visually-similar`, 'GET', params ); }