# FineProxy Agent Pack

Версия: 2026-09-22

Используйте этот файл, чтобы проверить возможность переноса существующей интеграции с прокси-провайдером на FineProxy. Файл не содержит API-ключей, данных аккаунта и приватных endpoints.

## Источники актуальных данных

- Интерактивная документация клиентского API: `https://fineproxy.org/account_new/docs`
- Настройка MCP: `https://fineproxy.org/account_new/mcp`
- Актуальная спецификация OpenAPI: скачивается из документации API в кабинете.
- Создание и управление API-ключами: `https://fineproxy.org/account_new/settings`
- MCP endpoint: `https://fineproxy.org/account_new/api/v1/mcp`

Не придумывайте endpoints на основе этого обзора. Пути, схемы, параметры и ответы запросов проверяйте по актуальной спецификации OpenAPI.

## Кратко о платформе

- REST API: OpenAPI 3.1, 49 документированных клиентских операций.
- MCP: 49 инструментов по stateless JSON-RPC 2.0 через Streamable HTTP.
- Авторизация: bearer API-ключи, созданные в кабинете клиента.
- API и MCP используют одинаковые ограниченные разрешения.
- Партнёрская документация API доступна только аккаунтам с активным партнёрским статусом.

## Поддерживаемые процессы

### Покупка и выдача услуг

- Получение списка стран и живых остатков IP.
- Расчёт точной стоимости пакета из нескольких стран без покупки.
- Покупка с баланса кабинета с защитой цены и ключом идемпотентности.

Стандартная последовательность покупки через MCP:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Управление услугами

- Просмотр и управление услугами.
- Продление, приостановка, восстановление и отмена, когда действие поддерживается.
- Включение и отключение автопродления.
- Замена и добавление IP.
- Изменение данных подключения к услуге.
- Просмотр и управление лимитами allowlist.
- Просмотр, покупка и отмена совместимых дополнений.

### Аналитика и диагностика

- Сводка использования и временные ряды.
- Основные направления трафика.
- Категории ошибок.
- Рекомендации по работе услуги.

### Платежи и поддержка

- Просмотр счетов и скачивание PDF.
- Получение списка платёжных шлюзов.
- Создание пополнения кошелька и проверка его статуса.
- Создание, чтение, ответы и закрытие тикетов поддержки.

### Доступ к прокси и аккаунт

- Получение конфигурации ротационных прокси.
- Изменение логина и пароля услуги.
- Управление лимитами соединений для каждого IP в allowlist.
- Просмотр профиля, IP вызывающей стороны и истории входов.
- Настройка вебхуков.

## Разрешения API-ключа

- `customer:read` — чтение данных клиента и аккаунта.
- `customer:write` — изменение данных клиента.
- `wallet:read` — чтение данных кошелька.
- `wallet:deposit` — создание и отслеживание пополнений.
- `wallet:spend` — расходование средств кошелька. Это финансовое разрешение.
- `services:read` — чтение услуг и настроек прокси.
- `services:write` — создание и изменение услуг и дополнений.
- `tickets:read` — чтение тикетов поддержки.
- `tickets:write` — создание, ответы, изменение и закрытие тикетов.
- `catalog:read` — чтение продуктов, опций, стран и остатков.
- `usage:read` — чтение статистики и диагностики.
- `webhooks` — управление подписками на вебхуки.

Начинайте аудит миграции с прав только на чтение. Права на изменение и финансовые операции добавляйте после проверки предложенного плана.

## Защитные механизмы

- Финансовым инструментам требуется `wallet:spend`.
- При покупке передаётся ожидаемая сумма из расчёта. При изменении цены операция отклоняется.
- Необратимые операции требуют явного подтверждения.
- В повторных финансовых запросах используется ключ идемпотентности, поэтому одна операция не оплачивается дважды.
- Живые остатки, возможности тарифа и права аккаунта могут запретить формально корректную операцию.
- MCP FineProxy управляет аккаунтом клиента. Доступ к исходному коду появляется только тогда, когда пользователь отдельно предоставляет репозиторий агенту разработки.

## Шаблон конфигурации MCP

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Храните настоящий ключ в переменной окружения или менеджере секретов. Не сохраняйте его в репозитории вместе с MCP-конфигурацией.

## Проверка совместимости при миграции

Найдите в существующей интеграции:

1. Инициализацию клиента провайдера и все специфичные импорты.
2. Заголовки авторизации, credentials, переменные окружения и хранение секретов.
3. Покупку, продление, отмену услуг и замену IP.
4. Идентификаторы стран и предположения о доступных остатках.
5. Форматы списков прокси, протоколы, порты, логины, пароли и IP allowlisting.
6. Пагинацию и фильтрацию.
7. Повторы, таймауты и идемпотентность.
8. Модели ошибок и обработку rate limits.
9. Статистику использования и диагностику.
10. Платежи, счета и пополнения.
11. Интеграцию с поддержкой.
12. Вебхуки и предположения о payload событий.
13. Тесты, fixtures, mocks и CI-секреты текущего провайдера.

Каждый процесс отнесите к одной из категорий:

- Совместим без изменений.
- Совместим после изменения конфигурации.
- Требует адаптера или преобразования данных.
- Требует другого рабочего процесса.
- Не поддерживается или не подтверждён актуальной документацией.

## Результат аудита

Аудит должен включать:

1. Перечень всех зависимостей от текущего провайдера.
2. Оценку совместимости каждого процесса.
3. Необходимые разрешения FineProxy.
4. Точные файлы и участки кода, которые потребуется изменить.
5. Изменения в авторизации и хранении секретов.
6. Вопросы, для которых нужна актуальная спецификация OpenAPI или подтверждение поддержки.
7. Поэтапный план миграции с откатом.
8. Интеграционные тесты перед переключением.

На первом этапе не изменяйте код.