Selectel Billing Server

MVP MCP-сервера для получения балансов Selectel через сервисного пользователя.

Возможности

• Подключение аккаунта Selectel один раз через .env, REST API или MCP tool
• Автоматическое обновление токена Selectel (24 часа) без участия пользователя
• MCP tools connect_selectel_account, get_balance и get_balance_prediction
• Audit log всех вызовов MCP tools

Стек

• Python 3.12+
• FastAPI
• PostgreSQL
• SQLAlchemy 2.x
• Alembic
• Pydantic Settings
• httpx
• MCP (Streamable HTTP transport)
• Docker / Docker Compose

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

app/
├── main.py                 # FastAPI + MCP mount
├── mcp_stdio.py            # Stdio entry point для Hermes Agent
├── config.py               # Настройки из env
├── db.py                   # SQLAlchemy engine/session
├── models.py               # ORM-модели
├── schemas.py              # Pydantic-схемы API
├── selectel_client.py      # Клиент Selectel API
├── mcp_tools.py            # MCP tools
├── api/
│   └── users.py            # REST API подключения аккаунта
├── services/
│   ├── balance_formatter.py
│   └── credentials_service.py
└── tests/
    └── test_balance_formatter.py

alembic/                    # Миграции БД
Dockerfile
docker-compose.yml
requirements.txt

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

1. Создайте .env

cp .env.example .env

Заполните учётные данные Selectel (один раз):

DEFAULT_USER_ID=default
SELECTEL_ACCOUNT_ID=12345
SELECTEL_SERVICE_USER_NAME=svc-user
SELECTEL_SERVICE_USER_PASSWORD=your-password

При старте сервис сохранит их в БД. Дальше авторизация и обновление токена выполняются автоматически.

2. Запуск через Docker Compose

docker compose up --build

Сервисы:

• app — http://localhost:8000
• postgres — localhost:5432

Миграции применяются автоматически при старте контейнера app.

3. Локальный запуск (без Docker)

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# PostgreSQL должен быть доступен
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/selectel_mcp

alembic upgrade head
uvicorn app.main:app --reload

Одноразовая настройка и автоматическая авторизация

Вы передаёте account_id, service_user_name и service_user_password один раз. Сервер:

1. Сохраняет credentials в PostgreSQL
2. Получает токен Selectel (живёт ~24 часа)
3. Кеширует токен в БД
4. Автоматически обновляет токен по логину/паролю из БД, когда он истекает
5. При 401 сбрасывает токен и запрашивает новый без вашего участия

Способ 1: через .env (рекомендуется для одного аккаунта)

DEFAULT_USER_ID=default
SELECTEL_ACCOUNT_ID=12345
SELECTEL_SERVICE_USER_NAME=svc-user
SELECTEL_SERVICE_USER_PASSWORD=your-password

Способ 2: через MCP tool connect_selectel_account

{
  "account_id": "12345",
  "service_user_name": "svc-user",
  "service_user_password": "your-password"
}

user_id опционален, если задан DEFAULT_USER_ID в .env.

Способ 3: через REST API

curl -X POST http://localhost:8000/users/demo-user/selectel-credentials \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "12345",
    "service_user_name": "svc-user",
    "service_user_password": "password"
  }'

После любого из способов достаточно вызывать get_balance — без повторной передачи пароля.

Подключение пользователя (REST API)

curl -X POST http://localhost:8000/users/demo-user/selectel-credentials \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "12345",
    "service_user_name": "svc-user",
    "service_user_password": "password"
  }'

Логика endpoint:

1. Получает токен Selectel по логину и паролю сервисного пользователя
2. Выполняет тестовый запрос баланса
3. При успехе сохраняет credentials в БД

Возможные ошибки:

• 400 — неверный логин или пароль
• 403 — нет доступа к балансу
• 502 — проблемы с Selectel API

Подключение в Cursor

1. Запустите сервис: docker compose up --build
2. Настройте credentials в .env или вызовите connect_selectel_account один раз
3. В проекте уже есть .cursor/mcp.json:

