Skip to content

Harden Zedcloud SDK: generator rewrite, multi-tenant auth, helpers, and guarded MCP server - #2

Merged
vignesh-zededa merged 6 commits into
mainfrom
feat/sdk-hardening
Sep 30, 2026
Merged

vignesh-zededa merged 6 commits into
mainfrom
feat/sdk-hardening

Conversation

@vignesh-zededa

Copy link
Copy Markdown
Owner

Summary

Builds on the initial SDK from cursor/zedcloud-python-sdk-5998 (included in this PR, since main only has the README) and makes it safe for real tenant automation and chat-driven use through MCP.

1. Bug fixes (4a93fde)

  • import zedcloud failed on Python 3.10 (typing.Self), although 3.10 is the declared minimum and is in CI.
  • POST/PUT/DELETE were retried after 5xx responses, which could create objects twice or reboot twice. They are now retried only on 429 or connection failures.
  • Path parameters were not encoded: get_edge_node_by_name("x/../../v1/users") requested a different endpoint.

2. Generator rewrite (5dfb811)

  • One shared models module (989 models). Previously 191 shared definitions were emitted 11 times as distinct classes.
  • Tolerant responses: unknown fields are kept and round-trip through updates, new enum values are accepted, and spec-"required" fields may be missing. Before this, real responses raised ValidationError.
  • Typed update bodies (42 of 121 were dict | Any), readable method names, keyword-only arguments, docstrings with a risk label, and multipart uploads (3 upload endpoints were unusable).
  • operations.json registry, --check mode in CI, and scripts/fetch_specs.py.

3. Runtime (5dfb811)

  • Sync and async clients, jittered backoff, and an X-Request-Id on every call.
  • Token or username/password auth, with automatic re-login on 401 and optional enterprise selection.
  • Multi-tenant profiles in TOML. Secrets can come from inline values, environment variables, commands or the OS keychain.
  • Error classes carrying the Zedcloud error code, details and request ID.

4. Helpers (d764e32)

  • iter_* for 56 paginated lists and lookup_* (name or ID) for 45 resource types.
  • wait_for_edge_node, wait_for_app_instance and wait_for_job.
  • zedcloud CLI: profiles, whoami, ops search/show, and call (writes need --yes).
  • Automation plugin: --zedcloud-profile, and integration tests skip unless the profile sets allow_writes.

5. MCP server (21a3630)

  • 17 tools: tenant switching, task-level reads (fleet health, nodes, app instances, projects, events, jobs), and search/describe/call covering all 470 operations.
  • Writes: plan_write_operation previews the change (merged update and field diff) and returns a single-use, expiring token. execute_write_operation runs exactly that stored request, asks the user via elicitation when the client supports it, and writes to a JSONL audit log with secrets redacted.
  • Tenants are read-only unless the profile sets allow_writes. --read-only and --require-human-approval flags are available.

Test plan

  • 602 unit tests on Python 3.12 (600 on 3.10). Every one of the 470 operations is checked for method, path, auth headers and request ID.
  • Tests cover tolerant models, retries, encoding, login/re-login, profiles, pagination, lookups, waiters, the CLI, the pytest plugin, and MCP tools end to end (including the preview → execute flow and audit log).
  • MCP server started over stdio with a real MCP client.
  • ruff check/format; scripts/generate.py --check.
  • Read-only smoke tests against a live tenant: uv run pytest -m smoke --zedcloud-profile <profile>.

Assumptions still to confirm against a live tenant

  • Login payload uses usernameAtRealm (or username + realm).
  • The Kubernetes X-API-KEY defaults to the session token.
  • Chunked-upload bodies are sent as a base64 JSON string.
  • next.pageNum starts at 1 and totalPages is reliable.
  • Whether one session token can reach several enterprises. Enterprise selection currently happens only at password login.

🤖 Generated with Claude Code

cursoragent and others added 6 commits September 25, 2026 05:39
Introduce a uv/hatchling workspace with:
- zedcloud: typed httpx + Pydantic v2 client generated from committed
  OpenAPI swagger specs (11 services), with retries, ApiError types,
  Bearer + X-API-KEY auth, and pagination helpers
