timeweb-mcp

v0.1.8

Published

2 days ago

MCP-сервер для управления инфраструктурой Timeweb Cloud

0High
0Medium
0Low

ichinya

mcp timeweb timeweb-cloud cloud infrastructure model-context-protocol

Timeweb Cloud MCP Server

MCP-сервер для управления инфраструктурой Timeweb Cloud из Cursor, VS Code и других клиентов, поддерживающих Model Context Protocol.

Сервер работает через stdio, принимает вызовы MCP-инструментов и выполняет соответствующие запросы к API Timeweb Cloud.

[!WARNING] Проект находится в активной экспериментальной разработке и развивается независимо от Timeweb Cloud. Некоторые возможности API могут быть реализованы не полностью или меняться между версиями.

Возможности

Текущая сборка регистрирует:

| Возможность MCP | Количество | | --------------- | ---------: | | Инструменты | 245 | | Ресурсы | 6 | | Промпты | 2 |

Инструменты охватывают основные операции со следующими сервисами:

приложения App Platform и VCS-провайдеры;
облачные и выделенные серверы, диски, резервные копии и образы;
проекты, VPC, плавающие IP, сетевые диски и Firewall;
Kubernetes, балансировщики и реестры контейнеров;
базы данных;
S3-хранилища;
домены, DNS и почта;
SSH-ключи и API-ключи;
AI-агенты;
аккаунт, платежная информация, тарифы и локации.

Доступные MCP-ресурсы:

allowed_presets;
vcs_providers;
vcs_provider_repositories;
deploy_settings;
database_presets;
get_vpcs.

Доступные промпты:

create_app_prompt;
add_vcs_provider_prompt.

Полный список фактически зарегистрированных инструментов находится в src/tools/index.ts.

[!NOTE] Официальная OpenAPI-спецификация содержит 341 операцию в 23 группах. Это не означает, что каждая операция уже представлена отдельным MCP-инструментом.

Требования

Node.js 20 или новее;
npm;
MCP-клиент с поддержкой локальных stdio-серверов;
API-токен Timeweb Cloud.

Получение API-токена

Создайте токен в панели Timeweb Cloud в разделе «API и Terraform». Официальная инструкция: Токены API и Terraform.

Проект ожидает токен в переменной окружения:

TIMEWEB_TOKEN

Не путайте её с TIMEWEB_CLOUD_TOKEN, которая используется в некоторых других инструментах Timeweb Cloud.

По возможности выпускайте токен с ограниченными правами и сроком действия. Не сохраняйте настоящий токен в Git.

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

Пакет не требует глобальной установки:

npx -y timeweb-mcp

Обычно сервер запускает MCP-клиент, передавая TIMEWEB_TOKEN через свою конфигурацию.

Подключение MCP-клиента

Cursor

Добавьте сервер в .cursor/mcp.json:

{
  "mcpServers": {
    "timeweb-cloud": {
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "your-timeweb-token"
      }
    }
  }
}

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

VS Code

VS Code хранит конфигурацию рабочего пространства в .vscode/mcp.json. Токен можно запрашивать через защищённое поле ввода:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "timeweb-token",
      "description": "Timeweb Cloud API token",
      "password": true
    }
  ],
  "servers": {
    "timeweb-cloud": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "${input:timeweb-token}"
      }
    }
  }
}

Управлять сервером можно через команды MCP: List Servers и MCP: Open Workspace Folder MCP Configuration.

Другие MCP-клиенты

Для клиентов, использующих формат mcpServers, базовая конфигурация выглядит так:

{
  "mcpServers": {
    "timeweb-cloud": {
      "command": "npx",
      "args": ["-y", "timeweb-mcp"],
      "env": {
        "TIMEWEB_TOKEN": "your-timeweb-token"
      }
    }
  }
}

Название корневого поля и способ безопасного хранения секретов зависят от конкретного MCP-клиента.

Локальная разработка

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/ichinya/timeweb-mcp.git
cd timeweb-mcp
npm ci

Создайте локальный файл .env:

TIMEWEB_TOKEN=your-timeweb-token

Проверьте типы и соберите сервер:

npm run type-check
npm run build

Запустите локальную сборку:

npm run start

MCP Inspector

MCP Inspector позволяет просматривать инструменты, ресурсы и промпты, а также выполнять тестовые вызовы:

npm run inspect

Перед запуском добавьте TIMEWEB_TOKEN в .env.

Команды разработки

| Команда | Назначение | Совместимость | | --------------------------- | ---------------------------------------------------------------------- | --------------------- | | npm run type-check | Проверка TypeScript без генерации файлов | Windows, macOS, Linux | | npm run build | Сборка проекта | Windows, macOS, Linux | | npm run test:release | Проверка логики определения новой версии и релизного тега | Windows, macOS, Linux | | npm run smoke | Проверка запуска собранного MCP-сервера и чистоты stdout | Windows, macOS, Linux | | npm run verify | Полная проверка OpenAPI, релизной логики, TypeScript, сборки и запуска | Windows, macOS, Linux | | npm run start | Запуск dist/index.js с загрузкой .env | Windows, macOS, Linux | | npm run inspect | Запуск MCP Inspector | Windows, macOS, Linux | | npm run clean | Удаление dist | Windows, macOS, Linux | | npm run normalize:openapi | Нормализация конфликтующих имён схем | Windows, macOS, Linux | | npm run validate:openapi | Проверка локальной OpenAPI-спецификации | Windows, macOS, Linux |

