# Vaper.club MCP Server

Vaper.club exposes a read-only [Model Context Protocol](https://modelcontextprotocol.io) server so AI agents can look up vape industry posts, brands, shops, products and reviews.

- **Endpoint:** `https://api.vaper.club/mcp`
- **Transport:** Streamable HTTP (stateless). No authentication required.
- **Access:** read-only public data, rate limited per IP.
- **Audience:** adults only. The tools provide objective product data and user feedback; they do not give guidance on circumventing age verification, purchase restrictions or other legal limits.

## Connect

VS Code (`mcp.json`):

```json
{
  "servers": {
    "vaper-club": { "type": "http", "url": "https://api.vaper.club/mcp" }
  }
}
```

Claude Code:

```bash
claude mcp add --transport http vaper-club https://api.vaper.club/mcp
```

Other clients: configure a remote/HTTP MCP server with the endpoint above.

## Tools

All parameters use snake_case. `page_size` is 1–20 (default 10). `language` is optional (for example `en`, `de`, `fr`); the site default is used if omitted or unsupported.

| Tool | Purpose | Key parameters |
|---|---|---|
| `get_latest_posts` | Latest news, reviews and guides (summaries only) | `limit` (≤50), `language`, `category`, `since` |
| `search_posts` | Keyword search over posts | `query` (required), `category`, `type`, `sort_by` (`relevance`\|`latest`), `start_date`, `end_date`, `page`, `page_size` |
| `search_brands` | Find brands by name, alias or company | `query` and/or `category_name` (at least one) |
| `get_brand_details` | Brand profile, aliases, categories and models | `brand_id` or `slug` or `brand_name` |
| `search_shops` | Find shops by name/website and/or country | `query` and/or `country` (ISO 3166-1 alpha-2, at least one) |
| `get_shop_details` | Shop profile, locations, main brands and categories | `shop_id` or `slug` or `shop_name` |
| `search_products` | Find shop product offers | `query` (required), `brand_name`, `model_name`, `category_name`, `country`, `shop`, `sort_by` (`relevance`\|`latest`\|`rating`\|`reviews`\|`price_asc`\|`price_desc`) |
| `compare_products` | Offers of the same product model across shops, cheapest first | same filters as `search_products`, `limit` (≤10) |
| `get_product_reviews` | Review statistics and newest reviews of the best-matching product | same filters as `search_products`, `limit` (≤20, default 10), `sort_by` (`latest`\|`helpful`) |

## Resources

| URI | Content |
|---|---|
| `vaper://site/about` | What Vaper.club is, disclaimer, data caveats |
| `vaper://site/faq` | Data sources, freshness, brand vs. model vs. product, reviews, rate limits, compliance |
| `vaper://site/categories` | Product categories (id, code, localized name) |
| `vaper://site/languages` | Supported languages |

## Response format

Tool results are JSON text with the same structure as the [REST API](https://vaper.club/developers/api.md):

```json
{
  "success": true,
  "data": {},
  "pagination": { "page": 1, "pageSize": 10, "total": 125, "hasMore": true },
  "meta": { "requestId": "req_...", "timestamp": "...", "language": "en", "warnings": [] },
  "error": null
}
```

Always read `meta.warnings` (for example an unrecognized brand name, or no comparable model found).

## Important semantics

- A **product** record is one shop's offer; several shops can offer the same **model**. A brand is not a model.
- Internal product identifiers are never returned. Identify products by title, shop and `sourceUrl`.
- Review `summary` covers all reviews; the returned `reviews` are only the latest sample.
- Prices and stock change; confirm on the shop website (`shopProductUrl`).

## Limits

Per IP, per minute: posts 30, brand/shop search 30, product search 30, details 60, compare 10, reviews 20, site 60, and 120 overall for MCP. When exceeded, the tool result contains `error.code = "RATE_LIMITED"` and `error.retryAfterSeconds`.

## Agent Skills

Ready-made instructions for agents that use these tools: [Skills index](https://vaper.club/.well-known/agent-skills/index.json).
