@jadenrazo/cloudcost-mcp 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,13 +4,64 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [1.2.0] - 2026-08-07
+
+> Released as 1.2.0, not 1.1.0. The `v1.1.0` tag was already taken by an earlier
+> 2026-04-16 release that was superseded by the `v1.0.1` hotfix and never
+> published to npm; npm therefore goes `1.0.1` → `1.2.0`.
+
+### Added
+
+- **`check_cost_budget` MCP tool**: agent-ready cost guardrail that returns `allow` / `warn` / `block` with `blocking_resources` populated. Designed to be called by an AI agent between generating IaC and writing it to disk, so a model can't silently commit a runaway configuration. Promotes the budget primitives that previously only lived inside `detect_anomalies`. See [docs/guardrails.md](./docs/guardrails.md) for integration patterns.
+- New env vars: `CLOUDCOST_GUARDRAIL_MAX_MONTHLY`, `CLOUDCOST_GUARDRAIL_MAX_PER_RESOURCE`, `CLOUDCOST_GUARDRAIL_WARN_RATIO`. Thresholds cascade: per-call params → `guardrail` env → `budget` env.
+- New `GuardrailConfig` type on `CloudCostConfig`.
+
+### Security
+
+- Defense-in-depth on outbound HTTP: the AWS pricing fetchers (`bulk-loader`, `reserved-client`) now validate region and service against a strict allowlist, pin fetches to `pricing.us-east-1.amazonaws.com`, enforce HTTPS, and cap response bodies at 512 MiB. Extends the v1.0.1 MCP-surface hardening down into the network layer. Closes URL-injection via attacker-controlled region/service strings and caps OOM risk from a misbehaving upstream.
+
+### Changed
+
+- MCP tools migrated from the deprecated `server.tool()` to `server.registerTool()`. Every tool now advertises `annotations.readOnlyHint: true`, and handler failures return a JSON `{error}` text payload with `isError: true` instead of a protocol-level failure. `check_cost_budget`'s structured error results (`provider_unresolved`, `non_finite_total`) also set `isError`. Result payloads remain JSON text in `content[0].text` — no client-facing format change.
+- Graceful shutdown: SIGINT/SIGTERM now close the MCP server connection and the SQLite pricing cache before exit; `unhandledRejection` logs, closes, and exits instead of hard-exiting.
+- Per-resource `monthly_cost` / `yearly_cost` on every `CostEstimate` are now consistently rounded to cents via the new shared estimate factory (previously only data-transfer estimates were rounded; totals were already rounded).
+- Data-transfer (egress) estimates now read regional multipliers from the shared `data/region-price-multipliers.json` instead of drifted per-provider in-file tables; estimates in non-baseline regions shift slightly.
+- Azure and GCP pricing normalizers validate/canonicalize upstream effective dates the same way AWS does (invalid dates fall back to "now"; valid ones normalize to ISO `.000Z` form).
+- Coverage thresholds in `vitest.config.ts` set to 75 / 71 / 80 / 75 (statements / branches / functions / lines) and now enforced in CI: the test job runs `npm run test:coverage`, so a regression below the floor fails the build. 71 is the measured branch-coverage floor at gate-enable time; the other thresholds were already met.
+- Lint upgraded to typescript-eslint `recommendedTypeChecked` for `src/` with `@typescript-eslint/no-explicit-any` promoted to error; the publish workflow now runs `npm run lint` before publishing and attaches a CycloneDX SBOM (`sbom.cdx.json`) to each GitHub release.
+- README: corrected the Limitations bullet that implied AWS Savings Plans were supported via `optimize_cost`. Savings Plans are not yet supported and are tracked in [docs/roadmap.md](./docs/roadmap.md).
+
+### Tests
+
+- `src/reporting/csv-escape.ts` extracted out of `csv-report` and `focus-report`; dedicated `csv-escape.test.ts` covers the formula-injection defense surface.
+- `test/helpers/factories.ts` + `setup.ts` centralise test fixture construction; `test/integration/full-stack.test.ts` replaces the older end-to-end test with wider tool coverage.
+- New unit tests: `api-gateway`, `messaging`, `ml-ai`, `search`, `waf`, `csv-parser`, `resource-extractor`, `markdown-report`, `check-cost-budget`.
+- New `register-tools` suite locks the MCP surface: all 12 tools register, names match VERSIONING.md's locked table, every tool carries `readOnlyHint`, and the error envelope (`isError` + JSON `{error}`) is exercised end-to-end over an in-memory transport.
+
+## [1.0.1] - 2026-04-18
+
+### Security
+
+Hardened the MCP tool surface against the attack classes catalogued in the OWASP MCP Top 10 (2025) and recent SDK advisories. No breaking API changes.
+
+- **Path traversal in module resolution (HIGH)**: A `module { source = "../../../etc" }` declaration in user-supplied HCL previously resolved without any containment check, turning any file-accepting tool into an arbitrary `*.tf` read primitive. All resolved paths are now confined to `process.cwd()` by default (configurable), symlinks are rejected, and `modules.json` entries are re-validated against the boundary. Added `src/parsers/path-safety.ts`.
+- **MCP SDK floor (MED)**: Bumped `@modelcontextprotocol/sdk` minimum from `^1.12.1` to `^1.25.2` so fresh installs cannot resolve a version affected by CVE-2025-66414 (DNS rebinding, `< 1.24.0`) or CVE-2026-0621 (UriTemplate ReDoS, `< 1.25.2`).
+- **Prototype pollution in `plan_json` / `state_json` (MED)**: Raw `JSON.parse` on user input followed by deep-merge was vulnerable to `__proto__` / `constructor` / `prototype` payloads. Added `safeJsonParse` with a reviver that strips these keys, applied to the Terraform plan and state parsers and to the HCL-JSON merge in `module-resolver`.
+- **Output-channel prompt injection ("Poison Everywhere", MED)**: User-supplied filenames, module names, and error strings were echoed verbatim into error responses and warnings. Added `sanitizeForMessage` which strips ASCII control characters, zero-width / bidi-override characters, and caps length; applied at every point where tool results flow back to the MCP client.
+- **Input-size DoS (LOW-MED)**: Tool inputs had no size limits. Added Zod `.max()` on every accepting schema — 5 MiB per file, 20 MiB per plan/state payload, 1 KiB per path, max 2000 files per request.
+
+### Tests
+
+- Added `test/unit/security/mcp-hardening.test.ts` with 19 regression tests covering sanitisation, prototype-pollution guards, path-boundary enforcement, symlink rejection, and every new Zod size limit.
+
 ## [1.0.0] - 2026-04-15
 
