# Toys Hub MCP Server

[![smithery badge](https://smithery.ai/badge/redilinxa/toyshub)](https://smithery.ai/servers/redilinxa/toyshub)

Read-only [Model Context Protocol](https://modelcontextprotocol.io) server for the **Toys Hub** online toy catalogue (toyshub.al) — the leading online toy store in Albania and Kosovo.

Lets AI clients like Claude Desktop, Cursor, Continue, Cline, Windsurf, and ChatGPT deep-research browse our live inventory, check prices in Albanian Lek (ALL), and look up product details in Albanian or English.

> **No installation, no API key.** The server runs at `https://toyshub.al/mcp` over plain HTTPS — just point your MCP client at the URL.

---

## Install

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "toyshub": {
      "url": "https://toyshub.al/mcp"
    }
  }
}
```

Restart Claude Desktop. You'll see the 🔌 indicator next to the message box.

### Cursor / Continue / Cline / Windsurf

Most MCP-capable IDEs accept the same URL-style config. Refer to your client's "Add MCP server" UI and paste:

```
https://toyshub.al/mcp
```

Transport: **HTTP** (POST JSON-RPC 2.0). No auth.

### Quick test from the terminal

```bash
curl -X POST https://toyshub.al/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

---

## Tools

| Tool | Description |
|------|-------------|
| `search_products(query, category?, limit?, lang?)` | Search the catalogue by keyword and/or category. Returns up to 50 products with name, price, stock, image, URL. Bilingual: pass `lang: "sq"` for Albanian, `lang: "en"` (default) for English. |
| `get_product(slug, lang?)` | Fetch full PDP data: description, SKU, stock status, all images, tags, recommended age range. Slug comes from the `url` returned by `search_products`. |
| `list_categories(lang?)` | All product categories with their slug, name, and product count. Call this first to discover valid `category` values for `search_products`. |
| `get_store_info()` | Static facts: currency, delivery areas (Albania + Kosovo), payment methods, business hours, contact email. Use for shipping / returns / contact questions. |

### Example: agent searching for a gift

```
User: "Find a magnetic building toy for a 6-year-old, under 7000 lek"

Agent calls search_products(query: "magnetic", limit: 5)
  → 3 results with prices 2,800 / 6,600 / 7,200 ALL
Agent calls get_product(slug: "magnetic-blocks-129pcs", lang: "en")
  → ageMin: 3, ageMax: 10, price: 6,600 — fits the brief.

Agent replies: "Magnetic blocks 129pcs at 6,600 ALL fits perfectly — 
ages 3-10, in stock. https://toyshub.al/products/magnetic-blocks-129pcs"
```

---

## About Toys Hub

- **Website**: [toyshub.al](https://toyshub.al)
- **Delivery**: Albania & Kosovo
- **Currency**: Albanian Lek (ALL)
- **Payment**: Cash on delivery, credit/debit card
- **Languages**: Albanian (sq), English (en)
- **Contact**: contact@toyshub.al

## Implementation

The server is implemented as a Symfony controller co-located with the Toys Hub e-commerce backend — the source for the actual handler is private, but the interface (this repo) and the live endpoint (`/mcp`) are public and stable.

It implements the [MCP `2024-11-05` specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/) including `initialize`, `tools/list`, `tools/call`, and `ping`. Errors follow the standard JSON-RPC 2.0 error codes (`-32600` through `-32603`). CORS is permissive (`Access-Control-Allow-Origin: *`) because all four tools are read-only with no cookies attached.

## License

[MIT](./LICENSE)