feat(mcp): require a USD cap on every real purchase

CHANGELOG.md

@@ -14,8 +14,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
   and `ARCHERA_PLAN_ID`; unconfigured calls error and send no request. It
   reads `https://api.archera.ai` only, never retries, and makes no purchase.
 
+- `CUDLY_MCP_MAX_COMMITMENT_USD`: a per-call ceiling on the total USD one
+  real purchase commits over its full term, priced from the provider's own
+  offering lookup (Savings Plans: hourly commitment x 8760 x years). USD only;
+  unpriceable purchases are refused.
+
 ### Security
 
+- A small `CUDLY_MCP_MAX_COUNT` no longer admits an enormous purchase (50 x
+  `u-24tb1` is about $286M): the USD cap bounds the real total.
+
 - `cudly_archera_comparison`: a transport error that echoed the API key with
   zero-width, bidi or control characters spliced into it could reassemble the
   plain key in the tool error, because the key was masked before those
@@ -48,12 +56,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Breaking
 
+- **`CUDLY_MCP_MAX_COMMITMENT_USD` is now required for every real purchase.**
+  Unset, empty or invalid refuses the purchase before credentials are
+  resolved. The MCPB bundle has a matching setting that must be filled in before any real purchase. Executing a
+  purchase now also needs credentials and network access for the provider's
+  offering lookup.
+- **Real GCP CUD purchases are refused** until the `cloud-commitments-go` pin
+  includes the CUD pricing fix (go#321), because their USD total cannot be
+  determined yet. Previews are unaffected.
+
 - **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
+  `CUDLY_MCP_MAX_MEMORY_GB` (GCP CUDs). Caps are per call; the count and
+  hourly caps are not USD caps (see `CUDLY_MCP_MAX_COMMITMENT_USD`). 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.

README.md

@@ -124,7 +124,7 @@ Every other provider's purchase tool (`cudly_aws_savingsplans_purchase`, `cudly_
 - `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 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_COMMITMENT_USD` (positive number, USD) is required for every real purchase and bounds the **total USD one call commits over the full term**: it is read from the provider's own offering lookup just before buying (Savings Plans: hourly commitment x 8760 x years, computed locally), so executing needs credentials and network access for that lookup. Only USD is supported; a purchase whose price is missing, zero, non-USD or errors is refused rather than assumed cheap. Real GCP CUD purchases are refused until the `cloud-commitments-go` pin includes the CUD pricing fix (go#321). The Azure figure is the Retail Prices list price, not a negotiated rate. The lookup and the purchase are separate calls, so the price can change between them. `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; a cumulative budget is tracked in [#51](https://github.com/LeanerCloud/cloud-commitments-mcp/issues/51). Choose the USD cap as the most one call may ever spend.
 - 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

@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"sync/atomic"
 	"testing"
@@ -125,11 +124,12 @@ func (p *fakeGCPProvider) GetRecommendationsClient(_ context.Context) (provider.
 // gcpComputeEngineRecommendationFromArgs never sets CommitmentCost, so old
 // and new library pins both yield "cost":0 here. The pin-sensitive cost proof
 // lives at the library boundary (tools/gcp_computeengine_cud_safeguards_test.go).
-func TestGCPComputeEngineCUDPurchaseStructuredCost(t *testing.T) {
+func TestGCPComputeEngineCUDPurchaseRefusedByUSDCap(t *testing.T) {
 	t.Setenv(tools.EnvEnableRealPurchases, "1")
 	t.Setenv(tools.EnvMaxCount, "1000")
 	t.Setenv(tools.EnvMaxHourlyCommitment, "1000")
 	t.Setenv(tools.EnvMaxMemoryGB, "1000")
+	t.Setenv(tools.EnvMaxCommitmentUSD, "1000000000")
 	service := &fakeComputeEngineCommitmentsService{}
 
 	provider.GetRegistry().Unregister("gcp")
@@ -190,21 +190,10 @@ func TestGCPComputeEngineCUDPurchaseStructuredCost(t *testing.T) {
 		},
 	})
 	require.NoError(t, err, "CallTool itself must not return a transport-level error")
-	require.False(t, result.IsError, "a successful fake-backed purchase must not surface as a tool error: %+v", result.Content)
-	require.Equal(t, int32(1), service.insertCalls.Load())
-
-	require.NotNil(t, result.StructuredContent, "structured output must be present")
-	encoded, err := json.Marshal(result.StructuredContent)
-	require.NoError(t, err)
-	var structured map[string]any
-	require.NoError(t, json.Unmarshal(encoded, &structured))
-
-	assert.Equal(t, true, structured["success"], "purchase must report success, got %s", encoded)
-	assert.Equal(t, false, structured["dry_run"], "this was a real purchase, got %s", encoded)
-	// The cost contract is an EXPLICIT zero: PurchaseResponse.Cost is a
-	// *float64 with omitempty, so a nil cost would drop the key entirely; a
-	// known zero upfront charge must survive as "cost":0.
-	cost, present := structured["cost"]
-	require.True(t, present, "structured output must carry an explicit cost field, got %s", encoded)
-	assert.Equal(t, 0.0, cost, "a Compute Engine CUD has no upfront charge, got %s", encoded)
+	// Real GCP CUD purchases are refused until USD totals exist (go#321).
+	require.True(t, result.IsError, "a real GCP CUD purchase must be refused: %+v", result.Content)
+	text, ok := result.Content[0].(*gosdk.TextContent)
+	require.True(t, ok)
+	assert.Contains(t, text.Text, "go#321")
+	require.Equal(t, int32(0), service.insertCalls.Load())
 }

cmd/cudly-mcp/main_test.go

@@ -303,6 +303,7 @@ func TestRealPurchasePastProviderRegistration(t *testing.T) {
 	t.Setenv(tools.EnvMaxCount, "1000")
 	t.Setenv(tools.EnvMaxHourlyCommitment, "1000")
 	t.Setenv(tools.EnvMaxMemoryGB, "1000")
+	t.Setenv(tools.EnvMaxCommitmentUSD, "1000000000")
 
 	server, err := cudlymcp.NewServer("test-regression")
 	require.NoError(t, err)

mcpb/manifest.json

@@ -29,6 +29,7 @@
         "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}",
+        "CUDLY_MCP_MAX_COMMITMENT_USD": "${user_config.max_commitment_usd}",
         "ARCHERA_API_KEY": "${user_config.archera_api_key}",
         "ARCHERA_ORG_ID": "${user_config.archera_org_id}",
         "ARCHERA_PLAN_ID": "${user_config.archera_plan_id}"
@@ -42,6 +43,7 @@
             "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}",
+            "CUDLY_MCP_MAX_COMMITMENT_USD": "${user_config.max_commitment_usd}",
             "ARCHERA_API_KEY": "${user_config.archera_api_key}",
             "ARCHERA_ORG_ID": "${user_config.archera_org_id}",
             "ARCHERA_PLAN_ID": "${user_config.archera_plan_id}"
@@ -55,6 +57,7 @@
             "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}",
+            "CUDLY_MCP_MAX_COMMITMENT_USD": "${user_config.max_commitment_usd}",
             "ARCHERA_API_KEY": "${user_config.archera_api_key}",
             "ARCHERA_ORG_ID": "${user_config.archera_org_id}",
             "ARCHERA_PLAN_ID": "${user_config.archera_plan_id}"
@@ -74,7 +77,7 @@
     "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.",
+      "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; it bounds size, not dollars (see the USD setting).",
       "min": 1,
       "required": false
     },
@@ -92,6 +95,13 @@
       "min": 1,
       "required": false
     },
