# FunPay MCP Server

[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg?logo=python&logoColor=white)](#)
[![MCP](https://img.shields.io/badge/MCP-1.x-purple.svg)](#)
[![FunPay](https://img.shields.io/badge/FunPay-API-orange.svg)](#)
[![Tests](https://img.shields.io/badge/Tests-9%2F9-brightgreen.svg)](#)
[![License](https://img.shields.io/badge/AGPL_3.0-green.svg)](LICENSE)
[![Public](https://img.shields.io/badge/Repo-Public-blue.svg)](#)

**FunPay MCP Server** — это MCP-сервер (Model Context Protocol), предоставляющий AI-агентам полный программный доступ к аккаунту FunPay: чтение чатов и заказов, создание и редактирование лотов, возвраты средств и многое другое.

Сервер работает напрямую с web-API FunPay, без Telegram и сторонних зависимостей, и реализует тот же поток запросов, что и [FunPayCardinal](https://github.com/sidor0912/FunPayCardinal), но без наследования его кода.

**FunPay MCP Server** is an MCP server that gives AI agents full programmatic access to a FunPay account: read chats and orders, create and edit lots, refund payments, and more. It talks directly to FunPay's web API, with no Telegram or third-party dependencies, and reproduces the request flow used by [FunPayCardinal](https://github.com/sidor0912/FunPayCardinal) without forking its code.

---

## ⚡ Возможности / Features

### 💬 Чаты и сообщения / Chats and messages
* **`get_chats()`** — список всех чатов с превью последнего сообщения и отметкой непрочитанных.
* **`get_chat_history(chat_id, last_message_id=None)`** — история сообщений конкретного чата (входящие/исходящие, автор, таймстамп, изображения).
* **`get_chats_histories(chat_ids)`** — пакетное чтение историй нескольких чатов одним запросом.
* **`send_message(chat_id, text, interlocutor_id=None)`** — отправка сообщения в чат.
* **`get_chats()` / `get_chat_history()` / `get_chats_histories()` / `send_message()`** — full chat read/write via FunPay's `runner/` long-polling endpoint, same approach as FunPayCardinal.

### 📦 Заказы / Orders
* **`get_orders_counters()`** — счётчики активных продаж и покупок через `runner/orders_counters`.
* **`get_sales(include_paid, include_closed, include_refunded, limit)`** — список заказов со страницы «Мои продажи» с полным описанием, ценой, валютой, покупателем, статусом и датой.
* **`get_order(order_id)`** — детальная карточка заказа: описание, цена, параметры заказа, продавец, покупатель, статус.
* **`refund(order_id)`** — оформление возврата средств покупателю.

### 🏪 Лоты и категории / Lots and categories
* **`get_my_lots(subcategory_id)`** — все ваши лоты в указанной подкатегории.
* **`get_lot_fields(lot_id)`** — текущие значения полей формы редактирования лота.
* **`save_lot(lot_id, fields)`** — создание или обновление лота.
* **`delete_lot(lot_id)`** — деактивация (удаление) лота.
* **`raise_lots(lot_ids)`** — поднятие лотов в каталоге (rate-limited).
* **`get_categories()`** — список категорий (по играм) с подкатегориями.
* **`get_subcategories(category_id)`** — подкатегории конкретной категории.

### 👤 Профиль и баланс / Profile and balance
* **`get_me()`** — собственный профиль: id, username, активные счётчики.
* **`get_user(user_id)`** — публичный профиль любого пользователя FunPay.
* **`get_balance()`** — баланс в RUB, USD и EUR (доступно и всего). FunPay в новом UI не различает «доступно» и «всего», поэтому `total_*` и `available_*` возвращают одно и то же значение (выводимый баланс).

---

## 📦 Установка / Installation

### Требования / Requirements
* Python **3.10+**
* Действующий аккаунт FunPay
* `golden_key` cookie и `User-Agent` из браузера, в котором вы авторизованы на FunPay

### Установка из исходного кода / Install from source
```bash
git clone https://github.com/fakelag28/funpay-mcp-server.git
cd funpay-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

---

## ⚙️ Первичная настройка / Setup

### 1. Получите `golden_key` / Get the `golden_key`
1. Авторизуйтесь на https://funpay.com в браузере Chromium.
2. Откройте DevTools (F12) → **Application** → **Cookies** → `https://funpay.com`.
3. Скопируйте значение cookie **`golden_key`**.
4. Также скопируйте значение **User-Agent** браузера: **DevTools** → **Network** → любой запрос → **Headers** → **User-Agent**.

### 2. Запуск сервера / Run the server
`golden_key` **никогда** не принимается через аргументы CLI и не хранится в коде. Используйте переменные окружения:

```bash
export FUNPAY_GOLDEN_KEY="<ваш golden_key>"
export FUNPAY_USER_AGENT="<ваш User-Agent>"
python -m funpay_mcp
```

Или через `.env`:
```bash
cp .env.example .env
# отредактируйте .env, затем:
export $(cat .env | xargs)
python -m funpay_mcp
```

### Переменные окружения / Environment variables

| Переменная | Обязательна | По умолчанию | Описание |
|---|---|---|---|
| `FUNPAY_GOLDEN_KEY` | ✅ | — | Значение cookie `golden_key` |
| `FUNPAY_USER_AGENT` | ❌ | Chrome 124 Linux | User-Agent браузера с активной сессией |
| `FUNPAY_TIMEOUT` | ❌ | `15` | HTTP timeout, секунды |
| `FUNPAY_LOCALE` | ❌ | `ru` | `ru`, `en` или `uk` |
| `FUNPAY_PROXY` | ❌ | — | Один URL, например `socks5://localhost:1080` |

---

## 🧩 Подключение к MCP-клиенту / Connecting an MCP client

### Claude Desktop
В `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "funpay": {
      "command": "python",
      "args": ["-m", "funpay_mcp"],
      "env": {
        "FUNPAY_GOLDEN_KEY": "<ваш ключ>",
        "FUNPAY_USER_AGENT": "<ваш UA>"
      }
    }
  }
}
```

### Cursor / любой MCP-клиент
Аналогично: зарегистрируйте сервер как `funpay` и передайте `FUNPAY_GOLDEN_KEY` / `FUNPAY_USER_AGENT` через env.

---

## 🔧 Разработка / Development

```bash
pip install -e .[dev]
pytest                          # 7 unit-тестов
FUNPAY_GOLDEN_KEY=*** \
  FUNPAY_USER_AGENT=*** \
  python tests/test_live.py     # live-тест против реального FunPay
```

### Структура проекта / Project layout
```
funpay-mcp-server/
├── src/funpay_mcp/
│   ├── client.py     # HTTP-клиент, golden_key, PHPSESSID, CSRF, runner/ polling
│   ├── parsers.py    # JSON-парсер runner-ответов + HTML-парсер trade-страницы
│   ├── account.py    # 17 методов бизнес-логики
│   ├── models.py     # 10 Pydantic-моделей
│   └── server.py     # FastMCP: 17 @mcp.tool() регистраций
├── tests/
│   ├── test_smoke.py # 7 unit-тестов
│   └── test_live.py  # live-тест (требует golden_key)
├── pyproject.toml
├── .env.example
└── .gitignore
```

### Архитектура / Architecture
* **HTTP-клиент** использует `runner/` long-polling endpoint (как в FunPayCardinal) для получения реальных данных чатов и счётчиков заказов. `runner/` возвращает JSON с типизированными объектами, а не HTML, что упрощает парсинг и позволяет читать сразу несколько чатов одним запросом.
* **CSRF-токен** извлекается из атрибута `data-app-data` на главной странице и автоматически обновляется при каждом успешном ответе.
* **Throttle** 400 мс между запросами защищает от FunPay anti-flood правил.
* **`golden_key` хранится только в env**, не логируется, не пишется в файлы, не коммитится.

---

## 🔒 Безопасность / Security

* `golden_key` — это эквивалент вашего пароля от FunPay. **Никогда** не коммитьте его, не вставляйте в публичные чаты и не логируйте. Если ключ утёк — немедленно смените его в настройках аккаунта FunPay (выйдите из всех сессий).
* Все **mutating**-операции (`send_message`, `refund`, `save_lot`, `delete_lot`, `raise_lots`) рекомендуется вызывать только по явному одобрению пользователя в чате с AI-агентом.
* Сервер single-account: один `golden_key` на один процесс.

---

## 📄 Лицензия / License

Этот проект распространяется под лицензией **AGPL-3.0**. См. файл [LICENSE](LICENSE).
This project is licensed under the **AGPL-3.0** License. See [LICENSE](LICENSE).