@mgcrea/mcp-ovh-api

Сервер Model Context Protocol для OVHcloud API, ориентированный на Object Storage: бакеты, объекты, пользователей проекта, S3-учётные данные и политики хранения, которые связывают их воедино.

Сервер по умолчанию работает только на чтение. Изменяющие состояние инструменты не просто отклоняются, когда запись выключена, — они вообще не регистрируются, так что агент не может их вызвать.

Возможности

• Подобранные инструменты для /1.0 API OVHcloud с описаниями, которые явно указывают на его ловушки (см. Ловушки, о которых стоит знать).

• Только чтение по умолчанию. OVH_ALLOW_WRITES=1 добавляет инструменты записи; разрушительные из них дополнительно требуют явного confirm: true при каждом вызове.

• Все три метода аутентификации OVH автоматически выбираются по присутствующим переменным окружения: сервисный аккаунт OAuth2 (рекомендуется), application key + consumer key (подпись SHA1 с автоматической коррекцией смещения часов) или статический токен доступа.

• Пресеты политик — включая write-only, которого нет в быстрых ролях OVH.

• Результаты списков выдаются в сводном виде, а устаревший массив objects[] в расчёте на бакет (который встраивает каждый объект бакета) подавляется на обоих концах.

• X-Ovh-QueryID выводится при каждой ошибке, потому что это первое, о чём спрашивает поддержка OVH.

• Запасной выход ovh_request для остальной части API (только GET, если запись не включена).

• Нативный fetch, без зависимостей времени выполнения, кроме MCP SDK и Zod.

Установка

pnpm install
pnpm build

Настройка

Выберите один метод аутентификации.

(A) Сервисный аккаунт OAuth2 — рекомендуется

1. Создайте сервисный аккаунт IAM на https://www.ovh.com/manager/#/iam/service-account.

2. Прикрепите IAM-политику, предоставляющую ему ваш проект public cloud (для object storage: publicCloudProject:apiovh:* на ресурсе проекта).

3. Скопируйте client id и secret в .env.

Токены действуют час, кэшируются и обновляются до истечения срока действия.

(B) Ключ приложения + потребительский ключ

Создайте тройку одним разом на https://eu.api.ovh.com/createToken/. Указанные там правила доступа зафиксированы навсегда — потребительский ключ впоследствии нельзя расширить, поэтому сразу выдайте всё, что нужно:

