workspaces-euc-mcp-server 0.1.1__tar.gz

workspaces_euc_mcp_server-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (into .venv to match the pyright config)
+        run: |
+          python -m venv .venv
+          . .venv/bin/activate
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: . .venv/bin/activate && ruff check .
+      - name: Format check
+        run: . .venv/bin/activate && ruff format --check .
+      - name: Type check
+        run: . .venv/bin/activate && pyright
+      - name: Security scan
+        run: . .venv/bin/activate && bandit -c pyproject.toml -r workspaces_euc_mcp_server
+      - name: Test (includes no-embedded-secrets guardrail)
+        run: . .venv/bin/activate && pytest -q

workspaces_euc_mcp_server-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+# Publishes the package to PyPI using OIDC Trusted Publishing (no API token stored).
+# Fires when a GitHub Release is published, or can be run manually from the Actions tab.
+#
+# One-time PyPI setup (project owner): add a "Trusted Publisher" (pending publisher is fine before
+# the first release) at https://pypi.org/manage/account/publishing/ with:
+#   PyPI project name: workspaces-euc-mcp-server
+#   Owner:             bengroeneveldsg
+#   Repository:        aws-workspaces-euc-mcp
+#   Workflow name:     publish.yml
+#   Environment:       pypi
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for OIDC trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

workspaces_euc_mcp_server-0.1.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+
+# OS / editor / tooling
+.DS_Store
+.idea/
+.vscode/
+.claude/
+
+# AWS / secrets — never commit credentials
+.aws/
+*.pem
+.env
+
+# Generated, account-specific report artifacts — these contain tenant data
+# (real WorkSpace IDs, metrics, costs) and must never be committed.
+*-perf.html
+ws-*.html
+/reports/

workspaces_euc_mcp_server-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.10
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        additional_dependencies: ["bandit[toml]"]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: detect-private-key

