opencloudcosts 0.7.0__tar.gz

opencloudcosts-0.7.0/.env.example

@@ -0,0 +1,24 @@
+# CloudCost MCP Server Configuration
+# Copy this file to .env and fill in the values you need.
+# Public AWS pricing works without any credentials.
+
+# --- General ---
+# OCC_CACHE_DIR=~/.cache/cloudcostmcp
+# OCC_CACHE_TTL_HOURS=24
+# OCC_DEFAULT_CURRENCY=USD
+# OCC_DEFAULT_REGIONS=us-east-1,us-west-2
+
+# --- AWS (optional — public pricing works without auth) ---
+# AWS_PROFILE=default
+# AWS_ACCESS_KEY_ID=...
+# AWS_SECRET_ACCESS_KEY=...
+# AWS_DEFAULT_REGION=us-east-1
+#
+# Enable Cost Explorer for effective/bespoke pricing (note: costs $0.01/API call)
+# OCC_AWS_ENABLE_COST_EXPLORER=false
+
+# --- GCP (Phase 3) ---
+# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+# OCC_GCP_PROJECT_ID=my-project
+# OCC_GCP_BILLING_DATASET=my-project.billing_export
+# OCC_GCP_API_KEY=...  # alternative to service account for catalog-only access

opencloudcosts-0.7.0/.github/workflows/workflow.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opencloudcosts-0.7.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.python-version
+
+# Secrets / local config — .env.example is tracked, .env is not
+.env
+
+# SQLite cache databases
+*.db
+*.db-shm
+*.db-wal
+
+# Test & lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Claude Code local state
+.claude/
+
+# Local LLM test harness — results, traces, scratch work
+local-test-harness/
+
+# macOS
+.DS_Store

opencloudcosts-0.7.0/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+RUN pip install uv
+
+WORKDIR /app
+COPY pyproject.toml uv.lock* ./
+RUN uv sync --frozen --no-dev 2>/dev/null || uv sync --no-dev
+
+COPY src/ src/
+
+ENV OCC_HTTP_HOST=0.0.0.0
+ENV OCC_HTTP_PORT=8080
+
+EXPOSE 8080
+
+CMD ["uv", "run", "opencloudcosts", "--transport", "http", "--host", "0.0.0.0"]