{
  "mcpServers": {
    "selectel": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

4. Откройте этот проект в Cursor (или добавьте блок selectel в ~/.cursor/mcp.json для всех проектов)
5. Cursor Settings → Tools & MCP — убедитесь, что сервер selectel в статусе connected (зелёный)
6. Если не подключается — перезапустите Cursor и проверьте curl http://localhost:8000/health

В чате можно спросить: «Проверь мой баланс в Selectel» — агент вызовет get_balance без передачи пароля.

Нужен Cursor 0.48+ (поддержка Streamable HTTP).

Подключение в Hermes Agent

Hermes удобнее подключается через stdio — агент сам запускает MCP-процесс, без Docker и PostgreSQL.

Вариант 1: stdio (рекомендуется)

git clone https://github.com/EduardGuselnikov/mcp_selectel_billing.git
cd mcp_selectel_billing
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Добавьте в ~/.hermes/config.yaml:

mcp_servers:
  selectel:
    command: "/absolute/path/to/mcp_selectel_billing/.venv/bin/python"
    args: ["-m", "app.mcp_stdio"]
    env:
      DATABASE_URL: "sqlite:////Users/you/.hermes/selectel-mcp.db"
      DEFAULT_USER_ID: "default"
      SELECTEL_ACCOUNT_ID: "12345"
      SELECTEL_SERVICE_USER_NAME: "svc-user"
      SELECTEL_SERVICE_USER_PASSWORD: "your-password"
    tools:
      resources: false
      prompts: false

Или через CLI:

hermes mcp add selectel \
  --command /absolute/path/to/mcp_selectel_billing/.venv/bin/python \
  --args -m app.mcp_stdio \
  --env DATABASE_URL=sqlite:////Users/you/.hermes/selectel-mcp.db \
  --env DEFAULT_USER_ID=default \
  --env SELECTEL_ACCOUNT_ID=12345 \
  --env SELECTEL_SERVICE_USER_NAME=svc-user \
  --env SELECTEL_SERVICE_USER_PASSWORD=your-password

Проверка:

hermes mcp test selectel
hermes mcp list

В чате Hermes: «Проверь мой баланс в Selectel».

Готовый манифест для каталога Hermes: hermes/manifest.yaml. Примеры конфигурации: hermes/config.example.yaml.

Вариант 2: HTTP (если уже запущен Docker)

mcp_servers:
  selectel:
    url: "http://localhost:8000/mcp"

Перед использованием: docker compose up --build и credentials в .env.

MCP tools

MCP endpoint: http://localhost:8000/mcp

Открытие /mcp в браузере может не показать страницу — это нормально, MCP работает через POST (JSON-RPC), а не через обычный GET.

connect_selectel_account (один раз)

{
  "account_id": "12345",
  "service_user_name": "svc-user",
  "service_user_password": "password"
}

get_balance

{}

или с явным user_id:

{
  "user_id": "demo-user"
}

Если задан DEFAULT_USER_ID в .env, user_id можно не передавать.

get_balance_prediction

Оценка, на сколько хватит текущего баланса (в часах по категориям услуг). API: GET /v2/billing/prediction (документация Selectel).

{}

Пример ответа:

Прогноз: на сколько хватит текущего баланса при текущем потреблении.

• Облачные серверы и основные услуги: 4 дн. 4 ч.
• Объектное хранилище: средств недостаточно
• VMware: 1 дн.
• VPC: 5 ч.

Возвращает человекочитаемый текст с балансами по agreement_id.

Пример ответа:

На аккаунте Selectel найдены балансы в валюте RUB.

ID договора: 263632, тип биллинга: primary

• Бонусный баланс: 36 614,64 ₽
• VK-баланс: 0 ₽
• Основной баланс: 5,14 ₽

Сумма балансов: 36 619,78 ₽
Задолженность: 0 ₽
Итоговый доступный баланс: 36 619,78 ₽

Режим оплаты: prepay

Health check

curl http://localhost:8000/health

Тесты

pytest

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

Переменная	Описание
DATABASE_URL	URL PostgreSQL
DEFAULT_USER_ID	Пользователь по умолчанию для get_balance
SELECTEL_ACCOUNT_ID	ID аккаунта Selectel (одноразовая настройка через .env)
SELECTEL_SERVICE_USER_NAME	Логин сервисного пользователя
SELECTEL_SERVICE_USER_PASSWORD	Пароль сервисного пользователя
SELECTEL_IDENTITY_URL	URL авторизации Selectel
SELECTEL_BALANCES_URL	URL API балансов
SELECTEL_BALANCE_PREDICTION_URL	URL API прогноза баланса
HTTP_TIMEOUT_SECONDS	Таймаут HTTP-запросов

Безопасность

• Авторизация в Selectel выполняется по логину и паролю сервисного пользователя
• Пароли и токены не логируются
• API не возвращает пароль и токен

Управление токенами Selectel

• Токен Selectel живёт ~24 часа — это ограничение API Selectel, не MCP-сервера
• Сервер кеширует токен в БД и обновляет его автоматически по сохранённому паролю
• Срок кеша: now() + 23 hours (запас 1 час до обновления)
• При 401 Unauthorized токен сбрасывается и запрос повторяется автоматически
• Пользователю не нужно повторно передавать credentials после первоначальной настройки

Дальнейшее расширение

Архитектура готова к добавлению:

• услуг
• счетов
• расходов
• отчётов
• аналитики