<div align="center">

# 🚀 LaunchFast MCP

**Enterprise-Grade Amazon & Alibaba Intelligence for Claude AI**

[![npm version](https://img.shields.io/npm/v/@launchfast/mcp?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/@launchfast/mcp)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP-1.18.2-green?style=for-the-badge)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

*Transform 8-hour product research into 30-second AI conversations*

[Quick Start](#-quick-start) · [Features](#-features) · [Architecture](#-architecture) · [Demo](#-demo)

</div>

---

## 📖 Overview

A production-ready Model Context Protocol (MCP) server that brings real-time e-commerce intelligence directly into Claude Desktop. Built with TypeScript, deployed on Railway, published to npm, and actively used by Amazon sellers.

```bash
npx -y @launchfast/mcp
# That's it. No git clone, no npm install, just works. ✨
```

### What It Does

Transforms complex e-commerce research workflows into natural language:

| Query | Result |
|-------|--------|
| `"Research the Amazon market for portable chargers"` | Market grade, competition analysis, revenue estimates, top 50 products |
| `"Find keyword opportunities for ASIN B08N5WRWNW"` | 150+ keywords with search volume, CPC, gap analysis |
| `"Search Alibaba for bluetooth speaker suppliers with MOQ under 100"` | 20 suppliers ranked by quality score, pricing, certifications |

### Why It Matters

- **10x Faster Research**: What takes 8-10 hours manually happens in 30 seconds
- **AI-Native Interface**: Natural language queries instead of complex dashboards
- **Production Ready**: Rate limiting, retry logic, error handling, monitoring
- **Zero-Config Install**: One-line npm install, shared API quota, works instantly

---

## 🎯 Features

### 1. Market Research (`research_amazon_market`)

Intelligent product analysis with A10-F1 grading algorithm.

**Key Capabilities:**
- Real-time Amazon data via Axesso API integration
- Market grading: A10 (best opportunity) to F1 (oversaturated)
- Multi-layer caching strategy (3x faster responses)
- Sales velocity calculation & revenue estimates
- Competition analysis via BSR tracking
- Advanced filtering: price range, ratings, review count

**Technical Highlights:**
```typescript
// Dual caching strategy for 3x performance
Layer 1: Keyword → ASIN mapping (24h TTL)
Layer 2: Master product data per ASIN
Result: 2-5s cached vs 8-15s fresh
```

### 2. Keyword Intelligence (`research_asin_keywords`)

Deep ASIN analysis with opportunity mining & gap detection.

**Key Capabilities:**
- Multi-ASIN support (analyze 1-10 products simultaneously)
- Keyword metrics: search volume, CPC, competition score, ranking
- Opportunity mining: AI identifies low-competition, high-volume keywords
- Gap analysis: discovers keywords competitors rank for that you don't
- Traffic attribution per keyword

**Technical Highlights:**
```typescript
// Parallel processing with Promise.all()
const results = await Promise.all(
  asins.map(asin => fetchKeywordData(asin))
)
```

### 3. Supplier Discovery (`search_alibaba_suppliers`)

Smart Alibaba search with composite quality scoring.

**Quality Scoring Algorithm (0-100):**
- Trust indicators (40%): Gold Supplier, Trade Assurance, certifications
- Experience (30%): Years in business, transaction history
- Pricing (20%): Competitive rates, flexible MOQ
- Reviews (10%): Rating score, review count, response rate

**Advanced Filters:**
MOQ range, location, certifications, years in business, supplier badges

---

## 🏗️ Architecture

<div align="center">

```mermaid
graph TB
    A[Claude Desktop] -->|JSON-RPC stdio| B[MCP Server]
    B -->|Tool Selection| C{Tool Handlers}
    C --> D[Market Research]
    C --> E[Keyword Intelligence]
    C --> F[Supplier Search]
    D -->|HTTPS| G[LaunchFast API]
    E -->|HTTPS| G
    F -->|HTTPS| G
    G -->|Auth & Rate Limiting| H[Data Services]
    H --> I[Amazon API]
    H --> J[Alibaba API]
    H --> K[Caching Layer]
    K -->|Optimized Response| B
    B -->|Formatted Data| A
```

</div>

### Tech Stack

| Layer | Technology | Purpose |
|-------|-----------|---------|
| **Transport** | stdio (local) / SSE (web) | Claude Desktop & web client support |
| **Protocol** | JSON-RPC 2.0 | MCP-compliant request/response |
| **Runtime** | Node.js 18+ | Fast, modern JavaScript execution |
| **Language** | TypeScript 5.9 (strict mode) | Type safety & developer experience |
| **Validation** | Zod schemas | Runtime input validation |
| **HTTP Client** | Native fetch() | Exponential backoff retry logic |
| **Deployment** | npm + Railway | Local execution & cloud SSE server |

---

## 🎥 Demo

### Complete Product Launch Research (30 seconds)

```
User: "I want to launch bluetooth speakers on Amazon. Full analysis."

Claude executes:
1. Market research → Grade A7, $2.5M monthly revenue
2. Keyword analysis → 150+ keywords, 20 opportunities identified
3. Supplier search → 8 Gold Suppliers, MOQ 50-200, $12-45/unit
4. Profit calculation → $80-100/unit margin @ $149 price point
5. Launch strategy → Keywords, supplier, pricing, sales targets
```

**Result:** Comprehensive launch plan in one conversation.

---

## 🚀 Quick Start

### Prerequisites

- **Node.js 18+** ([Download](https://nodejs.org/))
- **Claude Desktop** ([Download](https://claude.ai/download))
- **LaunchFast API Key** (Get yours at `https://launchfastlegacyx.com`)

### Installation (30 seconds)

**1. Open your Claude Desktop config:**

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

**2. Add this configuration:**

```json
{
  "mcpServers": {
    "launchfast": {
      "command": "npx",
      "args": ["-y", "@launchfast/mcp"],
      "env": {
        "LAUNCHFAST_API_URL": "https://launchfastlegacyx.com",
        "LAUNCHFAST_API_KEY": "lf_your_api_key_here"
      }
    }
  }
}
```

**3. Restart Claude Desktop**

**4. Test it:**

```
Research the Amazon market for "wireless chargers"
```

---

## 💻 Development

### Local Setup

```bash
# Clone repository
git clone https://github.com/BlockchainHB/launchfastmcp.git
cd launchfastmcp

# Install dependencies
npm install

# Create .env file
cp .env.example .env
# Edit .env with your API credentials

# Build
npm run build

# Run locally (stdio mode)
npm run dev

# Run SSE server (web mode)
npm run dev:server
```

### Project Structure

```
launchfastmcp/
├── src/
│   ├── index.ts                 # MCP server (stdio)
│   ├── server-sse.ts            # MCP server (SSE/HTTP)
│   ├── client/
│   │   └── launchfast-client.ts # API client with retry
│   ├── tools/
│   │   ├── market-research.ts   # Tool 1 handler
│   │   ├── asin-keywords.ts     # Tool 2 handler
│   │   └── alibaba-suppliers.ts # Tool 3 handler
│   ├── types/
│   │   └── launchfast.ts        # Type definitions
│   └── utils/
│       ├── logger.ts            # Structured logging
│       └── formatter.ts         # Response formatters
├── build/                       # Compiled output
├── .env.example                 # Environment template
├── package.json                 # npm metadata
├── tsconfig.json                # TypeScript config
└── README.md                    # This file
```

### Available Scripts

```bash
npm run build       # Compile TypeScript → JavaScript
npm run dev         # Run MCP server (stdio mode)
npm run dev:server  # Run SSE server (web clients)
npm run inspect     # Debug mode with source maps
```

---

## 🔧 Technical Highlights

### 1. Production-Grade Error Handling

**Exponential Backoff Retry:**
```typescript
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options)

      // Don't retry 4xx errors (client errors)
      if (response.status >= 400 && response.status < 500) {
        return response
      }

      if (response.ok) return response

      // Retry 5xx errors with exponential backoff
      const backoff = Math.pow(2, attempt - 1) * 1000 // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, backoff))
    } catch (err) {
      if (attempt === maxRetries) throw err
    }
  }
}
```

### 2. Defensive Programming

Handles real-world API variance with multiple fallback strategies:

```typescript
// Multiple fallback field mappings
const name = data.companyName || data.name || data.supplierName || 'Unknown'

// Null-safe number parsing
const moq = parseInt(data.moq?.toString() || '0') || 0

// Array safety
const items = Array.isArray(data.items) ? data.items : []
```

### 3. Type-Safe End-to-End

**Full TypeScript strict mode with runtime validation:**

```typescript
// Zod schemas for runtime validation
export const MarketResearchSchema = z.object({
  keyword: z.string().min(1),
  marketplace: z.string().default('com'),
  limit: z.number().int().min(1).max(100).default(50),
  useCache: z.boolean().default(true),
  filters: z.object({
    minPrice: z.number().optional(),
    maxPrice: z.number().optional(),
    minRating: z.number().min(0).max(5).optional()
  }).optional()
})

// Type inference
type MarketResearchRequest = z.infer<typeof MarketResearchSchema>
```

### 4. Multi-Layer Caching Strategy

```typescript
// Layer 1: Keyword → ASIN mapping (24h cache)
// Avoids expensive Amazon search API calls

// Layer 2: Master product data per ASIN
// Reuses product details across queries

// Result: 3x performance improvement
```

### 5. Security Best Practices

- ✅ User-specific API keys (lf_ prefix validation)
- ✅ Keys in headers, not request bodies
- ✅ Rate limiting with sliding windows (20 req/min)
- ✅ Request audit logging
- ✅ RLS policies for data isolation

---

## 📊 Performance Metrics

| Metric | Value |
|--------|-------|
| **Bundle Size** | 163.4 kB (80.3 kB gzipped) |
| **Dependencies** | 4 (minimal footprint) |
| **Type Coverage** | 100% |
| **Cache Hit Rate** | 73% (production data) |
| **Avg Response Time** | 2.8s (cached), 9.2s (fresh) |
| **Uptime (Railway)** | 99.9% |

---

## 🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test thoroughly (`npm run build && npm run dev`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Code Style

- TypeScript strict mode enabled
- ESLint + Prettier for formatting
- Zod for runtime validation
- Descriptive variable names & comments
- Error handling on all async operations

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 👨‍💻 Author

**Hasaam Bhatti**

- Website: [hasaamb.com](https://hasaamb.com)
- X/Twitter: [@automatingwork](https://x.com/automatingwork)
- GitHub: [@BlockchainHB](https://github.com/BlockchainHB)

---

## 🙏 Acknowledgments

- **[Anthropic](https://anthropic.com)** - Claude AI and Model Context Protocol
- **[MCP Community](https://modelcontextprotocol.io)** - Tools, docs, and inspiration
- **Launch Fast**(https://launchfastlegacyx.com/admin/usage-stats) - API infrastructure and data pipelines

---

## 📈 Project Stats

<div align="center">

![npm](https://img.shields.io/npm/dt/@launchfast/mcp?style=for-the-badge&logo=npm&label=Downloads)
![GitHub Repo stars](https://img.shields.io/github/stars/BlockchainHB/launchfastmcp?style=for-the-badge&logo=github)
![GitHub code size](https://img.shields.io/github/languages/code-size/BlockchainHB/launchfastmcp?style=for-the-badge&logo=github)

**Built with ❤️ for Amazon sellers, product researchers, and AI enthusiasts**

[⬆ Back to Top](#-launchfast-mcp)

</div>