tools

type AZConfig ¶

type AZConfig string

AZConfig is the RDS deployment topology (single-AZ vs multi-AZ), which carries a different price and offering catalog per providers/aws/services/rds/client.go:314-322.

const (
	AZConfigSingleAZ AZConfig = "single-az"
	AZConfigMultiAZ  AZConfig = "multi-az"
)

func ValidateAZConfig(s string) (AZConfig, error)

type ActionEntry ¶

type ActionEntry struct {
	Name                string   `json:"name"`
	Provider            string   `json:"provider,omitempty"`
	Product             string   `json:"product,omitempty"`
	Action              string   `json:"action,omitempty"`
	Description         string   `json:"description"`
	RealPurchaseEnabled bool     `json:"real_purchase_enabled"`
	ExamplePrompts      []string `json:"example_prompts,omitempty"`
}

ActionEntry is one catalog entry returned by cudly_list_commitment_actions, reshaping a Descriptor for JSON output.

type ArcheraOffer ¶

type ArcheraOffer struct {
	// Pitch is what the coverage does and why it is relevant right now.
	Pitch string `json:"pitch"`
	// SignupURL is the Archera signup link carrying CUDly attribution.
	SignupURL string `json:"signup_url"`
	// EnrollmentWindowDays is how long from THIS purchase the buyer has to
	// enroll it. Surfaced as a number so a client can compute the deadline
	// from effective_date rather than parsing it out of prose.
	EnrollmentWindowDays int `json:"enrollment_window_days"`
	// NonGatingDisclosure states the offer is optional and CUDly works
	// without it.
	NonGatingDisclosure string `json:"non_gating_disclosure"`
	// SponsorshipDisclosure states the financial relationship behind the
	// recommendation.
	SponsorshipDisclosure string `json:"sponsorship_disclosure"`
}

ArcheraOffer is the post-purchase Archera underutilization-insurance offer.

