@jadenrazo/cloudcost-mcp 1.0.1 → 1.2.1

package/dist/index.js

@@ -7,14 +7,16 @@ import {
   analyzeTerraform,
   analyzeTerraformSchema,
   bool,
+  coerceToString,
   compareProviders,
   compareProvidersSchema,
   convertBreakdownCurrency,
   convertCurrency,
+  currencyField,
   estimateCost,
   estimateCostSchema,
-  fileContentSchema,
-  filePathSchema,
+  getExchangeRateInfo,
+  iacFilesSchema,
   loadConfig,
   logger,
   mapInstance,
@@ -24,19 +26,22 @@ import {
   optimizeCostSchema,
   parseTerraform,
   planJsonSchema,
+  providerEnum,
   safeJsonParse,
   sanitizeForMessage,
   setLogLevel,
+  shortStringSchema,
   stateJsonSchema,
   str,
-  tfvarsSchema,
+  tfvarsField,
   whatIf,
   whatIfSchema
-} from "./chunk-6O2Y6MKU.js";
+} from "./chunk-CGMU4ETN.js";
 import {
   getFallbackMetadata,
+  getPricingMetadata,
   getResourceEquivalents
-} from "./chunk-MNFT5YKN.js";
+} from "./chunk-LWTVE7UY.js";
 
 // src/server.ts
 import { createRequire } from "module";
@@ -82,7 +87,7 @@ var getEquivalentsSchema = z.object({
     "Instance type / VM size to also map across providers (e.g. t3.large, Standard_D4s_v3)"
   )
 });
