# 🎮 WishlistDoc MCP Server

[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/Node-%3E%3D18.0.0-orange.svg)](https://nodejs.org/)
[![Website](https://img.shields.io/badge/Website-wishlistdoc.com-purple.svg)](https://wishlistdoc.com)

The official **[Model Context Protocol (MCP)](https://modelcontextprotocol.io)** server for **[WishlistDoc](https://wishlistdoc.com)** — giving AI agents (Claude, Cursor, Windsurf, Claude Code, Cline) direct access to Steam store algorithmic health audits, empirical P10/P50/P90 sales cone forecasts, and indie game market benchmarks.

---

## 🌟 Why WishlistDoc MCP?

Steam's recommendation algorithm is responsible for over 70% of an indie game's organic reach. **WishlistDoc MCP** enables your AI development assistant to evaluate any Steam store page instantly and forecast commercial outcomes based on empirical industry datasets from GameDiscoverCo and Steamworks.

- **🏥 Instant Store Page Health Audit:** Evaluates 6 algorithmic dimensions (Tag precision, Localization depth, Price resistance, Demo loop, Visual pacing, Short description hook) and returns an S/A/B/C letter grade and prioritized prescriptions.
- **📈 P10 / P50 / P90 Sales Cone Forecasting:** Predicts first-week unit sales and first-year gross revenue under pessimistic, median, and viral breakout scenarios with subgenre conversion rates.
- **📊 Subgenre Benchmarks:** Queries baseline conversion rates, wishlist decay half-life curves (e.g. 270 days), and minimum launch thresholds across RPG, Action, Simulation, Horror, and Casual genres.
- **🔗 Direct Web Report Integration:** Every diagnostic returns deep links to interactive web reports on [wishlistdoc.com](https://wishlistdoc.com).

---

## 🚀 Quick Start

### 1. Claude Desktop

Add `wishlistdoc-mcp` to your `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wishlistdoc": {
      "command": "npx",
      "args": ["-y", "wishlistdoc-mcp"]
    }
  }
}
```

### 2. Cursor (.cursor/mcp.json)

In your project root or user settings, configure `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "wishlistdoc": {
      "command": "npx",
      "args": ["-y", "wishlistdoc-mcp"]
    }
  }
}
```

### 3. Claude Code CLI

Add the server via CLI command:

```bash
claude mcp add wishlistdoc-mcp -- npx -y wishlistdoc-mcp
```

### 4. Smithery (1-Click Install)

Install automatically via [Smithery](https://smithery.ai):

```bash
npx -y @smithery/cli install wishlistdoc-mcp --client claude
```

---

## 🛠️ Available MCP Tools

### `audit_steam_store`
Audits the algorithmic readiness of any Steam store page by AppID.

**Inputs:**
- `appid` *(number, required)*: The Steam application ID (e.g., `105600` for Terraria, `1245620` for Elden Ring).

**Returns:**
- Overall Store Health Score (`0 - 100`) and Grade (`S`, `A`, `B`, `C`, `D`, `F`)
- 6-dimension score breakdown with status (`OPTIMAL`, `WARNING`, `CRITICAL`)
- Primary subgenre detection & algorithmic traffic multiplier
- Ranked action prescriptions with expected score boost and execution steps
- Direct link to web audit report on [wishlistdoc.com/report](https://wishlistdoc.com)

---

### `predict_sales_cone`
Forecasts launch performance and Year-1 gross revenue using empirical conversion models.

**Inputs:**
- `appid` *(number, required)*: The Steam application ID.
- `wishlists` *(number, optional)*: Pre-launch wishlist count. If omitted, empirical estimates based on reviews or median indie cohorts are used.
- `customPriceUSD` *(number, optional)*: Target launch price in USD (e.g. `19.99`).

**Returns:**
- Confidence tiers:
  - **P10 (Pessimistic Floor):** 90% probability above this floor (0.40x median).
  - **P50 (Median Benchmark):** Expected baseline for peer titles (1.0x).
  - **P90 (Breakout Ceiling):** Viral breakout tier (2.50x).
- First-week unit sales & Year-1 estimated gross revenue.
- Algorithmic multipliers (Localization, Demo, Pricing friction, Visual assets).

---

### `get_genre_benchmarks`
Retrieves industry launch benchmarks and wishlist decay parameters.

**Inputs:**
- `genre` *(string, optional)*: Query specific genre (`"rpg"`, `"action"`, `"simulation"`, `"horror"`, `"casual"`, or `"all"`).

**Returns:**
- Median first-week conversion percentage.
- Year-1 lifetime revenue multiplier.
- Wishlist decay half-life duration (in days).
- Recommended minimum pre-launch wishlist target.
- Key commercial drivers for the genre.
- Link to [wishlistdoc.com/benchmarks](https://wishlistdoc.com/benchmarks).

---

## 💬 Example AI Prompts

Once configured in Claude or Cursor, you can ask questions naturally:

- *"Audit my game on Steam (AppID: 2145320). What are the top 3 issues keeping it from getting algorithm recommendations?"*
- *"We are launching our deckbuilder RPG with 18,000 wishlists at $19.99 USD. Predict our P10, P50, and P90 first-week sales and Year 1 revenue."*
- *"What is the standard wishlist decay curve and launch conversion rate for an indie simulation game on Steam?"*

---

## 🔬 Empirical Methodology & Calculation Formulas

All diagnostic algorithms and forecasting cones implemented in **WishlistDoc MCP** run directly on the local Node.js engine using transparent, reproducible statistical formulas:

### 1. Base Conversion Rates by Genre ($C_{\text{base}}$)
Empirically calibrated from GameDiscoverCo dataset (Simon Carless) and Steamworks cohort analyses:
- **RPG / Turn-Based / Grand Strategy:** $16.0\%$
- **Action / Roguelite / Shooter:** $13.0\%$
- **Simulation / Colony / Tycoon:** $12.0\%$
- **Horror / Atmospheric Survival:** $14.0\%$
- **Casual / Narrative / Logic Puzzle:** $8.5\%$

### 2. Algorithmic Store Multiplier Matrix ($M_{\text{total}}$)
Accounts for Steam recommendation engine behavior and shopper conversion friction:
$$M_{\text{total}} = M_{\text{lang}} \times M_{\text{demo}} \times M_{\text{price}} \times M_{\text{vis}}$$
- **Localization ($M_{\text{lang}}$):** $1.10\times$ ($\ge 12$ languages including EFIGS + CJK), $0.85\times$ ($\le 5$ languages), $1.0\times$ (standard).
- **Playable Demo ($M_{\text{demo}}$):** $1.0\times$ with active demo (Next Fest eligible), $0.90\times$ without demo (conversion drag).
- **Price Resistance ($M_{\text{price}}$):** $1.20\times$ ($<\$9.99$), $1.0\times$ ($\$10-\$24.99$), $0.75\times$ ($>\$25.00$ high barrier).
- **Visual Impact ($M_{\text{vis}}$):** $1.05\times$ ($\ge 1$ gameplay trailer + $\ge 5$ screenshots).

### 3. P10 / P50 / P90 Sales Cone Confidence Intervals
- **P50 (Median Benchmark):**
  $$\text{Sales}_{W1, P50} = \max\left(\text{round}(W_{\text{eff}} \times C_{\text{base}} \times M_{\text{total}}), 20\right)$$
- **P10 (Pessimistic Floor - 90% Probability Above):**
  $$\text{Sales}_{W1, P10} = \max\left(\text{round}(\text{Sales}_{W1, P50} \times 0.40), 5\right)$$
- **P90 (Viral Breakout - 10% Probability Ceiling):**
  $$\text{Sales}_{W1, P90} = \max\left(\text{round}(\text{Sales}_{W1, P50} \times 2.50), 50\right)$$
- **Year-1 Lifetime Gross Revenue:**
  $$\text{Revenue}_{\text{Year 1}} = \text{Sales}_{W1} \times \text{Price}_{\text{USD}} \times 3.2$$
  *(where $3.2\times$ represents the empirical median multiplier from Week-1 sales to Year-1 total gross volume across Steam indies).*

### 4. Wishlist Decay Equation
Older wishlists experience natural interest decay. The 270-day half-life decay function computes effective purchase-intent volume:
$$W_{\text{eff}} = \sum_{i} W_i \cdot e^{-\lambda (t - t_i)}, \quad \lambda = \frac{\ln(2)}{270} \approx 0.002568 \text{ day}^{-1}$$

### 5. Data Privacy & Zero Lock-in
The MCP server communicates directly with Steam's public store API (`store.steampowered.com/api/appdetails`) and WishlistDoc's edge cache. All calculation formulas are executed locally within the MCP process with zero data retention.

---

## 🔗 Related Resources

- **Official Web Platform:** [wishlistdoc.com](https://wishlistdoc.com)
- **Interactive Store Audit:** [wishlistdoc.com/report](https://wishlistdoc.com/report)
- **Steam Benchmarks Calculator:** [wishlistdoc.com/benchmarks](https://wishlistdoc.com/benchmarks)
- **Model Context Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

---

## 📄 License

MIT © [WishlistDoc](https://wishlistdoc.com)