# Zenrus MCP Server
[](https://www.npmjs.com/package/zenrus-mcp)
[](https://opensource.org/licenses/MIT)
MCP-сервер для получения актуальных курсов валют и цен на нефть с сайта [zenrus.ru](https://zenrus.ru/).
## Возможности
Сервер предоставляет следующие инструменты:
### Базовые инструменты (получение данных)
- `get_usd_rate` - Get current USD/RUB exchange rate
- `get_eur_rate` - Get current EUR/RUB exchange rate
- `get_brent_usd_rate` - Get current Brent crude oil price in USD per barrel
- `get_brent_rub_rate` - Get current Brent crude oil price in RUB per barrel
### Расчетные инструменты (вычисления)
- `calculate_barrels_for_rub` - Calculate how many barrels can be purchased for given amount in RUB
- `calculate_barrels_for_usd` - Calculate how many barrels can be purchased for given amount in USD
- `calculate_barrels_for_eur` - Calculate how many barrels can be purchased for given amount in EUR
### Формат возвращаемых данных
Все инструменты возвращают **структурированные JSON данные** с числовыми значениями, которые могут быть использованы в вычислениях:
**Курсы валют** (`get_usd_rate`, `get_eur_rate`):
```json
{
"rate": 81.08,
"currency": "USD/RUB",
"description": "US Dollar to Russian Ruble exchange rate"
}
```
**Цены на нефть** (`get_brent_usd_rate`, `get_brent_rub_rate`):
```json
{
"price": 62.17,
"commodity": "Brent Crude Oil",
"currency": "USD",
"unit": "per barrel"
}
```
**Расчеты** (`calculate_barrels_for_rub`, `calculate_barrels_for_usd`, `calculate_barrels_for_eur`):
```json
{
"amount": 100000,
"currency": "RUB",
"barrels": 19.8374,
"pricePerBarrel": 5041,
"commodity": "Brent Crude Oil"
}
```
Такой подход позволяет AI-модели:
- Использовать данные в математических вычислениях
- Форматировать вывод по своему усмотрению
- Легко парсить и обрабатывать результаты
- Сохранять семантику данных
### Примеры использования
Для расчетных инструментов передавайте параметр `amount`:
```json
{
"name": "calculate_barrels_for_usd",
"arguments": {
"amount": 1000
}
}
```
Результат покажет, сколько баррелей можно купить:
```json
{
"amount": 1000,
"currency": "USD",
"barrels": 16.0848,
"pricePerBarrel": 62.17,
"commodity": "Brent Crude Oil"
}
```
## Установка
### Из npm (рекомендуется)
Пакет будет автоматически загружен при первом использовании с `npx`:
```bash
npx -y zenrus-mcp
```
### Для разработки
```bash
git clone https://github.com/DarkGenius/zenrus-mcp.git
cd zenrus-mcp
npm install
npm run build
```
## Использование
### Конфигурация
Добавьте следующую конфигурацию в файл настроек ваших AI-инструментов:
```json
{
"mcpServers": {
"zenrus": {
"command": "npx",
"args": ["-y", "zenrus-mcp"]
}
}
}
```
### Запуск сервера вручную
```bash
npm start
```
## Разработка
```bash
# Сборка проекта
npm run build
# Режим разработки с автоматической пересборкой
npm run dev
# Запуск тестов
npm test
# Запуск тестов в watch-режиме
npm run test:watch
# Отладка (выполняет запрос к API и выводит данные)
npm run debug
```
## Отладка
Для проверки работоспособности сервера используйте команду:
```bash
npm run debug
```
Этот скрипт выполнит реальный запрос к zenrus.ru и выведет:
- Полученные данные в JSON формате
- Результаты работы каждого MCP-инструмента
- Статистику выполнения
## Структура проекта
```
zenrus-mcp/
├── src/
│ ├── index.ts # Основной код MCP сервера
│ ├── api.ts # API модуль с кешированием
│ ├── debug.ts # Скрипт для отладки
│ └── __tests__/
│ └── parser.test.ts # Тесты парсинга данных
├── dist/ # Скомпилированные файлы
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md
```
## Как это работает
### Получение данных
Сервер получает данные с zenrus.ru из JavaScript файла `currents.js`, который содержит актуальные курсы в формате:
```javascript
var current = {0:81.08,1:94.15,2:62.17,...}
```
Где:
- `0` - курс USD в рублях
- `1` - курс EUR в рублях
- `2` - цена Brent в долларах
Цена Brent в рублях вычисляется автоматически: `USD * Brent(USD)`
### Кеширование
Данные кешируются на **60 минут** для снижения нагрузки на удаленный API. При каждом запросе:
1. Проверяется наличие и актуальность кешированных данных
2. Если данные устарели (прошло > 60 минут), выполняется новый запрос
3. Новые данные сохраняются в кеш
URL использует Unix timestamp для cache busting: `currents.js?v1234567890`
## Технологии
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - SDK для создания MCP серверов
- TypeScript
- Node.js
## Лицензия
MIT
