sample-aws-pricing-calculator-mcp 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +17 -0
  2. package/README.md +231 -0
  3. package/dist/mcp-server.js +98 -0
  4. package/mcp-server.js +328 -0
  5. package/package.json +20 -0
package/LICENSE ADDED
@@ -0,0 +1,17 @@
1
+ MIT No Attribution
2
+
3
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
6
+ this software and associated documentation files (the "Software"), to deal in
7
+ the Software without restriction, including without limitation the rights to
8
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9
+ the Software, and to permit persons to whom the Software is furnished to do so.
10
+
11
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
12
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
13
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
14
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
15
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
16
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
17
+
package/README.md ADDED
@@ -0,0 +1,231 @@
1
+ # AWS Pricing Calculator MCP Server
2
+
3
+ [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that programmatically creates, reads, updates [AWS Pricing Calculator](https://calculator.aws/#/estimate) estimates through natural language.
4
+
5
+ ## Key Features
6
+
7
+ - **Creating Estimates**: Supports all AWS services via live service definitions from the AWS Calculator CDN
8
+ - **Importing Estimates**: Download existing estimates by URL/ID as JSON (for modifications e.g. swap AWS regions) or Markdown (for LLM analysis)
9
+ - **Batch Processing**: Create estimates from Excel/CSV files via LLM-assisted parsing
10
+ - **No AWS Credentials Required**: Works without AWS account access
11
+
12
+ ## Example
13
+
14
+ Prompt:
15
+ > Create an AWS Pricing Calculator estimate for a common Wordpress environment on AWS (Dev, Quality, Production).
16
+
17
+ Output:
18
+ ![](example1.png)
19
+
20
+ ## Quick Start
21
+
22
+ Requires [Node.js®](https://nodejs.org/en/download).
23
+
24
+ ```bash
25
+ git clone https://github.com/aws-samples/sample-aws-pricing-calculator-mcp.git
26
+ cd sample-aws-pricing-calculator-mcp
27
+ npm install
28
+ npm run build
29
+ ```
30
+
31
+ The server communicates over stdio using the MCP protocol — it's designed to be used by MCP-compatible clients (e.g. Claude, Kiro), not called directly via HTTP.
32
+
33
+ ### MCP Client Configuration
34
+
35
+ Add to your MCP client config (e.g. `~/.kiro/settings/mcp.json`):
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "aws-pricing-calculator-mcp-server": {
41
+ "command": "node",
42
+ "args": ["/path/to/sample-aws-pricing-calculator-mcp/dist/mcp-server.js"]
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ## MCP Tools
49
+
50
+ | Tool | Description |
51
+ |---|---|
52
+ | `search_services` | Search AWS services by name or key. Supports comma-separated queries. |
53
+ | `get_service_fields` | Get input field IDs, types, labels, valid options, and selector values for one or more services. |
54
+ | `create_estimate` | Create a new empty estimate. Returns an estimate ID. |
55
+ | `add_service` | Add one or more services to an estimate with config values. Supports batch mode. |
56
+ | `export_estimate` | Export an estimate to calculator.aws and get a shareable URL. |
57
+ | `import_estimate` | Download an existing estimate by URL or ID. Returns JSON (raw) or Markdown. |
58
+ | `get_server_info` | Get version and capability information about this MCP server. |
59
+
60
+ ## Project Structure
61
+
62
+ ```
63
+ mcp-server.js # Entry point — stdio MCP server
64
+ lib/
65
+ aws-client.js # AWS manifest loading, service definitions, field extraction, save API
66
+ estimate-builder.js # Estimate builder with AWS payload generation and export
67
+ ec2.js # EC2 config transformation (agent-friendly -> calculator format)
68
+ test/
69
+ aws-client.test.js # Tests for AWS client
70
+ ec2.test.js # Tests for EC2 transform
71
+ estimate-builder.test.js # Tests for estimate builder
72
+ integration.test.js # Integration tests
73
+ validation.test.js # Config validation tests
74
+ ```
75
+
76
+ ## Build
77
+
78
+ ```bash
79
+ npm run build
80
+ ```
81
+
82
+ Produces `dist/mcp-server.js` — a single-file esbuild bundle (minified, CJS, Node platform).
83
+
84
+ ## Tests
85
+
86
+ ```bash
87
+ npm test
88
+ ```
89
+
90
+ ## Architecture
91
+
92
+ ```
93
+ ┌─────────────────┐ stdio ┌──────────────────────────────────────┐
94
+ │ MCP Client │◄──────────────────►│ MCP Server │
95
+ │ (Kiro, Claude, │ JSON-RPC over │ │
96
+ │ Cursor, etc.) │ stdin/stdout │ mcp-server.js (entry point) │
97
+ └─────────────────┘ │ ├── lib/aws-client.js │
98
+ │ ├── lib/estimate-builder.js │
99
+ │ └── lib/ec2.js │
100
+ └──────────┬───────────┬──────────────┘
101
+ │ │
102
+ HTTPS GET │ │ HTTPS POST
103
+ ▼ ▼
104
+ ┌──────────────┐ ┌──────────────────┐
105
+ │ CloudFront │ │ AWS Calculator │
106
+ │ CDN │ │ Save API │
107
+ │ │ │ │
108
+ │ • manifest │ │ POST /v2/saveAs │
109
+ │ • service │ │ → returns │
110
+ │ definitions│ │ shareable URL │
111
+ └──────────────┘ └──────────────────┘
112
+ ```
113
+
114
+ - The MCP server runs as a **local child process** spawned by the MCP client. It communicates exclusively over stdio — it is not network-accessible.
115
+ - All outbound requests are **HTTPS** to public, unauthenticated AWS CloudFront distributions. No AWS credentials are required or used.
116
+ - Estimate data is held **in memory only** and is lost when the process exits. No data is persisted to disk.
117
+
118
+ ## How It Works
119
+
120
+ ### Service Discovery
121
+
122
+ On first use, the server fetches the AWS Calculator manifest from CloudFront, which contains all 436+ services with their keys, names, and definition URLs. Service definitions are fetched on demand and cached. The `get_service_fields` tool parses these definitions to extract input field IDs, types, labels, and valid options into a flat, usable format.
123
+
124
+ ### Estimate Building
125
+
126
+ `EstimateBuilder` holds services and groups in memory. When you add a service via `add_service`, config is stored as-is using the AWS field IDs. Services can be organized into named groups, and multiple instances of the same service are supported via composite keys (e.g. `aWSLambda:Compute`).
127
+
128
+ ### EC2 Handling
129
+
130
+ EC2 uses a custom config transform (`lib/ec2.js`) that converts agent-friendly fields (instance type, OS, pricing strategy) into the `ec2Enhancement` format the calculator expects. This includes support for On-Demand, Savings Plans, Reserved Instances, and Spot pricing.
131
+
132
+ ### Partition Support
133
+
134
+ The server supports three AWS partitions:
135
+ - `aws` — standard commercial regions
136
+ - `aws-iso` — US ISO East/West
137
+ - `aws-iso-b` — US ISOB East
138
+
139
+ ### Export to calculator.aws
140
+
141
+ When `export_estimate` is called, the builder:
142
+
143
+ 1. Resolves each service name against the manifest
144
+ 2. Fetches the service definition to get the correct `version`, `serviceCode`, and template ID
145
+ 3. Maps config keys to `calculationComponents` in the AWS payload format
146
+ 4. POSTs the assembled payload to the AWS Calculator save API
147
+ 5. Returns the shareable `calculator.aws` URL
148
+
149
+ AWS recalculates the actual costs when someone opens the link.
150
+
151
+ ## Environment Variables
152
+
153
+ All optional:
154
+
155
+ | Variable | Default | Purpose |
156
+ |---|---|---|
157
+ | `AWS_MANIFEST_URL` | CloudFront manifest URL | AWS service catalog |
158
+ | `AWS_SAVE_URL` | CloudFront save URL | Estimate persistence |
159
+
160
+ ## Known Issues
161
+
162
+ - The CloudFront save/manifest APIs are undocumented and may change without notice.
163
+ - Callers must use the correct AWS field IDs — discover them via `get_service_fields`.
164
+ - While the tool discovers applicable selectorValues, it currently cannot resolve dependencies e.g. Instance Types <-> License
165
+ - Estimates live in memory and don't persist across restarts.
166
+ - No local cost calculation — pricing is computed by AWS when viewing the shareable link -> Make sure to press `Update estimate` to reflect latest pricing.
167
+ - Only https://calculator.aws/ supported for now
168
+
169
+ ## Security
170
+
171
+ This is sample code intended for educational purposes. You should work with your security and legal teams to meet your organizational security, regulatory, and compliance requirements before deployment.
172
+
173
+ ### Security Model
174
+
175
+ This MCP server is a **local tool provider** — it runs as a child process of an MCP client and is not network-accessible. It has no authentication or authorization layer; access control is the responsibility of the MCP client that spawns it.
176
+
177
+ The server does not handle AWS credentials, customer data, or PII. It processes only pricing configuration parameters (e.g., region, instance type, request counts) provided by the MCP client.
178
+
179
+ These are the same public, unauthenticated endpoints used by the [calculator.aws](https://calculator.aws) website. No AWS credentials are transmitted.
180
+
181
+ ### Input Validation and Sanitization
182
+
183
+ - All MCP tool inputs are validated using [Zod](https://zod.dev/) schemas before processing.
184
+ - User-provided descriptions and group names are sanitized to remove `<`, `>`, and `&` characters before inclusion in API payloads, preventing HTML/XML injection in the calculator frontend.
185
+ - Service configuration keys are validated against AWS service definitions with typo detection (Levenshtein distance), rejecting invalid field IDs before they reach the API.
186
+
187
+ ### Data Handling
188
+
189
+ - Estimate data is held **in memory only** for the lifetime of the process. No data is written to disk or persisted across restarts.
190
+ - The data consists of pricing configuration (region codes, service parameters, instance types) — not secrets, credentials, or personally identifiable information.
191
+ - Shareable URLs generated by the export contain only an opaque estimate ID. The estimate content is stored by AWS, not by this server.
192
+
193
+ ### Reporting Security Issues
194
+
195
+ See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for information on reporting security issues.
196
+
197
+ ## AWS MCP Servers Comparison: Pricing & Cost Management
198
+
199
+ | | **AWS Pricing Calculator MCP (This)** | **[AWS Billing & Cost Management MCP](https://github.com/awslabs/mcp#-cost--operations)** | **[AWS Pricing MCP](https://github.com/awslabs/mcp#-cost--operations)** |
200
+ |---|---|---|---|
201
+ | **Purpose** | Build shareable cost estimates for new workloads | Analyze historical spend & optimize existing costs | Query real-time pricing data from Price List API |
202
+ | **Data Source** | AWS Pricing Calculator (calculator.aws) | Cost Explorer, Cost Optimization Hub, Compute Optimizer, Savings Plans, Budgets, Storage Lens | AWS Price List Bulk API |
203
+ | **Output** | Shareable calculator.aws URL with full estimate | Natural language cost insights, savings recommendations | Raw pricing data, cost reports (markdown/CSV) |
204
+ | **Use Case** | "What will this new architecture cost?" | "Where am I overspending today?" | "What's the per-unit price of X?" |
205
+ | **Scope** | Forward-looking estimates | Historical & current spend | Current catalog pricing |
206
+ | **AWS Credentials** | Not required (uses public calculator API) | Required (reads your billing data) | Required (`pricing:*` permissions) |
207
+
208
+ TL;DR: Use the Pricing Calculator MCP to build estimates for proposals, the Billing & Cost Management MCP to analyze/optimize what you're already spending, and the Pricing MCP for granular unit-price lookups and IaC cost analysis.
209
+
210
+ ## Changelog
211
+
212
+ ### [1.0.1] - 2026-05-13
213
+ - Fixed Bug: Proper support for nested Structures e.g. Elasticache, RDS, Bedrock, ALB
214
+ - Fixed Bug: EC2/EBS iops, throughput not recognized
215
+ - Enriched field metadata with allowed values, also validates upon submission - yet dependencies are not resolved
216
+ - Costs are now displayed on initial load - however pressing 'Update estimate' is recommending
217
+ - Supports importing/reading estimates
218
+ - Dependencies updated
219
+ - Removed dead code
220
+ - Version info added (get_server_info)
221
+
222
+ ### [1.0.0] - 2026-04-30
223
+ - Initial Release
224
+
225
+ ## License
226
+
227
+ This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.
228
+
229
+ ## Disclaimer
230
+
231
+ Before using an MCP Server, you should consider conducting your own independent assessment to ensure that your use would comply with your own specific security and quality control practices and standards, as well as the laws, rules, and regulations that govern you and your content.