# Hotline Finance FAQ — MCP Server

MCP сервер для отримання FAQ та глосарію зі страхового сервісу [hotline.finance](https://hotline.finance/ua/).

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

- **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`.

---

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

```bash
npm install
```

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

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

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

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

---

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

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

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

```bash
# Термінал 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-сервер без зовнішніх фреймворків