GET    /cloud/project/*
POST   /cloud/project/*
PUT    /cloud/project/*
DELETE /cloud/project/*
GET    /me

Запросы подписываются по SHA1 над secret+consumerKey+METHOD+URL+BODY+TIMESTAMP. Если часы расходятся с часами OVH более чем на ~30 секунд, каждый вызов завершается ошибкой с вводящим в заблуждение Invalid signature, поэтому при запуске сервер один раз опрашивает /auth/time и корректирует разницу.

(C) Статический токен доступа

Установите OVH_ACCESS_TOKEN, и он будет отправлен как Authorization: Bearer.

cp .env.example .env

Запуск

pnpm start   # speaks JSON-RPC over stdio

Подключение к Claude Code

Добавьте в .mcp.json (проект) или ~/.claude.json (глобально):

{
  "mcpServers": {
    "ovh": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-ovh-api/dist/cli.js"],
      "env": {
        "OVH_CLIENT_ID": "...",
        "OVH_CLIENT_SECRET": "...",
        "OVH_CLOUD_PROJECT": "abcdef0123456789abcdef0123456789",
        "OVH_REGION": "UK"
      }
    }
  }
}

Просмотр инструментов

npx @modelcontextprotocol/inspector node dist/cli.js

Ловушки, о которых стоит знать

Все они вшиты в описания инструментов, но именно они объясняют устройство этого сервера:

1. В OVH нет политик бакетов — только пользовательские политики. Один «сырой» JSON-документ на каждого пользователя проекта, и этот документ — вся поверхность контроля доступа. Установка политики заменяет всё, что этот пользователь мог делать раньше, во всех бакетах.

2. Политика не может ограничить владельца бакета. OVH откатывается к ACL, и владелец обладает FULL_CONTROL: «если пользователь является владельцем бакета, он будет авторизован, даже если в файле политики нет явного разрешения». Поэтому ограниченный ключ должен принадлежать новому пользователю проекта, который не создавал бакет. ovh_provision_s3_user проверяет ownerId бакета и отказывает, если вы нацелили его на владельца.

3. То же самое касается каждого объекта. Кто загружает объект, тот владеет им и получает FULL_CONTROL через ACL объекта. Поэтому простое отсутствие s3:GetObject не мешает ключу, предназначенному только для загрузки, считывать всё, что он записал, — проверено на живом API: голая политика-разрешение охотно отдавала ключу его собственные загрузки и при этом корректно запрещала все объекты, загруженные кем-то другим. Требуется явный Deny, и он действительно перебивает ACL. Именно поэтому пресет write-only содержит оператор Deny, а не просто список разрешений.

Ещё две, поменьше. Один лишь s3:PutObject по-прежнему разрешает слепую перезапись существующих ключей внутри разрешённого префикса — ключ «write-only» не является ключом «только для добавления», что является веской причиной включить версионирование на бакете. А изменения политики распространяются до ~30 секунд: проверка, выполненная через пять секунд после ovh_set_storage_policy, всё ещё показывает старое поведение, что выглядит в точности как политика, которая молча не сработала.

Инструменты

Каждый инструмент уровня проекта принимает необязательный параметр project, а каждый инструмент хранилища — необязательный region, переопределяя OVH_CLOUD_PROJECT / OVH_REGION в рамках вызова. Инструменты, помеченные W, существуют только при OVH_ALLOW_WRITES=1; помеченные ⚠️ являются разрушительными и дополнительно требуют confirm: true.

Начните с ovh_whoami. Он показывает, какой метод аутентификации активен, под какой учётной записью вы работаете и какая разница часов с OVH — а именно об этом почти всегда говорит 401 при методе подписи.

ovh_presign_object — единственный способ перемещения данных: сервер никогда не проксирует содержимое объектов, а вместо этого выпускает ограниченную по времени предварительно подписанную S3-ссылку. При выключенной записи он подписывает только GET.

Пресеты политик

ovh_preview_policy, ovh_set_storage_policy и ovh_provision_s3_user используют три общих пресета, каждый из которых можно ограничить префиксом ключа:

Встроенные роли OVH (admin, deny, readOnly, readWrite, через ovh_grant_bucket_access) не имеют эквивалента write-only — именно поэтому существует путь через «сырую» политику. Пара multipart включена намеренно: любой S3 SDK автоматически переключается на multipart при размерах выше ~8-16 МБ, а без abort/list неудачная загрузка осиротит части, которые владелец ключа не может удалить и за хранение которых продолжает платить.

OVH проверяет действия политики по фиксированному перечислению и отклоняет весь документ с кодом 400, если какое-то действие неизвестно, — s3:GetObjectVersion и s3:DeleteObjectVersion существуют в AWS, но не здесь. В пресетах используются только принимаемые действия, и тест это закрепляет.

Выдача ключа для загрузки только на запись

Мотивирующий случай: приложение встраивает S3-ключ в поставляемый бинарный файл, поэтому ключ должен уметь только загружать, а ключ чтения/записи остаётся у разработчика.

ovh_get_bucket           bucket=dev-rgis-ar          → note ownerId
ovh_preview_policy       bucket=dev-rgis-ar preset=write-only prefix=uploads/
ovh_provision_s3_user    bucket=dev-rgis-ar preset=write-only prefix=uploads/ \
                         description=ar-app-uploader confirm=true

Это создаёт нового пользователя проекта (никогда не владельца бакета), применяет политику и только затем выпускает учётные данные — ключ, существовавший до своей политики, это ключ, который недолго имел всё, что разрешено по умолчанию. Секрет возвращается только один раз.

Проверьте на реальном S3 API, прежде чем передавать ключ, — политика, которая выглядит корректной, всё ещё может быть перекрыта владельцем, а подождите ~30 секунд после её установки, иначе вы будете проверять предыдущую политику:

export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
# An array, not a string: zsh does not word-split an unquoted $var, so the
# `S3='aws ...'` form you would write in bash silently becomes "command not found".
S3=(aws --endpoint-url https://s3.uk.io.cloud.ovh.net --region uk s3api)
"${S3[@]}" put-object      --bucket dev-rgis-ar --key uploads/probe.txt --body /dev/null   # 200
"${S3[@]}" get-object      --bucket dev-rgis-ar --key uploads/probe.txt /dev/null          # 403
"${S3[@]}" list-objects-v2 --bucket dev-rgis-ar                                            # 403
"${S3[@]}" delete-object   --bucket dev-rgis-ar --key uploads/probe.txt                    # 403
"${S3[@]}" put-object      --bucket dev-rgis-ar --key elsewhere/probe.txt --body /dev/null # 403

Строка get-object — вот что важно: это проверка, которая ловит ловушку № 3, и она проходит только благодаря Deny из пресета.

Разработка

pnpm dev            # tsdown --watch
pnpm test           # vitest
pnpm typecheck
pnpm lint
pnpm format

Лицензия

MIT