PyPI - workspaces-euc-mcp-server - Versions diffs - 0.1.2__tar.gz → 0.1.4__tar.gz - Mend

workspaces-euc-mcp-server 0.1.2tar.gz → 0.1.4tar.gz

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 (48) hide show

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.4}/CHANGELOG.md RENAMED Viewed

@@ -5,6 +5,35 @@ All notable changes to this project are documented here. The format is based on
 ## [Unreleased]
+## [0.1.4] - 2026-06-02
+### Added
+- `get_euc_cost_summary` now returns `by_period` — a per-bucket time series (one entry per day for
+  `DAILY`, per month for `MONTHLY`), each with its own per-service split. Previously the tool
+  collapsed all periods into per-service totals, so a `DAILY` request lost the daily breakdown and
+  clients had to query each day individually to chart trends.
+## [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.4}/DESIGN.md RENAMED Viewed

@@ -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.4}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspaces-euc-mcp-server
-Version: 0.1.2
+Version: 0.1.4
 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.4}/README.md RENAMED Viewed

@@ -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.4}/pyproject.toml RENAMED Viewed

@@ -1,6 +1,6 @@
 [project]
 name = "workspaces-euc-mcp-server"
-version = "0.1.2"
+version = "0.1.4"
 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.4}/tests/test_cost.py RENAMED Viewed

@@ -129,6 +129,150 @@ 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_daily_returns_per_period_time_series():
+    # DAILY granularity must preserve the per-day breakdown in by_period (for charts), not just
+    # collapse everything into by_service totals.
+    ce = types.SimpleNamespace(
+        get_cost_and_usage=lambda **_: {
+            "ResultsByTime": [
+                {
+                    "TimePeriod": {"Start": "2026-05-01", "End": "2026-05-02"},
+                    "Groups": [
+                        {
+                            "Keys": ["Amazon WorkSpaces Applications"],
+                            "Metrics": {"UnblendedCost": {"Amount": "30.00", "Unit": "USD"}},
+                        }
+                    ],
+                },
+                {
+                    "TimePeriod": {"Start": "2026-05-02", "End": "2026-05-03"},
+                    "Groups": [
+                        {
+                            "Keys": ["Amazon WorkSpaces Applications"],
+                            "Metrics": {"UnblendedCost": {"Amount": "45.00", "Unit": "USD"}},
+                        }
+                    ],
+                },
+            ]
+        }
+    )
+    factory = FakeFactory({consts.COST_EXPLORER_API: ce})
+    summary = cost.get_euc_cost_summary_core(
+        factory, granularity="DAILY", start_date="2026-05-01", end_date="2026-05-03"
+    )
+    # Aggregate total preserved...
+    assert summary.total == 75.0
+    # ...and the daily series is available, ordered by date.
+    assert [(p.start, p.total) for p in summary.by_period] == [
+        ("2026-05-01", 30.0),
+        ("2026-05-02", 45.0),
+    ]
+    assert summary.by_period[0].by_service[0].service == "Amazon WorkSpaces Applications"
+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.4}/workspaces_euc_mcp_server/__init__.py RENAMED Viewed

@@ -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.4"

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.4}/workspaces_euc_mcp_server/consts.py RENAMED Viewed

@@ -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.4}/workspaces_euc_mcp_server/models.py RENAMED Viewed

@@ -231,6 +231,15 @@ class CostLineItem(BaseModel):
     amount: float
+class CostPeriod(BaseModel):
+    """One time bucket (a day or a month, per the requested granularity)."""
+    start: str
+    end: str
+    total: float
+    by_service: list[CostLineItem] = Field(default_factory=list)
 class CostSummary(BaseModel):
     """Cost rollup for the EUC portfolio over a time window (account-wide)."""
@@ -244,6 +253,13 @@ class CostSummary(BaseModel):
     currency: str = "USD"
     total: float
     by_service: list[CostLineItem] = Field(default_factory=list)
+    by_period: list[CostPeriod] = Field(
+        default_factory=list,
+        description=(
+            "Per-bucket time series (one entry per day for DAILY, per month for MONTHLY). "
+            "Use this for charts / trend analysis."
+        ),
+    )
     errors: list[ServiceError] = Field(default_factory=list)
     notes: list[str] = Field(default_factory=list)

{workspaces_euc_mcp_server-0.1.2 → workspaces_euc_mcp_server-0.1.4}/workspaces_euc_mcp_server/tools/cost.py RENAMED Viewed

@@ -20,6 +20,7 @@ from .. import consts
 from ..clients import ClientFactory
 from ..models import (
     CostLineItem,
+    CostPeriod,
     CostSummary,
     Recommendation,
     RecommendationReport,
@@ -195,51 +196,95 @@ 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, keeping both
+    # the overall per-service totals and the per-period (daily/monthly) breakdown for charts.
     totals_by_service: dict[str, float] = {}
+    per_period: dict[tuple[str, str], 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", []):
+            tp = period.get("TimePeriod", {})
+            bucket = per_period.setdefault((tp.get("Start", ""), tp.get("End", "")), {})
+            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
+                bucket[service] = bucket.get(service, 0.0) + amount
+        next_token = response.get("NextPageToken")
+        if not next_token:
+            break
     by_service = [
         CostLineItem(service=s, amount=round(a, 2))
         for s, a in sorted(totals_by_service.items(), key=lambda kv: kv[1], reverse=True)
     ]
     total = round(sum(item.amount for item in by_service), 2)
+    by_period = [
+        CostPeriod(
+            start=p_start,
+            end=p_end,
+            total=round(sum(svc.values()), 2),
+            by_service=[
+                CostLineItem(service=s, amount=round(a, 2))
+                for s, a in sorted(svc.items(), key=lambda kv: kv[1], reverse=True)
+            ],
+        )
+        for (p_start, p_end), svc in sorted(per_period.items())
+    ]
     return CostSummary(
         start=start,
@@ -248,10 +293,15 @@ def get_euc_cost_summary_core(
         currency=currency,
         total=total,
         by_service=by_service,
+        by_period=by_period,
         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.",
+            "by_period gives the per-bucket time series (per day for DAILY, per month for MONTHLY) "
+            "for charts/trends; by_service is the total across the whole window.",
         ],
     )
@@ -293,18 +343,38 @@ 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.
+        Returns both `by_service` (totals across the whole window) and `by_period` (a per-bucket
+        time series — one entry per day for DAILY, per month for MONTHLY — each with its own
+        per-service split). Use `by_period` with granularity="DAILY" to chart daily trends in a
+        single call.
+        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(