workspaces-euc-mcp-server 0.1.2__tar.gz → 0.1.3__tar.gz

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-06-02
+
+### Fixed
+- `get_euc_cost_summary` no longer silently drops spend for services whose Cost Explorer `SERVICE`
+  name isn't an exact match to a hardcoded list. In real accounts this **hid all WorkSpaces
+  Applications spend**, which bills under the name `Amazon WorkSpaces Applications` (the AppStream
+  rebrand) rather than `Amazon AppStream`. EUC services are now selected by keyword
+  (`workspaces` / `appstream`) against every service in the period, with `Amazon WorkSpaces Thin
+  Client` (out of scope) explicitly excluded, and results are paginated.
+
+### Added
+- `get_euc_cost_summary` accepts optional `start_date` / `end_date` (YYYY-MM-DD, end exclusive) to
+  total an exact calendar month instead of only a rolling `lookback_days` window.
+
+### Docs
+- README: a "not an official AWS product" disclaimer at the top; an **Amazon Quick (Desktop)**
+  client example; an **AWS authentication** section (SSO login + auto-refresh; console sign-in does
+  not produce the on-disk token); and an explicit four-gate **write/destructive safety** section
+  noting that the launch flag grants no AWS access (IAM is still required).
+- DESIGN.md reconciled with the shipped code.
+
 ## [0.1.2] - 2026-06-01
 
 ### Added

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/DESIGN.md

@@ -4,12 +4,12 @@
 > inventory, troubleshooting, cost/utilization optimization, and guarded lifecycle management
 > across the Amazon WorkSpaces family of End User Computing services.
 >
-> **Shipped:** 10 read-only tools (Tier 0/1) + 10 guarded write tools (Tier 2) + 3 destructive
+> **Shipped:** 18 read-only tools (Tier 0/1) + 10 guarded write tools (Tier 2) + 3 destructive
 > tools (Tier 3), all behind opt-in flags with dry-run/confirm/blast-radius/typed-acknowledgement
-> guards. All four IAM policy tiers ship in `iam/`. CI (ruff/format/bandit/pytest on Py 3.11–3.13)
-> is green. See `README.md` for the live tool catalog and `CHANGELOG.md` for per-phase detail.
-> **Still deferred:** `recommend_bundle_rightsizing` (needs the WorkSpaces CloudWatch agent for
-> CPU/memory) — see §10.
+> guards. All four IAM policy tiers ship in `iam/`. CI (ruff/format/pyright/bandit/pytest on
+> Py 3.11–3.13) is green; published to PyPI and GHCR. **`README.md` is the source of truth for the
+> live tool catalog and exact tool names** — §5 below records the original design intent and is
+> kept reconciled with what shipped. See `CHANGELOG.md` for per-version detail.
 
 ## 1. Principles
 
@@ -55,26 +55,33 @@
 - **Observability:** Loguru with env-controlled log level (`FASTMCP_LOG_LEVEL`). Per-signal errors
   are returned in the structured result payload (deliberate: each tool makes many AWS calls and
   synthesizes one result), rather than `ctx.error`.
-- **Repo layout:**
+- **Repo layout** (independent package — **not** under an `awslabs/` namespace):
   ```
-  awslabs/workspaces_euc_mcp_server/
+  workspaces_euc_mcp_server/
     __init__.py        # version
-    server.py          # FastMCP app + tool registration
-    consts.py          # service/API constants, region maps
+    server.py          # FastMCP app + tool registration + main()/argparse
+    consts.py          # service/API constants, region→pricing-location maps
     models.py          # Pydantic request/response models
-    clients.py         # boto3 client factory (region/profile aware)
+    clients.py         # boto3 client factory (region/profile/assume-role aware)
     tools/
+      _common.py       # read_only/writes annotation helpers, try_call, paginate
       inventory.py
       diagnostics.py
       cost.py
+      performance.py   # perf + usage/history tools (native CloudWatch metrics)
       reporting.py
-      lifecycle.py     # Phase 2 (guarded writes)
-    iam/               # shippable least-privilege policy docs per tier
-  tests/               # pytest + pytest-asyncio + moto
+      secure_browser.py
+      pricing.py       # AWS Price List lookups for $ estimates
+      lifecycle.py     # Tier 2 (guarded writes)
+      destructive.py   # Tier 3 (terminate/rebuild/restore)
+  iam/                 # shippable least-privilege policy docs per tier (0–3)
+  tests/               # pytest + pytest-asyncio (no live AWS; calls are stubbed/monkeypatched)
+  Dockerfile, .dockerignore
   pyproject.toml, .pre-commit-config.yaml, README.md, CHANGELOG.md, LICENSE
   ```
-- **Quality gates:** ruff (format/lint), pyright (types), bandit (security), moto (AWS mocks),
-  pre-commit, Apache-2.0 headers.
+- **Quality gates:** ruff (format/lint), pyright (basic type-checking), bandit (security),
+  pre-commit (incl. `detect-private-key`), Apache-2.0 headers. Tests stub the boto3 layer rather
+  than hitting AWS.
 
 ## 4. Configuration / safety flags
 
@@ -91,50 +98,59 @@ and return a synthesized result, not raw API passthroughs.
 
 ### Phase 1 — Read / Diagnose / Optimize (read-only, Tiers 0–1)
 
+> Tool names below are the **shipped** names. Where the original plan used a different working
+> name, the shipped name is what appears here.
+
 **Inventory & discovery**
 | Tool | Purpose | IAM actions |
 |---|---|---|
-| `list_workspaces_personal` | Personal desktops + live connection status | `workspaces:DescribeWorkspaces`, `workspaces:DescribeWorkspacesConnectionStatus`, `workspaces:DescribeWorkspaceDirectories` |
-| `list_workspaces_pools` | Pools + active sessions | `workspaces:DescribeWorkspacesPools`, `workspaces:DescribeWorkspacesPoolSessions` |
-| `list_application_fleets` | WorkSpaces Applications fleets/stacks/associations | `appstream:DescribeFleets`, `appstream:DescribeStacks`, `appstream:DescribeFleetAssociations` |
-| `list_secure_browser_portals` | Secure Browser portals + settings | `workspaces-web:ListPortals`, `workspaces-web:GetPortal`, `workspaces-web:List*Settings` |
-| `get_euc_inventory_summary` | Cross-service rollup (counts, states, regions) | union of the above describes |
+| `get_euc_inventory_summary` | Cross-service rollup (counts, states, regions) across Personal, Pools, Applications, Secure Browser, Core | union of the in-scope describes |
+| `generate_inventory_report` | Structured per-resource inventory across all in-scope services | Phase-1 describes |
 
 **Troubleshooting & triage** (the flagship value)
 | Tool | Purpose | IAM actions |
 |---|---|---|
 | `diagnose_workspace_connectivity` | Correlate a Personal WorkSpace's state + connection status + directory health + CloudWatch into a root-cause narrative | `workspaces:Describe*`, `ds:DescribeDirectories`, `cloudwatch:GetMetricData` |
-| `diagnose_pool_session` | Why a Pools session failed/queued — capacity, errors, scaling | `workspaces:DescribeWorkspacesPool*`, `cloudwatch:GetMetricData` |
-| `diagnose_application_fleet` | Fleet state, capacity, scaling activity, fleet errors | `appstream:DescribeFleets`, `appstream:DescribeFleetAssociations`, `cloudwatch:GetMetricData`, `application-autoscaling:DescribeScalingActivities` |
-| `check_directory_health` | Shared dependency: directory reachability/registration | `ds:DescribeDirectories`, `workspaces:DescribeWorkspaceDirectories` |
+| `diagnose_pool` | Why a Pool is unhealthy/queued — capacity status, sessions, errors, scaling | `workspaces:DescribeWorkspacesPool*`, `cloudwatch:GetMetricData` |
+| `diagnose_application_fleet` | Fleet state, capacity, scaling activity, fleet errors | `appstream:DescribeFleets`, `appstream:ListAssociatedStacks`, `cloudwatch:GetMetricData`, `application-autoscaling:DescribeScalingActivities` |
+| `check_directory_health` | Shared dependency: directory reachability/registration (skips `ds` for WorkSpaces-managed `wsd-` directories) | `ds:DescribeDirectories`, `workspaces:DescribeWorkspaceDirectories` |
 
-**Cost & utilization optimization**
+**Cost, utilization & performance**
 | Tool | Purpose | IAM actions |
 |---|---|---|
 | `analyze_workspace_utilization` | Find idle/unused Personal WorkSpaces from connection metrics | `workspaces:DescribeWorkspaces*`, `cloudwatch:GetMetricData` |
-| `recommend_running_mode` | AlwaysOn → AutoStop candidates with $ estimate | `workspaces:DescribeWorkspaces`, `cloudwatch:GetMetricData`, `pricing:GetProducts` |
-| `recommend_bundle_rightsizing` | Over/under-sized bundles from CPU/mem metrics | `workspaces:DescribeWorkspaces`, `workspaces:DescribeWorkspaceBundles`, `cloudwatch:GetMetricData` |
-| `analyze_pool_capacity` | Pools over/under-provisioning | `workspaces:DescribeWorkspacesPool*`, `cloudwatch:GetMetricData` |
-| `analyze_fleet_capacity` | Applications fleet capacity vs demand | `appstream:DescribeFleets`, `cloudwatch:GetMetricData` |
+| `recommend_running_mode` | AlwaysOn → AutoStop candidates with a $ estimate | `workspaces:DescribeWorkspaces`, `cloudwatch:GetMetricData`, `pricing:GetProducts` |
+| `recommend_bundle_rightsizing` | Over/under-sized bundles from native CPU/mem metrics (see §10) | `workspaces:DescribeWorkspaces`, `workspaces:DescribeWorkspaceBundles`, `cloudwatch:GetMetricData` |
+| `get_workspace_performance` | Per-WorkSpace CPU/mem/GPU/FPS/latency from native `AWS/WorkSpaces` metrics | `workspaces:DescribeWorkspaces`, `cloudwatch:GetMetricData` |
+| `get_workspace_connection_history` | Per-WorkSpace connection timeline | `workspaces:DescribeWorkspaces*`, `cloudwatch:GetMetricData` |
+| `get_pool_session_history` | Pool session/capacity history | `workspaces:DescribeWorkspacesPool*`, `cloudwatch:GetMetricData` |
+| `get_application_fleet_usage` | Applications fleet utilization vs capacity | `appstream:DescribeFleets`, `cloudwatch:GetMetricData` |
 | `get_euc_cost_summary` | Spend rollup filtered to EUC services | `ce:GetCostAndUsage`, `ce:GetDimensionValues` |
 
+**Secure Browser**
+| Tool | Purpose | IAM actions |
+|---|---|---|
+| `get_secure_browser_portal_details` | Portal config + associated settings (browser/network/user/IP-access) | `workspaces-web:GetPortal`, `workspaces-web:List*`, `workspaces-web:Get*Settings` |
+| `get_secure_browser_portal_usage` | Portal session/usage metrics | `workspaces-web:ListPortals`, `cloudwatch:GetMetricData` |
+
 **Reporting & audit**
 | Tool | Purpose | IAM actions |
 |---|---|---|
-| `generate_inventory_report` | Structured inventory across all in-scope services | Phase-1 describes |
 | `audit_security_posture` | Encryption at rest, IP access control groups, directory config, portal policies | `workspaces:Describe*`, `workspaces-web:Get*/List*`, `appstream:Describe*` |
-| `list_unused_resources` | Idle desktops / empty fleets / orphaned associations | describes + `cloudwatch:GetMetricData` |
+| `list_unused_resources` | Idle desktops / empty fleets / orphaned resources | describes + `cloudwatch:GetMetricData` |
 
 ### Phase 2 — Guarded lifecycle (writes; Tier 2, `--enable-writes`)
 All support `dry_run`, return a plan + blast-radius before acting, and honor `--max-bulk-targets`.
 
 | Tool | Purpose | IAM actions |
 |---|---|---|
-| `start_workspaces` / `stop_workspaces` / `reboot_workspaces` | Power ops | `workspaces:Start/Stop/RebootWorkspaces` |
+| `start_workspaces` / `stop_workspaces` / `reboot_workspaces` | Personal power ops | `workspaces:Start/Stop/RebootWorkspaces` |
 | `modify_workspace_running_mode` | Apply AutoStop/AlwaysOn recommendation | `workspaces:ModifyWorkspaceProperties` |