+    "max_commitment_usd": {
+      "type": "number",
+      "title": "Maximum commitment per purchase call (USD)",
+      "description": "Per-call ceiling on the total USD one purchase commits over its full term, priced by the provider just before buying. Required before any real purchase: leave it empty and purchases are refused. USD only; purchases that cannot be priced (including real GCP CUD purchases for now) are refused. Applies per call, not cumulatively.",
+      "min": 1,
+      "required": false
+    },
     "archera_api_key": {
       "type": "string",
       "title": "Archera API key",

server.json

@@ -26,7 +26,7 @@
         },
         {
           "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'.",
+          "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. Bounds size, not dollars (see CUDLY_MCP_MAX_COMMITMENT_USD); not cumulative. See README 'Safety model'.",
           "isRequired": false,
           "isSecret": false,
           "format": "string"
@@ -45,6 +45,13 @@
           "isSecret": false,
           "format": "string"
         },
+        {
+          "name": "CUDLY_MCP_MAX_COMMITMENT_USD",
+          "description": "Positive number (USD). Per-call ceiling on the total USD one real purchase commits over its full term, priced by the provider just before buying. Required for any real purchase: unset, empty or invalid refuses it. USD only; purchases that cannot be priced (including real GCP CUD purchases for now) are refused. 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/adopted_go_safeguards_test.go

@@ -89,6 +89,8 @@ func rdsOffering(id, engine string) rdstypes.ReservedDBInstancesOffering {
 		MultiAZ:                       aws.Bool(true),
 		Duration:                      aws.Int32(3 * 365 * 24 * 3600),
 		OfferingType:                  aws.String("No Upfront"),
+		FixedPrice:                    aws.Float64(100),
+		CurrencyCode:                  aws.String("USD"),
 	}
 }