- zedcloud-automation: pytest fixtures, markers, and read-only smoke tests
- zedcloud-mcp: stdio MCP server exposing focused nodes/apps/networks/k8s/jobs tools
- codegen script, Makefile, CI (ruff + mocked tests), MIT license, docs

Co-authored-by: vignesh-zededa <vignesh-zededa@users.noreply.github.com>
Remove shared tests/__init__.py packages that collided across members
and use --import-mode=importlib for the monorepo.

Co-authored-by: vignesh-zededa <vignesh-zededa@users.noreply.github.com>
- Drop typing.Self (3.11+) so the package imports on the declared 3.10 floor.
- Only replay 5xx responses for idempotent methods; POST/PUT/DELETE are
  retried only on 429 or connection failures where the server never saw
  the request, preventing duplicate creates or repeated reboots.
- Percent-encode path parameters so values containing '/', '?' or '#'
  cannot escape their path segment and reach other endpoints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Generator (scripts/generate.py, replaces datamodel-codegen pipeline):
- Merge the 11 specs' definitions into one models module (191 shared
  definitions were emitted 11 times as distinct classes); conflicts fail.
- Tolerant response models: all fields optional, unknown fields kept and
  round-tripped, open enums accept server-added values, lenient timestamps,
  spec patterns not enforced. Fixes ValidationErrors on real responses.
- Hoist gRPC-gateway inline update bodies into typed *Body models
  (42 of 121 bodies were previously dict | Any).
- Readable method names via override table; collisions fail generation.
- Keyword-only optional args, pagination params renamed (page_size, ...),
  docstrings with parameter docs and read/write/destructive labels.
- Typed iter_* methods for all paginated list operations.
- Multipart upload support (formData params were silently dropped).
- Sync and async classes per service; operations.json registry.
- --check mode for CI; scripts/fetch_specs.py refreshes openapi/.

Runtime:
- Sync and async transports with idempotency-aware retries, jittered
  backoff, per-call X-Request-Id, debug logging without secrets.
- Username/password login with automatic re-login on 401, optional
  enterprise selection; token auth; X-API-KEY for the Kubernetes service.
- Multi-tenant profiles (TOML) with env/command/keyring secret sources.
- Error hierarchy that surfaces Zedcloud error codes and details.
- client.call(operation_id, ...) and zedcloud.operations search/registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Generate lookup_* (name-or-ID) for all 45 resources exposing /id/{id}
  and /name/{name} GETs; UUID-shaped values fall back to name on 404.
- wait_for_edge_node / wait_for_app_instance / wait_for_job (sync+async)
  on generic zedcloud.waiters, with fail states and WaitFailedError.
- lookup_project alias for resource groups.
- zedcloud CLI: profiles, whoami, ops search/show, call (writes need --yes).
- Profiles file default now applies when no environment config is set.
- zedcloud-automation: --zedcloud-profile option, config fixture, and
  integration tests skip unless the profile sets allow_writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Tenants from the zedcloud profiles file: list_tenants / use_tenant /
  whoami, optional tenant on every tool, tenant echoed in every result.
- Task tools: fleet_health, list/get edge nodes and app instances,
  list_projects, recent_events, get_job; compact, redacted outputs.
- Full API reach: search_operations, describe_operation, describe_model,
  call_read_operation (read-only operations only).
- Writes: plan_write_operation validates, fetches the target, merges
  partial updates onto the current object, diffs fields, flags
  destructive ops, and stores the exact request under a single-use,
  expiring token; execute_write_operation runs only that stored plan,
  asks the user via elicitation when supported, and audit-logs to JSONL.
- Writes require allow_writes on the profile; --read-only and
  --require-human-approval flags; MCP SDK >= 2.2 (MCPServer API).
- Docs: README, getting started, architecture, MCP safety model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vignesh-zededa
vignesh-zededa merged commit 5795ae4 into main Sep 30, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants