Hotline Finance FAQ MCP Server

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-сервер без зовнішніх фреймворків