# TheFashionDeals — Developer & AI Agent Integration Hub

> Official integration specifications and live developer documentation for TheFashionDeals (https://thefashiondeals.com).  
> Last Updated: 2026-09-17 | Maintained by TheFashionDeals Developer Platform Team

## Overview
TheFashionDeals provides real-time fashion deal intelligence across 60,000+ verified Amazon US apparel, footwear, and accessory products. Autonomous AI shopping agents and third-party developers can query live, 90-day baseline audited discount feeds via the Model Context Protocol (MCP) or high-speed REST APIs.

---

## 📖 TheFashionDeals Data Dictionary & Universe

To ensure academic and machine transparency, all deal metrics adhere to a strict semantic definition:

| Metric | Weekly Baseline Value | Semantic Definition |
| :--- | :--- | :--- |
| **Monitored Universe** | **63,594 ASINs** | Total Amazon US fashion catalog actively monitored at weekly snapshot time across clothing, shoes, bags & watches. |
| **Active Verified Deals** | **13,363 Deals** | Products in stock satisfying $\ge 15\%$ verified discount against 90-day historic median baseline. |
| **Market Average Discount** | **30.5% OFF** | Mean algorithmic discount across all live verified deal categories. |
| **Deep Liquidation Clearance** | **102 Deals** | Extreme price drops ($\ge 70\%$ discount) representing seasonal liquidation or algorithmic glitch drops. |
| **Consumer Savings Pool** | **$255,705.63** | Aggregate net dollar savings across all active verified deals at snapshot time. |

---

## 1. Model Context Protocol (MCP) Server

- **Protocol:** JSON-RPC 2.0 (Model Context Protocol Standard)
- **Production Endpoint:** `https://thefashiondeals.com/api/social/mcp`
- **Smithery Registry:** [smithery.ai/servers/bydoktor8181/thefashiondeals](https://smithery.ai/servers/bydoktor8181/thefashiondeals)
- **Glama Registry:** [glama.ai/mcp/servers/TheFashionDeals/thefashiondeals-mcp-server](https://glama.ai/mcp/servers/TheFashionDeals/thefashiondeals-mcp-server)
- **Well-Known Server Card:** `https://thefashiondeals.com/.well-known/mcp/server-card.json`

### Available Tools:
1. **`search_fashion_deals`**: Transactional search by keyword, category, max price, and min discount.
2. **`get_top_deals`**: Opportunity discovery for steepest clearance price drops (50% to 90% off).
3. **`get_brand_discounts`**: Brand intelligence and active verified deals for a specific fashion brand.

### Quick Setup for Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "thefashiondeals": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thefashiondeals.com/api/social/mcp"
      ]
    }
  }
}
```

### Quick Setup for Cursor IDE
- **Name:** `TheFashionDeals`
- **Type:** `sse`
- **Server URL:** `https://thefashiondeals.com/api/social/mcp`

---

## 2. The 3 Canonical Killer Demos (Executable Proof)

### 🛒 Demo 1 — Shopping Agent (Transactional Discovery)
**User Prompt:** *"Find 5 women's designer shoes on Amazon US under $50 with at least 60% verified discount."*

**Agent Tool Call:**
```json
{
  "name": "search_fashion_deals",
  "arguments": {
    "search": "designer shoes",
    "category": "womens-shoes",
    "max_price": 50.00,
    "min_discount": 60,
    "limit": 5
  }
}
```

**Validated Snapshot with Provenance:**
```json
{
  "asin": "B0D776LJJN",
  "title": "Reebok Club C 85 Mens Tennis Shoes, Chalk/Navy/Flint Grey",
  "brand": "Reebok",
  "current_price": 23.18,
  "original_price": 85.00,
  "currency": "USD",
  "discount_percentage": 73,
  "prime": true,
  "availability": "in_stock",
  "verification_method": "90_day_historic_median_audit",
  "source": "TheFashionDeals Real-Time Deal Intelligence",
  "canonical_url": "https://thefashiondeals.com/deal/reebok-club-c-85-b0d776ljjn",
  "deal_url": "https://thefashiondeals.com/deal/reebok-club-c-85-b0d776ljjn?utm_source=claude_mcp",
  "last_checked_at": "2026-09-17T16:06:41-07:00"
}
```

