VPf08 Forex

Локальный справочный проект по валютным парам Forex:

• MCP сервер (forex-pairs-mcp) — SQLite + HTTP API с MCP JSON Schema
• Telegram бот — aiogram + Ollama qwen3:14b + вызов MCP tools по HTTP

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

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

.
├── 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 с моделью qwen3:14b
• Telegram Bot Token (@BotFather)

Установка

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

# Скопировать переменные окружения
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:

.\.venv\Scripts\Activate.ps1

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

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

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

Запуск

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

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

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 бот

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:

LOG_LEVEL=DEBUG

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

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

Архитектура

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: Финальный ответ

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

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

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

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

После клонирования на другом ПК:

copy .env.example .env
powershell -ExecutionPolicy Bypass -File setup.ps1

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

1. Бот запущен? Нужны два терминала: MCP сервер + python bot.py
2. Доступ к Telegram API? Бот должен подключаться к api.telegram.org:443

   curl https://api.telegram.org/
   

   Если таймаут — включите VPN или укажите прокси в .env:

   TELEGRAM_PROXY=socks5://127.0.0.1:1080
   

3. Первый ответ долгий? Модель qwen3:14b думает 30–120 сек — подождите.
4. Команда /health в боте — проверит MCP сервер.