manage_durable_objects

Tool of io.github.butterbase-ai/mcp

Manage Durable Object (DO) classes for an app: register/update code, list/get/delete, view usage, and manage shared env vars. DOs are stateful per-key actors that persist state in memory and built-in storage. Use them when you need state for a single room/user/agent across requests (multiplayer games, chat rooms, rate limiters, long-running agents). For stateless work, use a Function instead. Actions: - "deploy": Register or update a DO class (single TypeScript file, one exported class) - "list": List all DO classes for the app - "get": Get a single DO class — includes the source code and current status - "delete": Delete a DO class — Cloudflare immediately deletes all instances and storage; cannot be undone - "usage": Get current-month DO usage (do_requests, do_cpu_ms) — refreshed every 15 min, app-wide totals - "list_env": List all env vars set on the app's DOs - "set_env": Create or overwrite a single env var - "delete_env": Remove a single env var Parameters by action: deploy: { app_id, action: "deploy", name, code, access_mode? } list: { app_id, action: "list" } get: { app_id, action: "get", name } delete: { app_id, action: "delete", name } usage: { app_id, action: "usage", name } list_env: { app_id, action: "list_env" } set_env: { app_id, action: "set_env", key, value } delete_env: { app_id, action: "delete_env", key } Deploy constraints: - One TypeScript file, exporting exactly ONE class with fetch(req) and optional state.storage / state.acceptWebSocket - No npm imports — only `import { ... } from 'cloudflare:workers'` - Max 5 DO classes per app. Bundle (sum of all DO code per app) ≤ 10 MB compressed. - Class name in code (PascalCase) is parsed automatically; URL "name" arg is kebab-case. URL after deploy: https://<subdomain>.butterbase.dev/_do/<name>/<instance-id> (HTTP and WebSocket) access_mode (v1 — shape check only at the dispatcher; validate inside fetch() for strong auth): - "public": open to anyone - "authenticated": requires Authorization that looks like an end-user JWT (default) - "service_key": requires Authorization starting with "Bearer bb_sk_" Env vars are key-value pairs injected into every DO class at runtime, scoped to all DO classes within the app. They are separate from function env vars. After set_env / delete_env, redeploy DOs for the change to take effect. Common errors: - RESOURCE_NOT_FOUND: app_id or DO class doesn't exist - AUTH_INSUFFICIENT_PERMISSIONS: must be app owner or collaborator - VALIDATION_ERROR: env key must be alphanumeric + underscores; class code must export exactly one class Idempotency: deploy/set_env/delete_env are safe to retry. delete is irreversible.