### 🏷️ Demo 2 — Brand Intelligence (Opportunity Discovery)
**User Prompt:** *"Audit current verified discount opportunities for Nike on Amazon US."*

**Agent Tool Call:**
```json
{
  "name": "get_brand_discounts",
  "arguments": {
    "brand": "Nike"
  }
}
```

### 📊 Demo 3 — Market Intelligence & Weekly Price Index
**User Prompt:** *"What are the steepest Amazon US fashion clearance drops right now, and how does this week's discount environment compare?"*

**Agent Tool Call:**
```json
{
  "name": "get_top_deals",
  "arguments": {
    "limit": 10
  }
}
```
**Connected Resource:** `https://thefashiondeals.com/reports/weekly-deal-index-latest.md`

---

## 3. High-Speed REST API

- **Endpoint:** `GET https://thefashiondeals.com/api/social/top-deals`
- **OpenAPI 3.1 Spec:** `https://thefashiondeals.com/api/social/openapi.json`
- **Throughput:** 60 requests/minute per client IP (No API key required for public tier)

```bash
curl -X GET "https://thefashiondeals.com/api/social/top-deals?category=shoes&min_discount=50&limit=5" \
     -H "Accept: application/json"
```

---

## 4. Weekly Open Datasets & Academic Citations

[![Hugging Face Dataset](https://img.shields.io/badge/🤗%20Hugging%20Face-Dataset-yellow.svg)](https://huggingface.co/datasets/thefashiondeals/amazon-us-fashion-deal-index)
[![GitHub Repository](https://img.shields.io/badge/GitHub-Dataset%20Repo-blue.svg)](https://github.com/TheFashionDeals/amazon-fashion-deal-index)
[![License: CC BY 4.0](https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by/4.0/)

- **Hugging Face Open Dataset:** [https://huggingface.co/datasets/thefashiondeals/amazon-us-fashion-deal-index](https://huggingface.co/datasets/thefashiondeals/amazon-us-fashion-deal-index)
- **Interactive Dataset Viewer:** Live tabular spreadsheet, streaming & filtering hosted on Hugging Face.
- **Reports Hub:** [https://thefashiondeals.com/reports](https://thefashiondeals.com/reports)
- **GitHub Open Data:** [https://github.com/TheFashionDeals/amazon-fashion-deal-index](https://github.com/TheFashionDeals/amazon-fashion-deal-index)
- **Weekly JSON Dataset:** `https://thefashiondeals.com/data/weekly/latest.json`
- **Weekly CSV Dataset:** `https://thefashiondeals.com/data/weekly/latest.csv`

### Direct Loading in Python (Pandas)
```python
import pandas as pd

# Load the latest weekly Amazon fashion deals dataset directly from Hugging Face
df = pd.read_csv("https://huggingface.co/datasets/thefashiondeals/amazon-us-fashion-deal-index/raw/main/data/latest.csv")
print(f"Loaded {len(df)} verified fashion price drops.")
print(df[['Brand', 'Title', 'Deal_Price_USD', 'Discount_Percent']].head())
```

### BibTeX Citation:
```bibtex
@dataset{thefashiondeals_2026_w38,
  author = {TheFashionDeals Editorial and Research Board},
  title = {Amazon US Fashion Deal Intelligence & Price Index (2026-W38)},
  year = {2026},
  publisher = {TheFashionDeals.com},
  url = {https://thefashiondeals.com/reports/weekly-deal-index-2026-w38}
}
```

---

## 5. Amazon Associates Compliance Notice
TheFashionDeals is a participant in the Amazon Services LLC Associates Program. As an Amazon Associate, TheFashionDeals earns from qualifying purchases. Product prices and availability are accurate as of the snapshot date/time indicated and are subject to change. Any price and availability information displayed on Amazon.com at the time of purchase will apply to the purchase of this product.