Managing Medusa Products

This skill provides guidance on managing products in the Laapak Medusa V2 system using the medusa-products MCP server.

Core Workflows

1. Finding & Inspecting

Use list_products with search queries to find items.
Use get_product to see metadata, variants, and images.

2. Technical Specifications (Metadata)

Technical specs follow this JSON structure in metadata.specs:

{
  "specs": {
    "processor": "Intel Core i7-11850H",
    "ram": "16GB DDR4",
    "storage": "512GB NVMe SSD",
    "gpu": "NVIDIA RTX A4000 8GB",
    "screen_size": "15.6\" FHD 1080p",
    "condition": "Excellent...",
    "battery": "Original - Excellent status"
  }
}

Rules for generate_formatted_description:

Conciseness: Keep CPU, GPU, RAM, and Storage to model names only. No frequencies or core counts.
Condition (الحالة): Stored in metadata but excluded from the generated description.
Battery (البطارية): Never include mAh, Wh, or cell counts. Only performance/status.

3. Media Management

Use upload_image to send a local file directly to the Medusa server.
The returned URL can then be added to the product's images array via update_product.

4. Description Formatting (Deep Detail)

Premium products should use the "Deep Detail" Arabic grid format (12 sections). Structure the description with these specific headers (in Arabic), separated by \n\n:

المعالج والسرعة (Processor)
ذاكرة الوصول العشوائي (الرام) (RAM)
وحدات التخزين (Storage)
كارت الشاشة والجرافيك (GPU)
الشاشة والدقة (Screen)
المنافذ والتوصيل (Ports)
البطارية والطاقة (Battery)
الأمان والخصوصية (Security)
التصميم والوزن (Design)
نظام التشغيل (OS)
الضمان والحالة (Warranty/Condition)
مميزات إضافية (Extras)

!TIP Use the generate_formatted_description tool with a full specs object to generate this structure automatically.

5. Catalog Workflows & Cloning

Cloning Strategy: For new models in an existing series (e.g., ZBook G6 from G5), always use clone_laptop_full. This preserves high-quality image sets and layout.
SKU Naming: Use BRAND-SERIES-MODEL-CONFIG (e.g., HP-ZBOOK-STUDIO-G6-I9-512).
Pricing: Always set both a base price and a sale price via a Price List to trigger the "Sale" badge and strikethrough UI on the storefront.

6. Inventory Management

Use audit_and_fix_inventory to ensure a variant is correctly linked to an inventory item.
Audit Mode: Set repair: false to diagnose.
Repair Mode: Set repair: true, quantity: X to automatically fix broken links and update the stock level.

MCP Tools Reference

Tool	Usage
`create_product`	ENHANCED Create product + options + variants + pricing in one call. Support `category_ids`, `collection_id`, `base_price`, and `sale_price`.
`list_products`	Search and pagination.
`get_product`	Inspect full product data.
`update_product`	Generic update for a single item.
`upload_image`	Upload local file to server.
`clone_product`	(Legacy) Simple copy of a product.
`bulk_update_products`	Update multiple products by ID.
`generate_formatted_description`	UPDATED Generate 12-section Arabic description.
`audit_and_fix_inventory`	Diagnose and repair inventory links & stock levels.
`list_categories`	REGISTERED Fetch category tree.
`list_collections`	NEW Fetch collection list.

SEO Operations

Manage SEO via metadata:

seo_title, seo_description, seo_keywords.
These are automatically rendered by the Next.js storefront.

⚠️ Verification

Always verify changes on https://admin.laapak.com or the storefront at https://laapak.com.

managing-medusa-products

Managing Medusa Products