feat: implementation vdc write ops

[cavramoniu-ionos]

Add opt-in write operations for Data Centers (blueprint)

Adds the first write tools to the (previously read-only) IONOS Cloud MCP server. Data Centers are the blueprint for other resources.

Enablement

• Read-only by default — unchanged unless opted in
• New env var IONOS_MCP_TOOL_SCOPE, hierarchical:
  • unset / read → read-only
  • write → + create_*, update_*
  • destructive → + delete_* (implies write)
• Unrecognised values → read-only; effective scope logged at startup

Tools added

• create_datacenter — one DC per call (no batch)
• update_datacenter — partial (PATCH); location immutable
• delete_datacenter — deletes the DC and everything inside it

Security controls

• Gate at registration: single tools.RegisterTool(server, scope, method, ...) helper
• Classifies by HTTP method → read / write / destructive
• Skips registration when scope disallows → blocked tools never in tools/list
• Enforced in all load modes (eager / lazy / dynamic) + re-checked in the dynamic dispatcher (defense-in-depth)
• Strict naming enforced: create_* / update_* / delete_* (panics at boot on mismatch)
• MCP annotations set per method (readOnlyHint / destructiveHint / idempotentHint)

Two-phase confirmation (create + delete)

• Call 1 (no token) → preview + one-time token
  • delete preview shows blast radius (servers, volumes, LANs, …)
• Call 2 (with token) → executes
• Token: single-use, target-bound, 5-min TTL, in-memory (tools.ConfirmationStore)
• Shared store → works across the dynamic-mode dispatcher

Known limitation

• Two-phase confirmation does not stop a client with auto-approve on (the agent can walk both calls itself)
• Real boundary for unattended/auto sessions: don't grant destructive

Tests

• Unit: scope parsing, class mapping, confirmation store (single-use, mismatch, expiry, concurrency)
• Protocol: create/update/delete two-phase, scope gating, bad/mismatched token, 404, dynamic-mode parity
• All green: build, vet, gofmt, lint (0 issues), unit + in-memory (-race), mocked e2e

Docs

• README repositioned to "read-only by default" + Write operations section
• CLAUDE.md: scope env var, write-ops invariants, tool recipe
• CHANGELOG entry

Out of scope / follow-ups

• Backfill readOnlyHint on the other ~117 read tools
• Extend writes to other resources using this blueprint

[Copilot]

Pull request overview

Adds opt-in write capabilities (create/update/delete) for Compute Engine data centers to the IONOS Cloud MCP server, introducing a scope-gated registration model plus a two-phase confirmation flow for create/delete to keep destructive actions explicit across eager/lazy/dynamic load modes.

Changes:

• Introduces IONOS_MCP_TOOL_SCOPE parsing and a centralized tools.RegisterTool gate that hides write/destructive tools unless explicitly enabled.
• Adds two-phase confirmation infrastructure (tools.ConfirmationStore) and implements create_datacenter, update_datacenter, delete_datacenter (with blast-radius preview for delete).
• Extends dynamic/lazy modes and the test harness to preserve scope/confirmation behavior and validate write-tool behavior/parity.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/scope.go	Adds scope parsing, tool classing, and gated registration helper.
tools/scope_test.go	Unit tests for scope parsing/classing/method-name matching/annotations.
tools/loader/loader.go	Threads scope + confirmation store through lazy compute loader.
tools/loader/loader_test.go	Updates loader tests for new compute loader signature.
tools/inputs.go	Adds typed inputs for create/update/delete datacenter tools.
tools/helpers.go	Adds ErrorText and IsNotFound helpers for user-facing tool errors and 404 detection.
tools/dynamic/search_test.go	Updates dynamic dispatcher tests to enforce scope-based guard instead of “read-only only”.
tools/dynamic/dynamic.go	Threads scope into dynamic registration and enforces scope gate in dispatcher call path.
tools/dynamic/catalog.go	Catalog now records per-tool mutation class via name-based classification.
tools/confirm.go	Implements in-memory, TTL, single-use confirmation token store.
tools/confirm_test.go	Unit tests for confirmation token mint/consume semantics, expiry, and concurrency.
tools/compute/register.go	Threads scope + confirmation store into compute registration; registers datacenter write tools.
tools/compute/datacenter.go	Switches read tools to go through tools.RegisterTool (read-only classification + annotations).
tools/compute/datacenter_write.go	Implements create/update/delete datacenter tools + previews and token-confirm flow.
test/setup_test.go	Enhances test harness (captures request bodies, adds scope-aware setup).
test/live/live_test.go	Updates live wiring to pass scope + confirmation store.
test/e2e/main_test.go	Ensures e2e runner strips IONOS_MCP_TOOL_SCOPE from ambient env by default.
test/dynamic_test.go	Adds scope-aware dynamic test setup and threads shared confirmation store.
test/compute_write_test.go	Adds protocol tests for write tools (two-phase, scope gating, dynamic parity).
README.md	Documents “read-only by default” + introduces Write operations section and examples.
docs/compute/datacenter.md	Documents new datacenter write tools, scope gating, and confirmation flow.
CLAUDE.md	Adds contributor guidance and invariants for scope + write-tool registration.
CHANGELOG.md	Adds release notes for opt-in datacenter write ops and confirmation flow.
main.go	Resolves scope at startup, builds shared confirmation store, threads both into load modes.
.mcp.json	Updates sample MCP config (currently opts into destructive scope).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[avirtopeanu-ionos]

nice work!!