workspaces_euc_mcp_server-0.1.1/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-06-01
+
+Best-practice alignment pass (audited against the awslabs MCP design guidelines and the MCP
+tool-annotations spec).
+
+### Added
+- MCP **tool annotations** on every tool (`readOnlyHint` / `destructiveHint` / `idempotentHint` /
+  `openWorldHint` / `title`), so clients can show appropriate consent UX — read-only tools are
+  marked read-only, lifecycle writes non-destructive (start/stop/modify idempotent), and
+  terminate/rebuild/restore destructive. Aligns with the awslabs MCP design guidelines and the
+  MCP tool-annotations spec.
+- `FASTMCP_LOG_LEVEL` env var to control the server log level (default `INFO`).
+- `Literal` types on fixed-value parameters (`running_mode`, cost `granularity`) for clearer
+  client-side validation.
+
+## [0.1.0] - 2026-06-01
+
+First tagged release. Admin-focused MCP server for the Amazon WorkSpaces EUC portfolio —
+18 read-only tools (inventory, diagnostics, performance/usage history, cost & right-sizing with
+$ estimates, audit, reporting) and 10 guarded write/destructive tools, across WorkSpaces Personal,
+Pools, Applications, Secure Browser, and Core Managed Instances. Four additive IAM tiers,
+multi-account/MSP via assume-role, no embedded tenant data, CI (ruff/format/pyright/bandit/pytest
+on Py 3.11–3.13).
+
+### Added
+- CI now also runs `pyright` (basic type-checking); the codebase type-checks clean.
+- Multi-account / MSP support: `--assume-role-arn` (+ optional `--external-id`) transparently
+  `sts:AssumeRole`s into another account, with auto-refreshing credentials and no tool-code
+  changes. The launching identity needs `sts:AssumeRole` on the target role; the role needs the
+  matching tier policy.
+- Estimated monthly $ savings on recommendations, via the AWS Price List API (new
+  `tools/pricing.py`, needs `pricing:GetProducts` / Tier 1): `recommend_running_mode` now fills
+  `estimated_monthly_savings_usd` for AlwaysOn→AutoStop candidates (AlwaysOn monthly − AutoStop
+  base − hourly×estimated-usage), and `recommend_bundle_rightsizing` fills the AlwaysOn
+  compute-tier monthly difference. Best-effort and conservative: matches the canonical
+  Included-license SKU on region/OS/compute/volume sizes and returns **null** (never a wrong
+  number) when it can't match. Validated live (Standard 80/50 → $35/mo, Power 175/100 → $98/mo).
+- `diagnose_pool` (Tier 0): a WorkSpaces Pool health diagnostic correlating pool state, pool
+  errors, user-session capacity, backing directory health, and CloudWatch session utilization —
+  bringing Pools to parity with the WorkSpace and fleet diagnostics.
+- WorkSpaces Core Managed Instances coverage (the `workspaces-instances` API, previously not
+  covered at all): `get_euc_inventory_summary` and `generate_inventory_report` now include managed
+  instances, enriched with the backing EC2 instance's type / state / launch time / private IP /
+  platform (via `ec2:DescribeInstances`). Adds the
+  `workspaces-instances:ListWorkspaceInstances`/`GetWorkspaceInstance`/`ListInstanceTypes`/`ListRegions`
+  and `ec2:DescribeInstances` IAM actions to all tiers.
+- WorkSpaces Secure Browser parity: `get_secure_browser_portal_details` (resolves user/network
+  settings — clipboard/print/download controls) and `get_secure_browser_portal_usage`
+  (`AWS/WorkSpacesWeb` session metrics; note Secure Browser only emits these during sessions, so
+  idle portals return nothing). Adds `workspaces-web:GetUserSettings`/`GetNetworkSettings` to the
+  IAM tiers.
+- `audit_security_posture` is now **cross-service**: in addition to WorkSpace volume encryption and
+  directory IP access control groups, it flags **Secure Browser portals** and **Applications
+  stacks** that permit data egress (clipboard-to-local / download / print).
+
+### Fixed
+- `generate_inventory_report` Pools capacity was always `null` — it read the wrong key (`Capacity`
+  instead of `CapacityStatus`). Now populated with the real session capacity.
+
+### Added
+- WorkSpaces Personal **user mapping** + many previously-dropped fields in `generate_inventory_report`
+  (found by auditing the raw API responses): each desktop now exposes assigned `UserName` (as the
+  record label), `ComputerName`, `IpAddress`, plus `OperatingSystemName`, `Protocols`, root/user
+  volume sizes, AutoStop timeout, root/user encryption flags, and subnet. `diagnose_workspace_connectivity`
+  signals now include `user_name`/`computer_name`. Pools also expose bundle/directory/running-mode/
+  description; Applications fleets expose image name and session/idle/disconnect timeouts; stacks
+  expose `UserSettings` (clipboard/print/file-transfer controls) and storage connectors; Secure
+  Browser portals expose authentication type, max concurrent sessions, instance and renderer type.
+- `get_workspace_connection_history` and `get_pool_session_history` (Tier 0): time-series usage
+  history for WorkSpaces Personal desktops (UserConnected + connection attempts/failures) and
+  WorkSpaces Pools (Active/Actual/Available/Desired/Pending user-session capacity +
+  utilization), each with a plain-language summary that flags unused desktops / idle pool
+  capacity. Generalized the CloudWatch series fetch and added a generic `UsageHistory` model.
+  Note: the Pools CloudWatch dimension is literally `"WorkSpaces pool ID"` (with spaces).
+- `get_application_fleet_usage` (Tier 0): time-series **usage history** for a WorkSpaces
+  Applications fleet from the `AWS/AppStream` namespace (InUseCapacity, CapacityUtilization,
+  Running/Available/Actual/Desired/Pending capacity) — per-bucket points plus latest/average/peak
+  and a plain-language summary that flags idle running capacity.
+- WorkSpaces Applications **stacks**: `get_euc_inventory_summary` now counts stacks (alongside
+  fleets) and `generate_inventory_report` lists each stack with its associated fleets
+  (`ListAssociatedFleets`). IAM policies updated to use `appstream:ListAssociatedFleets` /
+  `ListAssociatedStacks` (replacing a non-existent `DescribeFleetAssociations`).
+- Legacy service-name acceptance: the server instructions and application-fleet tool descriptions
+  now teach the model that "AppStream" / "AppStream 2.0" means Amazon WorkSpaces Applications (and
+  "WorkSpaces Web" means Secure Browser), so queries using former names route correctly while
+  output keeps the current name. Added a `LEGACY_NAME_ALIASES` map and guardrail tests.
+- `get_workspace_performance` (Tier 0): native per-desktop CPU/memory/GPU/FPS/disk/latency/uptime
+  metrics from the `AWS/WorkSpaces` namespace (latest/average/peak), no CloudWatch agent required.
+- `recommend_bundle_rightsizing` (Tier 0): now implemented on the native CPU/memory metrics —
+  suggests smaller/larger compute types from window-peak headroom (general families; graphics
+  excluded). This corrects an earlier wrong assumption that these metrics required the CloudWatch
+  agent; verified against a live account.
+
+### Changed
+- Internal: consolidated the per-module `try_call` / `paginate` / `count_by` helpers onto the
+  shared `tools/_common.py` (no behaviour change). Refreshed `DESIGN.md` to reflect shipped state
+  and added an "Example admin questions" section to the README.
+
+### Added
+- Phase 3 destructive tools (Tier 3), registered only with both `--enable-writes` and
+  `--enable-destructive`: `terminate_workspaces`, `rebuild_workspaces`, and `restore_workspace`.
+  On top of dry-run + blast-radius cap, each execution requires an exact typed acknowledgement
+  phrase (`"TERMINATE"` / `"REBUILD"` / `"RESTORE"`). Added the Tier 3 IAM policy
+  (`iam/tier3-destructive.json`) and an optional `acknowledgement_required` field on `WriteOutcome`.
+- Phase 2 guarded lifecycle tools for WorkSpaces Pools and Applications (writes, Tier 2):
+  `start_workspaces_pool`, `stop_workspaces_pool`, `update_workspaces_pool_capacity`,
+  `start_application_fleet`, `stop_application_fleet`, and `update_application_fleet_capacity`.
+  Same safety model (dry-run default, opt-in registration); Tier 2 policy extended with the Pools
+  and AppStream start/stop/update actions.
+- Phase 2 guarded lifecycle tools (writes, Tier 2), registered only with `--enable-writes`:
+  `start_workspaces`, `stop_workspaces`, `reboot_workspaces`, and `modify_workspace_running_mode`.
+  Mutations are dry-run unless `confirm=true`, and confirmed bulk actions are refused above
+  `--max-bulk-targets`. Added the Tier 2 IAM policy (`iam/tier2-lifecycle.json`) and
+  `WriteOutcome`/`TargetResult` models.
+- Phase 1 reporting & audit tools (read-only, Tier 0): `generate_inventory_report`,
+  `audit_security_posture` (volume encryption + directory IP access control groups), and
+  `list_unused_resources`. Added a shared `tools/_common.py` (best-effort call + pagination
+  helpers) and inventory/audit/unused-resource models; `Finding` gained an optional `resource_id`.
+- Phase 1 cost & utilization tools (read-only, Tier 1): `analyze_workspace_utilization`,
+  `recommend_running_mode`, and `get_euc_cost_summary`, plus the Tier 1 IAM policy
+  (`iam/tier1-cost.json`) adding Cost Explorer and Pricing access.
+- Utilization/recommendation/cost models (`WorkspaceUtilization`, `UtilizationReport`,
+  `Recommendation`, `RecommendationReport`, `CostSummary`).
+- Phase 1 diagnostics tools (read-only, Tier 0): `diagnose_workspace_connectivity`,
+  `diagnose_application_fleet`, and `check_directory_health` — each correlates resource state,
+  directory health, CloudWatch telemetry, and auto-scaling activity into a severity-ranked
+  diagnosis with recommendations.
+- Generic `ServiceError`, `Finding`, `Diagnosis`, and `DirectoryHealthReport` models.
+- Phase 0 scaffold: FastMCP server, region/profile-aware boto3 client factory, read-only safety
+  defaults, and the `get_euc_inventory_summary` tool spanning WorkSpaces Personal, Pools,
+  Applications, and Secure Browser.
+- Tier 0 (read-only) IAM policy and per-tier IAM documentation.
+- Test suite (fake-client based) and tooling config (ruff, pyright, bandit, pre-commit).
+- `DESIGN.md` with the full tool inventory and phased roadmap.

