Zenrus MCP Server

MCP-сервер для получения актуальных курсов валют и цен на нефть с сайта 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):

{
  "rate": 81.08,
  "currency": "USD/RUB",
  "description": "US Dollar to Russian Ruble exchange rate"
}

Цены на нефть (get_brent_usd_rate, get_brent_rub_rate):

{
  "price": 62.17,
  "commodity": "Brent Crude Oil",
  "currency": "USD",
  "unit": "per barrel"
}

Расчеты (calculate_barrels_for_rub, calculate_barrels_for_usd, calculate_barrels_for_eur):

{
  "amount": 100000,
  "currency": "RUB",
  "barrels": 19.8374,
  "pricePerBarrel": 5041,
  "commodity": "Brent Crude Oil"
}

Такой подход позволяет AI-модели:

Использовать данные в математических вычислениях
Форматировать вывод по своему усмотрению
Легко парсить и обрабатывать результаты
Сохранять семантику данных

Примеры использования

Для расчетных инструментов передавайте параметр amount:

{
  "name": "calculate_barrels_for_usd",
  "arguments": {
    "amount": 1000
  }
}

Результат покажет, сколько баррелей можно купить:

{
  "amount": 1000,
  "currency": "USD",
  "barrels": 16.0848,
  "pricePerBarrel": 62.17,
  "commodity": "Brent Crude Oil"
}

Установка

Из npm (рекомендуется)

Пакет будет автоматически загружен при первом использовании с npx:

npx -y zenrus-mcp

Для разработки

git clone https://github.com/DarkGenius/zenrus-mcp.git
cd zenrus-mcp
npm install
npm run build

Использование

Конфигурация

Добавьте следующую конфигурацию в файл настроек ваших AI-инструментов:

{
  "mcpServers": {
    "zenrus": {
      "command": "npx",
      "args": ["-y", "zenrus-mcp"]
    }
  }
}

Запуск сервера вручную

npm start

Разработка

# Сборка проекта
npm run build

# Режим разработки с автоматической пересборкой
npm run dev

# Запуск тестов
npm test

# Запуск тестов в watch-режиме
npm run test:watch

# Отладка (выполняет запрос к API и выводит данные)
npm run debug

Отладка

Для проверки работоспособности сервера используйте команду:

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, который содержит актуальные курсы в формате:

var current = {0:81.08,1:94.15,2:62.17,...}

Где:

0 - курс USD в рублях
1 - курс EUR в рублях
2 - цена Brent в долларах

Цена Brent в рублях вычисляется автоматически: USD * Brent(USD)

Кеширование

Данные кешируются на 60 минут для снижения нагрузки на удаленный API. При каждом запросе:

Проверяется наличие и актуальность кешированных данных
Если данные устарели (прошло > 60 минут), выполняется новый запрос
Новые данные сохраняются в кеш

URL использует Unix timestamp для cache busting: currents.js?v1234567890

Технологии

@modelcontextprotocol/sdk - SDK для создания MCP серверов
TypeScript
Node.js

Лицензия

MIT