ecommerce-fashion-market-analysis
by alexgenovese
README.md
<!-- prettier-ignore -->
<div align="center">
<img src="icon.png" alt="E-commerce Fashion Market Analysis" align="center" height="96" />
# E-commerce Fashion Market Analysis
**Fashion intelligence MCP server for AI agents.**
SEO audits, trend analysis, DTC demand forecasting, CRM enrichment, and campaign creative — built for Claude Code, Cursor, Codex, and any MCP-compatible agent.
[](https://smithery.ai/servers/alexgenovese/ecommerce-fashion-market-analysis)
[](https://smithery.ai/server/alexgenovese/ecommerce-fashion-market-analysis)
[](https://smithery.ai/servers/alexgenovese/ecommerce-fashion-market-analysis)
[](https://github.com/alexgenovese/ecommerce-fashion-market-analysis)
[](https://www.typescriptlang.org)
[](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
[](LICENSE)
[Overview](#overview) • [Quick Start](#quick-start) • [Tools](#tools) • [Examples](#examples) • [Architecture](#architecture) • [Skill Pack](#skill-pack) • [Configuration](#configuration)
</div>
---
## Overview
E-commerce Fashion Market Analysis is a vertical MCP server that gives your AI agent specialized fashion intelligence: SEO auditing, trend research, DTC demand forecasting, CRM segment enrichment, and campaign creative generation. It runs locally via stdio — no cloud deployment required.
Built by [alexgenovese.com](https://alexgenovese.com) for fashion brands, agencies, and creators.
> [!NOTE]
> **What is MCP?** [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI agents call external tools. This server exposes fashion-specific tools that any MCP-compatible client (Claude Code, Cursor, Codex, Gemini CLI, opencode) can discover and use.
### What it does
| Capability | Without this server | With Fashion MCP |
|---|---|---|
| **SEO audit** | Manual checklist, generic advice | Automated score 0-100 with 5 dimension scores and fashion-specific checks (fit, material, color, season, schema, OG, Twitter Cards) |
| **Trend research** | Generic Google searches | Category-level trend intelligence with keywords, colors, silhouettes, price tiers, market fit, evidence, and confidence |
| **Demand forecasting** | Spreadsheets + gut feel | Explainable weighted-rule forecast: `baseline × trend × media × retention × inventory × seasonality` with scenarios and backtesting |
| **CRM enrichment** | Static segments | Customer segments enriched with trending colors/silhouettes/keywords + audience clusters + ready-to-send messaging |
| **Campaign creative** | Copywriter per channel | Platform-specific campaign themes, hooks, value propositions, and creative briefs grounded in trend data |
### Why it's different
- **This server needs no API keys.** `product_seo_audit`, `dtc_forecast_analysis`, `category_demand_outlook`, `customer_trend_enrichment`, and `campaign_theme_recommendation` all work with data you provide directly. Only `fashion_trend_analysis` needs upstream search data, which comes from the separate [Tavily MCP](https://github.com/tavily-ai/tavily-cookbook) server (install it alongside and set `TAVILY_API_KEY` there — not here). Provider integrations (Shopify, Klaviyo, Meta Ads, etc.) are optional and read their own env vars when enabled.
- **Explainable outputs.** Every tool returns `assumptions[]`, `dataGaps[]`, `confidence`, and `recommendedNextCalls[]` — your agent always knows what it's missing.
- **Write-back is opt-in.** Default `dry_run: true`. PII filtering on every write-back. Forecasts use aggregated segments, never personal profiles.
- **Local SQLite persistence.** Zero-config (`~/.fashion-mcp/store.db`) for snapshots, TTL cache, feature store, and forecast actuals for backtesting.
- **Tool-agnostic skill pack.** 16 playbooks use `~~category` placeholders so they work with any MCP server in that category (swap Shopify for WooCommerce without touching the skill).
---
## Quick Start
### Install
```bash
git clone https://github.com/alexgenovese/ecommerce-fashion-market-analysis.git
cd ecommerce-fashion-market-analysis
npm install
npm run build
```
### Connect to your AI agent
<details open>
<summary><h3>Claude Code</h3></summary>
```bash
claude mcp add fashion -- node /path/to/ecommerce-fashion-market-analysis/dist/index.js
```
Then in chat:
> Run a product SEO audit on "Black Leather Jacket" — url: https://mystore.com/products/black-leather-jacket, category: Outerwear, brand: Acne Studios
</details>
<details>
<summary><h3>Cursor</h3></summary>
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"fashion": {
"command": "node",
"args": ["/path/to/ecommerce-fashion-market-analysis/dist/index.js"]
}
}
}
```
</details>
<details>
<summary><h3>Codex / Gemini CLI</h3></summary>
Add to your agent's MCP config:
```json
{
"mcpServers": {
"fashion": {
"command": "node",
"args": ["/path/to/ecommerce-fashion-market-analysis/dist/index.js"]
}
}
}
```
</details>
<details>
<summary><h3>opencode</h3></summary>
Add to `~/.config/opencode/opencode.json` or the project's `opencode.json`:
```json
{
"mcp": {
"fashion": {
"type": "local",
"command": ["node", "/path/to/ecommerce-fashion-market-analysis/dist/index.js"],
"enabled": true
}
}
}
```
Then restart opencode for the changes to take effect.
</details>
<details>
<summary><h3>GitHub Copilot</h3></summary>
Add to your VS Code `settings.json` (`Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"):
```json
{
"github.copilot.mcpServers": {
"fashion": {
"command": "node",
"args": ["/path/to/ecommerce-fashion-market-analysis/dist/index.js"]
}
}
}
```
</details>
<details>
<summary><h3>Continue.dev</h3></summary>
Add to your `~/.continue/config.json`:
```json
{
"experimental": {
"mcpServers": {
"fashion": {
"command": "node",
"args": ["/path/to/ecommerce-fashion-market-analysis/dist/index.js"]
}
}
}
}
```
</details>
<details>
<summary><h3>Smithery (cloud, no install)</h3></summary>
Connect directly without cloning:
```json
{
"mcpServers": {
"fashion": {
"url": "https://ecommerce-fashion-market-analysis--alexgenovese.run.tools"
}
}
}
```
</details>
---
## Tools
The server exposes **6 tools**. All accept `verbose` (0/1/2), `max_words`, and `format` (`json` | `markdown`) for cost control and output shaping. All return explainability blocks (`assumptions`, `dataGaps`, `recommendedNextCalls`).
### `product_seo_audit`
Full SEO audit of a fashion product page. Returns a score (0-100) across 5 dimensions with actionable, role-specific recommendations.
**Checks:** meta title length, meta description, Product JSON-LD schema completeness, image alt text, URL structure, H1 presence, fashion keywords (size, fit, material, color), seasonal context, canonical URL, hreflang, Open Graph, Twitter Cards, title/URL/H1/schema mismatch.
| Parameter | Required | Description |
|---|---|---|
| `title` | Yes | Product title |
| `url` | No | Full product URL |
| `description` | No | Meta description or product description |
| `price` | No | Product price |
| `images` | No | Product images with optional alt text |
| `category` | No | Product category |
| `brand` | No | Brand name |
| `season` | No | Season context (e.g. "SS25", "FW25") |
| `availability` | No | In stock? |
| `verbose` | No | 0=compact, 1=standard, 2=full (default: 1) |
| `max_words` | No | Max words in response (default: 200) |
| `format` | No | `json` or `markdown` (default: `json`) |
**Output:** `productTitle`, `score`, `dimensionScores` (metadata, schema, content, images, fashion_relevance), `checks[]`, `recommendations[]`, `structuredData`, `images[]`, `team_actions[]`, `assumptions[]`, `dataGaps[]`, `recommendedNextCalls[]`
### `fashion_trend_analysis`
Structured trend intelligence from Tavily MCP search data. Accepts results from `tavily_search`, `tavily_search_dedup`, and `tavily_social_media_search` — extracts trending keywords, colors, silhouettes, price tiers, market fit, and key insights.
| Parameter | Required | Description |
|---|---|---|
| `category` | Yes | Product category (e.g. "denim", "sneakers", "bags") |
| `season` | No | Season filter (default: auto-detected) |
| `market` | No | Target market (e.g. "US", "EU", "global") |
| `search_results` | No | Results array from `tavily_search` / `tavily_search_dedup` |
| `search_answer` | No | AI-generated answer from Tavily (`include_answer: true`) |
| `social_results` | No | Results from `tavily_social_media_search` |
| `verbose` | No | 0=compact, 1=standard, 2=full (default: 1) |
| `max_words` | No | Max words (default: 200) |
| `format` | No | `json` or `markdown` (default: `json`) |
**Output:** `category`, `season`, `market`, `generatedAt`, `trendingKeywords[]` (with `stage`, `confidence`, `evidence`), `trendingColors[]` (with hex), `silhouettes[]` (rising/peaking/declining/stable), `priceRanges[]`, `marketFit` (0-100), `priceTierOpportunity[]`, `keyInsights[]`, `assumptions[]`, `dataGaps[]`, `recommendedNextCalls[]`, `warnings[]`
> [!IMPORTANT]
> This tool does **not** make HTTP calls. It accepts data already gathered by Tavily MCP. Install [Tavily MCP](https://github.com/tavily-ai/tavily-cookbook) (`@tavily/mcp`) alongside — it handles search, this tool handles fashion analysis.
### `dtc_forecast_analysis`
Weighted-rule demand forecast for DTC fashion brands. Combines a seasonal baseline with five explainable multipliers to produce a forecast score, confidence interval, driver contributions, risks, and scenario projections.
**Forecast formula:**
```
forecast = baseline × trend × media_efficiency × retention × inventory × seasonality
```
| Parameter | Required | Description |
|---|---|---|
| `category` | Yes | Product category |
| `market` | No | Target market |
| `season` | No | Season context |
| `horizon` | No | `2w`, `1m`, `3m`, `6m` (default: `3m`) |
| `stockCoverDays` | No | Current days of stock cover |
| `campaignRoas` | No | Current campaign ROAS |
| `trendingKeywords` | No | Trend keywords from `fashion_trend_analysis` |
| `silhouetteSignals` | No | Silhouette signals from `fashion_trend_analysis` |
| `format` | No | `json` or `markdown` |
**Output:** `schemaVersion`, `data` → `baselineDemand`, `forecastScore`, `confidenceInterval` (low/high, ±20%), `drivers[]` (name, contribution %, explanation), `risks[]`, `scenarios[]` (base/upside/downside)
### `category_demand_outlook`
Lightweight demand snapshot by category — direction, top trend drivers, price tier winners, and inventory risk flags. Faster and cheaper than a full forecast.
**Output:** `schemaVersion`, `data` → `demandPulse` (0-100), `direction` (up/down/stable), `topDrivers[]`, `priceTierWinners[]`, `inventoryRiskFlags[]`
### `customer_trend_enrichment`
Enrich CRM customer segments with trend awareness. Maps trending keywords, colors, and silhouettes onto a segment profile and produces audience clusters with propensity scoring and a CRM-ready campaign message.
**Output:** `schemaVersion`, `enrichedProfile`, `audienceClusters[]` (name, propensity, recommendedAction), `crmReadyMessage`
### `campaign_theme_recommendation`
Generate campaign themes for fashion brands with platform-specific copy, hooks, value propositions, and creative briefs grounded in trend data.
**Output:** `schemaVersion`, `valueProposition`, `platformSpecific` (format/tone/CTA), `themeOptions[]` (hooks, angles), `creativeBrief` (visual direction, copy angle, hashtags)
> [!TIP]
> Use `verbose: 0` to control token cost when running multiple calls. Use `format: "json"` for AI-agent consumption, `format: "markdown"` for human-readable reports. All tools are read-only by default; write-back is explicitly opt-in.
---
## Examples
### 1. Product SEO Audit
**Ask your AI agent:**
> Audit "Linen Blend Midi Dress" — price: $189, category: Dresses, brand: Mango, material: linen, color: cream. We're launching this for Summer 2025.
**What happens:** The tool checks meta title length (30-60 chars), meta description (120-158 chars), Product schema completeness, fashion keyword coverage, seasonal alignment, canonical, Open Graph, and Twitter Cards. Returns a score, 5 dimension scores, and prioritized fixes with role-specific team actions.
### 2. Trend Research for Seasonal Buying
**Ask your AI agent:**
> What denim trends should I stock for this Fall? I run a contemporary denim brand.
**What happens:** The AI agent calls Tavily MCP (`tavily_search`) to get real web data, then passes the results to `fashion_trend_analysis` which extracts structured trend intelligence — keywords (with stage and confidence), colors (with hex), silhouettes (rising/peaking/declining), price tier opportunity, and a market fit score. No simulated data.
### 3. DTC Demand Forecast
**Ask your AI agent:**
> Forecast demand for our sneakers category for the next 3 months in the US market. We have 45 days of stock cover and our campaigns are running at 3.5x ROAS.
**What happens:** `dtc_forecast_analysis` computes a baseline demand for sneakers in summer, applies five multipliers (trend, media efficiency, retention, inventory, seasonality), and returns a forecast score with a ±20% confidence interval, driver contributions (each explained), risk flags, and three scenarios (base/upside/downside).
### 4. CRM Segment Enrichment
**Ask your AI agent:**
> Enrich our "VIP Female 25-35" segment (5,000 customers, prefers dresses and bags) with current Summer 2026 trends so we can target them.
**What happens:** `customer_trend_enrichment` maps trending keywords, colors, and silhouettes onto the segment, produces audience clusters with propensity scores, and generates a CRM-ready campaign message.
### 5. Full Competitive Intelligence Workflow
**Ask your AI agent:**
> I'm launching a sneaker brand. Analyze the current sneaker market trends, forecast demand, audit our first product page for SEO, and generate campaign creative.
**What happens:** Four tools fire in sequence — `fashion_trend_analysis` maps the market, `dtc_forecast_analysis` forecasts demand, `product_seo_audit` checks the launch page, and `campaign_theme_recommendation` generates platform-specific creative. Combined output gives market positioning + demand forecast + page fixes + campaign briefs.
---
## Architecture
The server is organized into **6 layers** that separate data acquisition, domain logic, fashion intelligence, and forecasting:
```
┌─────────────────────────────────────────────────────────┐
│ AI Agent │
│ (Claude Code, Cursor, Codex, Gemini CLI, opencode) │
└──────────────────────┬──────────────────────────────────┘
│
│ MCP stdio (JSON-RPC)
│ ListTools / CallTool
▼
┌─────────────────────────────────────────────────────────┐
│ fashion-mcp-server (6-layer) │
│ │
│ ┌───────────────┐ ┌────────────────────────────────┐ │
│ │ Server Layer │ │ Domain Layer │ │
│ │ index.ts │ │ ├── schemas/ (16 Zod schemas) │ │
│ │ mcp.ts │ │ ├── entities/ (canonical) │ │
│ │ registry.ts │ │ ├── normalization/ │ │
│ │ errors.ts │ │ │ ├── taxonomy/ │ │
│ │ (7 classes) │ │ │ ├── resolver.ts │ │
│ └───────┬───────┘ │ │ └── trends.ts │ │
│ │ │ ├── scoring/ (SEO) │ │
│ │ │ └── forecasting/ │ │
│ │ │ ├── engine.ts │ │
│ │ │ ├── baseline.ts │ │
│ │ │ ├── multipliers.ts │ │
│ │ │ ├── scenarios.ts │ │
│ │ │ └── backtest.ts │ │
│ ▼ └────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Services Layer │ │
│ │ trend-intelligence, seo-audit, demand-forecast │ │
│ │ feature-store │ │
│ └──────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────┴───────────┐ │
│ ▼ ▼ │
│ ┌─────────────────┐ ┌────────────────────────────┐ │
│ │ Provider Layer │ │ Storage Layer (SQLite) │ │
│ │ Shopify (6 mth) │ │ snapshots, cache (TTL), │ │
│ │ CRM (3: Klaviyo,│ │ features, forecast_actuals│ │
│ │ HubSpot, webhook)│ └────────────────────────────┘ │
│ │ Meta Ads, Google│ │
│ │ Ads, GA4, GSC │ ┌────────────────────────────┐ │
│ └─────────────────┘ │ Utils Layer │ │
│ │ text, dates, validation, │ │
│ │ pii-filter, write-back, │ │
│ │ env-check, logging │ │
│ └────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
| Layer | Role |
|---|---|
| **Server** | MCP stdio transport, tool registry, error taxonomy (7 classes with `metadata: { provider, retryable, suggested_action }`) |
| **Domain** | Canonical Zod schemas (16), entities, taxonomy (40+ colors, 30 silhouettes, 15 categories, 20 synonym groups), SEO scoring (15 audit functions), forecast engine (weighted rules + backtesting) |
| **Services** | Trend intelligence, SEO audit, demand forecast, feature store orchestration |
| **Providers** | Shopify (6 methods), CRM (Klaviyo + HubSpot stub + custom webhook), Meta Ads, Google Ads, GA4, Search Console — all normalize external payloads into canonical signals |
| **Storage** | SQLite (`better-sqlite3`, WAL mode) — `snapshots`, `cache` (TTL), `features`, `forecast_actuals` |
| **Utils** | Text cleaning, date helpers, validation, PII filter (email/phone/card redaction), write-back guard (`dry_run`/`allow_writeback`/`destination`), env checks (non-blocking), JSON logging |
### Forecast engine
The forecast engine is a **weighted-rule model** that is fully explainable:
```
forecast_score = baseline_demand
× trend_multiplier
× media_efficiency_multiplier
× retention_multiplier
× inventory_multiplier
× seasonality_multiplier
```
- **Baseline**: 9 categories × 4 seasons with market adjustment
- **Multipliers**: each returns a value and a human-readable explanation
- **Confidence interval**: ±20% around the forecast score
- **Scenarios**: base, upside (+20%), downside (-20%) with explicit adjustments
- **Driver contributions**: each driver reports its contribution % and explanation
- **Backtesting**: MAPE, WAPE, directional accuracy, bias, interval coverage — stored in `forecast_actuals` table
### Error taxonomy
7 error classes, all extending `McpError` with structured metadata:
| Class | When | Retryable |
|---|---|---|
| `ValidationError` | Invalid input (Zod parse failure) | No |
| `ConnectorAuthError` | Missing/invalid provider credentials | No |
| `ConnectorRateLimitError` | Provider rate limit hit | Yes (backoff) |
| `ConnectorUnavailableError` | Provider unreachable | Yes |
| `NormalizationError` | Payload can't be normalized | No |
| `ForecastComputationError` | Forecast engine failure | No |
| `MissingBaselineError` | No baseline for category/season | No |
### Privacy & safety
- **PII filter**: `stripPii()` redacts emails, phone numbers, credit cards on every write-back
- **Aggregated-only forecasts**: forecasts operate on segments, never personal profiles — `isAggregatedOnly()` guard
- **Write-back opt-in**: default `dry_run: true`; must explicitly set `allow_writeback: true` + `destination` to write
- **Non-blocking env checks**: providers are optional; missing credentials degrade gracefully
---
## Skill Pack
This repo includes **16 markdown playbooks** in `fashion-mcp-skills/skills/` that orchestrate MCP servers into fashion-specific workflows. Skills use **tool-agnostic `~~category` placeholders** so they work with any MCP server in that category — swap vendors without touching the playbook.
| Playbook | Problem it solves | Required categories |
|---|---|---|
| `seo-audit-fashion` | Full SEO audit for fashion e-commerce | `~~ecommerce` + `~~SEO` |
| `competitor-intelligence` | Competitor analysis in 10 minutes | `~~analytics` + `~~SEO` + `~~ecommerce` + `~~ads` + `~~search` |
| `competitor-pricing-audit` | Compare your prices with competitors | `~~ecommerce` + `~~analytics` + fashion-mcp-server |
| `trend-report` | Monthly trend report by category | fashion-mcp-server + `~~search` + `~~SEO` |
| `ad-copy-fashion` | Fashion ad copy for FB/IG/TikTok | `~~ecommerce` + `~~ads` + fashion-mcp-server |
| `full-store-audit` | 360-degree fashion store audit | All categories |
| `inventory-health-check` | Sell-through, stockout risk, markdown alerts | `~~ecommerce` + `~~analytics` |
| `seasonal-drop-planner` | Seasonal drop planning | fashion-mcp-server + `~~SEO` + `~~ads` + `~~ecommerce` |
| `email-campaign-fashion` | Fashion email campaigns | `~~ecommerce` + `~~CRM` + fashion-mcp-server |
| `social-content-calendar` | Weekly fashion social content | fashion-mcp-server + `~~ads` + `~~ecommerce` |
| `product-launch-checklist` | Pre-launch checklist | `~~ecommerce` + `~~SEO` + fashion-mcp-server |
| `brand-visibility-llm` | AI search visibility score | `~~SEO` + `~~search` |
| `dtc-forecast` | DTC demand forecast | fashion-mcp-server (`~~forecast`) |
| `category-demand-pulse` | Quick demand snapshot | fashion-mcp-server (`~~forecast`) |
| `customer-trend-enrichment` | Enrich CRM with trend data | fashion-mcp-server (`~~enrichment`) |
| `campaign-theme` | Campaign creative briefs | fashion-mcp-server (`~~campaign`) |
See [`fashion-mcp-skills/CONNECTORS.md`](fashion-mcp-skills/CONNECTORS.md) for the full category→placeholder mapping.
> [!IMPORTANT]
> The skill pack is the primary product for 85% of the market. The MCP server is for early adopters comfortable with MCP setup. The skills work with any MCP-compatible agent — no custom server required.
### Install skills
```bash
# Claude Code
cp -r fashion-mcp-skills/skills/* ~/.claude/skills/
# Cursor
cp -r fashion-mcp-skills/skills/* ~/.cursor/skills/
# Codex
cp -r fashion-mcp-skills/skills/* "${CODEX_HOME:-$HOME/.codex}/skills/"
```
---
## Configuration
This server itself needs **no API keys** to start — 5 of 6 tools (`product_seo_audit`, `dtc_forecast_analysis`, `category_demand_outlook`, `customer_trend_enrichment`, `campaign_theme_recommendation`) work with data you pass directly. The only prerequisite is `TAVILY_API_KEY`, which belongs to the separate [Tavily MCP](https://github.com/tavily-ai/tavily-cookbook) server that feeds search data to `fashion_trend_analysis`. Provider integrations (Shopify, Klaviyo, Meta Ads, etc.) are optional — set their env vars to enable them. Missing credentials degrade gracefully (non-blocking).
| Variable | Required | Description |
|---|---|---|
| `TAVILY_API_KEY` | **Yes** *(for Tavily MCP only)* | Required by `@tavily/mcp` (separate server). Not used by this server directly |
| `SHOPIFY_STORE` | No | Shopify store domain |
| `SHOPIFY_ACCESS_TOKEN` | No | Shopify Admin API access token |
| `KLAVIYO_API_KEY` | No | Klaviyo API key (CRM provider) |
| `HUBSPOT_API_KEY` | No | HubSpot API key (CRM provider, stub) |
| `CRM_WEBHOOK_URL` | No | Custom CRM webhook URL |
| `META_ACCESS_TOKEN` | No | Meta Ads access token |
| `META_AD_ACCOUNT_ID` | No | Meta Ads account ID |
| `GOOGLE_ADS_DEVELOPER_TOKEN` | No | Google Ads developer token |
| `GOOGLE_ADS_CUSTOMER_ID` | No | Google Ads customer ID |
| `GA4_PROPERTY_ID` | No | Google Analytics 4 property ID |
| `GSC_CLIENT_EMAIL` | No | Search Console service account email |
| `GSC_PRIVATE_KEY` | No | Search Console private key |
| `DEBUG_FASHION_MCP` | No | Set to `1` for structured JSON debug logging |
A ready-to-use MCP config template is at [`.mcp.json.example`](.mcp.json.example).
> [!IMPORTANT]
> `fashion_trend_analysis` requires Tavily MCP (`@tavily/mcp`) to gather search data first. Install both servers side by side — the AI agent orchestrates: Tavily MCP for search → this server for structured analysis. `product_seo_audit` works with data you provide directly and does not require any API keys.
---
## Development
```bash
npm run dev # Dev mode with hot reload
npm run typecheck # Type checking
npm run build # Production build
npm run start # Run the server
npm test # Run unit + e2e tests (141 tests)
npm run test:watch # Watch mode
```
### Testing
The project includes **141 tests** across 13 test files:
| Suite | Tests | Coverage |
|---|---|---|
| `normalization.test.ts` | 16 | Text cleaning, season detection, keyword/color/silhouette extraction, confidence, stage |
| `seo-scoring.test.ts` | 15 | All 15 SEO audit functions + dimension scoring + team actions |
| `forecast.test.ts` | 12 | Baseline, multipliers, computeForecast, backtest metrics |
| `taxonomy.test.ts` | 11 | Dictionary, synonyms, classifier, normalization |
| `errors.test.ts` | 7 | All 7 error classes with metadata |
| `pii-filter.test.ts` | 7 | PII redaction, aggregated-only guard |
| `e2e.test.ts` | 3 | Full MCP server lifecycle: ListTools + CallTool for 3 tools |
### Add a new tool
1. Create `src/tools/<name>.ts`
2. Define Zod input schema
3. Implement `execute<Name>` function
4. Export tool object with `name`, `description`, `inputSchema`, `outputSchema`, `handler`
5. Register in `src/server/registry.ts`
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for details.
---
## Project Structure
```
src/ # MCP server (Node/TypeScript)
├── index.ts # Server entry point
├── server/ # Server layer
│ ├── mcp.ts # MCP bootstrap (ListTools + CallTool)
│ ├── registry.ts # Tool registry (6 tools)
│ └── errors.ts # Error taxonomy (7 classes)
├── domain/ # Domain layer
│ ├── schemas/ # 16 Zod schemas (canonical)
│ ├── entities/ # Core entities
│ ├── normalization/ # Taxonomy + entity resolution
│ │ ├── taxonomy/ # dictionary, synonyms, classifier
│ │ ├── resolver.ts # Entity dedup
│ │ ├── trends.ts # Keyword/color/silhouette extraction
│ │ └── tavily.ts # Content collection
│ ├── scoring/ # SEO scoring (15 audit functions)
│ ├── forecasting/ # Forecast engine + backtesting
│ │ ├── engine.ts # computeForecast
│ │ ├── baseline.ts # 9 categories × 4 seasons
│ │ ├── multipliers.ts # 5 multipliers
│ │ ├── scenarios.ts # base/upside/downside
│ │ └── backtest.ts # MAPE, WAPE, directional accuracy
│ └── recommendations/ # Team actions generator
├── services/ # Service layer
│ ├── trend-intelligence-service.ts
│ ├── seo-audit-service.ts
│ ├── demand-forecast-service.ts
│ └── feature-store-service.ts
├── providers/ # Provider layer (normalizers)
│ ├── shopify/ # 6 methods
│ ├── crm/ # Klaviyo, HubSpot, webhook
│ ├── meta-ads/
│ ├── google-ads/
│ ├── ga4/
│ └── search-console/
├── storage/ # SQLite storage (better-sqlite3, WAL)
├── utils/ # Utilities
│ ├── text.ts, dates.ts, validation.ts, logging.ts
│ ├── pii-filter.ts # PII redaction
│ ├── write-back.ts # Write-back guard
│ └── env-check.ts # Non-blocking env checks
├── tools/ # 6 tool implementations
├── types/fashion.ts # Shared types
└── __tests__/ # Unit + e2e tests (141)
fashion-mcp-skills/ # Skill pack (16 playbooks)
├── skills/ # Playbook .md files
├── CONNECTORS.md # Category→placeholder mapping
├── README.md
└── CLAUDE.md
docs/ # Project docs
├── ROADMAP.md # 8-sprint roadmap
├── PAIN-MATRIX.md # Pain analysis
├── ARCHITECTURE.md # Architecture details
├── MCP-INTEGRATION-GUIDE.md # External MCP integration
└── MARKETPLACE_DEPLOYMENT.md # Publishing guide
```
---
## Roadmap status
All 8 sprints from [`docs/ROADMAP.md`](docs/ROADMAP.md) are complete:
| Sprint | Status | Deliverable |
|---|---|---|
| 1 — Structural refactor | ✅ Done | 6-layer architecture, 7 error classes, utils extraction |
| 2 — Canonical data model | ✅ Done | 16 Zod schemas, entities, taxonomy (40+ colors, 30 silhouettes), entity resolution |
| 3 — Connector layer + SQLite | ✅ Done | Shopify (6 methods), CRM (Klaviyo + HubSpot + webhook), Meta/Google Ads, GA4, GSC, SQLite |
| 4 — Tool v2.5 | ✅ Done | Confidence, evidence, stage, marketFit, priceTierOpportunity, dimension scores, explainability |
| 5 — Forecast engine | ✅ Done | Weighted-rule model, 4 new tools (forecast, demand outlook, enrichment, campaign) |
| 6 — Write-back + PII | ✅ Done | dry_run/allow_writeback/destination, PII filter, env checks |
| 7 — Backtesting | ✅ Done | MAPE, WAPE, directional accuracy, bias, interval coverage |
| 8 — Hardening | ✅ Done | 141 tests, e2e suite, skill pack placeholder refactor, CONNECTORS.md, .mcp.json.example |
---
## Marketplace
Published on:
- [Smithery](https://smithery.ai/server/alexgenovese/ecommerce-fashion-market-analysis) — install with one click
- [Glama](https://glama.ai) — MCP server discovery
- [Pulse](https://mcp.so) — MCP directory
See [docs/MARKETPLACE_DEPLOYMENT.md](docs/MARKETPLACE_DEPLOYMENT.md) for deployment instructions.
---
## Resources
- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol specification
- [MCP Servers Directory](https://mcpservers.org) — Community MCP server catalog
- [fashion-mcp-skills](fashion-mcp-skills/) — Open-source skill pack for fashion retail
- [MCP Integration Guide](docs/MCP-INTEGRATION-GUIDE.md) — How to connect external MCP servers
- [Roadmap](docs/ROADMAP.md) — 8-sprint development roadmap
TDQS
A4.2/5.0
Scored across 2 tools
Disambiguation5/5
The two tools serve entirely different purposes: one analyzes fashion trends, the other audits product SEO. There is no overlap or ambiguity.
Naming Consistency5/5
Both tools use consistent snake_case naming with a clear pattern: fashion_trend_analysis and product_seo_audit. The naming is descriptive and predictable.
Tool Count2/5
With only 2 tools, the server is undersized for its stated domain of e-commerce fashion market analysis. A typical server of this scope would need at least 5-10 tools to cover core functionalities like product data, competitor analysis, etc.
Completeness2/5
The server lacks essential tools for market analysis, such as product retrieval, competitor benchmarking, pricing data, or inventory insights. The trend analysis is limited to a few categories, and the SEO audit is a single-point check. Significant gaps prevent comprehensive market analysis.
Maintenance
ActivityMaintained
ResponsivenessSyncing