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

workspaces_euc_mcp_server/__init__.py

@@ -0,0 +1,6 @@
+# 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
+"""MCP server for administering the Amazon WorkSpaces End User Computing portfolio."""
+
+__version__ = "0.1.1"

workspaces_euc_mcp_server/clients.py

@@ -0,0 +1,101 @@
+# 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
+"""Region/profile-aware boto3 client factory.
+
+Clients are built from the standard boto3 credential chain (``AWS_PROFILE`` / ``AWS_REGION`` /
+instance role / SSO). For multi-account / MSP use, pass ``role_arn`` (and optional ``external_id``)
+to transparently ``sts:AssumeRole`` into another account — the assumed credentials auto-refresh
+before expiry, and no tool code changes (every tool just calls ``factory.client(...)``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+from botocore.config import Config
+from botocore.credentials import RefreshableCredentials
+from botocore.session import get_session as _botocore_get_session
+
+from . import consts
+
+
+class ClientFactory:
+    """Builds and caches boto3 clients for the in-scope EUC services."""
+
+    def __init__(
+        self,
+        region: str | None = None,
+        profile: str | None = None,
+        role_arn: str | None = None,
+        external_id: str | None = None,
+        role_session_name: str = "workspaces-euc-mcp-server",
+    ) -> None:
+        self._region = region
+        self._profile = profile
+        self._role_arn = role_arn
+        self._external_id = external_id
+        self._role_session_name = role_session_name
+        # The base session holds the caller's own credentials (profile / env / SSO / instance role).
+        self._base_session = boto3.Session(profile_name=profile, region_name=region)
+        # The effective session: the base one, or a cross-account assumed-role one (MSP / multi-
+        # account). Assumed credentials auto-refresh before expiry, so clients keep working.
+        self._session = self._build_assumed_session(role_arn) if role_arn else self._base_session
+        self._cache: dict[tuple[str, str | None], Any] = {}
+
+    def _build_assumed_session(self, role_arn: str) -> boto3.Session:
+        """Build a boto3 Session backed by auto-refreshing sts:AssumeRole credentials."""
+
+        external_id = self._external_id
+        session_name = self._role_session_name
+
+        def _refresh() -> dict[str, str]:
+            sts = self._base_session.client("sts", config=self._config())
+            kwargs: dict[str, str] = {"RoleArn": role_arn, "RoleSessionName": session_name}
+            if external_id:
+                kwargs["ExternalId"] = external_id
+            creds = sts.assume_role(**kwargs)["Credentials"]
+            return {
+                "access_key": creds["AccessKeyId"],
+                "secret_key": creds["SecretAccessKey"],
+                "token": creds["SessionToken"],
+                "expiry_time": creds["Expiration"].isoformat(),
+            }
+
+        refreshable = RefreshableCredentials.create_from_metadata(
+            metadata=_refresh(),
+            refresh_using=_refresh,
+            method="sts-assume-role",
+        )
+        botocore_session = _botocore_get_session()
+        botocore_session._credentials = refreshable
+        if self._region:
+            botocore_session.set_config_variable("region", self._region)
+        return boto3.Session(botocore_session=botocore_session)
+
+    @property
+    def region(self) -> str | None:
+        """Effective region (explicit override, else whatever the base session resolved)."""
+        return self._region or self._base_session.region_name
+
+    def _config(self) -> Config:
+        return Config(
+            user_agent_extra=f"{consts.SERVER_NAME}/{consts.SERVER_VERSION}",
+            retries={"max_attempts": 3, "mode": "standard"},
+        )
+
+    def client(self, service_name: str, region: str | None = None) -> Any:
+        """Return a cached boto3 client for ``service_name`` in the target region.
+
+        Typed ``Any`` because boto3 clients are dynamically generated per service.
+        """
+        target_region = region or self._region
+        key = (service_name, target_region)
+        if key not in self._cache:
+            self._cache[key] = self._session.client(
+                service_name,
+                region_name=target_region,
+                config=self._config(),
+            )
+        return self._cache[key]

workspaces_euc_mcp_server/consts.py

@@ -0,0 +1,154 @@
+# 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
+"""Constants for the WorkSpaces EUC MCP server.
+
+Note the distinction between **product names** (current official AWS branding, used everywhere a
+human reads) and **API identifiers** (the legacy boto3 client names the SDK still requires).
+"""
+
+from . import __version__
+
+SERVER_NAME = "workspaces-euc-mcp-server"
+SERVER_VERSION = __version__
+
+# boto3 client names (API identifiers — NOT product names).
+WORKSPACES_API = "workspaces"  # Amazon WorkSpaces Personal, Pools, and Core all use this client.
+APPSTREAM_API = "appstream"  # Amazon WorkSpaces Applications (formerly AppStream 2.0).
+SECURE_BROWSER_API = "workspaces-web"  # Amazon WorkSpaces Secure Browser (formerly WorkSpaces Web).
+WORKSPACES_INSTANCES_API = "workspaces-instances"  # Amazon WorkSpaces Core Managed Instances.
+DIRECTORY_API = "ds"  # AWS Directory Service (shared dependency).
+CLOUDWATCH_API = "cloudwatch"  # Telemetry for diagnostics/cost tools.
+EC2_API = "ec2"  # Used to enrich WorkSpaces Core Managed Instances with EC2 details.
+COST_EXPLORER_API = "ce"  # Cost Explorer (global; account-wide, not region-scoped).
+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",
+]
+
+# Current official product names (used in all human-facing output).
+PRODUCT_WORKSPACES_PERSONAL = "Amazon WorkSpaces Personal"
+PRODUCT_WORKSPACES_POOLS = "Amazon WorkSpaces Pools"
+PRODUCT_WORKSPACES_APPLICATIONS = "Amazon WorkSpaces Applications"
+PRODUCT_SECURE_BROWSER = "Amazon WorkSpaces Secure Browser"
+PRODUCT_WORKSPACES_CORE_INSTANCES = "Amazon WorkSpaces Core Managed Instances"
+
+# Legacy / former product names mapped to their current official name. Accept these as INPUT
+# (users will keep saying them) but always emit the current name in output. This is surfaced to the
+# MCP client model via the server instructions and tool descriptions so a query about, say,
+# "AppStream fleets" routes to the WorkSpaces Applications tools.
+LEGACY_NAME_ALIASES = {
+    "appstream": PRODUCT_WORKSPACES_APPLICATIONS,
+    "appstream 2.0": PRODUCT_WORKSPACES_APPLICATIONS,
+    "amazon appstream": PRODUCT_WORKSPACES_APPLICATIONS,
+    "amazon appstream 2.0": PRODUCT_WORKSPACES_APPLICATIONS,
+    "workspaces web": PRODUCT_SECURE_BROWSER,
+    "amazon workspaces web": PRODUCT_SECURE_BROWSER,
+}
+
+# Default blast-radius cap for any (future, Phase 2) bulk mutation.
+DEFAULT_MAX_BULK_TARGETS = 25
+
+# WorkSpaces Personal general-purpose compute types, smallest -> largest. Used by bundle
+# right-sizing to step a desktop up/down one size. Graphics families are intentionally excluded
+# (different hardware/pricing; not safe to auto-suggest across).
+WORKSPACES_COMPUTE_ORDER = ["VALUE", "STANDARD", "PERFORMANCE", "POWER", "POWERPRO"]
+
+# Performance metrics published natively to the AWS/WorkSpaces namespace (keyed by WorkspaceId),
+# with a best-effort unit label. No CloudWatch agent is required for these.
+WORKSPACES_PERFORMANCE_METRICS = [
+    ("CPUUsage", "Percent"),
+    ("MemoryUsage", "Percent"),
+    ("GPUUsage", "Percent"),
+    ("FramesPerSecond", "Count"),
+    ("RootVolumeDiskUsage", "Percent"),
+    ("UserVolumeDiskUsage", "Percent"),
+    ("InSessionLatency", "Milliseconds"),
+    ("UpTime", "Seconds"),
+    ("Bandwidth", "Bytes"),
+    ("BandwidthInbound", "Bytes"),
+    ("CPUQueueLength", "Count"),
+    ("MemoryPageHardFaults", "Count"),
+    ("RootVolumeDiskIOQueueLength", "Count"),
+    ("UserVolumeDiskIOQueueLength", "Count"),
+    ("TCPRetransmissionRate", "Percent"),
+    ("UDPPacketLossRate", "Percent"),
+]
+
+# Capacity/utilization metrics published to AWS/AppStream for a fleet (dimension Fleet), used for
+# WorkSpaces Applications fleet usage history. (ActiveSessions etc. only exist for elastic /
+# multi-session fleets, so they are not in the base set.)
+APPSTREAM_FLEET_METRICS = [
+    ("InUseCapacity", "Count"),
+    ("CapacityUtilization", "Percent"),
+    ("ActualCapacity", "Count"),
+    ("AvailableCapacity", "Count"),
+    ("RunningCapacity", "Count"),
+    ("DesiredCapacity", "Count"),
+    ("PendingCapacity", "Count"),
+]
+
+# WorkSpaces Personal connection/session metrics (AWS/WorkSpaces, dimension WorkspaceId). Idle
+# desktops typically publish only UserConnected; the rest emit when there are connection attempts.
+WORKSPACES_CONNECTION_METRICS = [
+    ("UserConnected", "Count"),
+    ("ConnectionAttempt", "Count"),
+    ("ConnectionSuccess", "Count"),
+    ("ConnectionFailure", "Count"),
+    ("SessionLaunchTime", "Milliseconds"),
+    ("InSessionLatency", "Milliseconds"),
+]
+
+# WorkSpaces Pools user-session metrics. NOTE the dimension name is literally "WorkSpaces pool ID"
+# (with spaces), not PoolId — verified against a live account.
+WORKSPACES_POOL_DIMENSION = "WorkSpaces pool ID"
+WORKSPACES_POOL_SESSION_METRICS = [
+    ("ActiveUserSessionCapacity", "Count"),
+    ("ActualUserSessionCapacity", "Count"),
+    ("AvailableUserSessionCapacity", "Count"),
+    ("DesiredUserSessionCapacity", "Count"),
+    ("PendingUserSessionCapacity", "Count"),
+    ("UserSessionsCapacityUtilization", "Percent"),
+]
+
+# Secure Browser session metrics (AWS/WorkSpacesWeb, dimension PortalId). NOTE: unlike the other
+# services, Secure Browser only emits these when sessions actually occur (idle portals publish
+# nothing), and richer usage goes via the Session Logger. Names below are per AWS docs and are
+# NOT yet verified against live data (the account's portals have had no sessions).
+SECURE_BROWSER_NAMESPACE = "AWS/WorkSpacesWeb"
+SECURE_BROWSER_PORTAL_DIMENSION = "PortalId"
+SECURE_BROWSER_SESSION_METRICS = [
+    ("SessionAttempt", "Count"),
+    ("SessionSuccess", "Count"),
+    ("SessionFailure", "Count"),
+]
+
+# Secure Browser user-settings flags that, when "Enabled", relax data-egress controls. Used by the
+# security audit. Verified live: GetUserSettings returns these as "Enabled"/"Disabled".
+SECURE_BROWSER_EGRESS_FLAGS = ["downloadAllowed", "copyAllowed", "printAllowed"]
+
+SERVER_INSTRUCTIONS = """\
+Administrator-focused MCP server for the Amazon WorkSpaces End User Computing portfolio:
+WorkSpaces Personal, WorkSpaces Pools, WorkSpaces Applications, WorkSpaces Secure Browser, and
+WorkSpaces Core. Tools are read-only by default and synthesize cross-service results for
+inventory, troubleshooting, and cost/utilization optimization. Write/lifecycle operations are not
+enabled unless the server was launched with --enable-writes and the matching IAM permissions are
+present.
+
+Legacy/former service names are fully supported as input — accept them and treat them as the
+current service, but ALWAYS use the current official name in your response:
+- "AppStream", "AppStream 2.0", "Amazon AppStream 2.0"  ->  Amazon WorkSpaces Applications
+- "WorkSpaces Web"                                       ->  Amazon WorkSpaces Secure Browser
+Amazon WorkSpaces Applications IS the rebranded AppStream 2.0 (same service and API), so a request
+about "AppStream fleets" or "AppStream stacks" is about WorkSpaces Applications and is handled by
+the application-fleet tools — do not say AppStream is unsupported.
+"""

workspaces_euc_mcp_server/models.py

@@ -0,0 +1,333 @@
+# 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
+"""Pydantic models for tool inputs and synthesized outputs."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ServiceInventory(BaseModel):
+    """Per-service rollup within an inventory summary."""
+
+    service: str = Field(description="Current official AWS product name.")
+    resource_type: str = Field(description="The kind of resource counted (e.g. WorkSpace, Fleet).")
+    count: int = Field(description="Number of resources of this type found in the region.")
+    by_state: dict[str, int] = Field(
+        default_factory=dict,
+        description="Breakdown of resources by their lifecycle state.",
+    )
+
+
+class ServiceError(BaseModel):
+    """A non-fatal error encountered while calling one AWS service.
+
+    Collection/diagnosis is best-effort: a permission gap or unsupported region for one service is
+    recorded here rather than failing the whole result.
+    """
+
+    service: str
+    operation: str = Field(description="The AWS API operation that failed.")
+    message: str
+
+
+# Backwards-compatible alias (the inventory tool predates the generic name).
+InventoryError = ServiceError
+
+
+class EucInventorySummary(BaseModel):
+    """Cross-service inventory of the Amazon WorkSpaces EUC portfolio in one region."""
+
+    region: str | None = Field(description="AWS region the summary covers.")
+    account_scope: str = Field(default="single-account")
+    total_resources: int = Field(description="Sum of counts across all services collected.")
+    services: list[ServiceInventory] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class Finding(BaseModel):
+    """A single observation from a diagnostic or audit tool."""
+
+    severity: str = Field(description="One of: info, warning, critical.")
+    title: str = Field(description="Short human-readable headline.")
+    detail: str = Field(description="What was observed and why it matters.")
+    recommendation: str | None = Field(default=None, description="Suggested next action, if any.")
+    resource_id: str | None = Field(
+        default=None, description="Resource the finding applies to, when relevant."
+    )
+
+
+class Diagnosis(BaseModel):
+    """Synthesized diagnosis for a single EUC resource."""
+
+    target_type: str = Field(description="Kind of resource diagnosed (official product name).")
+    target_id: str = Field(description="Identifier of the resource diagnosed.")
+    region: str | None = None
+    status: str = Field(
+        description="Overall verdict: healthy, degraded, unhealthy, unknown, or not_found."
+    )
+    summary: str = Field(description="One-line plain-language verdict.")
+    signals: dict[str, object] = Field(
+        default_factory=dict,
+        description="Key raw signals observed (state, capacity, connection status, etc.).",
+    )
+    findings: list[Finding] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class DirectoryHealthReport(BaseModel):
+    """Health of one or more WorkSpaces-registered directories in a region."""
+
+    region: str | None = None
+    directories: list[Diagnosis] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class MetricStat(BaseModel):
+    """Aggregated values for one CloudWatch metric over the window."""
+
+    latest: float | None = None
+    average: float | None = None
+    peak: float | None = None
+    unit: str
+
+
+class WorkspacePerformance(BaseModel):
+    """Native AWS/WorkSpaces performance metrics for one desktop."""
+
+    workspace_id: str
+    lookback_hours: int
+    metrics: dict[str, MetricStat] = Field(default_factory=dict)
+    note: str | None = None
+
+
+class PerformanceReport(BaseModel):
+    """Performance metrics across one or more WorkSpaces Personal desktops."""
+
+    region: str | None = None
+    lookback_hours: int
+    workspaces: list[WorkspacePerformance] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class UsagePoint(BaseModel):
+    """One time-bucket in a usage time-series."""
+
+    timestamp: str
+    average: float | None = None
+    peak: float | None = None
+
+
+class FleetMetricSeries(BaseModel):
+    """Aggregates plus the per-bucket time-series for one fleet metric."""
+
+    unit: str
+    latest: float | None = None
+    average: float | None = None
+    peak: float | None = None
+    series: list[UsagePoint] = Field(default_factory=list)
+
+
+class FleetUsage(BaseModel):
+    """Usage history for a WorkSpaces Applications fleet over a window."""
+
+    fleet_name: str
+    lookback_days: int
+    period_hours: int
+    metrics: dict[str, FleetMetricSeries] = Field(default_factory=dict)
+    summary: str | None = None
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class SecureBrowserPortalDetails(BaseModel):
+    """Resolved settings for a WorkSpaces Secure Browser portal."""
+
+    portal_arn: str
+    display_name: str | None = None
+    authentication_type: str | None = None
+    status: str | None = None
+    user_settings: dict[str, object] = Field(
+        default_factory=dict,
+        description="Clipboard/print/download/upload controls and timeouts.",
+    )
+    network: dict[str, object] = Field(default_factory=dict)
+    has_browser_policy: bool = False
+    has_data_protection: bool = False
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class UsageHistory(BaseModel):
+    """Generic metric time-series history for a single EUC resource over a window."""
+
+    target_type: str = Field(description="Resource kind, e.g. the current official product name.")
+    target_id: str
+    lookback_days: int
+    period_hours: int
+    metrics: dict[str, FleetMetricSeries] = Field(default_factory=dict)
+    summary: str | None = None
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class WorkspaceUtilization(BaseModel):
+    """Utilization classification for a single WorkSpaces Personal desktop."""
+
+    workspace_id: str
+    running_mode: str | None = None
+    lookback_days: int
+    active_days: int | None = Field(
+        default=None, description="Days with at least one user connection in the window."
+    )
+    classification: str = Field(description="unused, idle, active, or unknown.")
+    # Inputs for pricing/savings estimates (not always populated).
+    compute_type: str | None = None
+    operating_system: str | None = None
+    root_volume_gib: int | None = None
+    user_volume_gib: int | None = None
+
+
+class UtilizationReport(BaseModel):
+    """Utilization rollup across WorkSpaces Personal desktops in a region."""
+
+    region: str | None = None
+    lookback_days: int
+    total: int
+    counts: dict[str, int] = Field(
+        default_factory=dict, description="Count of desktops per classification."
+    )
+    workspaces: list[WorkspaceUtilization] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class Recommendation(BaseModel):
+    """A single cost/utilization optimization recommendation."""
+
+    target_id: str
+    kind: str = Field(description="The recommendation type, e.g. running_mode.")
+    current: str | None = None
+    recommended: str | None = None
+    rationale: str
+    estimated_monthly_savings_usd: float | None = Field(
+        default=None, description="Estimated saving, when it can be computed; otherwise null."
+    )
+    confidence: str = Field(description="low, medium, or high.")
+
+
+class RecommendationReport(BaseModel):
+    """Set of optimization recommendations for a region."""
+
+    region: str | None = None
+    lookback_days: int
+    recommendations: list[Recommendation] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class CostLineItem(BaseModel):
+    service: str
+    amount: float
+
+
+class CostSummary(BaseModel):
+    """Cost rollup for the EUC portfolio over a time window (account-wide)."""
+
+    scope: str = Field(
+        default="account-wide",
+        description="Cost Explorer is not region-scoped; figures are account-wide.",
+    )
+    start: str
+    end: str
+    granularity: str
+    currency: str = "USD"
+    total: float
+    by_service: list[CostLineItem] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class ResourceRecord(BaseModel):
+    """A single resource row in an inventory report."""
+
+    id: str
+    name: str | None = None
+    state: str | None = None
+    attributes: dict[str, object] = Field(default_factory=dict)
+
+
+class InventoryReportSection(BaseModel):
+    service: str
+    resource_type: str
+    resources: list[ResourceRecord] = Field(default_factory=list)
+
+
+class InventoryReport(BaseModel):
+    """Detailed per-resource inventory across the EUC portfolio in a region."""
+
+    region: str | None = None
+    total_resources: int = 0
+    sections: list[InventoryReportSection] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class AuditReport(BaseModel):
+    """Security-posture findings across the EUC portfolio in a region."""
+
+    region: str | None = None
+    findings: list[Finding] = Field(default_factory=list)
+    severity_counts: dict[str, int] = Field(default_factory=dict)
+    resources_checked: dict[str, int] = Field(default_factory=dict)
+    errors: list[ServiceError] = Field(default_factory=list)
+
+
+class UnusedResource(BaseModel):
+    service: str
+    resource_type: str
+    id: str
+    reason: str
+
+
+class UnusedResourcesReport(BaseModel):
+    """Candidate idle/unused resources worth reclaiming."""
+
+    region: str | None = None
+    lookback_days: int
+    items: list[UnusedResource] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class TargetResult(BaseModel):
+    """Outcome of a write action against a single target."""
+
+    target_id: str
+    status: str = Field(description="ok, error, or skipped.")
+    message: str | None = None
+
+
+class WriteOutcome(BaseModel):
+    """Result of a guarded write/lifecycle action.
+
+    Mutations are dry-run by default: unless ``confirmed`` is true the action only reports the plan
+    and changes nothing. Bulk actions are refused when the target count exceeds the blast-radius
+    cap.
+    """
+
+    action: str = Field(description="The lifecycle action requested.")
+    dry_run: bool = Field(description="True when nothing was changed (plan only).")
+    confirmed: bool = Field(description="Whether the caller explicitly confirmed execution.")
+    requested_targets: list[str] = Field(default_factory=list)
+    max_bulk_targets: int = Field(description="Configured blast-radius cap.")
+    blast_radius_ok: bool = Field(
+        description="False when the action was refused for being too large."
+    )
+    plan: str = Field(description="Human-readable description of what would happen / happened.")
+    acknowledgement_required: str | None = Field(
+        default=None,
+        description="For destructive actions: the exact phrase the caller must pass to proceed.",
+    )
+    results: list[TargetResult] = Field(default_factory=list)
+    errors: list[ServiceError] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)