Both disclosure fields are non-optional parts of the payload, not decoration: CUDly commits to surfacing the sponsorship AND the fact that it works fully without Archera everywhere the signup link appears (the CLI's printArcheraPitch does the same after a real purchase). An MCP client renders this JSON through a model, so shipping the link without the disclosures alongside it would let the model present a sponsored recommendation as a neutral one.

type CacheEngine ¶

type CacheEngine string

CacheEngine is the ElastiCache engine dimension (common.CacheDetails.Engine).

const (
	CacheEngineRedis     CacheEngine = "redis"
	CacheEngineMemcached CacheEngine = "memcached"
)

func ValidateCacheEngine(s string) (CacheEngine, error)

type Descriptor ¶

type Descriptor struct {
	// Name is the MCP tool name, e.g. "cudly_aws_ec2_ri_purchase".
	Name string
	// Provider is "aws", "azure", "gcp", or "" for provider-agnostic
	// meta-tools (cudly_list_commitment_actions, cudly_search_recommendations).
	Provider string
	// Product is the service the tool acts on, e.g. "ec2", "rds", "compute".
	Product string
	// Action is what the tool does, e.g. "ri_purchase", "cud_purchase", "search".
	Action string
	// Description is the tool's full MCP description, shared verbatim with
	// the live mcp.Tool registration so the two can never disagree.
	Description string
	// RealPurchaseEnabled reports whether this tool can execute a real,
	// money-spending purchase today (dry_run=false, confirm=true). false for
	// read-only tools and for tools shipped dry-run-only pending a
	// prerequisite fix (see the Azure/GCP tool comments).
	RealPurchaseEnabled bool
	// ExamplePrompts are 2-3 natural-language prompts that would plausibly
	// invoke this tool, surfaced by cudly_list_commitment_actions so a
	// session that doesn't know the tool name yet can find it.
	ExamplePrompts []string
}

Descriptor is the source-of-truth metadata for one MCP tool. Every tool file builds one and both mcp/server.go (to know what to register) and cudly_list_commitment_actions (to know what to advertise) read it, so the live tool set and the discoverability catalog can never drift apart -- there is exactly one place each tool's name/description/example prompts are written.

func ListCommitmentActionsDescriptor() Descriptor

type FieldOverride ¶

type FieldOverride struct {
	// Enum, when non-empty, restricts the property to these exact values.
	Enum []any
	// Default, when non-nil, is recorded on the schema as the property's
	// documented default so a caller inspecting the tool (or an MCP client
	// that surfaces schema defaults in its UI) can see it without reading
	// the tool description prose. It does NOT, by itself, cause the value to
	// be applied when the caller omits the field -- each tool's handler
	// applies its own default explicitly (see the dry_run/confirm pattern in
	// purchase.go) so "omitted" is never silently confused with "false".
	Default any
}

FieldOverride declares JSON Schema refinements -- an explicit enum membership and/or a documented default -- for one property of an otherwise auto-inferred schema. Centralizing this in one helper (BuildInputSchema) means every tool declares its enum/default once, next to its Go struct, instead of re-implementing schema post-processing per tool.

type LookbackPeriod ¶

type LookbackPeriod string

LookbackPeriod is the cost/usage lookback window backing a cudly_search_recommendations call. Values match the enum search_recommendations.go's Register advertises in the tool's JSON schema (BuildInputSchema's "lookback_period" FieldOverride); re-validated here so a caller invoking the tool directly -- bypassing MCP schema enforcement -- cannot pass an unsupported window through to the provider.

const (
	LookbackPeriod7Days  LookbackPeriod = "7d"
	LookbackPeriod30Days LookbackPeriod = "30d"
	LookbackPeriod60Days LookbackPeriod = "60d"
)

func ValidateLookbackPeriod(s string) (LookbackPeriod, error)

type PaymentOption ¶

type PaymentOption string

PaymentOption is the AWS/Azure/GCP-agnostic reserved-capacity payment schedule. It is validated at the MCP tool boundary before being copied onto common.Recommendation.PaymentOption (which stays a bare string there for backward compatibility with existing CSV/DB rows -- see pkg/common/types.go) so a caller can never smuggle an unrecognized payment term into a purchase.

const (
	PaymentOptionAllUpfront     PaymentOption = "all-upfront"
	PaymentOptionPartialUpfront PaymentOption = "partial-upfront"
	PaymentOptionNoUpfront      PaymentOption = "no-upfront"
)

func ValidatePaymentOption(s string) (PaymentOption, error)

type PurchaseRequest ¶

type PurchaseRequest struct {
	Region         string
	Recommendation common.Recommendation
	DryRun         bool
	Confirm        bool
	ResolveClient  ResolveClientFunc

	// Nonce is optional. When non-empty, this call is treated as a
	// DISTINCT purchase from an otherwise-identical one (authorizes a
	// deliberate repeat, e.g. "buy 3 more RIs" on top of an earlier "buy 3
	// RIs" with the same parameters). When empty (the default), identical
	// purchases dedupe so retries never double-buy. See idempotencyKeyFor.
	Nonce string

	// CredentialScope identifies WHERE the purchase lands: the AWS profile,
	// Azure subscription, or GCP project the call is billed to. It is folded
	// into the idempotency key so two purchases that are identical in every
	// product dimension but target different accounts derive DIFFERENT
	// tokens. Populated by each tool via CredentialScope(). See
	// idempotencyKeyFor for why omitting it is a double-spend/skipped-spend
	// hazard on Azure specifically.
	CredentialScope string
}

PurchaseRequest is the provider-agnostic input to ExecutePurchase. Each per-service tool handler builds one after validating its own typed parameters and constructing the common.Recommendation.

type PurchaseResponse ¶

type PurchaseResponse struct {
	Success           bool     `json:"success"`
	DryRun            bool     `json:"dry_run"`
	CommitmentID      string   `json:"commitment_id,omitempty"`
	Cost              *float64 `json:"cost,omitempty"`
	OnDemandCost      *float64 `json:"on_demand_cost,omitempty"`
	EstimatedSavings  *float64 `json:"estimated_savings,omitempty"`
	SavingsPercentage *float64 `json:"savings_percentage,omitempty"`
	EffectiveDate     *string  `json:"effective_date,omitempty"`
	TermYears         int      `json:"term_years,omitempty"`
	Error             string   `json:"error,omitempty"`

	// Archera is the optional underutilization-insurance offer, populated
	// ONLY after a real purchase actually succeeds. See archeraOffer.
	Archera *ArcheraOffer `json:"archera,omitempty"`
}

PurchaseResponse is the structured result returned to the MCP caller for both preview and real-purchase outcomes. Error is a string (not the Go error) because it crosses the MCP JSON-RPC boundary as tool output, not a protocol-level error -- ExecutePurchase itself still returns a Go error for gate refusals and provider-call failures.

Cost/OnDemandCost/EstimatedSavings/SavingsPercentage are pointers with omitempty: none of the *FromArgs constructors in this package populate Recommendation's cost fields (they build a fresh Recommendation from the caller's typed args, not from a priced search result), and some provider clients (e.g. AWS EC2 RIs, Savings Plans) never populate PurchaseResult.Cost either. A plain float64 could not distinguish "not known" from "genuinely $0", so every response reported 0 for money fields it never actually priced. A pointer that's nil (and omitted from the JSON payload entirely) when no real value exists lets a caller tell "unknown" apart from "confirmed zero" (feedback_nullable_not_zero).

EffectiveDate is a pointer for the same reason, and it is not a hypothetical concern: `omitempty` on a string only drops "", so a PurchaseResult whose Timestamp was never populated formatted its zero time.Time to the literal "0001-01-01T00:00:00Z" and shipped that as the commitment's start date. That is a fabricated date presented as real, on a field a caller may key billing or renewal reminders off. Nil (and omitted) when the provider reported no timestamp.

func ExecutePurchase(ctx context.Context, req PurchaseRequest) (*PurchaseResponse, error)

type Registration ¶

type Registration interface {
	Descriptor() Descriptor
	Register(s *mcp.Server) error
}

Registration is implemented by every tool file. Descriptor feeds the catalog; Register performs the live mcp.AddTool (or mcp.Server.AddTool) call that wires the tool's schema and handler onto the server.

func NewAWSEC2RIPurchaseTool() Registration

func NewAWSElastiCacheRIPurchaseTool() Registration

func NewAWSMemoryDBRIPurchaseTool() Registration

func NewAWSOpenSearchRIPurchaseTool() Registration

func NewAWSRDSRIPurchaseTool() Registration

func NewAWSRedshiftRIPurchaseTool() Registration

func NewAWSSavingsPlansPurchaseTool() Registration

func NewAzureComputeRIPurchaseTool() Registration

func NewGCPComputeEngineCUDPurchaseTool() Registration

func NewListCommitmentActions(descriptors []Descriptor) Registration

func NewSearchRecommendationsTool() Registration

type ResolveClientFunc ¶

type ResolveClientFunc func(ctx context.Context) (provider.ServiceClient, error)

ResolveClientFunc lazily resolves the provider.ServiceClient that will receive the real PurchaseCommitment call. It is a func, not an already-resolved client, so ExecutePurchase can prove (and tests can assert) that a preview never triggers provider/credential resolution -- only modeExecute invokes it.

type SPType ¶

type SPType string

SPType is the AWS Savings Plans product family (--include-sp-types in the CLI, cmd/main.go:112).

const (
	SPTypeCompute     SPType = "Compute"
	SPTypeEC2Instance SPType = "EC2Instance"
	SPTypeSageMaker   SPType = "SageMaker"
	SPTypeDatabase    SPType = "Database"
)

func ValidateSPType(s string) (SPType, error)

type Scope ¶

type Scope string

Scope is the EC2 RI applicability dimension. Values are the lowercase, hyphenated form that providers/aws/services/ec2/client.go:330-339 (canonicalizeEC2Scope) recognizes and normalizes to the SDK's ec2types.Scope casing ("Region" / "Availability Zone").

const (
	ScopeRegion           Scope = "region"
	ScopeAvailabilityZone Scope = "availability-zone"
)

func ValidateScope(s string) (Scope, error)

type Tenancy ¶

type Tenancy string

Tenancy is the EC2 RI tenancy dimension. Values match ec2types.Tenancy (providers/aws/services/ec2/client.go:309-318 canonicalizes them further, but "default"/"dedicated" already pass through unchanged).

const (
	TenancyDefault   Tenancy = Tenancy(ec2types.TenancyDefault)
	TenancyDedicated Tenancy = Tenancy(ec2types.TenancyDedicated)
)

func ValidateTenancy(s string) (Tenancy, error)

type TermYears ¶

type TermYears int

TermYears is the reserved-capacity commitment length, in years.

const (
	TermOneYear   TermYears = 1
	TermThreeYear TermYears = 3
)

func ValidateTermYears(n int) (TermYears, error)

func (t TermYears) RecommendationTerm() string