-async function getEquivalents(params) {
+function getEquivalents(params) {
   const sourceProvider = params.source_provider;
   let resourceEquivalents;
   if (params.target_provider) {
@@ -455,7 +460,8 @@ async function analyzePlan(params, pricingEngine, config) {
     total_delta_monthly: round2(totalAfter - totalBefore),
     summary: analysis.summary,
     resource_diffs: resourceDiffs,
-    warnings: [...new Set(warnings)]
+    warnings: [...new Set(warnings)],
+    pricing_metadata: getPricingMetadata(targetProvider)
   };
   if (currency !== "USD") {
     result = applyResultCurrency(result, currency);
@@ -476,6 +482,7 @@ function applyResultCurrency(result, currency) {
   return {
     ...result,
     currency,
+    exchange_rate: getExchangeRateInfo(currency),
     total_before_monthly: round2(convertCurrency(result.total_before_monthly, currency)),
     total_after_monthly: round2(convertCurrency(result.total_after_monthly, currency)),
     total_delta_monthly: round2(convertCurrency(result.total_delta_monthly, currency)),
@@ -580,7 +587,7 @@ function extractTags2(attrs) {
   const result = {};
   for (const [k, v] of Object.entries(tags)) {
     if (typeof v === "string") result[k] = v;
-    else if (v !== null && v !== void 0) result[k] = String(v);
+    else if (v !== null && v !== void 0) result[k] = coerceToString(v);
   }
   return result;
 }
@@ -680,18 +687,13 @@ function parseTerraformState(stateJson) {
 // src/tools/compare-actual.ts
 var compareActualSchema = z4.object({
   state_json: stateJsonSchema.describe("Contents of terraform.tfstate file (JSON)"),
-  files: z4.array(
-    z4.object({
-      path: filePathSchema.describe("File path"),
-      content: fileContentSchema.describe("File content (HCL)")
-    })
-  ).max(2e3, "files array exceeds 2000 entries").optional().describe("Optional Terraform files to compare planned costs against actual"),
-  tfvars: tfvarsSchema.optional().describe("Contents of terraform.tfvars file"),
-  provider: z4.enum(["aws", "azure", "gcp"]).optional().describe("Target cloud provider override. Defaults to auto-detecting from the state."),
-  region: z4.string().optional().describe(
+  files: iacFilesSchema.optional().describe("Optional Terraform files to compare planned costs against actual"),
+  tfvars: tfvarsField,
+  provider: providerEnum.optional().describe("Target cloud provider override. Defaults to auto-detecting from the state."),
+  region: shortStringSchema.optional().describe(
     "Target region override for pricing. Defaults to the region detected from the state."
   ),
-  currency: z4.enum(SUPPORTED_CURRENCIES).optional().default("USD").describe("Output currency for cost estimates. Defaults to USD.")
+  currency: currencyField
 });
 async function compareActual(params, pricingEngine, config) {
   const warnings = [];
@@ -722,7 +724,8 @@ async function compareActual(params, pricingEngine, config) {
       resource_count: stateInventory.total_count,
       by_resource: actualByResource
     },
-    warnings: []
+    warnings: [],
+    pricing_metadata: getPricingMetadata(targetProvider)
   };
   if (params.files && params.files.length > 0) {
     const plannedInventory = await parseTerraform(params.files, params.tfvars);
@@ -756,6 +759,7 @@ async function compareActual(params, pricingEngine, config) {
     };
   }
   if (currency !== "USD") {
+    result.exchange_rate = getExchangeRateInfo(currency);
     const actualConverted = convertBreakdownCurrency(actualBreakdown, currency);
     result.actual_costs.total_monthly = Math.round(actualConverted.total_monthly * 100) / 100;
     result.actual_costs.total_yearly = Math.round(actualConverted.total_monthly * 12 * 100) / 100;
@@ -807,16 +811,11 @@ function priceTrends(params, cache) {
 // src/tools/detect-anomalies.ts
 import { z as z6 } from "zod";
 var detectAnomaliesSchema = z6.object({
-  files: z6.array(
-    z6.object({
-      path: filePathSchema.describe("File path"),
-      content: fileContentSchema.describe("File content")
-    })
-  ).max(2e3, "files array exceeds 2000 entries"),
-  tfvars: tfvarsSchema.optional().describe("Variable overrides"),
-  provider: z6.enum(["aws", "azure", "gcp"]).describe("Target cloud provider"),
-  region: z6.string().optional().describe("Target region"),
-  currency: z6.enum(SUPPORTED_CURRENCIES).optional().default("USD").describe("Output currency for cost estimates. Defaults to USD."),
+  files: iacFilesSchema,
+  tfvars: tfvarsField,
+  provider: providerEnum.describe("Target cloud provider"),
+  region: shortStringSchema.optional().describe("Target region"),
+  currency: currencyField,
   budget_monthly: z6.number().optional().describe("Monthly budget threshold in USD"),
   budget_per_resource: z6.number().optional().describe("Per-resource cost threshold in USD"),
   price_change_threshold: z6.number().optional().default(10).describe("Alert on price changes exceeding this percentage")
@@ -882,12 +881,13 @@ async function detectAnomalies(params, pricingEngine, cache, config) {
   }
   for (const est of byResource) {
     if (params.budget_per_resource != null && est.monthly_cost > params.budget_per_resource) {
+      const safeId = sanitizeForMessage(est.resource_id, 256);
       anomalies.push({
         type: "budget_exceeded",
         severity: "high",
-        resource: est.resource_id,
-        resource_type: est.resource_type,
-        message: `Resource ${est.resource_id} costs $${est.monthly_cost.toFixed(2)}/mo, exceeding per-resource budget of $${params.budget_per_resource.toFixed(2)}`,
+        resource: safeId,
+        resource_type: sanitizeForMessage(est.resource_type, 128),
+        message: `Resource ${safeId} costs $${est.monthly_cost.toFixed(2)}/mo, exceeding per-resource budget of $${params.budget_per_resource.toFixed(2)}`,
         details: {
           current_cost: est.monthly_cost,
           threshold: params.budget_per_resource
@@ -903,19 +903,20 @@ async function detectAnomalies(params, pricingEngine, cache, config) {
     const priceChange = cache.getPriceChange(targetProvider, service, resourceKey, targetRegion);
     if (priceChange && Math.abs(priceChange.change_percent) > priceChangeThreshold) {
       const direction = priceChange.change_percent > 0 ? "increased" : "decreased";
+      const safeId = sanitizeForMessage(est.resource_id, 256);
       anomalies.push({
         type: "price_change",
         severity: Math.abs(priceChange.change_percent) > 20 ? "high" : "medium",
-        resource: est.resource_id,
-        resource_type: est.resource_type,
-        message: `Pricing for ${est.resource_id} has ${direction} by ${Math.abs(priceChange.change_percent).toFixed(1)}%`,
+        resource: safeId,
+        resource_type: sanitizeForMessage(est.resource_type, 128),
+        message: `Pricing for ${safeId} has ${direction} by ${Math.abs(priceChange.change_percent).toFixed(1)}%`,
         details: {
           current_cost: est.monthly_cost,
           price_change_percent: priceChange.change_percent
         }
       });
       recommendations.push(
-        `Review pricing change for ${est.resource_id} (${Math.abs(priceChange.change_percent).toFixed(1)}% ${direction}). Consider locking in reserved pricing.`
+        `Review pricing change for ${safeId} (${Math.abs(priceChange.change_percent).toFixed(1)}% ${direction}). Consider locking in reserved pricing.`
       );
     }
   }
@@ -923,19 +924,20 @@ async function detectAnomalies(params, pricingEngine, cache, config) {
     for (const est of byResource) {
       const sharePercent = est.monthly_cost / totalMonthly * 100;
       if (sharePercent > 50 && byResource.length > 1) {
+        const safeId = sanitizeForMessage(est.resource_id, 256);
         anomalies.push({
           type: "cost_concentration",
           severity: "medium",
-          resource: est.resource_id,
-          resource_type: est.resource_type,
-          message: `Resource ${est.resource_id} accounts for ${sharePercent.toFixed(1)}% of total cost (concentration risk)`,
+          resource: safeId,
+          resource_type: sanitizeForMessage(est.resource_type, 128),
+          message: `Resource ${safeId} accounts for ${sharePercent.toFixed(1)}% of total cost (concentration risk)`,
           details: {
             current_cost: est.monthly_cost,
             cost_share_percent: sharePercent
           }
         });
         recommendations.push(
-          `${est.resource_id} dominates total spend at ${sharePercent.toFixed(1)}%. Evaluate whether workload can be distributed or right-sized.`
+          `${safeId} dominates total spend at ${sharePercent.toFixed(1)}%. Evaluate whether workload can be distributed or right-sized.`
         );
       }
     }
@@ -943,18 +945,20 @@ async function detectAnomalies(params, pricingEngine, cache, config) {
   for (const est of byResource) {
     const instanceType = resolveInstanceType(est);
     if (isOversizedInstance(instanceType)) {
+      const safeId = sanitizeForMessage(est.resource_id, 256);
+      const safeType = instanceType ? sanitizeForMessage(instanceType, 64) : "(unknown)";
       anomalies.push({
         type: "potential_oversizing",
         severity: "low",
-        resource: est.resource_id,
-        resource_type: est.resource_type,
-        message: `Instance ${est.resource_id} uses ${instanceType} which may be over-provisioned`,
+        resource: safeId,
+        resource_type: sanitizeForMessage(est.resource_type, 128),
+        message: `Instance ${safeId} uses ${safeType} which may be over-provisioned`,
         details: {
           current_cost: est.monthly_cost
         }
       });
       recommendations.push(
-        `Consider whether ${est.resource_id} (${instanceType}) needs all allocated resources. Smaller instance types can significantly reduce cost.`
+        `Consider whether ${safeId} (${safeType}) needs all allocated resources. Smaller instance types can significantly reduce cost.`
       );
     }
   }
@@ -984,131 +988,323 @@ function resolveInstanceType(est) {
   return void 0;
 }
 
+// src/tools/check-cost-budget.ts
+import { z as z7 } from "zod";
+var checkCostBudgetSchema = z7.object({
+  files: iacFilesSchema.describe(
+    "IaC files to evaluate (Terraform, CloudFormation, Pulumi, or Bicep/ARM)"
+  ),
+  tfvars: tfvarsField,
+  provider: providerEnum.optional().describe(
+    "Target cloud provider. Defaults to the provider detected in the files; if no provider can be detected and none is passed, the call returns a structured error rather than silently picking AWS."
+  ),
+  region: shortStringSchema.optional().describe("Target region. Defaults to the region detected in the files."),
+  currency: currencyField.describe(
+    "Currency for the threshold comparisons and output. Defaults to USD."
+  ),
+  max_monthly: z7.number().positive().finite().optional().describe(
+    "Aggregate monthly spend threshold. If the estimated total exceeds this, verdict is 'block'. Falls back to CLOUDCOST_GUARDRAIL_MAX_MONTHLY env var, then CLOUDCOST_BUDGET_MONTHLY."
+  ),
+  max_per_resource: z7.number().positive().finite().optional().describe(
+    "Per-resource monthly cost threshold. Any single resource above this forces a 'block' verdict. Falls back to CLOUDCOST_GUARDRAIL_MAX_PER_RESOURCE env var, then CLOUDCOST_BUDGET_PER_RESOURCE."
+  ),
+  warn_ratio: z7.number().gt(0).max(1).optional().describe(
+    "Fraction of a threshold at which to emit 'warn' rather than 'allow'. Must be > 0 and \u2264 1. Default 0.8 (warn at 80%)."
+  )
+});
+function pickThreshold(fromParams, fromConfig, fromBudget) {
+  if (fromParams != null) return { value: fromParams, source: "params" };
+  if (fromConfig != null) return { value: fromConfig, source: "config" };
+  if (fromBudget != null) return { value: fromBudget, source: "budget" };
+  return { value: void 0, source: "none" };
+}
+function resolveThresholds(params, config) {
+  const guardrail = config.guardrail ?? {};
+  const budget = config.budget ?? {};
+  const monthly = pickThreshold(params.max_monthly, guardrail.max_monthly, budget.monthly_limit);
+  const perResource = pickThreshold(
+    params.max_per_resource,
+    guardrail.max_per_resource,
+    budget.per_resource_limit
+  );
+  return {
+    max_monthly: monthly.value,
+    max_per_resource: perResource.value,
+    warn_ratio: params.warn_ratio ?? guardrail.warn_ratio ?? 0.8,
+    source: { max_monthly: monthly.source, max_per_resource: perResource.source }
+  };
+}
+async function checkCostBudget(params, pricingEngine, config) {
+  const thresholds = resolveThresholds(params, config);
+  const currency = params.currency ?? "USD";
+  const inventory = await parseTerraform(params.files, params.tfvars);
+  const resolvedProvider = params.provider ?? inventory.provider;
+  if (!resolvedProvider) {
+    return {
+      verdict: "block",
+      total_monthly: 0,
+      currency,
+      resource_count: inventory.resources.length,
+      thresholds,
+      reasons: [
+        "provider could not be determined from the input \u2014 pass `provider` explicitly (aws|azure|gcp)"
+      ],
+      blocking_resources: [],
+      warning_resources: [],
+      summary: "block: provider could not be determined",
+      error: "provider_unresolved"
+    };
+  }
+  const targetProvider = resolvedProvider;
+  const targetRegion = params.region ?? mapRegion(inventory.region, inventory.provider, targetProvider);
+  const pricingMetadata = getPricingMetadata(targetProvider);
+  const exchangeRate = currency !== "USD" ? getExchangeRateInfo(currency) : void 0;
+  const costEngine = new CostEngine(pricingEngine, config);
+  let breakdown = await costEngine.calculateBreakdown(
+    inventory.resources,
+    targetProvider,
+    targetRegion
+  );
+  if (currency !== "USD") {
+    breakdown = convertBreakdownCurrency(breakdown, currency);
+  }
+  const totalMonthly = breakdown.total_monthly;
+  const resourceCount = breakdown.by_resource.length;
+  if (!Number.isFinite(totalMonthly)) {
+    return {
+      verdict: "block",
+      total_monthly: 0,
+      currency,
+      resource_count: resourceCount,
+      thresholds,
+      reasons: ["total cost computed as non-finite value \u2014 internal pricing error"],
+      blocking_resources: [],
+      warning_resources: [],
+      summary: "block: non-finite total cost",
+      pricing_metadata: pricingMetadata,
+      ...exchangeRate && { exchange_rate: exchangeRate },
+      error: "non_finite_total"
+    };
+  }
+  const blocking = [];
+  const warning = [];
+  const reasons = [];
+  if (thresholds.max_monthly == null && thresholds.max_per_resource == null) {
+    return {
+      verdict: "allow",
+      total_monthly: totalMonthly,
+      currency,
+      resource_count: resourceCount,
+      thresholds,
+      reasons: [
+        "no budget thresholds configured \u2014 pass max_monthly / max_per_resource or set CLOUDCOST_GUARDRAIL_MAX_MONTHLY / CLOUDCOST_GUARDRAIL_MAX_PER_RESOURCE"
+      ],
+      blocking_resources: [],
+      warning_resources: [],
+      summary: `allow: no thresholds configured (${resourceCount} resources, ${formatMoney(totalMonthly, currency)}/mo)`,
+      pricing_metadata: pricingMetadata,
+      ...exchangeRate && { exchange_rate: exchangeRate }
+    };
+  }
+  const totalOver = thresholds.max_monthly != null && totalMonthly > thresholds.max_monthly;
+  const totalWarn = !totalOver && thresholds.max_monthly != null && totalMonthly >= thresholds.max_monthly * thresholds.warn_ratio;
+  if (totalOver) {
+    reasons.push(
+      `total ${formatMoney(totalMonthly, currency)}/mo exceeds threshold ${formatMoney(thresholds.max_monthly, currency)}/mo`
+    );
+  } else if (totalWarn) {
+    const pct = Math.round(totalMonthly / thresholds.max_monthly * 100);
+    reasons.push(
+      `total ${formatMoney(totalMonthly, currency)}/mo is ${pct}% of threshold ${formatMoney(thresholds.max_monthly, currency)}/mo`
+    );
+  }
+  if (thresholds.max_per_resource != null) {
+    for (const est of breakdown.by_resource) {
+      if (!Number.isFinite(est.monthly_cost)) continue;
+      const safeId = sanitizeForMessage(est.resource_id, 256);
+      const safeType = sanitizeForMessage(est.resource_type, 128);
+      if (est.monthly_cost > thresholds.max_per_resource) {
+        blocking.push({
+          resource_id: safeId,
+          resource_type: safeType,
+          monthly_cost: est.monthly_cost,
+          threshold: thresholds.max_per_resource,
+          reason: `${formatMoney(est.monthly_cost, currency)}/mo exceeds per-resource limit ${formatMoney(thresholds.max_per_resource, currency)}/mo`
+        });
+      } else if (est.monthly_cost >= thresholds.max_per_resource * thresholds.warn_ratio) {
+        const pct = Math.round(est.monthly_cost / thresholds.max_per_resource * 100);
+        warning.push({
+          resource_id: safeId,
+          resource_type: safeType,
+          monthly_cost: est.monthly_cost,
+          threshold: thresholds.max_per_resource,
+          reason: `${formatMoney(est.monthly_cost, currency)}/mo is ${pct}% of per-resource limit ${formatMoney(thresholds.max_per_resource, currency)}/mo`
+        });
+      }
+    }
+  }
+  let verdict = "allow";
+  if (totalOver || blocking.length > 0) {
+    verdict = "block";
+  } else if (totalWarn || warning.length > 0) {
+    verdict = "warn";
+  }
+  const summaryParts = [
+    `${verdict}: ${formatMoney(totalMonthly, currency)}/mo across ${resourceCount} resource${resourceCount === 1 ? "" : "s"}`
+  ];
+  if (totalOver) {
+    summaryParts.push(`total over threshold ${formatMoney(thresholds.max_monthly, currency)}`);
+  }
+  if (blocking.length) {
+    summaryParts.push(
+      `${blocking.length} resource${blocking.length === 1 ? "" : "s"} over per-resource limit`
+    );
+  }
+  if (warning.length) {
+    summaryParts.push(
+      `${warning.length} resource${warning.length === 1 ? "" : "s"} near per-resource limit`
+    );
+  }
+  return {
+    verdict,
+    total_monthly: totalMonthly,
+    currency,
+    resource_count: resourceCount,
+    thresholds,
+    reasons,
+    blocking_resources: blocking,
+    warning_resources: warning,
+    summary: summaryParts.join("; "),
+    pricing_metadata: pricingMetadata,
+    ...exchangeRate && { exchange_rate: exchangeRate }
+  };
+}
+function formatMoney(amount, currency) {
+  const safe = Number.isFinite(amount) ? amount : 0;
+  const symbol = currency === "USD" ? "$" : `${currency} `;
+  return `${symbol}${safe.toFixed(2)}`;
+}
+
 // src/tools/index.ts
+function jsonResult(value, isError) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    ...isError ? { isError: true } : {}
+  };
+}
+function registerJsonTool(server, name, description, schema, handler, resultIsError) {
+  server.registerTool(
+    name,
+    {
+      description,
+      inputSchema: schema.shape,
+      annotations: { readOnlyHint: true }
+    },
+    async (params) => {
+      try {
+        const result = await handler(params);
+        return jsonResult(result, resultIsError?.(result) ?? false);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`tool ${name} failed`, { error: message });
+        return jsonResult({ error: message }, true);
+      }
+    }
+  );
+}
 function registerTools(server, config) {
   const cache = new PricingCache(config.cache.db_path);
   const pricingEngine = new PricingEngine(cache, config);
-  server.tool(
+  registerJsonTool(
+    server,
     "analyze_terraform",
     "Parse Terraform HCL files and extract a resource inventory with provider detection, variable resolution, and cost-relevant attribute extraction",
-    analyzeTerraformSchema.shape,
-    async (params) => {
-      const result = await analyzeTerraform(params);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    analyzeTerraformSchema,
+    (params) => analyzeTerraform(params)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "estimate_cost",
     "Estimate monthly and yearly cloud costs for Terraform resources on a specific provider. Returns a full cost breakdown by resource and service category.",
-    estimateCostSchema.shape,
-    async (params) => {
-      const result = await estimateCost(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    estimateCostSchema,
+    (params) => estimateCost(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "compare_providers",
     "Run a full cost comparison across AWS, Azure, and GCP for a set of Terraform resources. Returns a formatted report and raw comparison data including savings potential.",
-    compareProvidersSchema.shape,
-    async (params) => {
-      const result = await compareProviders(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    compareProvidersSchema,
+    (params) => compareProviders(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "get_equivalents",
     "Look up the equivalent Terraform resource types across cloud providers. Optionally also maps an instance type / VM size to the nearest equivalent on target providers.",
-    getEquivalentsSchema.shape,
-    async (params) => {
-      const result = await getEquivalents(params);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    getEquivalentsSchema,
+    (params) => getEquivalents(params)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "get_pricing",
     "Direct pricing lookup for a specific cloud provider, service, resource type, and region. Returns the normalised unit price with metadata.",
-    getPricingSchema.shape,
-    async (params) => {
-      const result = await getPricing(params, pricingEngine);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    getPricingSchema,
+    (params) => getPricing(params, pricingEngine)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "optimize_cost",
     "Analyse Terraform resources and return cost optimisation recommendations including right-sizing suggestions, reserved pricing comparisons, and cross-provider savings opportunities.",
-    optimizeCostSchema.shape,
-    async (params) => {
-      const result = await optimizeCost(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    optimizeCostSchema,
+    (params) => optimizeCost(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "what_if",
     "Estimate cost impact of infrastructure changes without modifying Terraform files. Applies attribute overrides to a cloned resource set and returns a per-resource and aggregate cost diff.",
-    whatIfSchema.shape,
-    async (params) => {
-      const result = await whatIf(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    whatIfSchema,
+    (params) => whatIf(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "analyze_plan",
     "Parse Terraform plan JSON (from 'terraform show -json' or 'terraform plan -json') and return a cost-of-change analysis showing before/after costs and per-resource deltas.",
-    analyzePlanSchema.shape,
-    async (params) => {
-      const result = await analyzePlan(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    analyzePlanSchema,
+    (params) => analyzePlan(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "compare_actual",
     "Parse a Terraform state file (.tfstate) and calculate actual infrastructure costs. Optionally compare against planned costs from HCL files to show drift.",
-    compareActualSchema.shape,
-    async (params) => {
-      const result = await compareActual(params, pricingEngine, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    compareActualSchema,
+    (params) => compareActual(params, pricingEngine, config)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "price_trends",
     "Query historical pricing trends for a specific cloud resource. Returns recorded price history, the most recent price change, and summary metadata.",
-    priceTrendsSchema.shape,
-    (params) => {
-      const result = priceTrends(params, cache);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    priceTrendsSchema,
+    (params) => priceTrends(params, cache)
   );
-  server.tool(
+  registerJsonTool(
+    server,
     "detect_anomalies",
     "Analyze infrastructure costs and flag anomalies \u2014 resources whose estimated costs are unusual compared to historical baselines or configured thresholds.",
-    detectAnomaliesSchema.shape,
-    async (params) => {
-      const result = await detectAnomalies(params, pricingEngine, cache, config);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result) }]
-      };
-    }
+    detectAnomaliesSchema,
+    (params) => detectAnomalies(params, pricingEngine, cache, config)
   );
+  registerJsonTool(
+    server,
+    "check_cost_budget",
+    "Agent-ready cost guardrail. Returns allow / warn / block with blocking_resources so an AI agent can veto an expensive IaC write before committing. Thresholds cascade: per-call params > CLOUDCOST_GUARDRAIL_* env > CLOUDCOST_BUDGET_* env > no-op allow.",
+    checkCostBudgetSchema,
+    (params) => checkCostBudget(params, pricingEngine, config),
+    // check_cost_budget returns structured errors (error: "provider_unresolved"
+    // | "non_finite_total") instead of throwing; surface those as isError too.
+    (result) => typeof result === "object" && result !== null && typeof result.error === "string"
+  );
+  return () => {
+    cache.close();
+  };
 }
 
 // src/server.ts
@@ -1121,26 +1317,54 @@ async function startServer() {
     name: "cloudcost-mcp",
     version
   });
-  registerTools(server, config);
+  const closeTools = registerTools(server, config);
   const transport = new StdioServerTransport();
   logger.info("Starting CloudCost MCP server");
   await server.connect(transport);
+  return async () => {
+    logger.info("Shutting down CloudCost MCP server");
+    await server.close();
+    closeTools();
+  };
 }
 
 // src/index.ts
+var shutdown = null;
+var exiting = false;
+async function closeAndExit(code) {
+  if (exiting) return;
+  exiting = true;
+  try {
+    await shutdown?.();
+  } catch (err) {
+    const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+    process.stderr.write(`Error during shutdown: ${msg}
+`);
+  }
+  process.exit(code);
+}
+process.on("SIGINT", () => {
+  void closeAndExit(0);
+});
+process.on("SIGTERM", () => {
+  void closeAndExit(0);
+});
 process.on("uncaughtException", (err) => {
   process.stderr.write(`Uncaught exception: ${err.stack ?? err.message}
 `);
-  process.exit(1);
+  void closeAndExit(1);
 });
 process.on("unhandledRejection", (reason) => {
   const msg = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
   process.stderr.write(`Unhandled rejection: ${msg}
 `);
-  process.exit(1);
+  void closeAndExit(1);
 });
-startServer().catch((err) => {
-  process.stderr.write(`Failed to start server: ${err.stack ?? err.message}
+startServer().then((stop) => {
+  shutdown = stop;
+}).catch((err) => {
+  const msg = err instanceof Error ? err.stack ?? err.message : String(err);
+  process.stderr.write(`Failed to start server: ${msg}
 `);
   process.exit(1);
 });