# Forex Pairs MCP + Telegram Bot + Ollama

Локальный справочный проект по валютным парам Forex:
- **MCP сервер** (`forex-pairs-mcp`) — SQLite + HTTP API с MCP JSON Schema
- **Telegram бот** — aiogram + Ollama `qwen3:14b` + вызов MCP tools по HTTP

> ⚠️ Учебный справочник. Не подключается к брокерам и не даёт инвестиционных рекомендаций.

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

```text
.
├── mcp_server/
│   ├── server.py          # FastAPI HTTP сервер
│   ├── db.py              # SQLite + 100 тестовых пар
│   ├── tools.py           # MCP инструменты + безопасный калькулятор
│   ├── requirements.txt
│   └── currency_pairs.db  # создаётся автоматически
├── telegram_bot/
│   ├── bot.py             # Telegram бот (aiogram 3)
│   ├── config.py          # Настройки из .env
│   ├── llm_client.py      # Ollama /api/chat + JSON parsing
│   ├── mcp_client.py      # HTTP клиент MCP сервера
│   └── requirements.txt
├── .env.example
├── README.md
└── scripts/
    └── verify.py          # Локальная самопроверка
```

## Требования

- Python 3.12+
- [Ollama](https://ollama.com/) с моделью `qwen3:14b`
- Telegram Bot Token ([@BotFather](https://t.me/BotFather))

## Установка

### 1. Виртуальное окружение (рекомендуется)

```powershell
# Скопировать переменные окружения
copy .env.example .env
# Заполнить TELEGRAM_API_TOKEN в .env

# Создать .venv, установить зависимости и активировать
powershell -ExecutionPolicy Bypass -File setup.ps1
```

В **Cursor / VS Code** окружение активируется автоматически в новых терминалах
(настроено в `.vscode/settings.json` → `python.terminal.activateEnvironment`).

Ручная активация в PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
```

### 2. Установка без скрипта (альтернатива)

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
$env:PIP_NO_PROXY="*"
pip install -r requirements.txt
```

> **Windows / SOCKS proxy:** если `pip` выдаёт `Missing dependencies for SOCKS support`, используйте `$env:PIP_NO_PROXY="*"` перед установкой.

### 4. Установить и запустить Ollama

```bash
# Установить Ollama: https://ollama.com/download
ollama pull qwen3:14b
ollama serve   # если не запущен автоматически
```

## Запуск

Откройте **два терминала**:

### Терминал 1 — MCP сервер

```bash
cd mcp_server
python server.py
```

Сервер будет доступен на `http://localhost:8000`

- `GET /health` — проверка здоровья
- `GET /tools` — список MCP инструментов (JSON Schema)
- `POST /tools/list_currency_pairs`
- `POST /tools/find_currency_pair`
- `POST /tools/add_currency_pair`
- `POST /tools/calculate`
- `POST /call/{tool_name}` — универсальный вызов

### Терминал 2 — Telegram бот

```bash
cd telegram_bot
python bot.py
```

## MCP инструменты

| Инструмент | Описание |
|---|---|
| `list_currency_pairs` | Список пар, опционально `category`: major/minor/exotic |
| `find_pairs_by_category` | Поиск по категории (мажорные / minor / exotic) — из `F_prompt.md` |
| `find_currency_pair` | Поиск по symbol, base или quote (EUR/USD, EURUSD, JPY) |
| `find_currency_pair_by_id` | Поиск одной пары по числовому `id` |
| `add_currency_pair` | Добавить новую пару |
| `calculate` | Безопасный калькулятор (AST, без `eval`) |
| `get_pairs_by_popularity` | Топ-N / фильтр по уровню востребованности (very_high → low) |
| `get_exchange_rate` | Справочный курс пары (open.er-api.com, без API-ключа) |

Промпт бота загружается из **`F_prompt.md`** в корне проекта.

## Логирование

Логи пишутся в **консоль** и в файлы `logs/forex-pairs-mcp.log`, `logs/forex-bot.log`.

| Переменная | Описание | По умолчанию |
|---|---|---|
| `LOG_LEVEL` | DEBUG, INFO, WARNING, ERROR | `INFO` |
| `LOG_DIR` | Каталог логов | `logs` |
| `LOG_TO_FILE` | Писать в файл (true/false) | `true` |

Для подробной отладки в `.env`:
```env
LOG_LEVEL=DEBUG
```

## Примеры запросов боту

- «покажи все валютные пары»
- «покажи только major пары»
- «найди EUR/USD»
- «найди пары с JPY»
- «добавь валютную пару USD/TRY exotic доллар к турецкой лире»
- «посчитай 25 * (7 + 3)»
- «покажи top 10 валютных пар по востребованности»
- «курс EUR/USD»

## Архитектура

```mermaid
sequenceDiagram
    participant User as Telegram User
    participant Bot as Telegram Bot
    participant Ollama as Ollama qwen3:14b
    participant MCP as forex-pairs-mcp

    User->>Bot: Сообщение
    Bot->>Ollama: /api/chat (JSON decision)
    Ollama-->>Bot: need_tool + tool_name + arguments
    alt need_tool=true
        Bot->>MCP: POST /call/{tool}
        MCP-->>Bot: tool result
        Bot->>Ollama: format final answer
        Ollama-->>Bot: текст ответа
    end
    Bot-->>User: Финальный ответ
```

## Локальная проверка

```bash
python scripts/verify.py
```

## Переменные окружения

| Переменная | Описание | По умолчанию |
|---|---|---|
| `TELEGRAM_API_TOKEN` | Токен Telegram бота | — (обязательно) |
| `TELEGRAM_PROXY` | Прокси для Telegram API | — (опционально) |
| `OLLAMA_BASE_URL` | URL Ollama API | `http://localhost:11434` |
| `OLLAMA_MODEL` | Модель Ollama | `qwen3:14b` |
| `MCP_SERVER_URL` | URL MCP сервера | `http://localhost:8000` |
| `HTTP_TIMEOUT` | Таймаут HTTP (сек) | `60` |
| `OLLAMA_TIMEOUT` | Таймаут Ollama (сек) | `180` |
| `RATES_API_URL` | API справочных курсов (MCP) | `https://open.er-api.com/v6/latest` |

## Публикация на GitHub

```powershell
# Из корня проекта (после git init и первого коммита)
git branch -M main
gh repo create VPf08-MCP-Forex --public --source=. --remote=origin --push
```

**Не коммитится** (см. `.gitignore`): `.env`, `.venv/`, `logs/`, `*.db`.

После клонирования на другом ПК:
```powershell
copy .env.example .env
powershell -ExecutionPolicy Bypass -File setup.ps1
```

## Бот не отвечает — что проверить

1. **Бот запущен?** Нужны **два** терминала: MCP сервер + `python bot.py`
2. **Доступ к Telegram API?** Бот должен подключаться к `api.telegram.org:443`
   ```powershell
   curl https://api.telegram.org/
   ```
   Если таймаут — включите **VPN** или укажите прокси в `.env`:
   ```env
   TELEGRAM_PROXY=socks5://127.0.0.1:1080
   ```
3. **Первый ответ долгий?** Модель `qwen3:14b` думает 30–120 сек — подождите.
4. **Команда `/health`** в боте — проверит MCP сервер.