MCP-сервер возвратов PageFly

MCP-сервер (Model Context Protocol) для ИИ-агента Hugo от Crisp, предназначенный для комплексной обработки запросов на возврат средств в PageFly.

Он предоставляет девять инструментов, сгруппированных по трем уровням:

Поиск (фикстуры)

• check_subscription → получение текущего тарифного плана для магазина или email

• get_billing_history → список всех счетов / предстоящих списаний для магазина

Чистая логика

• classify_refund_case → сопоставление контекста с одним из 7 сценариев (TH1–TH7)

• calculate_refund → расчет возврата средств (пропорционально за 30 дней или за несколько циклов) с учетом удержаний

• collect_refund_info → определение следующего вопроса для уточнения и выявление блокирующих факторов

• generate_refund_message → создание черновика ответа клиенту на основе шаблонов PageFly

Состояние (Turso / libSQL)

• get_case_state → возобновление работы с обращением по URL магазина

• save_case_state → сохранение прогресса на каждом значимом этапе

• list_pending_cases → просмотр обращений, ожидающих действий менеджера, клиента или оплаты счета

Создано с использованием TypeScript SDK для @modelcontextprotocol.

Окружение

Скопируйте .env.example в .env и заполните свои учетные данные Turso:

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

Миграции запускаются автоматически при старте сервера — их можно безопасно запускать повторно.

Related MCP server: Spaceship MCP

I. Установка и запуск

Чтобы начать работу с этим MCP-сервером, вы можете запустить его локально или использовать размещенную версию.

Использование размещенной версии

Этот MCP-сервер уже размещен и готов к подключению к вашему рабочему пространству Crisp, если вы хотите быстро его протестировать. Вы можете получить к нему доступ по адресу: https://crisp-mcp-demo.fly.dev/mcp

Локальный запуск

Предварительные требования:

• Установленный Node.js 24.x

• Клавиатура (необязательно, но рекомендуется)

Шаг 1 — Клонирование репозитория

Откройте терминал в нужной папке и выполните:

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

Шаг 2 — Запуск сервера

Вы можете собрать и запустить сервер или запустить его напрямую в режиме разработки.

Для сборки и запуска сервера используйте:

npm ci
npm run build
npm run start

Или для запуска в режиме разработки с помощью tsx (режим отслеживания изменений) используйте:

npm ci
npm run dev

Шаг 3 — Открытие доступа к серверу (при локальном запуске)

Если вы хотите запустить сервер локально, вам нужно будет открыть к нему доступ через туннель, чтобы Crisp мог к нему подключиться. Этот пакет предварительно настроен для использования Cloudflared, хотя вы можете использовать любое другое решение для туннелирования.

Если Cloudflared еще не установлен на вашем компьютере, перейдите по этой ссылке, чтобы найти инструкции по установке для вашей ОС:

После установки откройте новый терминал и выполните:

npm run tunnel

Вы можете посетить URL вашего туннеля, чтобы убедиться, что он работает. Вы должны увидеть приветственное сообщение.

Доступные скрипты

• npm run dev → сервер разработки (watch)

• npm run build → компиляция TypeScript

• npm run start → запуск скомпилированного сервера

• npm run tunnel → открытие доступа к localhost через Cloudflare Tunnel

• npm run inspect → запуск инспектора @modelcontextprotocol

II. Подключение к Crisp

Этот раздел представляет собой краткое руководство по подключению данного MCP-сервера к вашему рабочему пространству Crisp. Мы также рекомендуем ознакомиться с нашей официальной документацией для получения более подробных инструкций.

Предварительные требования:

• Аккаунт Crisp

• Рабочее пространство Crisp с планом Essentials или Plus

Шаг 1 — Перейдите на app.crisp.chat

Шаг 2 — В меню AI Agent перейдите в AI Agent → Automate → Integrations & MCP → External MCP servers и нажмите на зону Add MCP server.

Шаг 3 — Введите URL вашего MCP-сервера (ваш размещенный/туннелированный URL или нашу размещенную версию) и нажмите Add MCP Server.

Шаг 4 — Настройте MCP-сервер:

1. Дайте ему имя

2. Нажмите Refresh tools from server, если инструменты не были получены автоматически

3. Включите MCP-сервер

4. Нажмите кнопку Save changes

Шаг 5 — Ваш MCP-сервер теперь должен быть зарегистрирован и готов к использованию!

III. Тестирование MCP-сервера

Все еще находясь в меню Automations, вы можете перейти в Playground, чтобы протестировать ваш MCP-сервер и различные модели ИИ. Задайте ему вопрос!

Примеры для Playground

Одиночные вопросы:

Можешь проверить, был ли обработан возврат по моему заказу OID_002?

Привет, включены ли уведомления в моем аккаунте baptiste@acme.com?

ИИ может объединять несколько вызовов инструментов (например, найти аккаунт, вывести список недавних заказов и получить детали продукта):

На товары из моего заказа OID_001 все еще действует гарантия?

Когда будет доставлен мой последний заказ? Я chris@acme.com

Также попробуйте задавать неполные вопросы и позвольте ИИ запросить у вас дополнительную информацию:

Какова была сумма моего последнего заказа?

Я не могу найти свой номер отслеживания, вы можете помочь?

Доступные аккаунты и заказы

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

Рекомендации по работе с MCP

Проектирование MCP

• Описание сервера: Опишите общую цель MCP-сервера

• Именование инструментов: используйте понятные и явные имена (например, get_order, а не orderLookup)

• Описание инструментов: кратко опишите, что делает инструмент, когда его вызывать, и при необходимости приведите примеры использования

• Схемы: предоставляйте точные схемы для входных данных инструментов, чтобы обеспечить их правильное использование

Верификация пользователя

В конфигурации вашего MCP-сервера вы также можете при необходимости потребовать от пользователей аутентификации перед тем, как ИИ сможет вызвать инструмент MCP. Это повышает безопасность при выполнении конфиденциальных операций.

Если пользователь еще не прошел аутентификацию, Crisp отправит ему OTP-код по электронной почте или SMS перед тем, как разрешить ИИ вызвать ваш инструмент MCP.

Для этого просто перейдите к вашему MCP-серверу и нажмите Manage. Для каждого инструмента вы можете переключить опцию Require user identification verification.

Аутентификация сервера

В рабочей среде вы можете ограничить доступ к вашему MCP-серверу и предотвратить несанкционированное использование. Доступны два метода аутентификации:

• Bearer Token: статический токен, отправляемый в заголовке Authorization каждого запроса

• Basic Auth: имя пользователя и пароль, отправляемые в заголовке Authorization каждого запроса