AI Асистент для ServiceFusion: Запит роботи через чат, а не кліки
Ситуація
Оператор польового обслуговування, що працює на ServiceFusion, хотів, щоб диспетчери та офісний персонал перестали переходити через меню щоразу, коли їм потрібно перевірити історію роботи клієнта, відкрити оцінки або побачити, який технік призначений на роботу. Команда вже використовувала Claude для інших завдань. Очевидний наступний крок: дозволити Claude спілкуватися безпосередньо з ServiceFusion.
Проблема
ServiceFusion надає REST API, але AI асистенти не можуть викликати його безпосередньо. Протокол контексту моделі (MCP) є новим стандартом для надання AI клієнтам структурованого доступу до зовнішніх інструментів, і жодного MCP сервера для ServiceFusion не існувало. Правильне створення одного означало вирішення трьох проблем одночасно:
Життєвий цикл токена OAuth2. ServiceFusion використовує короткочасні токени доступу, які закінчуються і повинні бути оновлені прозоро, щоб AI ніколи не стикався з помилкою авторизації під час розмови.
Багатокористувацькість. Один екземпляр сервера повинен був ізолювати облікові дані та API виклики для кількох компаній, кожна з яких має свій обліковий запис ServiceFusion.
Самообслуговування при onboarding. Оператор не хотів вручну налаштовувати кожного нового орендаря.
Рішення
Я створив багатокористувацький MCP сервер на Node.js та TypeScript, який знаходиться між AI клієнтами (Claude, Cursor, ChatGPT) та ServiceFusion. Він надає 13 структурованих інструментів, що охоплюють основні сутності, які насправді використовують диспетчери: клієнти, роботи, оцінки, техніки та обладнання.
Сервер обробляє два незалежні шари OAuth2. Один аутентифікує вхідні AI клієнти до MCP сервера. Другий керує власними токенами ServiceFusion сервера, включаючи автоматичне оновлення з блокуванням конкурентності, щоб одночасні запити ніколи не викликали дублювання оновлень.
Всі чутливі облікові дані (ідентифікатори клієнтів, секрети, токени) шифруються в спокої за допомогою AES-256-GCM у Supabase PostgreSQL. Нові орендарі самостійно реєструються через REST API, підтверджують через OTP і надають свої облікові дані ServiceFusion для активації. Жодної ручної роботи оператора при реєстрації.
Легка адміністративна панель дозволяє оператору переглядати використання за орендарем, регулювати ліміти швидкості та активувати або деактивувати облікові записи.
Технічний стек: Node.js 20, TypeScript, @modelcontextprotocol/sdk, Express, Supabase (PostgreSQL), шифрування AES-256-GCM, Zod, Winston, Docker, nginx, Let's Encrypt
Результати
13 MCP інструментів працюють з клієнтами, роботами, оцінками, техніками та обладнанням
Жодної ручної налаштування для орендаря. Процес реєстрації та активації через OTP
Прозорий OAuth2. Токени, що закінчилися, автоматично оновлюються з захистом від гонки
Ліміти швидкості для кожного орендаря (безкоштовні, професійні, корпоративні рівні) забезпечуються на рівні запиту
Повне відстеження використання (назва інструменту, кінцева точка, код статусу, час відповіді) реєструється для кожного орендаря для виставлення рахунків та аналітики
Розгорнуто в продукції на Hetzner VPS за nginx з SSL, співіснуючи з братнім MCP сервером на тому ж хостингу
Як це працює
1. Орендар надсилає POST запит на /api/register з назвою компанії та електронною поштою, отримує 6-значний OTP
2. Орендар підтверджує через /api/confirm, а потім активує, надаючи облікові дані OAuth ServiceFusion
3. Облікові дані шифруються за допомогою AES-256-GCM і зберігаються в Supabase
4. AI клієнт (Claude, Cursor) викликає /mcp з токеном доступу; проміжне програмне забезпечення ідентифікує орендаря та перевіряє ліміт швидкості
5. При виклику інструменту сервер перевіряє дійсність токена і автоматично оновлює його, якщо він закінчився
6. Структурована відповідь повертається до AI клієнта, а виклик реєструється для аналітики використання
Оператор польового обслуговування, що працює на ServiceFusion, хотів, щоб диспетчери та офісний персонал перестали переходити через меню щоразу, коли їм потрібно перевірити історію роботи клієнта, відкрити оцінки або побачити, який технік призначений на роботу. Команда вже використовувала Claude для інших завдань. Очевидний наступний крок: дозволити Claude спілкуватися безпосередньо з ServiceFusion.
Проблема
ServiceFusion надає REST API, але AI асистенти не можуть викликати його безпосередньо. Протокол контексту моделі (MCP) є новим стандартом для надання AI клієнтам структурованого доступу до зовнішніх інструментів, і жодного MCP сервера для ServiceFusion не існувало. Правильне створення одного означало вирішення трьох проблем одночасно:
Життєвий цикл токена OAuth2. ServiceFusion використовує короткочасні токени доступу, які закінчуються і повинні бути оновлені прозоро, щоб AI ніколи не стикався з помилкою авторизації під час розмови.
Багатокористувацькість. Один екземпляр сервера повинен був ізолювати облікові дані та API виклики для кількох компаній, кожна з яких має свій обліковий запис ServiceFusion.
Самообслуговування при onboarding. Оператор не хотів вручну налаштовувати кожного нового орендаря.
Рішення
Я створив багатокористувацький MCP сервер на Node.js та TypeScript, який знаходиться між AI клієнтами (Claude, Cursor, ChatGPT) та ServiceFusion. Він надає 13 структурованих інструментів, що охоплюють основні сутності, які насправді використовують диспетчери: клієнти, роботи, оцінки, техніки та обладнання.
Сервер обробляє два незалежні шари OAuth2. Один аутентифікує вхідні AI клієнти до MCP сервера. Другий керує власними токенами ServiceFusion сервера, включаючи автоматичне оновлення з блокуванням конкурентності, щоб одночасні запити ніколи не викликали дублювання оновлень.
Всі чутливі облікові дані (ідентифікатори клієнтів, секрети, токени) шифруються в спокої за допомогою AES-256-GCM у Supabase PostgreSQL. Нові орендарі самостійно реєструються через REST API, підтверджують через OTP і надають свої облікові дані ServiceFusion для активації. Жодної ручної роботи оператора при реєстрації.
Легка адміністративна панель дозволяє оператору переглядати використання за орендарем, регулювати ліміти швидкості та активувати або деактивувати облікові записи.
Технічний стек: Node.js 20, TypeScript, @modelcontextprotocol/sdk, Express, Supabase (PostgreSQL), шифрування AES-256-GCM, Zod, Winston, Docker, nginx, Let's Encrypt
Результати
13 MCP інструментів працюють з клієнтами, роботами, оцінками, техніками та обладнанням
Жодної ручної налаштування для орендаря. Процес реєстрації та активації через OTP
Прозорий OAuth2. Токени, що закінчилися, автоматично оновлюються з захистом від гонки
Ліміти швидкості для кожного орендаря (безкоштовні, професійні, корпоративні рівні) забезпечуються на рівні запиту
Повне відстеження використання (назва інструменту, кінцева точка, код статусу, час відповіді) реєструється для кожного орендаря для виставлення рахунків та аналітики
Розгорнуто в продукції на Hetzner VPS за nginx з SSL, співіснуючи з братнім MCP сервером на тому ж хостингу
Як це працює
1. Орендар надсилає POST запит на /api/register з назвою компанії та електронною поштою, отримує 6-значний OTP
2. Орендар підтверджує через /api/confirm, а потім активує, надаючи облікові дані OAuth ServiceFusion
3. Облікові дані шифруються за допомогою AES-256-GCM і зберігаються в Supabase
4. AI клієнт (Claude, Cursor) викликає /mcp з токеном доступу; проміжне програмне забезпечення ідентифікує орендаря та перевіряє ліміт швидкості
5. При виклику інструменту сервер перевіряє дійсність токена і автоматично оновлює його, якщо він закінчився
6. Структурована відповідь повертається до AI клієнта, а виклик реєструється для аналітики використання
Харків 
Вільний для роботи