-| `modify_workspace_compute_type` | Apply right-sizing recommendation | `workspaces:ModifyWorkspaceProperties` |
-| `update_pool_capacity` | Resize a Pool | `workspaces:UpdateWorkspacesPool` |
-| `start_application_fleet` / `stop_application_fleet` / `update_fleet_capacity` | Applications fleet ops | `appstream:Start/Stop/UpdateFleet` |
+| `start_workspaces_pool` / `stop_workspaces_pool` / `update_workspaces_pool_capacity` | Pool power + resize | `workspaces:Start/Stop/UpdateWorkspacesPool` |
+| `start_application_fleet` / `stop_application_fleet` / `update_application_fleet_capacity` | Applications fleet ops | `appstream:Start/Stop/UpdateFleet` |
+
+> Note: bundle right-sizing is **recommend-only** (`recommend_bundle_rightsizing`); there is no
+> `modify_workspace_compute_type` write tool — applying a compute change is left to the operator.
 
 ### Phase 3 — Destructive (Tier 3, `--enable-destructive`, hardest gating)
 | Tool | Purpose | IAM actions |
@@ -177,7 +193,7 @@ human operator** (the pattern the AWS MCP Server uses).
 ## 8. Phased roadmap
 
 - **Phase 0 — Scaffold:** repo per awslabs layout, client factory, auth, `--readonly` flag,
-  one end-to-end tool (`get_euc_inventory_summary`), tests with moto, CI/pre-commit. Ship to
+  one end-to-end tool (`get_euc_inventory_summary`), tests (stubbed boto3), CI/pre-commit. Ship to
   internal users.
 - **Phase 1 — Read/Diagnose/Optimize:** full inventory + diagnostics + cost tools (Tiers 0–1).
   This is the demonstrable-value milestone.

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspaces-euc-mcp-server
-Version: 0.1.2
+Version: 0.1.3
 Summary: MCP server for administering the Amazon WorkSpaces family of End User Computing services (Personal, Pools, Applications, Secure Browser, Core).
 Project-URL: Homepage, https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp
 Project-URL: Repository, https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp
@@ -32,6 +32,14 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp/actions/workflows/ci.yml)
 
+> **Disclaimer:** This project is not an official AWS product, service, or solution, and is not
+> affiliated with or endorsed by Amazon Web Services. It is an independent, community example
+> implementation intended to demonstrate what is possible when combining the Amazon WorkSpaces End
+> User Computing APIs with the Model Context Protocol. It is provided as a starting point to learn
+> from, adapt, and iterate on — not as a supported or production-certified offering. Use it at your
+> own discretion and always validate it against your organisation's security, compliance, and
+> operational requirements before deploying to production.
+
 An [MCP](https://modelcontextprotocol.io) server that gives administrators AI-assisted
 **inventory, troubleshooting, and cost/utilization optimization** across the Amazon WorkSpaces
 End User Computing (EUC) portfolio:
@@ -78,7 +86,7 @@ diagnosis, a right-sizing recommendation) instead of returning raw API output. S
 | `get_workspace_connection_history` | A desktop's connection/session **history** (UserConnected + connection attempts/failures) over a window, with a summary (Tier 0). |
 | `get_pool_session_history` | A WorkSpaces Pool's user-**session history** (active/available/utilization capacity time-series), flags idle pool capacity (Tier 0). |
 | `recommend_bundle_rightsizing` | Suggests smaller/larger compute types from CPU & memory headroom (general families; graphics excluded) (Tier 0). |
-| `get_euc_cost_summary` | EUC spend by service over a window via Cost Explorer, account-wide (Tier 1). |
+| `get_euc_cost_summary` | EUC spend by service over a window (or an explicit `start_date`/`end_date` calendar month) via Cost Explorer, account-wide. Services are matched by keyword so naming variants (e.g. AppStream 2.0) aren't dropped; note Cost Explorer bills WorkSpaces Personal/Pools/Core together as one "Amazon WorkSpaces" line (Tier 1). |
 | `generate_inventory_report` | Detailed per-resource inventory (desktops **with assigned user / computer name / IP**, pools, fleets, **stacks + their associated fleets**, portals) with key attributes (Tier 0). |
 | `audit_security_posture` | Cross-service: flags unencrypted WorkSpace volumes, directories without IP access control groups, and **Secure Browser portals / Applications stacks that allow data egress** (clipboard/download/print) (Tier 0). |
 | `get_secure_browser_portal_details` | Resolves a Secure Browser portal's user settings (clipboard/print/download controls + timeouts), network, and attached policies (Tier 0). |