Выпуск новой версии

Пакет публикуется автоматически из GitHub Actions через npm Trusted Publishing. Постоянный NPM_TOKEN в репозитории не используется.

Обновите версию одновременно в package.json и package-lock.json:
```
npm version patch --no-git-tag-version
```
Вместо patch можно использовать minor, major или указать точную версию.
Закоммитьте и отправьте изменения в main.
Workflow .github/workflows/publish.yml сравнит новую версию с версией предыдущего коммита.
Если версия увеличилась, workflow проверит проект, создаст тег vX.Y.Z, опубликует пакет с той же версией в npm и создаст GitHub Release.

Создавать тег или GitHub Release вручную не нужно. Изменение других полей package.json без повышения версии не запускает выпуск. Понижение версии считается ошибкой.

Trusted Publisher в настройках npm должен быть связан со следующими значениями:

GitHub user: ichinya;
repository: timeweb-mcp;
workflow filename: publish.yml;
allowed action: npm publish;
environment: не задан.

Публикация выполняется на GitHub-hosted runner через OIDC и автоматически получает npm provenance.

OpenAPI-спецификация

Официальные источники:

Локальная копия находится в specs/openapi.json.

Текущая спецификация содержит:

OpenAPI 3.0.0;
212 путей;
341 операцию;
23 группы;
283 схемы компонентов.

Обновление спецификации

PowerShell:

Invoke-WebRequest `
  -Uri "https://timeweb.cloud/api-docs-data/bundle.json" `
  -OutFile "specs/openapi.json"

npm run normalize:openapi
npm run validate:openapi

macOS или Linux:

curl -fsSL \
  https://timeweb.cloud/api-docs-data/bundle.json \
  -o specs/openapi.json

npm run normalize:openapi
npm run validate:openapi

Нормализация переименовывает только конфликтующие ключи в components.schemas и соответствующие внутренние $ref:

| Официальное имя | Локальное имя | | ------------------------ | ------------------------- | | meta | CollectionMeta | | Meta | RequiredCollectionMeta | | location | ServiceLocation | | Location | ImageLocation | | autoreply-is-enabled | MailV2AutoReplyEnabled | | autoreply-is-disabled | MailV2AutoReplyDisabled | | auto-reply-is-enabled | MailV1AutoReplyEnabled | | auto-reply-is-disabled | MailV1AutoReplyDisabled |

Это устраняет коллизии имён файлов и TypeScript-моделей на файловых системах без учёта регистра. Названия полей запросов и ответов, пути API и wire-формат данных не изменяются.

Скрипт проверки контролирует:

версию OpenAPI;
наличие и уникальность operationId;
разрешение внутренних $ref;
отсутствие коллизий генерируемых TypeScript-имён моделей.

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

src/
  actions/      вызовы API и прикладные операции
  api/          клиенты сервисов Timeweb Cloud
  prompts/      MCP-промпты
  resources/    MCP-ресурсы
  tools/        определения и схемы MCP-инструментов
  types/        типы и DTO
scripts/
  normalize-openapi.mjs
  validate-openapi.mjs
specs/
  openapi.json

API-клиенты в src/api поддерживаются вручную. Код сервера пока не генерируется автоматически из specs/openapi.json.

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

Инструменты выполняют операции над реальной инфраструктурой и могут создавать платные ресурсы, менять конфигурацию или удалять данные.

Проверяйте имя инструмента и все аргументы перед подтверждением вызова.
Используйте отдельный API-токен с минимально необходимыми правами.
Не передавайте токен в сообщения модели и не сохраняйте его в Git.
Сначала проверяйте опасные сценарии на тестовых ресурсах.
Не полагайтесь только на MCP-аннотации: сейчас инструменты регистрируются с одинаковыми подсказками и не всегда корректно обозначают операции удаления или изменения данных.

Локальные MCP-серверы выполняются на машине пользователя с правами запустившего их процесса. Подключайте только доверенный код и проверяйте изменения перед обновлением.

Известные ограничения

Проект находится в экспериментальном состоянии.
MCP-покрытие не равно полному покрытию официальной OpenAPI-спецификации.
API-клиенты и DTO поддерживаются вручную и могут отставать от API.
Автоматические тесты и отдельный CI-workflow пока не настроены; GitHub Actions используется только для публикации релизов в npm.

Ссылки

Репозиторий: ichinya/timeweb-mcp
npm: timeweb-mcp
Официальная документация Timeweb Cloud: timeweb.cloud/docs
Официальная документация API: timeweb.cloud/api-docs

Лицензия

В package.json указано UNLICENSED, отдельный файл лицензии отсутствует. Не предполагайте разрешение на распространение или повторное лицензирование кода без согласования с правообладателем.