workspaces-euc-mcp-server 0.1.1__py3-none-any.whl

workspaces_euc_mcp_server/server.py

@@ -0,0 +1,129 @@
+# Copyright bengroeneveldsg. Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at http://www.apache.org/licenses/LICENSE-2.0
+"""FastMCP application entry point for the WorkSpaces EUC MCP server."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from loguru import logger
+from mcp.server.fastmcp import FastMCP
+
+from . import consts
+from .clients import ClientFactory
+from .tools import (
+    cost,
+    destructive,
+    diagnostics,
+    inventory,
+    lifecycle,
+    performance,
+    reporting,
+    secure_browser,
+)
+
+
+def create_server(
+    *,
+    region: str | None = None,
+    profile: str | None = None,
+    role_arn: str | None = None,
+    external_id: str | None = None,
+    enable_writes: bool = False,
+    enable_destructive: bool = False,
+    max_bulk_targets: int = consts.DEFAULT_MAX_BULK_TARGETS,
+) -> FastMCP:
+    """Build the FastMCP server, registering tools according to the safety flags."""
+    factory = ClientFactory(
+        region=region, profile=profile, role_arn=role_arn, external_id=external_id
+    )
+    mcp = FastMCP(consts.SERVER_NAME, instructions=consts.SERVER_INSTRUCTIONS)
+
+    # Phase 1 read-only tools are always registered.
+    inventory.register(mcp, factory)
+    diagnostics.register(mcp, factory)
+    cost.register(mcp, factory)
+    reporting.register(mcp, factory)
+    performance.register(mcp, factory)
+    secure_browser.register(mcp, factory)
+
+    if enable_writes:
+        logger.info(
+            "Write tools enabled (Tier 2). Mutations are dry-run unless confirm=true and are "
+            "capped at {} targets per bulk action.",
+            max_bulk_targets,
+        )
+        lifecycle.register(
+            mcp,
+            factory,
+            max_bulk_targets=max_bulk_targets,
+            enable_destructive=enable_destructive,
+        )
+
+        if enable_destructive:
+            logger.warning(
+                "Destructive tools enabled (Tier 3): terminate/rebuild/restore. These require "
+                "confirm=true AND an exact acknowledgement phrase to execute."
+            )
+            destructive.register(mcp, factory, max_bulk_targets=max_bulk_targets)
+
+    return mcp
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog=consts.SERVER_NAME,
+        description="Admin MCP server for the Amazon WorkSpaces EUC portfolio (read-only default).",
+    )
+    parser.add_argument("--region", help="AWS region (overrides AWS_REGION / profile default).")
+    parser.add_argument("--profile", help="AWS named profile to use.")
+    parser.add_argument(
+        "--assume-role-arn",
+        help="Cross-account IAM role ARN to assume (multi-account / MSP). The caller needs "
+        "sts:AssumeRole on it; the role needs the matching tier permissions.",
+    )
+    parser.add_argument(
+        "--external-id",
+        help="ExternalId to pass when assuming --assume-role-arn (if the role requires one).",
+    )
+    parser.add_argument(
+        "--enable-writes",
+        action="store_true",
+        help="Register Phase 2 lifecycle (write) tools. Off by default.",
+    )
+    parser.add_argument(
+        "--enable-destructive",
+        action="store_true",
+        help="Allow destructive ops (terminate/rebuild/restore). Requires --enable-writes.",
+    )
+    parser.add_argument(
+        "--max-bulk-targets",
+        type=int,
+        default=consts.DEFAULT_MAX_BULK_TARGETS,
+        help="Blast-radius cap for bulk mutations (Phase 2).",
+    )
+    args = parser.parse_args()
+
+    if args.enable_destructive and not args.enable_writes:
+        parser.error("--enable-destructive requires --enable-writes.")
+
+    logger.remove()
+    logger.add(sys.stderr, level=os.environ.get("FASTMCP_LOG_LEVEL", "INFO").upper())
+
+    mcp = create_server(
+        region=args.region,
+        profile=args.profile,
+        role_arn=args.assume_role_arn,
+        external_id=args.external_id,
+        enable_writes=args.enable_writes,
+        enable_destructive=args.enable_destructive,
+        max_bulk_targets=args.max_bulk_targets,
+    )
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

workspaces_euc_mcp_server/tools/__init__.py

@@ -0,0 +1,4 @@
+# Copyright bengroeneveldsg. Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at http://www.apache.org/licenses/LICENSE-2.0
+"""Tool implementations, grouped by capability area."""

workspaces_euc_mcp_server/tools/_common.py

@@ -0,0 +1,87 @@
+# Copyright bengroeneveldsg. Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at http://www.apache.org/licenses/LICENSE-2.0
+"""Shared best-effort AWS-call helpers used by the tool modules."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from botocore.exceptions import BotoCoreError, ClientError
+from loguru import logger
+from mcp.types import ToolAnnotations
+
+from ..models import ServiceError
+
+
+def read_only(title: str) -> ToolAnnotations:
+    """Annotations for a read-only tool (closed-domain: the configured AWS account)."""
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+
+
+def writes(title: str, *, idempotent: bool = False, destructive: bool = False) -> ToolAnnotations:
+    """Annotations for a mutating tool (lifecycle or destructive)."""
+    return ToolAnnotations(
+        title=title,
+        readOnlyHint=False,
+        destructiveHint=destructive,
+        idempotentHint=idempotent,
+        openWorldHint=False,
+    )
+
+
+def try_call(
+    errors: list[ServiceError],
+    service: str,
+    operation: str,
+    fn: Callable[[], Any],
+    default: Any = None,
+) -> Any:
+    """Run an AWS call, recording (not raising) errors so collection can continue."""
+    try:
+        return fn()
+    except (ClientError, BotoCoreError) as exc:
+        logger.warning("AWS call failed: {} {} -> {}", service, operation, exc)
+        errors.append(ServiceError(service=service, operation=operation, message=str(exc)))
+        return default
+
+
+def paginate(
+    operation: Callable[..., dict[str, Any]],
+    list_key: str,
+    pagination_in: str = "NextToken",
+    pagination_out: str = "NextToken",
+    **kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Drain a paginated AWS list/describe operation into a flat list.
+
+    ``pagination_in`` / ``pagination_out`` are the request and response field names AWS uses for
+    the continuation marker (e.g. ``NextToken``, or ``nextToken`` for camelCase services).
+    """
+    items: list[dict[str, Any]] = []
+    marker: str | None = None
+    while True:
+        params = dict(kwargs)
+        if marker:
+            params[pagination_in] = marker
+        response = operation(**params)
+        items.extend(response.get(list_key, []))
+        marker = response.get(pagination_out)
+        if not marker:
+            return items
+
+
+def count_by(items: list[dict[str, Any]], state_key: str) -> dict[str, int]:
+    """Count items grouped by a state-like field (missing values count as UNKNOWN)."""
+    counts: dict[str, int] = {}
+    for item in items:
+        state = item.get(state_key, "UNKNOWN")
+        counts[state] = counts.get(state, 0) + 1
+    return counts

workspaces_euc_mcp_server/tools/cost.py

@@ -0,0 +1,314 @@
+# Copyright bengroeneveldsg. Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at http://www.apache.org/licenses/LICENSE-2.0
+"""Cost & utilization optimization tools (read-only, IAM Tier 1).
+
+These add Cost Explorer and Pricing access on top of Tier 0. They identify under-used WorkSpaces
+Personal desktops, recommend running-mode changes, and summarize EUC spend — returning opinionated
+findings rather than raw billing/metric data.
+
+Utilization is derived from the standard ``AWS/WorkSpaces`` ``UserConnected`` metric (1 when a user
+is connected during a period); no CloudWatch agent is required.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal
+
+from .. import consts
+from ..clients import ClientFactory
+from ..models import (
+    CostLineItem,
+    CostSummary,
+    Recommendation,
+    RecommendationReport,
+    ServiceError,
+    UtilizationReport,
+    WorkspaceUtilization,
+)
+from . import pricing
+from ._common import paginate, read_only, try_call
+
+
+def _daily_connected_values(cloudwatch: Any, workspace_id: str, lookback_days: int) -> list[float]:
+    """Per-day maximum of UserConnected (1 if the desktop had any connection that day)."""
+    end = datetime.now(UTC)
+    start = end - timedelta(days=lookback_days)
+    response = cloudwatch.get_metric_data(
+        MetricDataQueries=[
+            {
+                "Id": "uc",
+                "MetricStat": {
+                    "Metric": {
+                        "Namespace": "AWS/WorkSpaces",
+                        "MetricName": "UserConnected",
+                        "Dimensions": [{"Name": "WorkspaceId", "Value": workspace_id}],
+                    },
+                    "Period": 86400,
+                    "Stat": "Maximum",
+                },
+                "ReturnData": True,
+            }
+        ],
+        StartTime=start,
+        EndTime=end,
+    )
+    return response.get("MetricDataResults", [{}])[0].get("Values", [])
+
+
+def _classify(active_days: int | None, lookback_days: int, idle_threshold: int) -> str:
+    if active_days is None:
+        return "unknown"
+    if active_days == 0:
+        return "unused"
+    if active_days <= idle_threshold:
+        return "idle"
+    return "active"
+
+
+def _collect_utilization(
+    factory: ClientFactory, region: str | None, lookback_days: int
+) -> tuple[list[WorkspaceUtilization], list[ServiceError]]:
+    errors: list[ServiceError] = []
+    workspaces_client = factory.client(consts.WORKSPACES_API, region=region)
+    cloudwatch = factory.client(consts.CLOUDWATCH_API, region=region)
+
+    workspaces = try_call(
+        errors,
+        consts.PRODUCT_WORKSPACES_PERSONAL,
+        "DescribeWorkspaces",
+        lambda: paginate(workspaces_client.describe_workspaces, "Workspaces"),
+        default=[],
+    )
+
+    idle_threshold = max(1, lookback_days // 7)
+    items: list[WorkspaceUtilization] = []
+    for ws in workspaces or []:
+        wid = ws.get("WorkspaceId", "")
+        props = ws.get("WorkspaceProperties", {})
+        values = try_call(
+            errors,
+            "Amazon CloudWatch",
+            "GetMetricData",
+            lambda wid=wid: _daily_connected_values(cloudwatch, wid, lookback_days),
+        )
+        active_days = sum(1 for v in values if v >= 1) if values is not None else None
+        items.append(
+            WorkspaceUtilization(
+                workspace_id=wid,
+                running_mode=props.get("RunningMode"),
+                lookback_days=lookback_days,
+                active_days=active_days,
+                classification=_classify(active_days, lookback_days, idle_threshold),
+                compute_type=props.get("ComputeTypeName"),
+                operating_system=props.get("OperatingSystemName"),
+                root_volume_gib=props.get("RootVolumeSizeGib"),
+                user_volume_gib=props.get("UserVolumeSizeGib"),
+            )
+        )
+    return items, errors
+
+
+def analyze_workspace_utilization_core(
+    factory: ClientFactory, region: str | None, lookback_days: int = 14
+) -> UtilizationReport:
+    items, errors = _collect_utilization(factory, region, lookback_days)
+    counts: dict[str, int] = {}
+    for item in items:
+        counts[item.classification] = counts.get(item.classification, 0) + 1
+    return UtilizationReport(
+        region=region,
+        lookback_days=lookback_days,
+        total=len(items),
+        counts=counts,
+        workspaces=items,
+        errors=errors,
+        notes=[
+            "Utilization is based on the AWS/WorkSpaces UserConnected metric; a desktop with no "
+            "datapoints over the window is reported as unused."
+        ],
+    )
+
+
+def recommend_running_mode_core(
+    factory: ClientFactory, region: str | None, lookback_days: int = 14
+) -> RecommendationReport:
+    items, errors = _collect_utilization(factory, region, lookback_days)
+    recommendations: list[Recommendation] = []
+    for item in items:
+        if item.running_mode == "ALWAYS_ON" and item.classification in {"unused", "idle"}:
+            prices = pricing.get_workspace_prices(
+                factory,
+                region,
+                item.operating_system,
+                item.compute_type,
+                item.root_volume_gib,
+                item.user_volume_gib,
+            )
+            savings = pricing.estimate_alwayson_to_autostop_savings(
+                prices, item.active_days, lookback_days
+            )
+            recommendations.append(
+                Recommendation(
+                    target_id=item.workspace_id,
+                    kind="running_mode",
+                    current="ALWAYS_ON",
+                    recommended="AUTO_STOP",
+                    rationale=(
+                        f"Connected on {item.active_days} of the last {lookback_days} days "
+                        f"({item.classification}); AlwaysOn bills the full month regardless of "
+                        "use, so AutoStop typically costs less at low usage."
+                    ),
+                    estimated_monthly_savings_usd=savings,
+                    confidence="high" if item.classification == "unused" else "medium",
+                )
+            )
+        elif (
+            item.running_mode == "AUTO_STOP"
+            and item.active_days is not None
+            and item.active_days >= lookback_days
+        ):
+            recommendations.append(
+                Recommendation(
+                    target_id=item.workspace_id,
+                    kind="running_mode",
+                    current="AUTO_STOP",
+                    recommended="evaluate ALWAYS_ON",
+                    rationale=(
+                        f"Connected every day in the last {lookback_days} days; if daily usage is "
+                        "also long-duration, AlwaysOn may be cheaper than per-hour AutoStop."
+                    ),
+                    confidence="low",
+                )
+            )
+    return RecommendationReport(
+        region=region,
+        lookback_days=lookback_days,
+        recommendations=recommendations,
+        errors=errors,
+        notes=[
+            "estimated_monthly_savings_usd is a best-effort Price List estimate (Included license, "
+            "on-demand, matched on compute type / OS / volume sizes); it is null when prices can't "
+            "be matched or pricing:GetProducts is not permitted. Assumes ~8h per active day."
+        ],
+    )
+
+
+def get_euc_cost_summary_core(
+    factory: ClientFactory, lookback_days: int = 30, granularity: str = "MONTHLY"
+) -> 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={},
+    )
+
+    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
+
+    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)
+
+    return CostSummary(
+        start=start,
+        end=end,
+        granularity=granularity,
+        currency=currency,
+        total=total,
+        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."
+        ],
+    )
+
+
+def register(mcp: Any, factory: ClientFactory) -> None:
+    """Register cost & utilization tools on the FastMCP app."""
+
+    async def analyze_workspace_utilization(
+        region: str | None = None, lookback_days: int = 14
+    ) -> dict[str, Any]:
+        """Classify WorkSpaces Personal desktops as unused / idle / active.
+
+        Uses the AWS/WorkSpaces UserConnected metric over the window to count active days per
+        desktop, returning per-desktop classifications and a rollup. Read-only.
+
+        Args:
+            region: AWS region. Defaults to the server's configured region.
+            lookback_days: Window for the usage analysis (default 14).
+        """
+        report = analyze_workspace_utilization_core(
+            factory, region or factory.region, lookback_days
+        )
+        return report.model_dump()
+
+    async def recommend_running_mode(
+        region: str | None = None, lookback_days: int = 14
+    ) -> dict[str, Any]:
+        """Recommend AlwaysOn -> AutoStop running-mode changes for under-used desktops.
+
+        Identifies AlwaysOn WorkSpaces Personal desktops with low usage that would typically cost
+        less on AutoStop (and flags the reverse, low-confidence, for daily-used AutoStop desktops).
+        Read-only.
+
+        Args:
+            region: AWS region. Defaults to the server's configured region.
+            lookback_days: Window for the usage analysis (default 14).
+        """
+        report = recommend_running_mode_core(factory, region or factory.region, lookback_days)
+        return report.model_dump()
+
+    async def get_euc_cost_summary(
+        lookback_days: int = 30, granularity: Literal["MONTHLY", "DAILY"] = "MONTHLY"
+    ) -> 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.
+
+        Args:
+            lookback_days: How far back to total (default 30).
+            granularity: Cost Explorer granularity: MONTHLY or DAILY (default MONTHLY).
+        """
+        summary = get_euc_cost_summary_core(factory, lookback_days, granularity)
+        return summary.model_dump()
+
+    mcp.add_tool(
+        analyze_workspace_utilization, annotations=read_only("Analyze WorkSpace utilization")
+    )
+    mcp.add_tool(recommend_running_mode, annotations=read_only("Recommend running mode"))
+    mcp.add_tool(get_euc_cost_summary, annotations=read_only("EUC cost summary"))