workspaces-euc-mcp-server 0.1.7__tar.gz → 0.1.8__tar.gz

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-06-03
+
+### Added
+- **`--sso-auto-login`** (opt-in; also `WORKSPACES_EUC_SSO_AUTO_LOGIN=1`): when an AWS call fails
+  with an expired SSO token, the server automatically runs `aws sso login` — opening the browser to
+  the approval screen — so the user re-authenticates without opening a terminal. Debounced so a
+  burst of failing calls opens sign-in only once. Off by default; never stores credentials (it only
+  invokes the AWS CLI). Expired-token errors also now carry a clearer hint, including that signing
+  into the AWS Console does **not** refresh the CLI/SSO token.
+
 ## [0.1.7] - 2026-06-02
 
 ### Fixed

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/DESIGN.md

@@ -65,6 +65,7 @@
     consts.py          # service/API constants, region→pricing-location maps
     models.py          # Pydantic request/response models
     clients.py         # boto3 client factory (region/profile/assume-role aware)
+    sso.py             # opt-in SSO auto-login (launches `aws sso login` on token expiry)
     tools/
       _common.py       # read_only/writes annotation helpers, try_call, paginate
       inventory.py
@@ -93,6 +94,10 @@
 - `--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.
+- `--sso-auto-login` (default **off**): on an expired-SSO-token error, launch `aws sso login`
+  (opens the browser) so the user needn't use a terminal. Opt-in; never stores credentials — it
+  only invokes the AWS CLI, which writes the standard token cache. Debounced so a burst of failing
+  calls opens the browser once.
 - `AWS_REGION` / `AWS_PROFILE`: standard.
 
 ## 5. Tool inventory

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workspaces-euc-mcp-server
-Version: 0.1.7
+Version: 0.1.8
 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
@@ -264,6 +264,14 @@ If calls fail with an expired-token / `UnauthorizedException` error, your sessio
 re-authenticate (for SSO, `aws sso login --profile <name>`) and retry. Nothing in the MCP config
 changes.
 
+> **Tip — auto re-login (no terminal):** launch the server with **`--sso-auto-login`** (or set
+> `WORKSPACES_EUC_SSO_AUTO_LOGIN=1`). When an AWS call then fails with an expired SSO token, the
+> server **automatically runs `aws sso login` for you** — opening your browser to the approval
+> screen — so you just click *Allow* and re-ask, without ever opening a terminal. Off by default;
+> the browser approval itself is still required (inherent to SSO), and the server still never
+> stores credentials (it just invokes the AWS CLI). Note: signing into the AWS **Console** does
+> *not* refresh the CLI/SSO token — only `aws sso login` does.
+
 ## Enabling write / destructive tools — the safety gates
 
 The config above is **read-only**: the write and destructive tools are not even registered, so
@@ -359,6 +367,7 @@ workspaces-euc-mcp-server --enable-writes --enable-destructive --max-bulk-target
 | `--enable-writes` | off | Register Phase 2 lifecycle (write) tools. |
 | `--enable-destructive` | off | Allow terminate/rebuild/restore (requires `--enable-writes`). |
 | `--max-bulk-targets` | 25 | Blast-radius cap for bulk mutations (Phase 2). |
+| `--sso-auto-login` | off | On an expired SSO token, auto-launch `aws sso login` (opens your browser) instead of requiring a manual terminal command. Also via `WORKSPACES_EUC_SSO_AUTO_LOGIN=1`. |
 
 The server starts **read-only**; mutating tools require both the launch flag **and** the matching
 IAM tier.

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/README.md

@@ -234,6 +234,14 @@ If calls fail with an expired-token / `UnauthorizedException` error, your sessio
 re-authenticate (for SSO, `aws sso login --profile <name>`) and retry. Nothing in the MCP config
 changes.
 
+> **Tip — auto re-login (no terminal):** launch the server with **`--sso-auto-login`** (or set
+> `WORKSPACES_EUC_SSO_AUTO_LOGIN=1`). When an AWS call then fails with an expired SSO token, the
+> server **automatically runs `aws sso login` for you** — opening your browser to the approval
+> screen — so you just click *Allow* and re-ask, without ever opening a terminal. Off by default;
+> the browser approval itself is still required (inherent to SSO), and the server still never
+> stores credentials (it just invokes the AWS CLI). Note: signing into the AWS **Console** does
+> *not* refresh the CLI/SSO token — only `aws sso login` does.
+
 ## Enabling write / destructive tools — the safety gates
 
 The config above is **read-only**: the write and destructive tools are not even registered, so
@@ -329,6 +337,7 @@ workspaces-euc-mcp-server --enable-writes --enable-destructive --max-bulk-target
 | `--enable-writes` | off | Register Phase 2 lifecycle (write) tools. |
 | `--enable-destructive` | off | Allow terminate/rebuild/restore (requires `--enable-writes`). |
 | `--max-bulk-targets` | 25 | Blast-radius cap for bulk mutations (Phase 2). |
+| `--sso-auto-login` | off | On an expired SSO token, auto-launch `aws sso login` (opens your browser) instead of requiring a manual terminal command. Also via `WORKSPACES_EUC_SSO_AUTO_LOGIN=1`. |
 
 The server starts **read-only**; mutating tools require both the launch flag **and** the matching
 IAM tier.

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "workspaces-euc-mcp-server"
-version = "0.1.7"
+version = "0.1.8"
 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.8/tests/test_sso.py

@@ -0,0 +1,102 @@
+# 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
+"""Tests for opt-in SSO auto-login and its integration with try_call."""
+
+from __future__ import annotations
+
+from botocore.exceptions import BotoCoreError
+
+from workspaces_euc_mcp_server.models import ServiceError
+from workspaces_euc_mcp_server.sso import SsoAutoLogin, looks_like_sso_token_error
+from workspaces_euc_mcp_server.tools import _common
+
+
+class _Clock:
+    def __init__(self) -> None:
+        self.t = 1000.0
+
+    def __call__(self) -> float:
+        return self.t
+
+
+def test_detects_sso_token_errors():
+    assert looks_like_sso_token_error(Exception("Token has expired and refresh failed"))
+    assert looks_like_sso_token_error(Exception("Error when retrieving token from sso: ..."))
+    assert not looks_like_sso_token_error(Exception("AccessDenied"))
+
+
+def test_disabled_handler_never_logs_in():
+    calls: list[str | None] = []
+    h = SsoAutoLogin(enabled=False, runner=lambda p: calls.append(p) or "ran")
+    assert h.maybe_login() is None
+    assert calls == []
+
+
+def test_enabled_handler_debounces_burst_then_allows_after_cooldown():
+    clock = _Clock()
+    calls: list[str | None] = []
+    h = SsoAutoLogin(
+        enabled=True,
+        profile="ben-euc",
+        cooldown_seconds=60.0,
+        runner=lambda p: calls.append(p) or "opened browser",
+        clock=clock,
+    )
+    # First failure triggers a login...
+    assert h.maybe_login() == "opened browser"
+    # ...a burst within the cooldown does NOT open another browser.
+    assert h.maybe_login() is None
+    assert h.maybe_login() is None
+    # ...but after the cooldown elapses it triggers again.
+    clock.t += 61.0
+    assert h.maybe_login() == "opened browser"
+    assert calls == ["ben-euc", "ben-euc"]
+
+
+def test_try_call_triggers_auto_login_on_token_error():
+    triggered: list[str | None] = []
+    handler = SsoAutoLogin(
+        enabled=True, profile="p", runner=lambda p: triggered.append(p) or "opened sign-in"
+    )
+    _common.register_sso_handler(handler)
+    try:
+        errors: list[ServiceError] = []
+
+        def boom():
+            raise BotoCoreError(error="Token has expired and refresh failed")
+
+        # BotoCoreError formats its message from the template; force a token-like message.
+        def boom2():
+            raise _FakeTokenError("Token has expired and refresh failed")
+
+        _common.try_call(errors, "svc", "op", boom2, default=None)
+
+        assert triggered == ["p"]  # browser sign-in launched
+        assert len(errors) == 1
+        assert "SSO session expired" in errors[0].message
+        assert "opened sign-in" in errors[0].message
+    finally:
+        _common.register_sso_handler(None)
+
+
+def test_try_call_hint_when_auto_login_disabled():
+    _common.register_sso_handler(None)
+    errors: list[ServiceError] = []
+
+    def boom():
+        raise _FakeTokenError("the sso session associated with this profile has expired")
+
+    _common.try_call(errors, "svc", "op", boom, default=None)
+    assert "aws sso login" in errors[0].message
+    assert "Console does NOT refresh" in errors[0].message
+
+
+class _FakeTokenError(BotoCoreError):
+    """A BotoCoreError subclass whose str() is a controllable token-error message."""
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+
+    def __str__(self) -> str:
+        return self._message

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/workspaces_euc_mcp_server/__init__.py

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

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/workspaces_euc_mcp_server/server.py

@@ -14,7 +14,9 @@ from mcp.server.fastmcp import FastMCP
 
 from . import consts
 from .clients import ClientFactory
+from .sso import SsoAutoLogin
 from .tools import (
+    _common,
     cost,
     destructive,
     diagnostics,
@@ -37,11 +39,21 @@ def create_server(
     enable_writes: bool = False,
     enable_destructive: bool = False,
     max_bulk_targets: int = consts.DEFAULT_MAX_BULK_TARGETS,
+    sso_auto_login: bool = False,
 ) -> 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
     )
+
+    # Opt-in: when an AWS call fails with an expired SSO token, auto-launch `aws sso login`
+    # (opens the browser) so the user never has to use a terminal. No-op unless enabled.
+    _common.register_sso_handler(
+        SsoAutoLogin(profile=profile, enabled=sso_auto_login) if sso_auto_login else None
+    )
+    if sso_auto_login:
+        logger.info("SSO auto-login enabled: expired tokens will trigger `aws sso login`.")
+
     mcp = FastMCP(consts.SERVER_NAME, instructions=consts.SERVER_INSTRUCTIONS)
 
     # Phase 1 read-only tools are always registered.
@@ -109,11 +121,22 @@ def main() -> None:
         default=consts.DEFAULT_MAX_BULK_TARGETS,
         help="Blast-radius cap for bulk mutations (Phase 2).",
     )
+    parser.add_argument(
+        "--sso-auto-login",
+        action="store_true",
+        help="When an AWS call fails with an expired SSO token, auto-launch `aws sso login` "
+        "(opens your browser) instead of requiring a manual terminal command. Off by default; "
+        "can also be enabled with WORKSPACES_EUC_SSO_AUTO_LOGIN=1.",
+    )
     args = parser.parse_args()
 
     if args.enable_destructive and not args.enable_writes:
         parser.error("--enable-destructive requires --enable-writes.")
 
+    sso_auto_login = args.sso_auto_login or os.environ.get(
+        "WORKSPACES_EUC_SSO_AUTO_LOGIN", ""
+    ).strip().lower() in ("1", "true", "yes")
+
     logger.remove()
     logger.add(sys.stderr, level=os.environ.get("FASTMCP_LOG_LEVEL", "INFO").upper())
 
@@ -125,6 +148,7 @@ def main() -> None:
         enable_writes=args.enable_writes,
         enable_destructive=args.enable_destructive,
         max_bulk_targets=args.max_bulk_targets,
+        sso_auto_login=sso_auto_login,
     )
     mcp.run()
 

workspaces_euc_mcp_server-0.1.8/workspaces_euc_mcp_server/sso.py

@@ -0,0 +1,104 @@
+# 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
+"""Opt-in AWS SSO auto-login.
+
+When enabled (``--sso-auto-login``), and a tool call fails because the SSO token has expired, the
+server launches ``aws sso login`` for the configured profile — which opens the user's browser to
+the approval screen — so the user never has to drop to a terminal. The interactive browser approval
+itself is still required (that is inherent to the OAuth flow). The server never stores credentials;
+it only invokes the AWS CLI, which writes to the standard SSO token cache.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+
+# `subprocess` is used solely to launch `aws sso login` with a fixed argv (shell=False) below.
+import subprocess  # nosec B404
+import time
+from collections.abc import Callable
+
+from loguru import logger
+
+# Marker phrases (lowercased) that indicate an expired / unretrievable SSO token.
+_SSO_TOKEN_ERROR_MARKERS = (
+    "token has expired",
+    "expired and refresh failed",
+    "error when retrieving token from sso",
+    "ssotokenload",
+    "unauthorizedssotoken",
+    "the sso session associated with this profile has expired",
+    "sso session",
+    "tokenretrievalerror",
+)
+
+# Conservative profile-name charset so a configured profile can never be argv-injected.
+_PROFILE_RE = re.compile(r"^[A-Za-z0-9_.:@/-]+$")
+
+
+def looks_like_sso_token_error(exc: BaseException) -> bool:
+    """True if an exception message looks like an expired/unretrievable SSO token."""
+    msg = str(exc).lower()
+    return any(marker in msg for marker in _SSO_TOKEN_ERROR_MARKERS)
+
+
+def _default_runner(profile: str | None) -> str:
+    """Launch `aws sso login` (opens the browser). Returns a human-readable status string."""
+    aws = shutil.which("aws")
+    if not aws:
+        return "AWS CLI not found on PATH — run `aws sso login` manually to re-authenticate."
+    args = [aws, "sso", "login"]
+    if profile:
+        if not _PROFILE_RE.match(profile):
+            return "the configured AWS profile name is invalid — sign in manually."
+        args += ["--profile", profile]
+    try:
+        # Fixed argv, shell=False, profile validated against _PROFILE_RE — no injection surface.
+        subprocess.Popen(  # nosec B603
+            args,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError as exc:  # pragma: no cover - environment dependent
+        return f"could not launch `aws sso login`: {exc}"
+    suffix = f" --profile {profile}" if profile else ""
+    return f"opened browser sign-in (`aws sso login{suffix}`) — approve it, then re-run."
+
+
+class SsoAutoLogin:
+    """Debounced launcher for `aws sso login`, triggered on detected token expiry."""
+
+    def __init__(
+        self,
+        *,
+        profile: str | None = None,
+        enabled: bool = False,
+        cooldown_seconds: float = 60.0,
+        runner: Callable[[str | None], str] | None = None,
+        clock: Callable[[], float] | None = None,
+    ) -> None:
+        self.enabled = enabled
+        self._profile = profile
+        self._cooldown = cooldown_seconds
+        self._runner = runner or _default_runner
+        self._clock = clock or time.monotonic
+        self._last: float | None = None
+
+    def maybe_login(self) -> str | None:
+        """Trigger a login if enabled and not within the cooldown; returns a status or None."""
+        if not self.enabled:
+            return None
+        now = self._clock()
+        if self._last is not None and (now - self._last) < self._cooldown:
+            # A burst of failing calls (e.g. one report) should open the browser only once.
+            return None
+        self._last = now
+        profile = self._profile or os.environ.get("AWS_PROFILE")
+        status = self._runner(profile)
+        logger.info("SSO auto-login triggered: {}", status)
+        return status

{workspaces_euc_mcp_server-0.1.7 → workspaces_euc_mcp_server-0.1.8}/workspaces_euc_mcp_server/tools/_common.py

@@ -13,6 +13,16 @@ from loguru import logger
 from mcp.types import ToolAnnotations
 
 from ..models import ServiceError
+from ..sso import SsoAutoLogin, looks_like_sso_token_error
+
+# Optional process-wide SSO auto-login handler, installed by the server when --sso-auto-login is on.
+_SSO_HANDLER: SsoAutoLogin | None = None
+
+
+def register_sso_handler(handler: SsoAutoLogin | None) -> None:
+    """Install the process-wide SSO auto-login handler (called once at server start)."""
+    global _SSO_HANDLER
+    _SSO_HANDLER = handler
 
 
 def read_only(title: str) -> ToolAnnotations:
@@ -49,10 +59,31 @@ def try_call(
         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)))
+        message = str(exc)
+        if looks_like_sso_token_error(exc):
+            message += _sso_hint()
+        errors.append(ServiceError(service=service, operation=operation, message=message))
         return default
 
 
+def _sso_hint() -> str:
+    """Append an actionable hint to SSO-token errors, auto-launching sign-in if enabled."""
+    handler = _SSO_HANDLER
+    if handler is not None and handler.enabled:
+        status = handler.maybe_login()
+        if status:
+            return f" [SSO session expired — {status}]"
+        return (
+            " [SSO session expired — a browser sign-in is already in progress; approve it, "
+            "then retry]"
+        )
+    return (
+        " [SSO session expired — run `aws sso login --profile <your-profile>` to re-authenticate "
+        "(or launch the server with --sso-auto-login to open sign-in automatically). "
+        "Note: signing into the AWS Console does NOT refresh the CLI/SSO token.]"
+    )
+
+
 def paginate(
     operation: Callable[..., dict[str, Any]],
     list_key: str,