Hotline Finance FAQ — MCP Server

MCP сервер для отримання FAQ та глосарію зі страхового сервісу hotline.finance.

Підтримує два режими запуску:

• stdio — для Cursor / Claude Desktop
• HTTP — для ChatGPT та інших клієнтів з підтримкою мережевого MCP

---

Інструменти (Tools)

list_faq_categories

Повертає повний список доступних категорій FAQ з їх slug-назвами (80+ категорій). Параметрів немає. Slug потрібен для виклику get_faq_questions.

get_faq_questions

Отримує питання та відповіді FAQ для вказаної категорії з hotline.finance. У ChatGPT відображає інтерактивний UI-віджет з картками питань.

Параметр	Тип	Опис
category	string (required)	Slug категорії (наприклад: автоцивілка, туристичне-страхування, виїзд-за-кордон)

find_faq ✦ sampling

Приймає довільний текстовий запит українською, автоматично визначає категорію через LLM-класифікацію (createMessage) та повертає відповідні FAQ. Якщо клієнт не підтримує sampling — повертає підказку з доступними категоріями.

Потребує підтримки sampling з боку клієнта (Cursor, Claude Desktop).

Параметр	Тип	Опис
query	string (required)	Довільний текст (наприклад: «де купити страховку в Харкові», «як оформити каско»)

faq_wizard ✦ elicitation

Інтерактивний майстер без аргументів. Показує форму з 10 найпопулярніших видів страхувань через elicitInput, отримує вибір користувача та повертає відповідні FAQ. Якщо клієнт не підтримує elicitation — повертає список slug для ручного виклику.

Потребує підтримки elicitation з боку клієнта.

get_glossary_list

Повертає список усіх термінів страхового глосарію (24 терміни) з їх slug та назвами. Параметрів немає. Slug потрібен для виклику get_glossary_item.

get_glossary_item

Отримує детальний опис терміну страхового глосарію: назву, пояснення та пов'язані питання.

Параметр	Тип	Опис
slug	string (required)	Slug терміну (наприклад: автоцивілка, франшиза, каско)

---

Промпти (Prompts)

Промпти — це готові шаблони розмов, доступні як slash-команди в Cursor і Claude Desktop. Аргументи мають автодоповнення при наборі завдяки completable().

faq-search

Шаблон для пошуку FAQ по категорії страхування. Аргумент category автодоповнюється зі списку 80+ slug.

Аргумент	Тип	Опис
category	string	Slug категорії з автодоповненням по CATEGORY_SLUGS

glossary-explain

Шаблон для пояснення страхового терміну. Аргумент slug автодоповнюється зі списку термінів глосарію.

Аргумент	Тип	Опис
slug	string	Slug терміну з автодоповненням по GLOSSARY_SLUGS

---

Ресурси (Resources)

ui://widget/faq.html

HTML-віджет для відображення FAQ-карток в інтерфейсі ChatGPT (ext-apps). Підключається автоматично при виклику get_faq_questions, find_faq та faq_wizard.

---

Встановлення та запуск

npm install

Режим розробки (tsx)

npm start
# або з HTTP-портом:
PORT=3333 npm start

Продакшн-збірка (TypeScript → JS)

npm run build         # компілює TypeScript у build/
npm run build:start   # компілює та запускає

---

Режим 1 — Cursor / Claude Desktop (stdio)

Додай до конфігу MCP сервера зібраний JS після npm run build:

{
  "mcpServers": {
    "hotline-faq": {
      "command": "node",
      "args": [
        "c:\\Users\\Denys\\Desktop\\WORK\\MCP_FAQ_Server\\build\\index.js"
      ]
    }
  }
}

Cursor: Settings → MCP → Add server

Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

В Cursor і Claude Desktop будуть доступні:

• Промпти faq-search та glossary-explain як slash-команди з автодоповненням
• Інструмент find_faq з LLM-класифікацією (через sampling)
• Інструмент faq_wizard з формою вибору (через elicitation)

---

Режим 2 — ChatGPT / HTTP-клієнти

HTTP-сервер підтримує два протоколи одночасно:

• Streamable HTTP (MCP 2025-06-18) — основний протокол
• Legacy SSE (MCP 2024-11-05) — зворотна сумісність

MCP endpoint: POST /mcp

Локальна розробка з ngrok

# Термінал 1 — запуск сервера
PORT=3333 npm start

# Термінал 2 — публічний тунель
ngrok http 3333

Скопіюй URL з ngrok (наприклад https://abc123.ngrok.app) і в ChatGPT:

• Натисни + → Add connector → вставити https://abc123.ngrok.app/mcp

В ChatGPT доступні всі інструменти. Промпти та sampling/elicitation залежать від підтримки клієнта.

---

Структура проекту

MCP_FAQ_Server/
├── package.json
├── tsconfig.json
├── public/
│   └── faq-widget.html           ← HTML-віджет (iframe в ChatGPT)
└── src/
    ├── index.ts                   ← Точка входу (вибір транспорту)
    ├── server.ts                  ← Створення MCP сервера, реєстрація інструментів
    ├── config.ts                  ← Категорії FAQ, терміни глосарію, константи
    ├── types.ts                   ← TypeScript типи
    ├── api/
    │   ├── faq.ts                 ← Запити до hotline.finance/api/faq-questions
    │   └── glossary.ts            ← Запити до hotline.finance/api/glossary
    ├── prompts/
    │   ├── faq-search.ts          ← Промпт faq-search + completable(CATEGORY_SLUGS)
    │   └── glossary-explain.ts    ← Промпт glossary-explain + completable(GLOSSARY_SLUGS)
    ├── tools/
    │   ├── list-categories.ts     ← Інструмент list_faq_categories
    │   ├── get-faq-questions.ts   ← Інструмент get_faq_questions
    │   ├── get-glossary-list.ts   ← Інструмент get_glossary_list
    │   ├── get-glossary-item.ts   ← Інструмент get_glossary_item
    │   ├── find-faq.ts            ← Інструмент find_faq (createMessage / sampling)
    │   └── faq-wizard.ts          ← Інструмент faq_wizard (elicitInput / elicitation)
    ├── resources/
    │   └── faq-widget.ts          ← Ресурс ui://widget/faq.html
    ├── transports/
    │   ├── http.ts                ← HTTP-транспорт (Streamable + SSE)
    │   └── stdio.ts               ← stdio-транспорт
    └── utils/
        ├── categories.ts          ← Пошук категорії за slug
        ├── glossary.ts            ← Пошук терміну за slug
        └── html.ts                ← Очищення HTML-тегів з відповідей

---

Категорії FAQ

Повний список доступний через інструмент list_faq_categories. Деякі з них:

Slug	Назва
автоцивілка	Автоцивілка
туристичне-страхування	Туристичне страхування
каско	КАСКО
зелена-картка	Зелена картка
страхування-житла	Страхування житла
виїзд-за-кордон	Страховка для виїзду за кордон
обліковий-запис	Питання Підтримка з облікового запису
загальні	Загальні питання
мінікаско	МініКАСКО
бонуси	Бонуси
штрафи	Штрафи
реферальна-програма	Реферальна програма

Щоб додати нові категорії — оновіть масив CATEGORIES у src/config.ts.

---

Терміни глосарію

Повний список доступний через інструмент get_glossary_list. Деякі з них:

Slug	Назва
автоцивілка	Автоцивілка (ОСЦПВ)
зелена-картка	Зелена картка
каско	КАСКО
франшиза	Франшиза
страховка	Страховка (страховий поліс, договір страхування)
страховий-випадок	Страховий випадок
страхова-сума	Страхова сума
туристичне-страхування	Туристичне Страхування

Щоб додати нові терміни — оновіть масив GLOSSARY_ENTRIES у src/config.ts.

---

Стек

• TypeScript + tsx (dev runner)
• @modelcontextprotocol/sdk — MCP протокол (Tools, Prompts, Resources, sampling, elicitation)
• @modelcontextprotocol/ext-apps — підтримка UI-ресурсів (ChatGPT ext-apps)
• zod + completable() — валідація та автодоповнення аргументів промптів
• Вбудований node:http — HTTP-сервер без зовнішніх фреймворків