@@ -201,6 +209,140 @@ Running from a source checkout instead of `uvx`:
 }
 ```
 
+The two blocks above are the standard `mcpServers` shape used by most clients (Claude Desktop,
+Cursor, etc.). Some clients use a **form** instead of raw JSON — see the example below.
+
+### Example: Amazon Quick (Desktop)
+
+Amazon Quick's **Capabilities → MCP → Add MCP** uses a form rather than JSON. Choose connection
+type **Local** ("Run a command on your machine") and fill in:
+
+| Field | Value |
+|-------|-------|
+| **Name** | `WorkSpaces EUC` |
+| **Command** | `uvx` |
+| **Arguments** | `workspaces-euc-mcp-server@latest --region us-east-1` |
+| **Description** | `Admin tools for Amazon WorkSpaces EUC — inventory, troubleshooting, cost/utilization. Read-only.` |
+| **Environment variables** | `AWS_PROFILE` = `your-euc-admin-profile`  ·  `AWS_REGION` = `us-east-1` |
+| **Timeout (seconds)** | `60` |
+
+Notes:
+- Set `--region` (in Arguments) and `AWS_REGION` to where your WorkSpaces actually live; keep the
+  two in sync.
+- **Bump the timeout from the default 30 → 60–120 for the first run** — `uvx` downloads the package
+  on first launch, which can exceed 30 s and look like a failed connection. Later starts are fast.
+- If `uvx` isn't on your `PATH`, use Command `workspaces-euc-mcp-server` (after
+  `pip install workspaces-euc-mcp-server`) with Arguments `--region us-east-1`, or Command `python`
+  with Arguments `-m workspaces_euc_mcp_server.server --region us-east-1`.
+- To enable writes/destructive, append the flags to **Arguments** (e.g.
+  `… --enable-writes --max-bulk-targets 10`) — and attach the matching IAM tier (see
+  [the safety gates](#enabling-write--destructive-tools--the-safety-gates)).
+- A local MCP server has **no "Sign in" button** (that's a Quick *Connections* feature). It uses
+  your AWS credential chain, so authenticate first — e.g. `aws sso login --profile your-profile` for
+  SSO — then the server connects. See [AWS authentication](#aws-authentication).
+
+## AWS authentication
+
+The server uses the **standard AWS credential chain** — it does not handle sign-in itself. Provide
+credentials however boto3 expects them:
+
+- **IAM Identity Center (SSO):** configure an `sso-session` profile, then `aws sso login --profile
+  <name>`. With the modern `sso-session` format, botocore **auto-refreshes** the token for the
+  session window, so you log in once rather than every few hours. (Signing into the AWS Console or
+  access portal in a browser does **not** create the on-disk token the server needs — only
+  `aws sso login` does.)
+- **Static / temporary keys:** a named profile in `~/.aws/credentials`, or `AWS_ACCESS_KEY_ID` /
+  `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars.
+- **Assumed role / multi-account:** see [Multi-account / MSP](#multi-account--msp).
+
+If calls fail with an expired-token / `UnauthorizedException` error, your session has lapsed —
+re-authenticate (for SSO, `aws sso login --profile <name>`) and retry. Nothing in the MCP config
+changes.
+
+## Enabling write / destructive tools — the safety gates
+
+The config above is **read-only**: the write and destructive tools are not even registered, so
+they cannot be called no matter what the model or the IAM policy allows. Enabling them is a
+deliberate act, and **IAM permissions alone are not enough**. A destructive call (e.g.
+`terminate_workspaces`) only runs after clearing **all four** of these independent gates:
+
+| # | Gate | Where it lives | What it does |
+|---|------|----------------|--------------|
+| 1 | **Launch flag** | The `args` in your MCP-client config | Destructive tools aren't registered unless the server was started with **both** `--enable-writes` **and** `--enable-destructive`. Default launch = read-only. |
+| 2 | **IAM tier** | The AWS profile / assumed role | The credentials must carry the matching tier ([`iam/tier2-lifecycle.json`](iam/tier2-lifecycle.json) for writes, [`iam/tier3-destructive.json`](iam/tier3-destructive.json) for destructive). Without it, AWS denies the call. |
+| 3 | **`confirm=true`** | The tool call | Every mutation is **dry-run by default** — it returns a plan and changes nothing. You must explicitly pass `confirm=true`. |
+| 4 | **Typed acknowledgement + blast-radius cap** | The tool call | Destructive ops also require the **exact** phrase (`acknowledge="TERMINATE"` / `"REBUILD"` / `"RESTORE"`) and must stay within `--max-bulk-targets`. Wrong phrase or too many targets → refused, nothing changes. |
+
+> **The launch flag grants no AWS permission.** Gate 1 (the `--enable-*` flag) and Gate 2 (IAM) are
+> two *separate* switches and you need **both**. Turning on `--enable-destructive` only *exposes* the
+> tool in the client — it does not give your AWS profile any access. If the flag is on but the
+> profile/role is **missing the matching tier policy**, the tool is callable and its dry-run works,
+> but the real `confirm=true` call **fails with an AWS `AccessDenied` error and nothing is deleted**.
+> So enabling writes/destructive in your MCP client is necessary but **not** sufficient: you must
+> *also* attach [`iam/tier2-lifecycle.json`](iam/tier2-lifecycle.json) /
+> [`iam/tier3-destructive.json`](iam/tier3-destructive.json) to the AWS profile (or assumed role)
+> the server runs as.
+>
+> Gates **1–2** are the real security boundary (config + AWS-enforced IAM). Gates **3–4** are
+> in-tool guardrails against an over-eager agent or a fat-fingered single call — they are **not** a
+> substitute for IAM. The genuine least-privilege control is: **don't grant Tier 2/3 and don't pass
+> the flags unless you truly want those operations available.** For an extra backstop, scope the
+> Tier 2/3 policy with resource tags / conditions so even an enabled server can only touch a bounded
+> set of resources.
+
+**MCP-client config — writes enabled (Tier 2):** add the flag to `args` and attach the Tier 2 policy.
+
+```json
+{
+  "mcpServers": {
+    "workspaces-euc": {
+      "command": "uvx",
+      "args": ["workspaces-euc-mcp-server@latest", "--enable-writes", "--max-bulk-targets", "10"],
+      "env": {
+        "AWS_PROFILE": "your-euc-admin-profile",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+**MCP-client config — destructive enabled (Tier 3):** both flags, and attach the Tier 3 policy. Use
+a tightly-scoped profile.
+
+```json
+{
+  "mcpServers": {
+    "workspaces-euc": {
+      "command": "uvx",
+      "args": [
+        "workspaces-euc-mcp-server@latest",
+        "--enable-writes",
+        "--enable-destructive",
+        "--max-bulk-targets", "5"
+      ],
+      "env": {
+        "AWS_PROFILE": "your-euc-admin-profile",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+Even with the destructive config above, a call still does nothing until gates 3–4 are satisfied:
+
+```text
+terminate_workspaces(workspace_ids=["ws-abc123"], confirm=true, acknowledge="TERMINATE")
+```
+
+Equivalent CLI launches (e.g. for the Docker entrypoint or a shell):
+
+```bash
+workspaces-euc-mcp-server --enable-writes --max-bulk-targets 10                      # Tier 2 only
+workspaces-euc-mcp-server --enable-writes --enable-destructive --max-bulk-targets 5  # + Tier 3
+```
+
 ## Command-line flags
 
 | Flag | Default | Purpose |
@@ -256,19 +398,9 @@ pick the right tool. A few examples:
 | "Reboot these three stuck desktops." | `reboot_workspaces` (dry-run, then `confirm=true`) |
 
 **Write/destructive tools are off unless enabled.** Mutations show a dry-run plan first; to execute
-you pass `confirm=true` (and, for destructive ops, the exact acknowledge phrase). For example, a
-full destructive run looks like:
-
-```text
-terminate_workspaces(workspace_ids=["ws-abc123"], confirm=true, acknowledge="TERMINATE")
-```
-
-Launch with writes/destructive enabled:
-
-```bash
-workspaces-euc-mcp-server --enable-writes                      # Tier 2 power/capacity tools
-workspaces-euc-mcp-server --enable-writes --enable-destructive # + Tier 3 terminate/rebuild/restore
-```
+you pass `confirm=true` (and, for destructive ops, the exact acknowledge phrase). See
+[Enabling write / destructive tools — the safety gates](#enabling-write--destructive-tools--the-safety-gates)
+for how to turn them on (MCP-client config + IAM) and the four gates each call must clear.
 
 ## Development
 

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/README.md

@@ -2,6 +2,14 @@
 
 [![CI](https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bengroeneveldsg/aws-workspaces-euc-mcp/actions/workflows/ci.yml)
 
+> **Disclaimer:** This project is not an official AWS product, service, or solution, and is not
+> affiliated with or endorsed by Amazon Web Services. It is an independent, community example
+> implementation intended to demonstrate what is possible when combining the Amazon WorkSpaces End
+> User Computing APIs with the Model Context Protocol. It is provided as a starting point to learn
+> from, adapt, and iterate on — not as a supported or production-certified offering. Use it at your
+> own discretion and always validate it against your organisation's security, compliance, and
+> operational requirements before deploying to production.
+
 An [MCP](https://modelcontextprotocol.io) server that gives administrators AI-assisted
 **inventory, troubleshooting, and cost/utilization optimization** across the Amazon WorkSpaces
 End User Computing (EUC) portfolio:
@@ -48,7 +56,7 @@ diagnosis, a right-sizing recommendation) instead of returning raw API output. S
 | `get_workspace_connection_history` | A desktop's connection/session **history** (UserConnected + connection attempts/failures) over a window, with a summary (Tier 0). |
 | `get_pool_session_history` | A WorkSpaces Pool's user-**session history** (active/available/utilization capacity time-series), flags idle pool capacity (Tier 0). |
 | `recommend_bundle_rightsizing` | Suggests smaller/larger compute types from CPU & memory headroom (general families; graphics excluded) (Tier 0). |
-| `get_euc_cost_summary` | EUC spend by service over a window via Cost Explorer, account-wide (Tier 1). |
+| `get_euc_cost_summary` | EUC spend by service over a window (or an explicit `start_date`/`end_date` calendar month) via Cost Explorer, account-wide. Services are matched by keyword so naming variants (e.g. AppStream 2.0) aren't dropped; note Cost Explorer bills WorkSpaces Personal/Pools/Core together as one "Amazon WorkSpaces" line (Tier 1). |
 | `generate_inventory_report` | Detailed per-resource inventory (desktops **with assigned user / computer name / IP**, pools, fleets, **stacks + their associated fleets**, portals) with key attributes (Tier 0). |
 | `audit_security_posture` | Cross-service: flags unencrypted WorkSpace volumes, directories without IP access control groups, and **Secure Browser portals / Applications stacks that allow data egress** (clipboard/download/print) (Tier 0). |
 | `get_secure_browser_portal_details` | Resolves a Secure Browser portal's user settings (clipboard/print/download controls + timeouts), network, and attached policies (Tier 0). |
@@ -171,6 +179,140 @@ Running from a source checkout instead of `uvx`:
 }
 ```
 
+The two blocks above are the standard `mcpServers` shape used by most clients (Claude Desktop,
+Cursor, etc.). Some clients use a **form** instead of raw JSON — see the example below.
+
+### Example: Amazon Quick (Desktop)
+
+Amazon Quick's **Capabilities → MCP → Add MCP** uses a form rather than JSON. Choose connection
+type **Local** ("Run a command on your machine") and fill in:
+
+| Field | Value |
+|-------|-------|
+| **Name** | `WorkSpaces EUC` |
+| **Command** | `uvx` |
+| **Arguments** | `workspaces-euc-mcp-server@latest --region us-east-1` |
+| **Description** | `Admin tools for Amazon WorkSpaces EUC — inventory, troubleshooting, cost/utilization. Read-only.` |
+| **Environment variables** | `AWS_PROFILE` = `your-euc-admin-profile`  ·  `AWS_REGION` = `us-east-1` |
+| **Timeout (seconds)** | `60` |
+
+Notes:
+- Set `--region` (in Arguments) and `AWS_REGION` to where your WorkSpaces actually live; keep the
+  two in sync.
+- **Bump the timeout from the default 30 → 60–120 for the first run** — `uvx` downloads the package
+  on first launch, which can exceed 30 s and look like a failed connection. Later starts are fast.
+- If `uvx` isn't on your `PATH`, use Command `workspaces-euc-mcp-server` (after
+  `pip install workspaces-euc-mcp-server`) with Arguments `--region us-east-1`, or Command `python`
+  with Arguments `-m workspaces_euc_mcp_server.server --region us-east-1`.
+- To enable writes/destructive, append the flags to **Arguments** (e.g.
+  `… --enable-writes --max-bulk-targets 10`) — and attach the matching IAM tier (see
+  [the safety gates](#enabling-write--destructive-tools--the-safety-gates)).
+- A local MCP server has **no "Sign in" button** (that's a Quick *Connections* feature). It uses
+  your AWS credential chain, so authenticate first — e.g. `aws sso login --profile your-profile` for
+  SSO — then the server connects. See [AWS authentication](#aws-authentication).
+
+## AWS authentication
+
+The server uses the **standard AWS credential chain** — it does not handle sign-in itself. Provide
+credentials however boto3 expects them:
+
+- **IAM Identity Center (SSO):** configure an `sso-session` profile, then `aws sso login --profile
+  <name>`. With the modern `sso-session` format, botocore **auto-refreshes** the token for the
+  session window, so you log in once rather than every few hours. (Signing into the AWS Console or
+  access portal in a browser does **not** create the on-disk token the server needs — only
+  `aws sso login` does.)
+- **Static / temporary keys:** a named profile in `~/.aws/credentials`, or `AWS_ACCESS_KEY_ID` /
+  `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` env vars.
+- **Assumed role / multi-account:** see [Multi-account / MSP](#multi-account--msp).
+
+If calls fail with an expired-token / `UnauthorizedException` error, your session has lapsed —
+re-authenticate (for SSO, `aws sso login --profile <name>`) and retry. Nothing in the MCP config
+changes.
+
+## Enabling write / destructive tools — the safety gates
+
+The config above is **read-only**: the write and destructive tools are not even registered, so
+they cannot be called no matter what the model or the IAM policy allows. Enabling them is a
+deliberate act, and **IAM permissions alone are not enough**. A destructive call (e.g.
+`terminate_workspaces`) only runs after clearing **all four** of these independent gates:
+
+| # | Gate | Where it lives | What it does |
+|---|------|----------------|--------------|
+| 1 | **Launch flag** | The `args` in your MCP-client config | Destructive tools aren't registered unless the server was started with **both** `--enable-writes` **and** `--enable-destructive`. Default launch = read-only. |
+| 2 | **IAM tier** | The AWS profile / assumed role | The credentials must carry the matching tier ([`iam/tier2-lifecycle.json`](iam/tier2-lifecycle.json) for writes, [`iam/tier3-destructive.json`](iam/tier3-destructive.json) for destructive). Without it, AWS denies the call. |
+| 3 | **`confirm=true`** | The tool call | Every mutation is **dry-run by default** — it returns a plan and changes nothing. You must explicitly pass `confirm=true`. |
+| 4 | **Typed acknowledgement + blast-radius cap** | The tool call | Destructive ops also require the **exact** phrase (`acknowledge="TERMINATE"` / `"REBUILD"` / `"RESTORE"`) and must stay within `--max-bulk-targets`. Wrong phrase or too many targets → refused, nothing changes. |
+
+> **The launch flag grants no AWS permission.** Gate 1 (the `--enable-*` flag) and Gate 2 (IAM) are
+> two *separate* switches and you need **both**. Turning on `--enable-destructive` only *exposes* the
+> tool in the client — it does not give your AWS profile any access. If the flag is on but the
+> profile/role is **missing the matching tier policy**, the tool is callable and its dry-run works,
+> but the real `confirm=true` call **fails with an AWS `AccessDenied` error and nothing is deleted**.
+> So enabling writes/destructive in your MCP client is necessary but **not** sufficient: you must
+> *also* attach [`iam/tier2-lifecycle.json`](iam/tier2-lifecycle.json) /
+> [`iam/tier3-destructive.json`](iam/tier3-destructive.json) to the AWS profile (or assumed role)
+> the server runs as.
+>
+> Gates **1–2** are the real security boundary (config + AWS-enforced IAM). Gates **3–4** are
+> in-tool guardrails against an over-eager agent or a fat-fingered single call — they are **not** a
+> substitute for IAM. The genuine least-privilege control is: **don't grant Tier 2/3 and don't pass
+> the flags unless you truly want those operations available.** For an extra backstop, scope the
+> Tier 2/3 policy with resource tags / conditions so even an enabled server can only touch a bounded
+> set of resources.
+
+**MCP-client config — writes enabled (Tier 2):** add the flag to `args` and attach the Tier 2 policy.
+
+```json
+{
+  "mcpServers": {
+    "workspaces-euc": {
+      "command": "uvx",
+      "args": ["workspaces-euc-mcp-server@latest", "--enable-writes", "--max-bulk-targets", "10"],
+      "env": {
+        "AWS_PROFILE": "your-euc-admin-profile",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+**MCP-client config — destructive enabled (Tier 3):** both flags, and attach the Tier 3 policy. Use
+a tightly-scoped profile.
+
+```json
+{
+  "mcpServers": {
+    "workspaces-euc": {
+      "command": "uvx",
+      "args": [
+        "workspaces-euc-mcp-server@latest",
+        "--enable-writes",
+        "--enable-destructive",
+        "--max-bulk-targets", "5"
+      ],
+      "env": {
+        "AWS_PROFILE": "your-euc-admin-profile",
+        "AWS_REGION": "us-east-1"
+      }
+    }
+  }
+}
+```
+
+Even with the destructive config above, a call still does nothing until gates 3–4 are satisfied:
+
+```text
+terminate_workspaces(workspace_ids=["ws-abc123"], confirm=true, acknowledge="TERMINATE")
+```
+
+Equivalent CLI launches (e.g. for the Docker entrypoint or a shell):
+
+```bash
+workspaces-euc-mcp-server --enable-writes --max-bulk-targets 10                      # Tier 2 only
+workspaces-euc-mcp-server --enable-writes --enable-destructive --max-bulk-targets 5  # + Tier 3
+```
+
 ## Command-line flags
 
 | Flag | Default | Purpose |
@@ -226,19 +368,9 @@ pick the right tool. A few examples:
 | "Reboot these three stuck desktops." | `reboot_workspaces` (dry-run, then `confirm=true`) |
 
 **Write/destructive tools are off unless enabled.** Mutations show a dry-run plan first; to execute
-you pass `confirm=true` (and, for destructive ops, the exact acknowledge phrase). For example, a
-full destructive run looks like:
-
-```text
-terminate_workspaces(workspace_ids=["ws-abc123"], confirm=true, acknowledge="TERMINATE")
-```
-
-Launch with writes/destructive enabled:
-
-```bash
-workspaces-euc-mcp-server --enable-writes                      # Tier 2 power/capacity tools
-workspaces-euc-mcp-server --enable-writes --enable-destructive # + Tier 3 terminate/rebuild/restore
-```
+you pass `confirm=true` (and, for destructive ops, the exact acknowledge phrase). See
+[Enabling write / destructive tools — the safety gates](#enabling-write--destructive-tools--the-safety-gates)
+for how to turn them on (MCP-client config + IAM) and the four gates each call must clear.
 
 ## Development
 

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workspaces-euc-mcp-server"
-version = "0.1.2"
+version = "0.1.3"
 description = "MCP server for administering the Amazon WorkSpaces family of End User Computing services (Personal, Pools, Applications, Secure Browser, Core)."
 readme = "README.md"
 requires-python = ">=3.11"

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/tests/test_cost.py

@@ -129,6 +129,107 @@ def test_cost_summary_aggregates_by_service():
     assert summary.by_service[1].amount == 40.0
 
 
+def test_cost_summary_keyword_matches_variants_and_excludes_noneuc():
+    # Real-world Cost Explorer SERVICE names: AppStream now bills as "Amazon WorkSpaces
+    # Applications" (the rebrand that the old exact-match list missed) and must be captured;
+    # "Amazon WorkSpaces Thin Client" contains "workspaces" but is OUT of scope and must be
+    # excluded; non-EUC services (EC2) are excluded.
+    ce = types.SimpleNamespace(
+        get_cost_and_usage=lambda **_: {
+            "ResultsByTime": [
+                {
+                    "Groups": [
+                        {
+                            "Keys": ["Amazon WorkSpaces Applications"],
+                            "Metrics": {"UnblendedCost": {"Amount": "1006.85", "Unit": "USD"}},
+                        },
+                        {
+                            "Keys": ["Amazon WorkSpaces"],
+                            "Metrics": {"UnblendedCost": {"Amount": "694.97", "Unit": "USD"}},
+                        },
+                        {
+                            "Keys": ["Amazon WorkSpaces Thin Client"],
+                            "Metrics": {"UnblendedCost": {"Amount": "6.00", "Unit": "USD"}},
+                        },
+                        {
+                            "Keys": ["Amazon Elastic Compute Cloud - Compute"],
+                            "Metrics": {"UnblendedCost": {"Amount": "485.58", "Unit": "USD"}},
+                        },
+                    ]
+                }
+            ]
+        }
+    )
+    factory = FakeFactory({consts.COST_EXPLORER_API: ce})
+
+    summary = cost.get_euc_cost_summary_core(factory, lookback_days=30)
+
+    # WorkSpaces Applications captured, Thin Client + EC2 excluded.
+    assert {li.service for li in summary.by_service} == {
+        "Amazon WorkSpaces Applications",
+        "Amazon WorkSpaces",
+    }
+    assert summary.total == 1701.82
+
+
+def test_cost_summary_explicit_date_range_overrides_lookback():
+    captured: dict = {}
+
+    def get_cost_and_usage(**kwargs):
+        captured.update(kwargs)
+        return {"ResultsByTime": []}
+
+    ce = types.SimpleNamespace(get_cost_and_usage=get_cost_and_usage)
+    factory = FakeFactory({consts.COST_EXPLORER_API: ce})
+
+    summary = cost.get_euc_cost_summary_core(
+        factory, start_date="2026-05-01", end_date="2026-06-01"
+    )
+
+    assert captured["TimePeriod"] == {"Start": "2026-05-01", "End": "2026-06-01"}
+    assert summary.start == "2026-05-01"
+    assert summary.end == "2026-06-01"
+
+
+def test_cost_summary_follows_pagination():
+    page1 = {
+        "ResultsByTime": [
+            {
+                "Groups": [
+                    {
+                        "Keys": ["Amazon WorkSpaces"],
+                        "Metrics": {"UnblendedCost": {"Amount": "10.00", "Unit": "USD"}},
+                    }
+                ]
+            }
+        ],
+        "NextPageToken": "p2",
+    }
+    page2 = {
+        "ResultsByTime": [
+            {
+                "Groups": [
+                    {
+                        "Keys": ["Amazon AppStream"],
+                        "Metrics": {"UnblendedCost": {"Amount": "20.00", "Unit": "USD"}},
+                    }
+                ]
+            }
+        ]
+    }
+
+    def get_cost_and_usage(**kwargs):
+        return page2 if kwargs.get("NextPageToken") == "p2" else page1
+
+    ce = types.SimpleNamespace(get_cost_and_usage=get_cost_and_usage)
+    factory = FakeFactory({consts.COST_EXPLORER_API: ce})
+
+    summary = cost.get_euc_cost_summary_core(factory, lookback_days=30)
+
+    assert summary.total == 30.0
+    assert {li.service for li in summary.by_service} == {"Amazon WorkSpaces", "Amazon AppStream"}
+
+
 def test_cost_summary_records_errors_gracefully():
     from botocore.exceptions import ClientError
 

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/workspaces_euc_mcp_server/__init__.py

@@ -3,4 +3,4 @@
 # A copy of the License is located at http://www.apache.org/licenses/LICENSE-2.0
 """MCP server for administering the Amazon WorkSpaces End User Computing portfolio."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/workspaces_euc_mcp_server/consts.py

@@ -26,14 +26,16 @@ PRICING_API = "pricing"  # AWS Price List (global).
 # Cost Explorer is a global endpoint served from us-east-1 regardless of the working region.
 COST_EXPLORER_REGION = "us-east-1"
 
-# Cost Explorer SERVICE dimension values that map to the EUC portfolio. Names can vary by
-# account/era; the filter simply ignores values that produce no results.
-EUC_COST_EXPLORER_SERVICES = [
-    "Amazon WorkSpaces",
-    "Amazon AppStream",
-    "Amazon WorkSpaces Web",
-    "Amazon WorkSpaces Secure Browser",
-]
+# Substrings (lowercased) that identify an EUC service in the Cost Explorer SERVICE dimension.
+# Matched in code against every service returned — NOT used as an exact-name server-side filter —
+# so account/era naming variants (e.g. "Amazon AppStream 2.0") and casing differences can never be
+# silently dropped. "workspaces" covers Personal/Pools/Core/Web/Secure Browser; "appstream" covers
+# WorkSpaces Applications (AppStream 2.0).
+EUC_COST_EXPLORER_SERVICE_TOKENS = ["workspaces", "appstream"]
+# Substrings that EXCLUDE a service even when an include token matches. WorkSpaces Thin Client is
+# out of scope for this server, but its Cost Explorer name ("Amazon WorkSpaces Thin Client")
+# contains "workspaces" — so exclude it explicitly.
+EUC_COST_EXPLORER_EXCLUDE_TOKENS = ["thin client"]
 
 # Current official product names (used in all human-facing output).
 PRODUCT_WORKSPACES_PERSONAL = "Amazon WorkSpaces Personal"

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.3}/workspaces_euc_mcp_server/tools/cost.py

@@ -195,45 +195,72 @@ def recommend_running_mode_core(
     )
 
 
+def _is_euc_service(service_name: str) -> bool:
+    """True if a Cost Explorer SERVICE value belongs to the EUC portfolio.
+
+    Matches by keyword rather than exact name, so account/era naming variants
+    (e.g. "Amazon AppStream 2.0") are never silently excluded.
+    """
+    name = service_name.lower()
+    if any(token in name for token in consts.EUC_COST_EXPLORER_EXCLUDE_TOKENS):
+        return False
+    return any(token in name for token in consts.EUC_COST_EXPLORER_SERVICE_TOKENS)
+
+
 def get_euc_cost_summary_core(
-    factory: ClientFactory, lookback_days: int = 30, granularity: str = "MONTHLY"
+    factory: ClientFactory,
+    lookback_days: int = 30,
+    granularity: str = "MONTHLY",
+    start_date: str | None = None,
+    end_date: str | None = None,
 ) -> CostSummary:
     errors: list[ServiceError] = []
     # Cost Explorer is a global endpoint served from us-east-1, regardless of working region.
     cost_explorer = factory.client(consts.COST_EXPLORER_API, region=consts.COST_EXPLORER_REGION)
 
-    end_date = datetime.now(UTC).date()
-    start_date = end_date - timedelta(days=lookback_days)
-    start, end = start_date.isoformat(), end_date.isoformat()
-
-    response = try_call(
-        errors,
-        "AWS Cost Explorer",
-        "GetCostAndUsage",
-        lambda: cost_explorer.get_cost_and_usage(
-            TimePeriod={"Start": start, "End": end},
-            Granularity=granularity,
-            Metrics=["UnblendedCost"],
-            Filter={
-                "Dimensions": {
-                    "Key": "SERVICE",
-                    "Values": consts.EUC_COST_EXPLORER_SERVICES,
-                }
-            },
-            GroupBy=[{"Type": "DIMENSION", "Key": "SERVICE"}],
-        ),
-        default={},
-    )
+    if start_date and end_date:
+        start, end = start_date, end_date
+    else:
+        end_d = datetime.now(UTC).date()
+        start_d = end_d - timedelta(days=lookback_days)
+        start, end = start_d.isoformat(), end_d.isoformat()
 
+    # Group by SERVICE across ALL spend and select EUC services in code (see _is_euc_service).
+    # A server-side exact-name SERVICE filter would silently drop any naming variant — the very
+    # bug that hid AppStream / WorkSpaces Applications spend. Page through all results.
     totals_by_service: dict[str, float] = {}
     currency = "USD"
-    for period in (response or {}).get("ResultsByTime", []):
-        for group in period.get("Groups", []):
-            service = (group.get("Keys") or ["Unknown"])[0]
-            metric = group.get("Metrics", {}).get("UnblendedCost", {})
-            amount = float(metric.get("Amount", 0.0))
-            currency = metric.get("Unit", currency)
-            totals_by_service[service] = totals_by_service.get(service, 0.0) + amount
+    next_token: str | None = None
+    while True:
+        kwargs: dict[str, Any] = {
+            "TimePeriod": {"Start": start, "End": end},
+            "Granularity": granularity,
+            "Metrics": ["UnblendedCost"],
+            "GroupBy": [{"Type": "DIMENSION", "Key": "SERVICE"}],
+        }
+        if next_token:
+            kwargs["NextPageToken"] = next_token
+        response = try_call(
+            errors,
+            "AWS Cost Explorer",
+            "GetCostAndUsage",
+            lambda kwargs=kwargs: cost_explorer.get_cost_and_usage(**kwargs),
+            default={},
+        )
+        if not response:
+            break
+        for period in response.get("ResultsByTime", []):
+            for group in period.get("Groups", []):
+                service = (group.get("Keys") or ["Unknown"])[0]
+                if not _is_euc_service(service):
+                    continue
+                metric = group.get("Metrics", {}).get("UnblendedCost", {})
+                amount = float(metric.get("Amount", 0.0))
+                currency = metric.get("Unit", currency)
+                totals_by_service[service] = totals_by_service.get(service, 0.0) + amount
+        next_token = response.get("NextPageToken")
+        if not next_token:
+            break
 
     by_service = [
         CostLineItem(service=s, amount=round(a, 2))
@@ -250,8 +277,10 @@ def get_euc_cost_summary_core(
         by_service=by_service,
         errors=errors,
         notes=[
-            "Filtered to EUC SERVICE dimension values; some products (e.g. Secure Browser) may "
-            "bill under a different service name depending on the account."
+            "EUC services are selected by matching the Cost Explorer SERVICE name against the EUC "
+            "keyword set (workspaces / appstream), so naming variants are not dropped.",
+            "Cost Explorer bills WorkSpaces Personal, Pools, and Core together under the single "
+            "'Amazon WorkSpaces' service; they cannot be separated via the SERVICE dimension.",
         ],
     )
 
@@ -293,18 +322,33 @@ def register(mcp: Any, factory: ClientFactory) -> None:
         return report.model_dump()
 
     async def get_euc_cost_summary(
-        lookback_days: int = 30, granularity: Literal["MONTHLY", "DAILY"] = "MONTHLY"
+        lookback_days: int = 30,
+        granularity: Literal["MONTHLY", "DAILY"] = "MONTHLY",
+        start_date: str | None = None,
+        end_date: str | None = None,
     ) -> dict[str, Any]:
         """Summarize EUC spend by service over a window (account-wide via Cost Explorer).
 
-        Returns unblended cost grouped by service for the EUC portfolio. Cost Explorer is not
-        region-scoped, so figures are account-wide. Read-only.
+        Returns unblended cost grouped by service for the EUC portfolio (WorkSpaces, including
+        Personal/Pools/Core which Cost Explorer bills together as "Amazon WorkSpaces"; WorkSpaces
+        Applications/AppStream; and Secure Browser). Services are matched by keyword, so naming
+        variants are never dropped. Cost Explorer is not region-scoped, so figures are account-wide.
+        Read-only.
+
+        For a specific calendar month, pass start_date/end_date instead of lookback_days — Cost
+        Explorer's end is EXCLUSIVE, so for May 2026 use start_date="2026-05-01",
+        end_date="2026-06-01".
 
         Args:
-            lookback_days: How far back to total (default 30).
+            lookback_days: How far back to total when start_date/end_date are omitted (default 30).
             granularity: Cost Explorer granularity: MONTHLY or DAILY (default MONTHLY).
+            start_date: Optional inclusive start, "YYYY-MM-DD". Use with end_date; overrides
+                lookback_days.
+            end_date: Optional EXCLUSIVE end, "YYYY-MM-DD". Use with start_date.
         """
-        summary = get_euc_cost_summary_core(factory, lookback_days, granularity)
+        summary = get_euc_cost_summary_core(
+            factory, lookback_days, granularity, start_date, end_date
+        )
         return summary.model_dump()
 
     mcp.add_tool(