# MCP Affiliate Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that enables AI assistants to **search products and generate affiliate links** across European and global affiliate networks.

Built for the maker/STEM community. Works with Claude Code, Claude Desktop, and any MCP-compatible client.

## The Problem

You're building content with AI (project tutorials, product guides, comparison articles) and want to monetize with affiliate links. Currently you must:

1. Manually search each shop for products
2. Manually generate tracking links per network
3. Copy-paste prices and URLs into your content
4. Repeat for every product, every shop, every article

**This server automates all of it.** Ask your AI assistant to find products, and it returns affiliate-ready links with prices from multiple shops.

## Features

| Tool | Description |
|------|-------------|
| `search_products` | Search across Awin, Amazon, Tradedoubler, AliExpress |
| `match_bom` | Match a Bill of Materials to products with affiliate links |
| `generate_affiliate_link` | Convert any product URL into a tracking link |
| `list_merchants` | Show configured merchants with commission rates |
| `sync_feeds` | Download and update product feeds |

### Example: BOM Matching

```
You: "Find affiliate links for these parts: 6x STS3215 Servo, 1x ESP32 DevKit, PLA Filament 1kg"

MCP Server returns:
[
  {
    "name": "STS3215 Servo",
    "quantity": 6,
    "shops": [
      { "shopName": "Conrad", "price": "EUR 24.90", "url": "https://...", "isAffiliate": true },
      { "shopName": "Amazon.de", "price": "EUR 22.99", "url": "https://...", "isAffiliate": true }
    ]
  },
  ...
]
```

## Supported Networks

| Network | Merchants | Commission | API Type |
|---------|-----------|------------|----------|
| **Awin** | Conrad, Reichelt, 3DJake, Bambu Lab | 4-6% | Product Feeds + Batch Link Gen |
| **Amazon** | Amazon.de | 1-7% | Creators API (search + links) |
| **Tradedoubler** | Galaxus/Digitec | ~3% | Product Search + Feeds |
| **AliExpress** | AliExpress | 3-8% | Product Search + Links |
| **Impact** | Elegoo | 4.5% | REST API |

> **Note:** Amazon PA-API 5.0 is deprecated April 30, 2026. This server uses the new Creators API.

## Quick Start

### 1. Install

```bash
git clone https://github.com/Scientia07/Luno-MCP-Affiliate.git
cd Luno-MCP-Affiliate
npm install
npm run build
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env with your API keys
```

### 3. Add to Claude Code

Add to `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "affiliate": {
      "command": "node",
      "args": ["/path/to/Luno-MCP-Affiliate/dist/index.js"],
      "env": {
        "AWIN_API_KEY": "your_key",
        "AWIN_PUBLISHER_ID": "your_id",
        "AMAZON_PARTNER_TAG": "your_tag-21"
      }
    }
  }
}
```

### 4. Sync Product Feeds

In Claude Code, run:
```
Use the sync_feeds tool to download product catalogs
```

### 5. Use It

```
Search for "Raspberry Pi 5" across all affiliate shops
```

```
Match these BOM items to affiliate products: 6x STS3215 Servo, 1x ESP32-S3, PLA Filament 1kg
```

```
Generate an affiliate link for https://www.conrad.de/de/p/raspberry-pi-5-8gb-2849738.html
```

## Architecture

```
┌─────────────────────────────────────────┐
│  MCP Client (Claude Code / Desktop)      │
│  "Find products for ESP32 DevKit"        │
└──────────────┬──────────────────────────┘
               │ MCP Protocol (stdio)
┌──────────────▼──────────────────────────┐
│  MCP Affiliate Server                    │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐  │
│  │ search  │ │ match    │ │ generate │  │
│  │ products│ │ bom      │ │ link     │  │
│  └────┬────┘ └────┬─────┘ └────┬─────┘  │
│       └───────────┼────────────┘         │
│              ┌────▼─────┐                │
│              │ Product  │                │
│              │ Database │ (SQLite)        │
│              └────┬─────┘                │
└───────────────────┼─────────────────────┘
                    │ synced from
    ┌───────────────┼───────────────┐
    │               │               │
┌───▼───┐     ┌────▼────┐    ┌────▼─────┐
│ Awin  │     │ Amazon  │    │Tradedblr │
│ Feeds │     │Creators │    │  API     │
│(CSV)  │     │  API    │    │(JSON)    │
└───────┘     └─────────┘    └──────────┘
```

## Project Structure

```
src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup (tools + resources)
├── tools/
│   ├── search.ts         # Aggregated product search
│   ├── awin.ts           # Awin feed search + link generation
│   ├── amazon.ts         # Amazon Creators API
│   ├── tradedoubler.ts   # Tradedoubler/Galaxus
│   ├── aliexpress.ts     # AliExpress API
│   ├── bom-matcher.ts    # BOM → affiliate links pipeline
│   ├── link-generator.ts # URL → affiliate link converter
│   └── merchants.ts      # Merchant configuration
├── feeds/
│   ├── feed-manager.ts   # Feed download orchestration
│   └── product-db.ts     # SQLite product database
├── matching/
│   └── fuzzy-match.ts    # Fuse.js fuzzy product matching
└── types/
    └── index.ts          # Shared TypeScript types
```

## Development Status

This project is in **early development**. The MCP server interface and tool definitions are complete. API integrations are stubbed with clear TODOs.

### Roadmap

- [x] MCP server scaffold with 5 tools
- [x] Type system and interfaces
- [x] Merchant configuration (8 merchants across 4 networks)
- [x] Fuzzy matching with Fuse.js
- [ ] Awin product feed download + SQLite storage
- [ ] Awin batch link generation (100 links/request)
- [ ] Amazon Creators API integration
- [ ] Tradedoubler product search
- [ ] AliExpress product search
- [ ] Feed sync scheduling (cron-like)
- [ ] MCP Inspector testing
- [ ] npm publishable package

## API Keys Required

| Network | Where to Get | Notes |
|---------|-------------|-------|
| Awin | [awin.com](https://www.awin.com/) | Free signup, apply per merchant |
| Amazon | [partnernet.amazon.de](https://partnernet.amazon.de/) | Need 10+ sales/30 days for API |
| Tradedoubler | [tradedoubler.com](https://www.tradedoubler.com/) | Apply for Galaxus program |
| AliExpress | [portals.aliexpress.com](https://portals.aliexpress.com/) | Free developer account |

## Contributing

Contributions welcome! This is a LunoLabs open-source project. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Key areas where help is needed:
- API integration implementations (see TODO comments in `src/tools/`)
- Additional affiliate network support
- Test coverage
- Documentation

## License

MIT - see [LICENSE](LICENSE)

---

Built by [LunoLabs](https://lunolabs.ch) - Technologie fur alle.