fix(mcp): require operator spend caps before real purchases and price Savings Plan previews

CHANGELOG.md

@@ -5,6 +5,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [Unreleased]
 
+### Breaking
+
+- **Real purchases now require operator spend caps.** With
+  `CUDLY_MCP_ENABLE_REAL_PURCHASES=1`, every real purchase is refused unless
+  the relevant cap is set to a valid value: `CUDLY_MCP_MAX_COUNT` (RIs, and
+  vCPUs for GCP CUDs), `CUDLY_MCP_MAX_HOURLY_COMMITMENT` (Savings Plans) and
+  `CUDLY_MCP_MAX_MEMORY_GB` (GCP CUDs). Caps are per call and are not USD
+  caps. The MCPB bundle exposes them as optional settings. Previews are
+  unaffected. Savings Plan previews now report `cost` (total commitment over
+  the term), and Savings Plan audit lines now carry that figure as the
+  estimated cost.
+
 ### Notices
 
 - **Federation IaC bundles downloaded before 2026-04-22 need to be

README.md

@@ -114,16 +114,17 @@ AZURE_SUBSCRIPTION_ID = "00000000-0000-0000-0000-000000000000"
 A typical session searches for a recommendation, previews the purchase, then executes it:
 
 1. **Search**: call `cudly_search_recommendations` with `provider="aws"`, `service="ec2"`, `region="us-east-1"` to see what AWS Cost Explorer currently recommends reserving.
