# Zenrus MCP Server

[![npm version](https://badge.fury.io/js/zenrus-mcp.svg)](https://www.npmjs.com/package/zenrus-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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