feat: full Cloud API coverage — 246 tools across 23 resource groups (supersedes #3)#4
Open
artgas1 wants to merge 1 commit into
Open
feat: full Cloud API coverage — 246 tools across 23 resource groups (supersedes #3)#4artgas1 wants to merge 1 commit into
artgas1 wants to merge 1 commit into
Conversation
* feat: add Cloud API tools for Servers + Account Adds 11 new MCP tools covering VPS lifecycle and account finances: Servers: - list_servers, get_server - start_server, shutdown_server, reboot_server - get_server_logs - list_server_disk_backups, create_server_disk_backup, delete_server_disk_backup Account: - get_account_finances, get_account_status Follows existing code structure (api/ -> actions/ -> tools/). Reuses BaseApiClient and TIMEWEB_TOKEN env var. Tool descriptions hand-polished with context on when and how to use each. Smoke-tested against live account: all 11 tools registered, read-only endpoints return expected payloads. Relates to upstream issue timeweb-cloud#2 (proposal for Cloud API extension). * feat: add follow-up tools (resize, hard variants, clone, disks, services cost) Extends the MVP with 6 additional tools: Servers: - resize_server — change preset or custom configurator (cpu/ram/disk/gpu) - hard_reboot_server, hard_shutdown_server — force power operations - clone_server — create full VPS copy - list_server_disks — get disk IDs (required for disk backup tools) Account: - get_account_services_cost — per-service cost breakdown (VPS, DB, S3, etc.) Also adds a `prepare` script to package.json so the package can be installed and run directly from GitHub (e.g., `npx github:org/repo#branch`) without needing a pre-built dist/ in the repo or an npm publish. Smoke-tested: all 17 new tools register via tools/list, list_server_disks and get_account_services_cost return expected payloads from a real account. * feat: add server catalogs (presets/os/configurator/software/locations) * feat: add ssh-keys tools - list_ssh_keys - create_ssh_key - get_ssh_key - update_ssh_key - delete_ssh_key - add_ssh_keys_to_server - remove_ssh_key_from_server * feat: add network-drives tools - list_network_drives - get_network_drive - create_network_drive - update_network_drive - delete_network_drive - mount_network_drive - unmount_network_drive - list_network_drive_available_resources - list_network_drive_presets * feat: add projects tools - list_projects, get_project, create_project, update_project, delete_project - list_project_resources (aggregate) - list_project_{balancers,buckets,clusters,servers,databases,dedicated} - add_{balancer,bucket,cluster,server,database,dedicated}_to_project - list_all_project_{balancers,servers,buckets,clusters,databases,dedicated} - transfer_project_resource * feat: add images-snapshots tools * feat: add load-balancers tools - list_balancers - get_balancer - create_balancer - update_balancer - delete_balancer (with 2FA hash/code support) - list_balancer_ips - add_balancer_ips - remove_balancer_ips - list_balancer_rules - create_balancer_rule - update_balancer_rule - delete_balancer_rule - list_balancer_presets * feat: add mail tools Implements Timeweb Cloud Почта (Mail) endpoints as MCP tools. Prefers API v2 where available; falls back to v1 for endpoints unique to that version (list-by-domain, delete, domain info). Tools added (14): - list_mailboxes (v2), list_mailboxes_v1, list_mailboxes_by_domain (v1) - get_mailbox (v2), get_mailbox_v1 - create_mailbox (v2), create_mailbox_v1 - batch_create_mailboxes (v2), batch_create_mailboxes_v1 - update_mailbox (v2), update_mailbox_v1 - delete_mailbox (v1 — единственный вариант) - get_mail_domain_info, update_mail_domain_info * feat: add kubernetes tools * feat: add firewall tools 14 endpoints for Timeweb Cloud Firewall (groups, rules, resources): - list_firewall_groups / get_firewall_group - create_firewall_group / update_firewall_group / delete_firewall_group - list_firewall_group_resources - link_firewall_resource / unlink_firewall_resource - list_firewall_rules / get_firewall_rule - create_firewall_rule / update_firewall_rule / delete_firewall_rule - list_firewall_groups_by_resource * feat: add container-registry + dedicated-servers tools Container Registry (7 tools): - list_container_registries - get_container_registry - create_container_registry (preset_id XOR configurator_id+disk) - update_container_registry - delete_container_registry - list_container_registry_presets - list_container_registry_repositories Dedicated Servers (7 tools): - list_dedicated_servers - get_dedicated_server - create_dedicated_server - update_dedicated_server - delete_dedicated_server - list_dedicated_server_presets (optional location filter) - list_dedicated_server_additional_services * feat: add server-lifecycle tools (agent-generated, rate-limited before push) * feat: add database-extras tools (agent-generated, rate-limited before push) * feat: add dns-domains tools (agent-generated, rate-limited before push) * feat: add networking-extras tools (agent-generated, rate-limited before push) * feat: add s3-buckets tools (agent-generated, rate-limited before push) * feat: add ai-suite tools (agent-generated, rate-limited before push) * chore: ignore .specs/ (OpenAPI bundle for agent workflows) * fix: type errors after full-coverage merge - s3-buckets: use protected makeRequest directly (avoid any cast with type args) - servers: remove unused CreateServerDiskRequestDto import - create-floating-ip: handle undefined created_at - index.ts: loosen registerTool/Resource/Prompt param types to any (union grew to 250+) * fix: register 30 tool exports missed by rate-limited agents Agents for server-lifecycle, database-extras, and ai-suite hit extra-usage limit after writing .tool.ts files but before updating tools/index.ts. Added exports for: server lifecycle (create/delete/update/reset/boot/nat/ips), database admin+instance+cluster CRUD, AI agents CRUD. * fix(ssh-keys): use underscore response keys (ssh_key/ssh_keys) Timeweb API returns response objects with underscore-separated keys (ssh_keys, ssh_key) but the MCP client was reading hyphen-separated keys (ssh-keys, ssh-key) — causing "Cannot read properties of undefined" errors in all SSH-key operations. Verified via direct curl to /api/v1/ssh-keys on 2026-04-22: response shape is { meta: {...}, ssh_keys: [...] }. Fixes: - list_ssh_keys: was returning undefined → crash on .length - create_ssh_key: was returning undefined → crash on .id (but API call itself succeeded — key was actually created despite the error) - get_ssh_key, update_ssh_key: same pattern Files changed: - src/api/ssh-keys.ts (4 response key reads) - src/types/dto/list-ssh-keys-response.dto.ts - src/types/dto/create-ssh-key-response.dto.ts - src/types/dto/get-ssh-key-response.dto.ts - src/types/dto/update-ssh-key-response.dto.ts Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Artem Gasparyan <artgas1@users.noreply.github.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Author
|
@kradko-ai hi! Re-opening the Cloud API coverage effort — this supersedes #3 (which I closed since it was outdated and missed the ssh-keys underscore fix). Current state: 246 tools across 23 resource groups, build/type-check clean, ssh-keys response keys match what API actually returns. Happy to split into smaller PRs if the single-diff size is the blocker, or iterate on anything else. Thanks! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Расширяет MCP до полного покрытия Timeweb Cloud API — 246 тулов в 20+ API-клиентах (было 13).
Покрыто ~196 OpenAPI endpoints / 23 resource groups (некоторые endpoints маппятся в несколько тулов для удобства, напр.
add_server_to_project/add_database_to_project).Что добавлено
P0 — Core
create_server(XOR-валидацияpreset_idvsconfigurator,os_idvsimage_id),delete_server,update_server,reset_server_password,set_server_boot_mode,set_server_nat_mode,unmount_server_image, Server IPs CRUD, Disks create/patch/deletelist_server_presets,list_server_os,list_server_configurators,list_server_software,list_locationsssh_key/ssh_keys)P1 — Networking & DNS
create_imageс upload_url)P1/P2 — Platform
/cloud-ai/*Design notes
src/tools/*.tool.ts+src/actions/*.action.ts+ per-resourcesrc/api/*.tsextendingBaseApiClient+ DTOs +ToolNamesenum + exports.hash?/code?query параметры.preset_idXORconfigurator) валидируется в handler, возвращаяcreateToolResponseс понятной ошибкой.src/index.ts— registerTool/Resource/Prompt теперь принимаютanyв forEach callback, т.к. union тулов вырос до 245+ (TS сдавался на 200+).Changes vs #3
src/api/ssh-keys.tsи ssh-key DTO используютssh_key/ssh_keys(underscore), как возвращает Timeweb Cloud API. В feat: full Cloud API coverage — 245 tools across 23 resource groups #3 ошибочно было"ssh-key"/"ssh-keys"(dash), из-за чегоlist_ssh_keys,create_ssh_key,get_ssh_key,update_ssh_keyвозвращалиundefined.Build
bun install bun run build bun run type-check # cleanBundle: ~610KB (was ~220KB).
Test plan
bun run buildbun run type-checknode dist/index.jsпечатает "Timeweb MCP server started"list_server_presetsвозвращает пресетыlist_ssh_keysвозвращает массив (не undefined)create_ssh_key+create_serverсоздают VPS (end-to-end)How it was built
Спека (OpenAPI 3.0 bundle 1.9MB) вытянута с
https://timeweb.cloud/api-docs-data/bundle.json. Coverage-аудит определил gap — 170 недостающих endpoint. 16 agent-сессий (по одной на группу ресурсов) сгенерировали тулы параллельно в отдельных git-worktree. Merge через serial branch-by-branch с автоматическим union-резолвом конфликтов в registry-файлах (tool-names.enum.ts,tools/index.ts,api/index.ts, частичноapi/dbaas.ts/api/servers.ts). Финальный ssh-keys underscore-fix прошёл отдельным review на форке.🤖 Generated with Claude Code