-2. **Preview**: take a result's `region`/`resource_type`/`count` and call `cudly_aws_ec2_ri_purchase` with those values and `term_years`/`payment_option` of your choice. Leave `dry_run` at its default (`true`) -- the response validates your parameters without contacting AWS or spending anything, and reports `cost`/`on_demand_cost`/`estimated_savings`/`savings_percentage` only when a real figure is actually known (omitted otherwise, never a fabricated `0`).
+2. **Preview**: take a result's `region`/`resource_type`/`count` and call `cudly_aws_ec2_ri_purchase` with those values and `term_years`/`payment_option` of your choice. Leave `dry_run` at its default (`true`) -- the response validates your parameters without contacting AWS or spending anything, and reports `cost`/`on_demand_cost`/`estimated_savings`/`savings_percentage` only when a real figure is actually known (omitted otherwise, never a fabricated `0`). Today only Savings Plan previews are priced (`cost` is the total commitment over the term, `hourly_commitment` x 8760 x `term_years`, computed locally); RI and CUD previews carry no price because the preview never contacts the provider.
 3. **Execute**: once the preview looks right, call the same tool again with `dry_run=false, confirm=true`. This is the only combination that performs a real purchase, and only when the operator has also enabled `CUDLY_MCP_ENABLE_REAL_PURCHASES=1` on the server process; any other combination either previews or returns an explicit refusal error (see [Safety model](#safety-model)).
 
 Every other provider's purchase tool (`cudly_aws_savingsplans_purchase`, `cudly_aws_rds_ri_purchase`, `cudly_azure_compute_ri_purchase`, `cudly_gcp_computeengine_cud_purchase`, ...) follows the identical dry_run-then-confirm pattern. Call `cudly_list_commitment_actions` at any point for the full, always-current list of tools, which ones can spend real money today, and 2-3 example prompts per tool.
 
 ## Safety model
 
-- `dry_run` defaults to `true` on every purchase tool. A dry-run call never contacts the cloud provider and never spends money -- it only validates your parameters. It reports pricing (`cost`/`on_demand_cost`/`estimated_savings`/`savings_percentage`) only when a real figure is genuinely known; those fields are omitted, not zeroed, when it isn't.
+- `dry_run` defaults to `true` on every purchase tool. A dry-run call never contacts the cloud provider and never spends money -- it only validates your parameters. It reports pricing (`cost`/`on_demand_cost`/`estimated_savings`/`savings_percentage`) only when a real figure is genuinely known; those fields are omitted, not zeroed, when it isn't. Only Savings Plan previews are priced (total commitment over the term, computed locally); RI and CUD previews show no price.
 - `dry_run=true` always previews, including when `confirm=true`. A real purchase requires **both** `dry_run=false` **and** `confirm=true`; `dry_run=false` with `confirm=false` is refused with a structured error, not silently downgraded to a preview.
 - A real purchase **also** requires the operator to have set `CUDLY_MCP_ENABLE_REAL_PURCHASES=1` (or `true`, case-insensitive) in the environment `cudly-mcp` was launched with. This is layered underneath `confirm`: `confirm` only proves the model asked to spend money, it does not prove the operator running this server wants it able to. The gate is unset (disabled) by default -- unset, empty, `0`, `false`, or any other value all disable real purchases -- so a fresh install cannot spend money until the operator explicitly opts in. When disabled, a `dry_run=false, confirm=true` call is refused before any provider or credential is touched, naming the flag to set. Dry runs are unaffected by this flag; they never spend regardless of its value.
+- A real purchase also requires **operator-set spend caps**, read from the server's environment (never from tool arguments, which the model controls). Unset, empty or invalid caps refuse the purchase, naming the variable; there is no default and no "unlimited". `CUDLY_MCP_MAX_COUNT` (positive integer) bounds `count` for every RI purchase and `vcpu_count` for GCP CUDs. `CUDLY_MCP_MAX_HOURLY_COMMITMENT` (positive number, USD/hour) bounds Savings Plan `hourly_commitment`. `CUDLY_MCP_MAX_MEMORY_GB` (positive number) bounds `memory_gb` for GCP CUDs. Previews need no caps. **Limits you must understand:** the caps apply **per call**, not cumulatively, so a fresh `idempotency_nonce`, region or profile repeats the call and spends again; and the count cap is **not a USD cap**: unit prices differ by orders of magnitude (50 x `u-24tb1` at about $218/hour each for 3 years is roughly $286M under a `CUDLY_MCP_MAX_COUNT=50` that looks small). Choose caps with the most expensive resource type in mind. A USD cap and a cumulative budget are tracked in [#51](https://github.com/LeanerCloud/cloud-commitments-mcp/issues/51).
 - A real purchase requires the **target account to be named**: `aws_profile` (AWS) or `azure_subscription_id` (Azure), either as the tool argument or via the matching environment variable the provider itself reads (`AWS_PROFILE`, `AZURE_SUBSCRIPTION_ID`). **GCP has no environment fallback, so `gcp_project_id` is required for a real CUD purchase.** That is deliberate: nothing in `providers/gcp` reads `GOOGLE_CLOUD_PROJECT` or `CLOUDSDK_CORE_PROJECT`, and with no project configured the provider falls back to the *first active project* in your `ListProjects` response -- an artifact of IAM visibility and API ordering rather than a project anyone chose, which is not a defensible default for spending money. Pointing the scope at an environment variable the provider ignores would be worse still: the idempotency token would name one project while the commitment landed in another. If neither is set, the real purchase is refused before any credential is touched, naming the argument to pass. **Dry runs do not require it** -- you can price a purchase without naming an account. This is not bookkeeping: the account is folded into the idempotency token, so leaving it to ambient credentials on one call and naming it explicitly on the next derives two *different* tokens for the *same* account. Every provider's dedupe is token-keyed, so the second call's lookup would miss and buy a second commitment. Refusing an undeterminable account makes that aliasing unreachable. Naming an account explicitly and inheriting the same value from the environment always agree, so they still dedupe normally.
 - Every money-affecting parameter (region, resource type, count, term, payment option, and any provider-specific dimension such as RDS's `az_config`) is validated against an explicit enum or non-empty check before anything is built or sent. There is no silent default for a value that materially changes what gets purchased.
 - Every real purchase is tagged with a source identifying it came from this MCP server (never a user-suppliable string) and a deterministic idempotency token derived from the request's own parameters. By default, retrying an identical tool call -- however long after the original, and regardless of any clock boundary -- always derives the same token, so the provider dedupes the retry instead of buying twice; this is a fail-safe default, since the worst case of a false dedupe is a skipped intentional repeat, never a double purchase. To deliberately make a second, otherwise-identical purchase (e.g. "buy 3 RIs now" and "buy 3 more next week"), pass a fresh `idempotency_nonce` value on the second call; passing the same nonce on a retry of that same call still dedupes correctly.

cmd/cudly-mcp/gcp_purchase_protocol_test.go

@@ -127,6 +127,9 @@ func (p *fakeGCPProvider) GetRecommendationsClient(_ context.Context) (provider.
 // lives at the library boundary (tools/gcp_computeengine_cud_safeguards_test.go).
 func TestGCPComputeEngineCUDPurchaseStructuredCost(t *testing.T) {
 	t.Setenv(tools.EnvEnableRealPurchases, "1")
+	t.Setenv(tools.EnvMaxCount, "1000")
+	t.Setenv(tools.EnvMaxHourlyCommitment, "1000")
+	t.Setenv(tools.EnvMaxMemoryGB, "1000")
 	service := &fakeComputeEngineCommitmentsService{}
 
 	provider.GetRegistry().Unregister("gcp")

cmd/cudly-mcp/main_test.go

@@ -300,6 +300,9 @@ func TestRealPurchasePastProviderRegistration(t *testing.T) {
 	// must clear the operator-side EnvEnableRealPurchases gate too, or every
 	// assertion below would instead observe the gate's own refusal.
 	t.Setenv(tools.EnvEnableRealPurchases, "1")
+	t.Setenv(tools.EnvMaxCount, "1000")
+	t.Setenv(tools.EnvMaxHourlyCommitment, "1000")
+	t.Setenv(tools.EnvMaxMemoryGB, "1000")
 
 	server, err := cudlymcp.NewServer("test-regression")
 	require.NoError(t, err)

mcpb/manifest.json

@@ -13,7 +13,10 @@
   },
   "license": "OSL-3.0",
   "compatibility": {
-    "platforms": ["darwin", "linux"]
+    "platforms": [
+      "darwin",
+      "linux"
+    ]
   },
   "server": {
     "type": "binary",
@@ -22,21 +25,30 @@
       "command": "${__dirname}/server/linux-launch.sh",
       "args": [],
       "env": {
-        "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}"
+        "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}",
+        "CUDLY_MCP_MAX_COUNT": "${user_config.max_count}",
+        "CUDLY_MCP_MAX_HOURLY_COMMITMENT": "${user_config.max_hourly_commitment}",
+        "CUDLY_MCP_MAX_MEMORY_GB": "${user_config.max_memory_gb}"
       },
       "platform_overrides": {
         "darwin": {
           "command": "${__dirname}/server/darwin-launch.sh",
           "args": [],
           "env": {
-            "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}"
+            "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}",
+            "CUDLY_MCP_MAX_COUNT": "${user_config.max_count}",
+            "CUDLY_MCP_MAX_HOURLY_COMMITMENT": "${user_config.max_hourly_commitment}",
+            "CUDLY_MCP_MAX_MEMORY_GB": "${user_config.max_memory_gb}"
           }
         },
         "linux": {
           "command": "${__dirname}/server/linux-launch.sh",
           "args": [],
           "env": {
-            "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}"
+            "CUDLY_MCP_ENABLE_REAL_PURCHASES": "${user_config.enable_real_purchases}",
+            "CUDLY_MCP_MAX_COUNT": "${user_config.max_count}",
+            "CUDLY_MCP_MAX_HOURLY_COMMITMENT": "${user_config.max_hourly_commitment}",
+            "CUDLY_MCP_MAX_MEMORY_GB": "${user_config.max_memory_gb}"
           }
         }
       }
@@ -49,6 +61,27 @@
       "description": "DANGER: turns on cudly-mcp's ability to execute REAL, money-spending cloud purchases (AWS Reserved Instances, Savings Plans, Azure Reservations, GCP CUDs) when a client explicitly requests dry_run=false and confirm=true. Leave this off until you have exercised the dry-run path and are ready to let it spend real money.",
       "default": false,
       "required": false
+    },
+    "max_count": {
+      "type": "number",
+      "title": "Maximum count per purchase call",
+      "description": "Per-call ceiling on instances/nodes (or vCPUs for GCP CUDs) for a real purchase. Required before any real purchase: leave it empty and purchases are refused. Applies per call, not cumulatively, and is not a USD cap.",
+      "min": 1,
+      "required": false
+    },
+    "max_hourly_commitment": {
+      "type": "number",
+      "title": "Maximum hourly commitment (USD/hour)",
+      "description": "Per-call ceiling on a Savings Plan hourly commitment. Required before any real Savings Plan purchase. Applies per call, not cumulatively.",
+      "min": 1,
+      "required": false
+    },
+    "max_memory_gb": {
+      "type": "number",
+      "title": "Maximum committed memory (GB)",
+      "description": "Per-call ceiling on memory for a GCP CUD. Required before any real GCP CUD purchase. Applies per call, not cumulatively.",
+      "min": 1,
+      "required": false
     }
   },
   "privacy_policies": [

server.json

@@ -24,6 +24,27 @@
           "isSecret": false,
           "format": "string"
         },
+        {
+          "name": "CUDLY_MCP_MAX_COUNT",
+          "description": "Positive integer. Per-call ceiling on count (RIs) and vcpu_count (GCP CUDs) for real purchases. Required for any real purchase: unset, empty or invalid refuses it. Not a USD cap and not cumulative; see README 'Safety model'.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "CUDLY_MCP_MAX_HOURLY_COMMITMENT",
+          "description": "Positive number (USD/hour). Per-call ceiling on Savings Plan hourly_commitment. Required for real Savings Plan purchases: unset, empty or invalid refuses it. Not cumulative.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "CUDLY_MCP_MAX_MEMORY_GB",
+          "description": "Positive number. Per-call ceiling on memory_gb for GCP CUD purchases. Required for real GCP CUD purchases: unset, empty or invalid refuses it. Not cumulative.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
         {
           "name": "CUDLY_MCP_AUDIT_LOG",
           "description": "Overrides the local JSONL purchase audit path after trimming. When unset, writes to $XDG_STATE_HOME/cudly/mcp-audit.jsonl; if XDG_STATE_HOME is unset, empty, or relative, it is ignored and the fallback is ~/.local/state/cudly/mcp-audit.jsonl. An empty or whitespace-only CUDLY_MCP_AUDIT_LOG value disables auditing.",

tools/aws_ec2_ri.go

@@ -40,7 +40,7 @@ type ec2RIPurchaseArgs struct {
 	Scope            string `json:"scope,omitempty" jsonschema:"region or availability-zone; defaults to region"`
 	AWSProfile       string `json:"aws_profile,omitempty" jsonschema:"AWS named profile override (~/.aws/config); default uses ambient credentials"`
 	IdempotencyNonce string `json:"idempotency_nonce,omitempty" jsonschema:"optional; set to a fresh value to authorize a purchase that is otherwise identical to a previous one (e.g. buy 3 more RIs with the same parameters); leave empty (the default) so retries with identical parameters dedupe and never double-buy"`
-	Count            int    `json:"count" jsonschema:"number of instances to reserve, must be > 0"`
+	Count            int    `json:"count" jsonschema:"number of instances to reserve, must be > 0; real purchases are capped by the operator (CUDLY_MCP_MAX_COUNT)"`
 	TermYears        int    `json:"term_years" jsonschema:"commitment length in years"`
 }
 

tools/aws_elasticache_ri.go

@@ -33,7 +33,7 @@ type elasticacheRIPurchaseArgs struct {
 	Engine           string `json:"engine" jsonschema:"cache engine"`
 	AWSProfile       string `json:"aws_profile,omitempty" jsonschema:"AWS named profile override (~/.aws/config); default uses ambient credentials"`
 	IdempotencyNonce string `json:"idempotency_nonce,omitempty" jsonschema:"optional; set to a fresh value to authorize a purchase that is otherwise identical to a previous one (e.g. buy 3 more RIs with the same parameters); leave empty (the default) so retries with identical parameters dedupe and never double-buy"`
-	Count            int    `json:"count" jsonschema:"number of cache nodes to reserve, must be > 0"`
+	Count            int    `json:"count" jsonschema:"number of cache nodes to reserve, must be > 0; real purchases are capped by the operator (CUDLY_MCP_MAX_COUNT)"`
 	TermYears        int    `json:"term_years" jsonschema:"commitment length in years"`
 }
 

tools/aws_rds_ri.go

@@ -36,7 +36,7 @@ type rdsRIPurchaseArgs struct {
 	AZConfig         string `json:"az_config" jsonschema:"single-az or multi-az; must match the recommendation exactly (different price, no cross-coverage)"`
 	AWSProfile       string `json:"aws_profile,omitempty" jsonschema:"AWS named profile override (~/.aws/config); default uses ambient credentials"`
 	IdempotencyNonce string `json:"idempotency_nonce,omitempty" jsonschema:"optional; set to a fresh value to authorize a purchase that is otherwise identical to a previous one (e.g. buy 3 more RIs with the same parameters); leave empty (the default) so retries with identical parameters dedupe and never double-buy"`
-	Count            int    `json:"count" jsonschema:"number of instances to reserve, must be > 0"`
+	Count            int    `json:"count" jsonschema:"number of instances to reserve, must be > 0; real purchases are capped by the operator (CUDLY_MCP_MAX_COUNT)"`
 	TermYears        int    `json:"term_years" jsonschema:"commitment length in years"`
 }
 

tools/aws_savingsplans.go

@@ -29,6 +29,10 @@ const awsSavingsPlansPurchaseDescription = "Purchase an AWS Savings Plan (Comput
 	"payment_option=no-upfront; AWS does not offer a 3-year Database Savings Plan or all-upfront/" +
 	"partial-upfront billing for it."
 
+// savingsPlanHoursPerYear is 365 days of hours, matching
+// providers/aws/services/savingsplans hoursInTerm.
+const savingsPlanHoursPerYear = 24 * 365
+
 // savingsPlansAccountLevelRegion is the region used to resolve the account-
 // level Savings Plans service client when the caller omits region -- Compute,
 // SageMaker, and Database plans are global, and cmd/multi_service_helpers.go
@@ -49,7 +53,7 @@ type savingsPlansPurchaseArgs struct {
 	Region           string  `json:"region,omitempty" jsonschema:"AWS region; required for sp_type=EC2Instance, ignored for account-level plan types"`
 	AWSProfile       string  `json:"aws_profile,omitempty" jsonschema:"AWS named profile override (~/.aws/config); default uses ambient credentials"`
 	IdempotencyNonce string  `json:"idempotency_nonce,omitempty" jsonschema:"optional; set to a fresh value to authorize a purchase that is otherwise identical to a previous one (e.g. buy 3 more RIs with the same parameters); leave empty (the default) so retries with identical parameters dedupe and never double-buy"`
-	HourlyCommitment float64 `json:"hourly_commitment" jsonschema:"USD/hour commitment amount, must be > 0"`
+	HourlyCommitment float64 `json:"hourly_commitment" jsonschema:"USD/hour commitment amount, must be > 0; real purchases are capped by the operator (CUDLY_MCP_MAX_HOURLY_COMMITMENT)"`
 	TermYears        int     `json:"term_years" jsonschema:"commitment length in years"`
 }
 
@@ -229,6 +233,10 @@ func savingsPlanRecommendationFromArgs(args savingsPlansPurchaseArgs) (rec commo
 		Term:           term.RecommendationTerm(),
 		PaymentOption:  string(paymentOption),
 		Details:        details,
+		// Total commitment over the term, computed locally (no provider call)
+		// with the 365-day year the savingsplans client also uses. Lets the
+		// offline preview show a price for this dollar-denominated product.
+		CommitmentCost: args.HourlyCommitment * savingsPlanHoursPerYear * float64(term),
 	}
 
 	dryRun, confirm = ResolveDryRunConfirm(args.DryRun, args.Confirm)