FunPay MCP Server

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

Сервер работает напрямую с web-API FunPay, без Telegram и сторонних зависимостей, и реализует тот же поток запросов, что и 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 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

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 и не хранится в коде. Используйте переменные окружения:

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

Или через .env:

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:

{
  "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

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. This project is licensed under the AGPL-3.0 License. See LICENSE.