Three-Layer Architecture Design

// Using @rekog/mcp-nest for MCP tool definition
import { Tool } from '@rekog/mcp-nest';
import { z } from 'zod';

// Zod schema for type-safe validation
const SearchProductSchema = z.object({
  query: z.string().min(1).describe('Natural language search query'),
  take: z.number().int().positive().optional().default(10),
  skip: z.number().int().nonnegative().optional().default(0),
});

@Injectable()
export class McpToolsService {
  constructor(
    @Inject(SEARCH_SERVICE) 
    private readonly searchService: SearchService,
  ) {}

  @Tool({
    name: 'search_product',
    description: 'Search products using natural language with AI-powered filter extraction',
    parameters: SearchProductSchema,
  })
  async searchProduct(params: z.infer<typeof SearchProductSchema>) {
    return this.searchService.search(params);
  }
}

{
  "tools": [
    {
      "name": "search_product",
      "description": "Search products using natural language with AI-powered filter extraction",
      "parameters": {
        "query": "string (required) - Natural language search",
        "take": "number (optional, default: 10) - Results limit",
        "skip": "number (optional, default: 0) - Pagination offset"
      }
    }
  ]
}

Query → Embed (OpenAI) → Vector Search (Qdrant) → Results

Query → LangGraph 4-Stage Pipeline → Verified Results

// Feature extraction using LangChain structured output
import { ChatOpenAI } from '@langchain/openai';
import { z } from 'zod';

const ExtractedFiltersSchema = z.object({
  brand: z.array(z.string()).optional().describe('Brand names mentioned'),
  excludedBrand: z.array(z.string()).optional().describe('Brands to exclude'),
  priceRange: z.object({
    min: z.number().optional(),
    max: z.number().optional(),
    currency: z.string().default('USD'),
  }).optional(),
  category: z.string().optional(),
  cleanedQuery: z.string().describe('Query without filter terms'),
});

@Injectable()
export class FeatureExtractionService {
  private model: ChatOpenAI;

  constructor() {
    this.model = new ChatOpenAI({
      modelName: 'gpt-4o-mini',
      temperature: 0,
    });
  }

  async extractFilters(query: string) {
    const structuredModel = this.model.withStructuredOutput(ExtractedFiltersSchema);
    
    return structuredModel.invoke([
      {
        role: 'system',
        content: 'Extract shopping filters from the query. Identify brands, price limits, and categories.',
      },
      { role: 'user', content: query },
    ]);
  }
}

@Injectable()
export class VectorizationService {
  private openai: OpenAI;

  constructor(private config: ConfigService) {
    this.openai = new OpenAI({
      apiKey: config.get('OPENAI_API_KEY'),
    });
  }

  async embedString(text: string): Promise<number[]> {
    const response = await this.openai.embeddings.create({
      model: 'text-embedding-3-small',
      input: text,
    });
    return response.data[0].embedding; // 1536 dimensions
  }

  async embedProduct(product: UnifiedProduct): Promise<number[]> {
    const textToEmbed = [
      `Title: ${product.title}`,
      `Description: ${product.description}`,
      `Keywords: ${product.keywords.join(', ')}`,
      product.brand ? `Brand: ${product.brand}` : '',
      product.category ? `Category: ${product.category}` : '',
    ].filter(Boolean).join('\n');

    return this.embedString(textToEmbed);
  }
}

@Injectable()
export class SearchService {
  constructor(
    @Inject(VECTORIZATION_SERVICE)
    private vectorization: VectorizationService,
    @Inject(FEATURE_EXTRACTION_SERVICE)
    private featureExtraction: FeatureExtractionService,
    @Inject(PRODUCT_REPOSITORY)
    private repository: ProductRepository,
  ) {}

  async search(params: { query: string; take?: number; skip?: number }) {
    // Step 1: Extract filters from natural language
    const filters = await this.featureExtraction.extractFilters(params.query);
    
    // Step 2: Generate embedding for cleaned query
    const vector = await this.vectorization.embedString(filters.cleanedQuery);
    
    // Step 3: Hybrid search in Qdrant
    const results = await this.repository.hybridSearch(
      vector,
      filters,
      params.take ?? 10,
      params.skip ?? 0,
    );

    return {
      meta: {
        count: results.length,
        query: params.query,
        filteringStatus: filters.brand || filters.priceRange ? 'AI_FILTERED' : 'RAG_ONLY',
        appliedFilters: filters,
      },
      items: results,
    };
  }
}

// src/modules/ingestion/mapper/product-mapper.interface.ts
import { UnifiedProduct } from '../../../domain/product.schema';

export interface ProductMapper {
  map(raw: any): Promise<UnifiedProduct>;
}

// Future: Platform adapter interface for live search
interface IProductService {
  searchProducts(query: string, options?: SearchOptions): Promise<Product[]>;
  getProduct(id: string): Promise<Product>;
  getProductBySlug(slug: string): Promise<Product>;
}

// src/domain/product.schema.ts
import { z } from 'zod';

export const PriceSchema = z.object({
  amount: z.number().nonnegative(),
  currency: z.enum(['UAH', 'USD', 'EUR']),
});

export const AttributeSchema = z.object({
  name: z.string(),
  value: z.union([z.string(), z.number(), z.boolean()]),
});

export const VariantSchema = z.object({
  sku: z.string(),
  title: z.string(),
  price: PriceSchema.nullable(),
  available: z.boolean(),
});

export const UnifiedProductSchema = z.object({
  externalId: z.string(),
  url: z.string(),
  title: z.string().min(3),
  description: z.string(),
  brand: z.string().optional(),
  category: z.string().optional(),
  price: PriceSchema,
  mainImage: z.string(),
  attributes: z.array(AttributeSchema),
  variants: z.array(VariantSchema),
  keywords: z.array(z.string()),
});

export type UnifiedProduct = z.infer<typeof UnifiedProductSchema>;

// src/modules/ingestion/mapper/strategies/vendure/vendure.mapper.ts
@Injectable()
export class VendureMapper implements ProductMapper {
  constructor(private config: ConfigService) {}

  async map(raw: VendureProduct): Promise<UnifiedProduct> {
    const basePrice = raw.variants[0]?.priceWithTax ?? 0;
    
    return UnifiedProductSchema.parse({
      externalId: raw.id,
      url: this.buildProductUrl(raw.slug),
      title: raw.name,
      description: this.stripHtml(raw.description || ''),
      brand: this.extractBrand(raw.facetValues),
      category: this.extractCategory(raw.collections),
      price: {
        amount: basePrice / 100, // Vendure stores cents
        currency: raw.variants[0]?.currencyCode || 'USD',
      },
      mainImage: this.transformImageUrl(raw.featuredAsset?.preview || ''),
      attributes: this.mapFacetsToAttributes(raw.facetValues),
      variants: this.mapVariants(raw.variants, basePrice),
      keywords: this.generateKeywords(raw),
    });
  }
}

# Sync products from configured SOURCE_URL
curl -X POST http://localhost:8080/admin/sync \
  -H "x-admin-api-key: your-secret-key"

# Response
{
  "status": "success",
  "message": "Queued 150 products from URL",
  "count": 150
}