opencloudcosts-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 x7even
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opencloudcosts-0.7.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: opencloudcosts
+Version: 0.7.0
+Summary: Open source MCP server for accurate public and effective cloud pricing (AWS, GCP, Azure)
+Project-URL: Homepage, https://github.com/x7even/cloudcostmcp
+Project-URL: Repository, https://github.com/x7even/cloudcostmcp
+Project-URL: Issues, https://github.com/x7even/cloudcostmcp/issues
+Author-email: x7even <x7sima@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: aws,azure,cloud,cost,finops,gcp,mcp,pricing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: boto3>=1.34
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: boto3-stubs[ce,pricing,savingsplans]>=1.34; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: gcp
+Requires-Dist: google-cloud-billing>=1.13; extra == 'gcp'
+Description-Content-Type: text/markdown
+
+# OpenCloudCosts MCP
+
+An open source MCP server that gives AI assistants accurate cloud pricing data for AWS, GCP, and Azure.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Supports both **public list pricing** (no credentials needed for AWS and Azure; GCP requires a free API key) and **effective/bespoke pricing** (post-discount: Reserved Instances, Savings Plans, CUDs, EDPs).
+
+## Key Use Cases
+
+- "What is the on-demand price of an m5.xlarge in us-east-1 vs ap-southeast-2, and what's the % delta?"
+- "Give me a TCO estimate for this architecture: 3x m5.xlarge + 1x 500GB gp3 EBS in us-east-1"
+- "What's the cost per user if I run this stack for 50,000 MAUs?"
+- "List all c6g instances in eu-west-1 with >= 8 vCPUs"
+- "What's my effective hourly rate on m5.xlarge after Savings Plans?"
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+**Pricing Lookup**
+
+| Tool | Description |
+|------|-------------|
+| `get_compute_price` | Price for a specific instance type in a region |
+| `get_storage_price` | EBS/S3/GCS storage pricing |
+| `get_service_price` | **Generic pricing for any AWS service** — CloudWatch, data transfer, RDS, Lambda, ELB, Route53, DynamoDB, EFS, and 250+ others |
+| `get_prices_batch` | Prices for multiple instance types in one call (concurrent) |
+| `compare_compute_prices` | Compare same instance across multiple regions with optional baseline deltas |
+| `search_pricing` | Search pricing catalog by keyword — any service, not just EC2 |
+
+**Effective & Discount Pricing**
+
+| Tool | Description |
+|------|-------------|
+| `get_effective_price` | Effective rate after account discounts (requires credentials) |
+| `get_discount_summary` | All active RIs and Savings Plans with utilization % |
+
+**Discovery**
+
+| Tool | Description |
+|------|-------------|
+| `list_services` | All 260+ AWS services with pricing data |
+| `list_regions` | All regions with friendly names |
+| `list_instance_types` | Available instance types with vCPU/memory filters |
+| `check_availability` | Is a SKU available in a region? |
+
+**Region Analysis**
+
+| Tool | Description |
+|------|-------------|
+| `find_cheapest_region` | Cheapest region for an instance type with optional baseline deltas |
+| `find_available_regions` | Every region where an instance exists — prices, region names, deltas |
+
+**Cost Estimation**
+
+| Tool | Description |
+|------|-------------|
+| `estimate_bom` | TCO for a Bill of Materials |
+| `estimate_unit_economics` | Cost per user/request/transaction |
+
+**Cache**
+
+| Tool | Description |
+|------|-------------|
+| `refresh_cache` | Invalidate pricing cache |
+| `cache_stats` | Cache entry counts and DB size |
+
+See [docs/tools.md](docs/tools.md) for full parameter reference and [docs/finops-guide.md](docs/finops-guide.md) for usage examples.
+
+## Setup
+
+### Prerequisites
+- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- AWS credentials (optional — public pricing works without them)
+
+### Clone & configure
+
+```bash
+git clone https://github.com/x7even/cloudcostsmcp opencloudcosts
+cd opencloudcosts
+cp .env.example .env
+# Edit .env if you want effective pricing / Cost Explorer
+```
+
+### Test it works
+
+```bash
+uv run pytest
+```
+
+### Run the server
+
+```bash
+uv run opencloudcosts
+```
+
+### Run as HTTP server
+
+HTTP transport enables shared/remote deployments — one server, many clients.
+
+```bash
+# Localhost only (default)
+uv run opencloudcosts --transport http --port 8080
+
+# Bind to all interfaces (e.g. for Docker or remote access)
+uv run opencloudcosts --transport http --host 0.0.0.0 --port 8080
+```
+
+Environment variable equivalents: `OCC_HTTP_HOST` and `OCC_HTTP_PORT`.
+
+Connect to Claude Code via `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloudcost": {
+      "transport": "http",
+      "url": "http://localhost:8080/mcp/v1"
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker build -t opencloudcosts .
+docker run -p 8080:8080 \
+  -e OCC_GCP_API_KEY=AIza... \
+  -v ~/.aws:/root/.aws:ro \
+  opencloudcosts
+```
+
+The container starts in HTTP transport mode by default (bound to `0.0.0.0:8080`).
+Pass cloud credentials via `-e` flags or mount your AWS credentials directory.
+
+### Connect to Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloudcost": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/opencloudcosts", "opencloudcosts"],
+      "env": {
+        "AWS_PROFILE": "default",
+        "OCC_GCP_API_KEY": "AIza..."
+      }
+    }
+  }
+}
+```
+
+Or to `~/.claude/settings.json` for global access:
+
+```json
+{
+  "mcpServers": {
+    "cloudcost": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/opencloudcosts", "opencloudcosts"]
+    }
+  }
+}
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector uv run --directory /path/to/opencloudcosts opencloudcosts
+```
+
+## AWS Credentials
+
+| Feature | Credentials needed |
+|---------|--------------------|
+| Public pricing (EC2, EBS, RDS list prices) | None |
+| Effective pricing (RI / SP discounts) | AWS credentials + `OCC_AWS_ENABLE_COST_EXPLORER=true` |
+
+Minimal IAM policy for public pricing:
+```json
+{
+  "Effect": "Allow",
+  "Action": ["pricing:GetProducts", "pricing:DescribeServices", "pricing:GetAttributeValues"],
+  "Resource": "*"
+}
+```
+
+Add these for effective pricing:
+```json
+"ce:GetCostAndUsage", "savingsplans:DescribeSavingsPlans", "savingsplans:DescribeSavingsPlanRates"
+```
+
+## Configuration
+
+All settings via environment variables (prefix `OCC_`) or `.env` file:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OCC_CACHE_TTL_HOURS` | 24 | Public price cache TTL |
+| `OCC_AWS_ENABLE_COST_EXPLORER` | false | Enable effective pricing (costs $0.01/call) |
+| `OCC_DEFAULT_REGIONS` | us-east-1,us-west-2 | Default regions |
+| `AWS_PROFILE` | (default chain) | AWS credentials profile |
+
+## Caching
+
+Prices are cached in SQLite at `~/.cache/opencloudcosts/pricing.db`. Public list prices are cached for 24 hours — AWS pricing changes infrequently. Use the `refresh_cache` tool to force a refresh.
+
+## GCP Setup
+
+Unlike AWS (which has public bulk pricing endpoints), GCP's pricing API always requires at least a free API key. No credit card or billing account is needed.
+
+**Option A — Free API key (recommended, 2 min setup):**
+1. Go to [console.cloud.google.com/apis/credentials](https://console.cloud.google.com/apis/credentials)
+2. Create a Project if you don't have one (free)
+3. Click **Create Credentials → API key**
+4. Set the key:
+
+```bash
+export OCC_GCP_API_KEY=AIza...
+```
+
+Or add `OCC_GCP_API_KEY=AIza...` to your `.env` file.
+
+**Option B — Application Default Credentials** (if you already use `gcloud`):
+```bash
+gcloud auth application-default login
+# or set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
+```
+
+**GCP instance type format:** `{family}-{series}-{vcpus}` e.g. `n2-standard-4`, `e2-highmem-8`, `c2-standard-16`
+
+## Azure Setup
+
+Azure pricing is fully public — no credentials, API key, or subscription needed.
+
+```bash
+# No configuration needed — works out of the box
+uv run opencloudcosts
+```
+
+**Azure instance type format:** ARM SKU names e.g. `Standard_D4s_v3`, `Standard_E8s_v3`, `Standard_B2ms`
+
+**Azure pricing terms:** `on_demand` (default), `reserved_1yr`, `reserved_3yr`, `spot`
+
+**Azure regions:** ARM region names e.g. `eastus`, `westeurope`, `southeastasia` (use `list_regions` for full list)
+
+**GCP pricing terms:** `on_demand` (default), `spot` (preemptible), `cud_1yr`, `cud_3yr`
+
+## Phases
+
+- **Phase 1** ✅ AWS public pricing (EC2, EBS, list instances)
+- **Phase 2** ✅ AWS effective pricing (Cost Explorer, Savings Plans, Reserved Instances)
+- **Phase 3** ✅ GCP public pricing (Compute Engine families, Persistent Disk, CUDs)
+- **Phase 4** ✅ Azure public pricing (Retail Prices API, no credentials)
+- **Phase 4** ✅ Streamable-HTTP transport (`--transport http`), Dockerfile
+- **Phase 4** ✅ Spot price history tool (`get_spot_history`), GCP Windows pricing
+- **Phase 5**: GCP effective pricing (BigQuery billing export)