workspaces_euc_mcp_server-0.1.1/DESIGN.md

@@ -0,0 +1,203 @@
+# Amazon WorkSpaces EUC Admin MCP Server — Design & Build Plan
+
+> Status: **Phases 0–3 shipped** (2026-05-31). An MCP server giving administrators AI-assisted
+> 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
+> 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.
+
+## 1. Principles
+
+1. **Admin persona only.** Operators managing fleets — not end users.
+2. **Domain intelligence over API mirroring.** Generic servers (AWS MCP Server, Cloud Control,
+   AWS API) already call EUC APIs raw. Our value is cross-service diagnosis, fleet-level
+   optimization, and EUC-aware guardrails — not 1:1 API wrappers.
+3. **Security-first, least privilege.** Read-only by default. Writes are opt-in, separately
+   permissioned, dry-run-able, confirmation-gated, and blast-radius-limited.
+4. **No embedded tenant data — ever.** This is redistributable software run by many parties.
+   Credentials, account IDs, ARNs, profile names, regions, and any other consumer-specific data
+   are supplied **only at runtime** (AWS credential chain, CLI flags, env vars) and are **never**
+   hardcoded, persisted to disk, or committed. The codebase ships with zero account-specific data.
+5. **Official AWS naming everywhere a human reads.** Legacy identifiers only where the SDK/API
+   literally requires them (and labelled as such).
+6. **Build on awslabs conventions** so we match patterns customers already trust.
+
+## 2. Services in scope (official naming → API identifier)
+
+| Product name | Underlying API (boto3 client) | Notes |
+|---|---|---|
+| Amazon WorkSpaces Personal | `workspaces` | Persistent desktops |
+| Amazon WorkSpaces Pools | `workspaces` (Pools operations) | Non-persistent pooled |
+| Amazon WorkSpaces Applications | `appstream` | App streaming (formerly AppStream 2.0) |
+| Amazon WorkSpaces Secure Browser | `workspaces-web` | Managed browser (formerly WorkSpaces Web) |
+| Amazon WorkSpaces Core | `workspaces` | Partner/BYO-VDI integration |
+
+**Excluded:** Amazon WorkSpaces Thin Client.
+
+## 3. Architecture & stack (per awslabs DESIGN_GUIDELINES)
+
+- **Language/framework:** Python 3.11+, FastMCP, Pydantic models, boto3, async/await.
+- **Auth:** standard boto3 credential chain via `AWS_PROFILE` / `AWS_REGION`; no secrets stored
+  in the server. Assumed-role / Identity Center friendly. **Single-account v1**, with a client
+  factory designed to add cross-account `sts:AssumeRole` later without touching tool code.
+- **Transport:** local `uvx`/stdio first; tool logic kept transport-agnostic so a remote
+  (AgentCore Runtime) deployment can be added later.
+- **Distribution:** `uvx awslabs.workspaces-euc-mcp-server@latest` and a Docker image.
+- **Observability:** Loguru with env-controlled log level; structured tool errors via `ctx.error`.
+- **Repo layout:**
+  ```
+  awslabs/workspaces_euc_mcp_server/
+    __init__.py        # version
+    server.py          # FastMCP app + tool registration
+    consts.py          # service/API constants, region maps
+    models.py          # Pydantic request/response models
+    clients.py         # boto3 client factory (region/profile aware)
+    tools/
+      inventory.py
+      diagnostics.py
+      cost.py
+      reporting.py
+      lifecycle.py     # Phase 2 (guarded writes)
+    iam/               # shippable least-privilege policy docs per tier
+  tests/               # pytest + pytest-asyncio + moto
+  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.
+
+## 4. Configuration / safety flags
+
+- `--readonly` (default **on**): only Describe/Get/List tools are registered.
+- `--enable-writes`: registers Phase-2 lifecycle tools (still dry-run/confirm gated).
+- `--enable-destructive`: separately gates terminate/rebuild/restore.
+- `--max-bulk-targets N`: blast-radius cap for any bulk mutation.
+- `AWS_REGION` / `AWS_PROFILE`: standard.
+
+## 5. Tool inventory
+
+Each tool lists the IAM actions it needs. Tools are *workflows* that compose several API calls
+and return a synthesized result, not raw API passthroughs.
+
+### Phase 1 — Read / Diagnose / Optimize (read-only, Tiers 0–1)
+
+**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 |
+
+**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` |
+
+**Cost & utilization optimization**
+| 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` |
+| `get_euc_cost_summary` | Spend rollup filtered to EUC services | `ce:GetCostAndUsage`, `ce:GetDimensionValues` |
+
+**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` |
+
+### 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` |
+| `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` |
+
+### Phase 3 — Destructive (Tier 3, `--enable-destructive`, hardest gating)
+| Tool | Purpose | IAM actions |
+|---|---|---|
+| `rebuild_workspaces` / `restore_workspace` | Recover a desktop (data impact) | `workspaces:Rebuild/RestoreWorkspace` |
+| `terminate_workspaces` | Decommission (irreversible) | `workspaces:TerminateWorkspaces` |
+
+## 6. IAM policy tiers (shipped with the server)
+
+We ship a managed policy document per tier so customers grant exactly what they enable.
+
+- **Tier 0 — Diagnostics (read-only):** `workspaces:Describe*`, `appstream:Describe*`,
+  `workspaces-web:Get*`/`List*`, `ds:DescribeDirectories`, `cloudwatch:GetMetricData`,
+  `application-autoscaling:DescribeScalingActivities`.
+- **Tier 1 — Cost/optimization (read-only):** Tier 0 + `ce:GetCostAndUsage`,
+  `ce:GetDimensionValues`, `pricing:GetProducts`.
+- **Tier 2 — Lifecycle (writes):** Tier 1 + `workspaces:Start/Stop/Reboot/ModifyWorkspace*`,
+  `workspaces:UpdateWorkspacesPool`, `appstream:Start/Stop/UpdateFleet`.
+- **Tier 3 — Destructive:** Tier 2 + `workspaces:Rebuild/Restore/TerminateWorkspaces`.
+
+Each tier is additive; default install = Tier 0. Recommend scoping by resource tag / directory
+where the API supports it, and using **IAM context keys to separate the agent identity from the
+human operator** (the pattern the AWS MCP Server uses).
+
+## 7. Security model
+
+- Read-only default; writes require an explicit launch flag *and* the matching IAM tier.
+- Every mutation: `dry_run` plan → explicit confirmation → blast-radius cap.
+- **No credentials or tenant data in the server.** Credentials are resolved solely from the
+  standard AWS chain (`AWS_PROFILE` / `AWS_REGION` / SSO / assumed role) at runtime. The server
+  stores nothing to disk — boto3 clients are cached in memory only; there is no config/state file,
+  no credential cache, no account ID, ARN, or profile name baked into source.
+- **Redistributable-safe repo:** nothing account-specific is ever committed. `.gitignore` blocks
+  `.aws/`, `.env`, `*.pem`; pre-commit runs `detect-private-key`; CI greps for hardcoded
+  account IDs/ARNs/secrets. Examples in docs use placeholders only.
+- Full auditability via CloudTrail (every underlying API call is attributable).
+- Optional `audit_security_posture` self-check against EUC best practices.
+- Input validation with Pydantic; bandit + AST checks in CI.
+
+## 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
+  internal users.
+- **Phase 1 — Read/Diagnose/Optimize:** full inventory + diagnostics + cost tools (Tiers 0–1).
+  This is the demonstrable-value milestone.
+- **Phase 2 — Guarded lifecycle:** writes behind `--enable-writes`, dry-run + confirm + caps.
+- **Phase 3 — Destructive ops:** terminate/rebuild/restore behind `--enable-destructive`.
+- **Phase 4 — Polish:** packaging (uvx/Docker), docs, optional remote/AgentCore deployment.
+
+## 9. Decisions
+
+1. **Distribution:** standalone **public repo on the author's personal GitHub**, consumable and
+   self-deployable by others, with full documentation (README, install, IAM setup, examples).
+   Follows awslabs conventions so it feels familiar, but lives independently (not in `awslabs/mcp`).
+2. **Account model:** **single-account first** (standard boto3 credential chain). Architect the
+   client factory so cross-account role assumption (MSP/multi-account) can be added later without
+   refactoring tools.
+3. **Deployment:** **local `uvx` first**, but design transport/config so the same server can be
+   deployed remotely (e.g. Bedrock AgentCore Runtime) later — keep tool logic transport-agnostic.
+
+## 10. Still open (defer)
+
+- **CORRECTED & SHIPPED:** `recommend_bundle_rightsizing` was previously deferred on the
+  (incorrect) assumption that `AWS/WorkSpaces` doesn't publish CPU/memory. It does — the namespace
+  natively emits `CPUUsage`, `MemoryUsage`, `GPUUsage`, `FramesPerSecond`, disk usage, latency,
+  uptime, etc., keyed by `WorkspaceId`, with **no CloudWatch agent required** (verified against a
+  live account). `get_workspace_performance` and `recommend_bundle_rightsizing` now ship on these
+  native metrics (Tier 0).
+- Cost tools: Cost Explorer (`ce`) only for v1, or add CUR for finer granularity later?
+- Resource-tag / directory-scoped IAM conditions — which services support them well enough to
+  recommend by default.