-First stable release. No breaking API changes from 0.5 — this version ratifies the existing surface as SemVer-locked. See [`MIGRATION.md`](./MIGRATION.md) for details.
+First stable release. No breaking API changes from 0.5 — this version ratifies the existing surface as SemVer-locked. See [`VERSIONING.md`](./VERSIONING.md#migration-notes) for details.
 
 ### Added
-- **`STABILITY.md`**: Formal stability contract defining the SemVer-locked public surface (11 MCP tools, CLI binaries, package entry points) and the change-classification policy.
-- **`MIGRATION.md`**: 0.x → 1.0 migration guide and forward-looking support policy.
+- **`VERSIONING.md`**: Formal stability contract defining the SemVer-locked public surface (12 MCP tools, CLI binaries, package entry points), the change-classification policy, and the 0.x → 1.0 migration notes. (At release this lived in two files, `STABILITY.md` and `MIGRATION.md`; they were later consolidated.)
 - **Smoke integration tests**: Live-API smoke coverage for AWS Bulk Pricing, Azure Retail Prices, and GCP Cloud Billing Catalog, gated behind `RUN_INTEGRATION=1`. New `integration-smoke` CI job runs on manual dispatch and weekly schedule (Mondays 12:00 UTC).
 - **Publish workflow gates**: `npm audit --audit-level=high` and `npm test` now run before `npm publish`, preventing broken or vulnerable releases.
 
@@ -23,7 +74,7 @@ First stable release. No breaking API changes from 0.5 — this version ratifies
 - `npm audit --audit-level=high` now reports zero vulnerabilities.
 
 ### Packaging
-- `STABILITY.md`, `MIGRATION.md`, and `CHANGELOG.md` are now included in the published npm tarball.
+- `VERSIONING.md` and `CHANGELOG.md` are now included in the published npm tarball. (Originally shipped as `STABILITY.md` + `MIGRATION.md`, now merged.)
 
 ## [0.4.0] - 2026-03-28
 
@@ -44,7 +95,7 @@ First stable release. No breaking API changes from 0.5 — this version ratifies
 - **Performance benchmarks**: Parsing, pricing cache, and calculator benchmarks via `vitest bench`
 - **CI hardening**: Security audit job, Prettier format check, concurrency groups, job timeouts
 - **SECURITY.md**: Vulnerability reporting policy and security design documentation
-- **ARCHITECTURE.md**: Layered architecture documentation with extension guides
+- **`docs/architecture.md`**: Layered architecture documentation with extension guides (originally at repo root, moved to `docs/` in a later cleanup).
 
 ### Changed
 - Refactored `bulk-loader.ts` (929 -> 708 lines) into focused modules: csv-parser, fallback-data

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://github.com/jadenrazo/CloudCostMCP/actions/workflows/ci.yml"><img src="https://github.com/jadenrazo/CloudCostMCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://www.npmjs.com/package/@jadenrazo/cloudcost-mcp"><img src="https://img.shields.io/npm/v/@jadenrazo/cloudcost-mcp.svg" alt="npm version" /></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js" />
+  <img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen" alt="Node.js" />
 </p>
 
 <p align="right">
@@ -53,28 +53,55 @@ CloudCost MCP is a [Model Context Protocol](https://modelcontextprotocol.io) ser
 | Pulumi | `.json` (stack export) | Yes |
 | Bicep/ARM | `.json` (ARM template) | Yes |
 
+### How this compares to Infracost
+
+Infracost is the mature choice for **Terraform-on-AWS cost estimation in CI** — PR-comment cost deltas, threshold gating, deep Terragrunt support. If that's your workflow, use it.
+
+CloudCostMCP targets a different surface:
+
+- **Agent-native via MCP.** Models call it as a tool *during* generation. `check_cost_budget` returns `allow` / `warn` / `block` with the specific blocking resources named, fast enough on a warm pricing cache for an agent to veto an expensive config before writing it to disk.
+- **Multi-IaC in one server.** Terraform, CloudFormation, Pulumi, Bicep/ARM — one tool, not four.
+- **Zero credentials.** All pricing comes from public endpoints. No account, no cloud IAM, no API keys.
+- **Optimization + what-if scenarios built in.** Right-sizing, reserved-pricing, cross-provider switching, and spot modeling are first-class tools.
+
+The two are complementary. Use Infracost in CI; use CloudCostMCP inside your agent or editor.
+
 ---
 
 ## Installation
 
 Requires **Node.js 20** or later.
 
+### 60-second quick start (Claude Code)
+
 ```bash
+npm install -g @jadenrazo/cloudcost-mcp
+claude mcp add cloudcost -- cloudcost-mcp
+```
+
+Then, inside a project directory with Terraform files, ask Claude:
+
+> *"Use cloudcost to estimate the monthly AWS cost of this Terraform config, then check it against a $2000/month budget with check_cost_budget."*
+
+No API keys, no cloud credentials, no separate account. For other MCP clients (Claude Desktop, Cursor, any MCP-compatible agent), see the detailed setup below.
+
+### All install options
+
+```bash
+# From source
 git clone https://github.com/jadenrazo/CloudCostMCP.git
 cd CloudCostMCP
 npm install
 npm run build
 ```
 
-Or install from npm:
-
 ```bash
+# Global npm install
 npm install -g @jadenrazo/cloudcost-mcp
 ```
 
-Or run directly without installing:
-
 ```bash
+# One-shot, no install
 npx -y @jadenrazo/cloudcost-mcp
 ```
 
@@ -127,7 +154,9 @@ node dist/index.js
 
 ## Tools
 
-The server exposes eleven MCP tools. Each accepts JSON input and returns structured JSON output.
+The server exposes twelve MCP tools. Each accepts JSON input and returns structured JSON output. For agent-centric workflows, `check_cost_budget` is the headline tool: it returns an `allow` / `warn` / `block` verdict fast enough to be called between IaC generation and disk write — see [docs/guardrails.md](./docs/guardrails.md).
+
+Cost-reporting tools (`estimate_cost`, `compare_providers`, `check_cost_budget`, `analyze_plan`, `compare_actual`) also include a `pricing_metadata` block — `{ source, as_of, age_days, staleness }` — describing the vintage of the bundled pricing data behind the numbers (`fresh` < 14 days, `aging` < 45 days, `stale` ≥ 45 days; `compare_providers` reports one block per compared provider). When a non-USD `currency` is requested, responses additionally carry `exchange_rate: { rate, rate_as_of }` — conversions use a static rate snapshot (currently `2026-03`), not a live FX feed.
 
 ### `analyze_terraform`
 
@@ -262,6 +291,21 @@ Cost anomaly detection with budget checks, price changes, concentration risk, an
 | `budget_monthly` | `number` | No | Monthly budget cap in USD |
 | `currency` | `string` | No | Output currency (default: `USD`) |
 
+### `check_cost_budget`
+
+Fast cost-safety guardrail designed for AI agents. Returns `allow` / `warn` / `block` with the specific blocking resources named, so an agent can veto an expensive IaC generation before writing it to disk. Thresholds cascade: per-call params → `CLOUDCOST_GUARDRAIL_*` env → `CLOUDCOST_BUDGET_*` env. See [docs/guardrails.md](./docs/guardrails.md) for integration patterns.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `files` | `{path, content}[]` | Yes | IaC files to evaluate |
+| `tfvars` | `string` | No | Variable overrides |
+| `provider` | `aws \| azure \| gcp` | No | Target provider (auto-detected if omitted) |
+| `region` | `string` | No | Target region (auto-detected if omitted) |
+| `currency` | `string` | No | Output currency (default: `USD`) |
+| `max_monthly` | `number` | No | Aggregate monthly threshold. Over = `block`. |
+| `max_per_resource` | `number` | No | Per-resource threshold. One over = `block`. |
+| `warn_ratio` | `number` (0–1) | No | Fraction of limit that triggers `warn` (default `0.8`) |
+
 ---
 
 ## How Pricing Works
@@ -374,12 +418,15 @@ All configuration is optional. The server works out of the box with sensible def
 | `CLOUDCOST_CACHE_PATH` | `~/.cloudcost/cache.db` | SQLite cache file location |
 | `CLOUDCOST_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
 | `CLOUDCOST_MONTHLY_HOURS` | `730` | Hours per month for cost calculations |
-| `CLOUDCOST_INCLUDE_DATA_TRANSFER` | `false` | Include estimated data transfer costs in reports |
+| `CLOUDCOST_INCLUDE_DATA_TRANSFER` | `true` | Include a synthetic default estimate of 100 GB/month internet egress per provider+region. Its share of the total is surfaced separately as `estimated_egress_monthly` (still included in `total_monthly`) |
 | `CLOUDCOST_PRICING_MODEL` | `on_demand` | Default pricing model: `on_demand`, `spot`, or `reserved` |
 | `CLOUDCOST_RESOLVE_MODULES` | `true` | Expand referenced Terraform modules during parsing |
 | `CLOUDCOST_BUDGET_MONTHLY` | | Monthly budget cap in USD. Triggers a warning when exceeded |
 | `CLOUDCOST_BUDGET_PER_RESOURCE` | | Per-resource monthly budget cap in USD |
 | `CLOUDCOST_BUDGET_WARN_PCT` | `80` | Percentage of budget at which a warning is surfaced (default: 80%) |
+| `CLOUDCOST_GUARDRAIL_MAX_MONTHLY` | | Aggregate monthly ceiling for `check_cost_budget`. Over = `block` verdict |
+| `CLOUDCOST_GUARDRAIL_MAX_PER_RESOURCE` | | Per-resource ceiling for `check_cost_budget`. One over = `block` verdict |
+| `CLOUDCOST_GUARDRAIL_WARN_RATIO` | `0.8` | Fraction of guardrail threshold that triggers `warn` instead of `allow` |
 
 ### Config File
 
@@ -441,13 +488,7 @@ Configuration priority: environment variables > config file > built-in defaults.
   CSV (public)       (public, no auth)      (bundled files)
 ```
 
-### Key Design Decisions
-
-- **Zero API keys.** All pricing comes from public endpoints. AWS uses the unauthenticated Bulk Pricing files. Azure uses the free Retail Prices REST API. GCP queries the Cloud Billing Catalog API with bundled fallback.
-- **SQLite cache.** A single `better-sqlite3` database caches all pricing lookups with configurable TTL. Shared across all tools per server lifetime.
-- **Streaming for large files.** AWS EC2 pricing data (~267 MB CSV) is streamed line-by-line rather than loaded into memory. Prices for a region are extracted in one pass and cached.
-- **Graceful degradation.** If any live pricing source is unavailable, the server falls back to built-in tables with size-interpolation. Every response includes the pricing source so the consumer knows the confidence level.
-- **ESM-only.** Requires Node 20+. All internal imports use `.js` extensions.
+Highlights: zero API keys (all providers exposed via public endpoints), SQLite-backed price cache shared across tool calls, streaming ingest for the 267 MB AWS bulk CSV, and a graceful live → fallback → interpolated-table chain so every response carries a `pricing_source` and `confidence` field. Full layer-by-layer walkthrough and extension guides in [docs/architecture.md](./docs/architecture.md).
 
 ---
 
@@ -475,113 +516,27 @@ Instance type mapping covers 70+ AWS instance types (including Graviton/ARM fami
 
 ## Limitations
 
-- **On-demand pricing only** by default. Prices reflect pay-as-you-go rates. The `optimize_cost` tool will recommend reserved instances and savings plans, but base estimates use on-demand. Pass `pricing_model: "spot"` in `what_if` scenarios to model spot/preemptible pricing.
+- **On-demand pricing only** by default. Prices reflect pay-as-you-go rates. The `optimize_cost` tool recommends reserved instances; AWS Savings Plans are not yet supported (tracked in [docs/roadmap.md](./docs/roadmap.md)). Pass `pricing_model: "spot"` in `what_if` scenarios to model spot/preemptible pricing.
 - **GCP live pricing** is fetched from the Cloud Billing Catalog API with automatic fallback to bundled data when the API is unreachable. Bundled prices may lag slightly behind actual rates.
+- **Fallback-data signaling.** When a live pricing API is unreachable and `estimate_cost` / `compare_providers` / `get_pricing` serve data from bundled or fallback tables, the response includes a `warnings` entry ("using fallback/bundled pricing data for …") so callers can flag stale estimates. Bundled data is refreshed weekly via CI.
+- **Synthetic egress line item.** Unless `CLOUDCOST_INCLUDE_DATA_TRANSFER=false`, every breakdown includes an assumed 100 GB/month of internet egress per provider+region. `total_monthly` includes it (unchanged behavior); its share is reported separately as `estimated_egress_monthly` with an explanatory warning so the composition is visible.
+- **Static FX rates.** Non-USD output is converted with a bundled rate table, not a live feed. Every converted response carries `exchange_rate: { rate, rate_as_of }` so consumers know which snapshot produced the figures.
 - **First request latency**. The initial EC2 pricing lookup for a new AWS region may take 30-120 seconds as the CSV file is streamed. Subsequent lookups for the same region are instant (cached for 24 hours).
 - **Specialty instance types**. GPU instances (p4d, g5, etc.), high-memory (x2idn), and bare-metal types may fall back to interpolated pricing if not in the built-in tables and live fetch fails.
 
 ---
 
-## Troubleshooting
-
-**$0 cost estimates.** The instance type string in your Terraform code probably doesn't match any known pricing data. Check that you're using a real instance type (e.g., `t3.xlarge`) rather than a variable reference that wasn't resolved. Pass your `terraform.tfvars` content via the `tfvars` parameter to resolve variables.
-
-**Slow first request.** The first EC2 pricing lookup for a new region streams the full AWS pricing CSV (~267 MB). One-time cost per region; subsequent lookups hit the local SQLite cache. Set `CLOUDCOST_LOG_LEVEL=debug` to see progress.
-
-**Cache issues.** Delete `~/.cloudcost/cache.db` to clear all cached pricing data. The cache rebuilds automatically on the next request.
-
-**Node version.** Requires Node.js 20+. Uses ESM modules, Web Streams API (`TextDecoderStream`), and `AbortSignal.timeout()`.
-
----
-
-## GitHub Actions
-
-A reusable composite action is included at `.github/actions/cost-estimate/`. It detects changed `.tf` files, runs a cost comparison, and posts the result as a PR comment.
-
-```yaml
-# .github/workflows/cost-estimate.yml
-name: Terraform Cost Estimate
-
-on:
-  pull_request:
-    types: [opened, synchronize]
-
-jobs:
-  cost-estimate:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: ./.github/actions/cost-estimate
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          # terraform_dir: "./terraform"
-          # providers: "aws,azure,gcp"
-          # format: "markdown"
-          # currency: "USD"
-```
-
-The action auto-detects the directory containing changed `.tf` files and skips gracefully when no Terraform changes are present in the PR.
-
----
-
-## Development
-
-```bash
-npm run dev            # Run with tsx (hot reload, no build needed)
-npm test               # Run all tests (vitest)
-npm run test:watch     # Watch mode
-npm run build          # Production build (tsup → dist/)
-npm run lint           # Type check (tsc --noEmit)
-```
-
-### Project Structure
-
-```
-src/
-├── index.ts              # Entry point (process error handlers + start)
-├── server.ts             # MCP server setup, tool registration
-├── config.ts             # Config loader (defaults → file → env vars)
-├── logger.ts             # Structured logger
-├── currency.ts           # Multi-currency conversion and formatting
-├── tools/
-│   ├── ...               # MCP tool handlers + Zod schemas
-│   └── what-if.ts        # Hypothetical scenario modeling
-├── parsers/
-│   ├── ...               # HCL parsing, variable resolution
-│   ├── module-resolver.ts  # Terraform module expansion
-│   └── dependency-graph.ts # Resource dependency graph builder
-├── pricing/
-│   ├── pricing-engine.ts # Router: dispatches to provider adapters
-│   ├── cache.ts          # SQLite-backed pricing cache
-│   ├── aws/              # Bulk CSV streaming + JSON + fallback
-│   ├── azure/            # Retail Prices REST API + fallback
-│   └── gcp/
-│       ├── bundled-loader.ts    # Static bundled pricing fallback
-│       └── cloud-billing-client.ts  # Live GCP Cloud Billing Catalog API
-├── calculator/
-│   ├── ...               # Cost calculations per resource type
-│   ├── projection.ts     # Multi-horizon cost projections
-│   ├── container-registry.ts
-│   ├── secrets.ts
-│   └── dns.ts
-├── mapping/              # Cross-provider resource/instance mapping
-├── reporting/
-│   ├── ...               # Markdown, JSON, CSV formatters
-│   └── focus-report.ts   # FOCUS-compliant export format
-└── types/                # Shared TypeScript interfaces
-
-data/
-├── instance-map.json     # Bidirectional instance type mappings
-├── storage-map.json      # Cross-provider storage type mappings
-├── gcp-pricing/          # Bundled GCP pricing data
-└── instance-types/       # Instance type metadata
-```
+## More docs
+
+- **[docs/guardrails.md](./docs/guardrails.md)** — `check_cost_budget` integration patterns for Claude Code, Cursor, and other agents.
+- **[docs/architecture.md](./docs/architecture.md)** — internal layers, design decisions, extension guides.
+- **[docs/ci-integration.md](./docs/ci-integration.md)** — GitHub Actions cost-estimate composite action for PR comments.
+- **[docs/development.md](./docs/development.md)** — local setup, npm scripts, source layout.
+- **[docs/troubleshooting.md](./docs/troubleshooting.md)** — `$0` estimates, slow first request, cache issues, fallback warnings.
+- **[docs/roadmap.md](./docs/roadmap.md)** — what's shipped, in flight, backlog, and explicitly not planned.
+- **[VERSIONING.md](./VERSIONING.md)** — SemVer-locked public surface and support policy.
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — PR guidelines and code style.
+- **[SECURITY.md](./SECURITY.md)** — vulnerability reporting.
 
 ---
 

package/VERSIONING.md

@@ -0,0 +1,99 @@
+# Versioning & Stability
+
+Starting with v1.0.0, CloudCostMCP follows [Semantic Versioning](https://semver.org/). This document defines the **stable public surface** covered by that guarantee, the change-classification rules that determine major/minor/patch bumps, the support policy, and notes for anyone migrating from v0.x.
+
+## Stable surface (SemVer-locked)
+
+Changes to anything in this section are breaking and require a major version bump.
+
+### MCP tools
+
+The following 12 tools and their input schemas are locked. Their names, required fields, and the type shape of their output are stable. See `src/tools/*.ts` for the Zod schemas.
+
+| Tool                 | Purpose                                                                   |
+| -------------------- | ------------------------------------------------------------------------- |
+| `analyze_terraform`  | Parse Terraform HCL and extract a resource inventory                      |
+| `estimate_cost`      | Estimate monthly/yearly cost for a Terraform resource set on one provider |
+| `compare_providers`  | Full multi-cloud cost comparison with savings analysis                    |
+| `get_equivalents`    | Map Terraform resource types and instance sizes across providers          |
+| `get_pricing`        | Direct pricing lookup for a service/resource/region                       |
+| `optimize_cost`      | Right-sizing and reserved-pricing recommendations                         |
+| `what_if`            | Scenario cost modeling without modifying source files                     |
+| `analyze_plan`       | Cost-of-change analysis from a Terraform plan JSON                        |
+| `compare_actual`     | `.tfstate` vs planned cost drift detection                                |
+| `price_trends`       | Historical pricing trend query                                            |
+| `detect_anomalies`   | Budget and concentration-risk anomaly detection                           |
+| `check_cost_budget`  | Agent-side cost guardrail with allow/warn/block verdict                   |
+
+### CLI
+
+The `cloudcost-mcp` and `cloudcost` binaries and their documented flags in the README are stable.
+
+### Package entry points
+
+- `main`: `dist/index.js`
+- `types`: `dist/index.d.ts`
+- `bin`: `cloudcost-mcp`, `cloudcost`
+- Node engine: `>=20.0.0`
+
+## Not stable (may change in any release)
+
+- Internal parser implementations under `src/parsers/`
+- Pricing adapter internals under `src/pricing/aws`, `src/pricing/azure`, `src/pricing/gcp`
+- The on-disk SQLite cache schema (cache is rebuilt on upgrade)
+- Bundled fallback pricing tables under `data/`
+- Log line format and log levels
+- Exit codes beyond `0` (success) and `1` (failure)
+- Benchmark scripts and unreleased helper modules
+
+## Change classification
+
+| Change                                           | Bump  |
+| ------------------------------------------------ | ----- |
+| Remove or rename a tool                          | Major |
+| Remove a required input field from a tool schema | Major |
+| Change the type of an existing output field      | Major |
+| Raise the minimum Node.js version                | Major |
+| Add a new tool                                   | Minor |
+| Add an optional input field                      | Minor |
+| Add a new output field                           | Minor |
+| Add a new provider/region/resource               | Minor |
+| Bugfix                                           | Patch |
+| Performance improvement                          | Patch |
+| Pricing data refresh                             | Patch |
+| Dependency bump without API change               | Patch |
+
+## Deprecation
+
+Before a tool or field is removed in a future major, it will be marked deprecated in its description for at least one minor release, with the replacement documented in `CHANGELOG.md`.
+
+## Support policy
+
+- The latest minor line receives security and bug fixes.
+- The previous minor line receives security fixes only, for 6 months after the next minor is released.
+- CVE reports: see [`SECURITY.md`](./SECURITY.md).
+
+## Migration notes
+
+### 0.x → 1.0
+
+**There are no breaking API changes.** v1.0 ratifies the existing v0.5 surface as stable under SemVer. If your integration works on v0.5.x it will work on v1.0.0 without modification.
+
+What v1.0 added beyond the v0.5 surface:
+
+- Formal stability contract (this document).
+- Security advisories in transitive dependencies (hono, `@hono/node-server`, path-to-regexp, vite) resolved via npm overrides.
+- Smoke integration tests against live provider pricing APIs, runnable via `RUN_INTEGRATION=1` and scheduled weekly in CI.
+- Hardened npm publish workflow (tests + audit gate releases).
+
+Node 20 remains the minimum. No change from v0.5.
+
+### Pinning
+
+Once on v1.0 you can safely pin with a caret range:
+
+```json
+"@jadenrazo/cloudcost-mcp": "^1.0.0"
+```
+
+This accepts bugfixes, pricing refreshes, and additive features, and will not pull in breaking changes.

package/data/aws-pricing/metadata.json

@@ -0,0 +1,8 @@
+{
+  "last_updated": "2026-08-05",
+  "source": "https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws",
+  "sku_count": 142,
+  "refresh_script_version": "2.0.0",
+  "currency": "USD",
+  "notes": "Written by scripts/refresh-pricing.ts --write"
+}

package/data/azure-pricing/metadata.json

@@ -0,0 +1,8 @@
+{
+  "last_updated": "2026-08-05",
+  "source": "https://prices.azure.com/api/retail/prices",
+  "sku_count": 70,
+  "refresh_script_version": "2.0.0",
+  "currency": "USD",
+  "notes": "Written by scripts/refresh-pricing.ts --write"
+}

package/data/gcp-pricing/metadata.json

@@ -1,6 +1,8 @@
 {
-  "last_updated": "2026-04-11",
+  "last_updated": "2026-04-15",
   "source": "Google Cloud Pricing Calculator",
   "currency": "USD",
-  "notes": "Bundled pricing data for offline/zero-auth usage"
+  "notes": "Bundled pricing data for offline/zero-auth usage",
+  "refresh_script_version": "2.0.0",
+  "sku_count": 1197
 }