# Currency MCP Bot (учебный проект)

Простой пример связки **Telegram Bot + публичный API + Docker/PostgreSQL + MCP + Cursor**.

## Схема

```text
Telegram
   ↓
Python Bot
   ↓
API курса валют

Python Bot
   ↓
PostgreSQL
   ↑
   MCP
   ↑
Cursor
```

## Что здесь делает Telegram Bot

Принимает команды `/start`, `/usd`, `/eur`, `/cny` и отвечает курсом валюты к рублю.

## Что здесь делает API

Бот запрашивает актуальный курс у бесплатного публичного API (`open.er-api.com`) — без ключа и без регистрации.

## Что здесь делает Docker

`docker compose` поднимает PostgreSQL в контейнере. Сам бот запускается локально на Python.

## Что здесь делает MCP

MCP-сервер даёт Cursor два инструмента к той же базе:

1. `get_recent_requests` — последние запросы пользователей
2. `get_currency_stats` — сколько раз спрашивали USD / EUR / CNY

## Файлы

| Файл | Назначение |
|------|------------|
| `bot.py` | Telegram-бот (aiogram) |
| `db.py` | PostgreSQL без ORM |
| `mcp_server.py` | MCP-сервер для Cursor |
| `docker-compose.yml` | PostgreSQL в Docker |
| `.cursor/mcp.json` | Подключение MCP в этом проекте |
| `.env` | Секреты и настройки (не в Git) |

## Быстрый старт

### 1. Зависимости Python

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

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

Скопируйте пример и вставьте токен бота:

```powershell
copy .env.example .env
```

В `.env` заполните:

```env
TELEGRAM_BOT_TOKEN=ваш_токен_от_BotFather
```

### 3. PostgreSQL через Docker

```powershell
docker compose up -d
```

Проверка:

```powershell
docker compose ps
```

### 4. Запуск бота

```powershell
python bot.py
```

В Telegram отправьте боту `/start`, затем `/usd`, `/eur`, `/cny`.

### 5. MCP в Cursor

В проекте есть `.cursor/mcp.json`. На Windows сервер также добавлен в пользовательский `~/.cursor/mcp.json`, чтобы он точно появился в списке Connected.

1. Сначала создайте venv и установите зависимости (шаг 1 выше)
2. `Ctrl+Shift+P` → **Developer: Reload Window**
3. Откройте **Settings → MCP**
4. Найдите `currency-bot-db` — статус должен быть зелёным, tools: `get_recent_requests`, `get_currency_stats`

Если сервера нет или статус красный: проверьте PostgreSQL (`docker compose ps`) и что `.venv` установлен.

## Где взять Telegram Bot Token

1. Откройте Telegram и найдите **@BotFather**
2. Отправьте `/newbot`
3. Придумайте имя и username бота
4. BotFather пришлёт токен вида `123456:ABC...`
5. Вставьте его в `.env` как `TELEGRAM_BOT_TOKEN=...`

Токен не коммитьте в Git — файл `.env` уже в `.gitignore`.

## Тестовые запросы к MCP в Cursor

После нескольких команд боту напишите в чат Cursor:

- «Покажи последние запросы пользователей»
- «Какие валюты пользователи запрашивали чаще всего?»
- «Вызови get_recent_requests с limit=5»
- «Вызови get_currency_stats»

Cursor должен использовать MCP-инструменты `get_recent_requests` и `get_currency_stats`.