Skip to content

Automate browser based workflows with AI

align workflow CLI commands with MCP parity (#4792)

Marc Kelechava46a7ec1d26c1
diff --git a/docs/integrations/mcp.mdx b/docs/integrations/mcp.mdx
index 00c48d9d1..87485813f 100644
--- a/docs/integrations/mcp.mdx
+++ b/docs/integrations/mcp.mdx
@@ -68,6 +68,30 @@ Add this to your MCP client's configuration file:
Replace `/usr/bin/python3` with the output of `which python3` on your machine. For local mode, set `SKYVERN_BASE_URL` to `http://localhost:8000` and find your API key in the `.env` file after running `skyvern init`.
+### Option C: Remote MCP over HTTPS (streamable HTTP)
+
+Use this when your team provides a hosted MCP endpoint (for example: `https://mcp.skyvern.com/mcp`).
+
+In remote HTTP mode:
+- Clients must send `x-api-key` on every request.
+- Use `skyvern_session_create` first, then pass `session_id` explicitly on subsequent browser tool calls.
+
+If your MCP client supports native remote HTTP transport, configure it directly:
+
+```json
+{
+ "mcpServers": {
+ "SkyvernRemote": {
+ "type": "streamable-http",
+ "url": "https://mcp.skyvern.com/mcp",
+ "headers": {
+ "x-api-key": "YOUR_SKYVERN_API_KEY"
+ }
+ }
+ }
+}
+```
+
<Accordion title="Config file locations by client">
| Client | Path |
diff --git a/skyvern/cli/core/api_key_hash.py b/skyvern/cli/core/api_key_hash.py
new file mode 100644
index 000000000..ad89d414b
--- /dev/null
+++ b/skyvern/cli/core/api_key_hash.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import hashlib
+import os
+
+
+def _resolve_api_key_hash_iterations() -> int:
+ raw = os.environ.get("SKYVERN_MCP_API_KEY_HASH_ITERATIONS", "120000")
+ try:
+ return max(10_000, int(raw))
+ except ValueError:
+ return 120_000
+
+
+_API_KEY_HASH_ITERATIONS = _resolve_api_key_hash_iterations()
+_API_KEY_HASH_SALT = os.environ.get(
+ "SKYVERN_MCP_API_KEY_HASH_SALT",
+ "skyvern-mcp-api-key-cache-v1",
+).encode("utf-8")
+
+
+def hash_api_key_for_cache(api_key: str) -> str:
+ """Derive a deterministic, non-reversible fingerprint for API-key keyed caches."""
+ return hashlib.pbkdf2_hmac(
+ "sha256",
+ api_key.encode("utf-8"),
+ _API_KEY_HASH_SALT,
+ _API_KEY_HASH_ITERATIONS,
+ ).hex()
diff --git a/skyvern/cli/core/client.py b/skyvern/cli/core/client.py
index ef02634a3..623f3ec1c 100644
--- a/skyvern/cli/core/client.py
+++ b/skyvern/cli/core/client.py
@@ -1,7 +1,10 @@
from __future__ import annotations
+import asyncio
import os
-from contextvars import ContextVar
+from collections import OrderedDict
+from contextvars import ContextVar, Token
+from threading import RLock
import structlog
@@ -9,35 +12,126 @@ from skyvern.client import SkyvernEnvironment
from skyvern.config import settings
from skyvern.library.skyvern import Skyvern
+from .api_key_hash import hash_api_key_for_cache
+
_skyvern_instance: ContextVar[Skyvern | None] = ContextVar("skyvern_instance", default=None)
+_api_key_override: ContextVar[str | None] = ContextVar("skyvern_api_key_override", default=None)
_global_skyvern_instance: Skyvern | None = None
+_api_key_clients: OrderedDict[str, Skyvern] = OrderedDict()
+_clients_lock = RLock()
LOG = structlog.get_logger(__name__)
+def _resolve_api_key_cache_size() -> int:
+ raw = os.environ.get("SKYVERN_MCP_API_KEY_CLIENT_CACHE_SIZE", "128")
+ try:
+ return max(1, int(raw))
+ except ValueError:
+ return 128
+
+
+_API_KEY_CLIENT_CACHE_MAX = _resolve_api_key_cache_size()
+
+
+def _cache_key(api_key: str) -> str:
+ """Hash API key so raw secrets are never stored as dict keys."""
+ return hash_api_key_for_cache(api_key)
+
+
+def _resolve_api_key() -> str | None:
+ return settings.SKYVERN_API_KEY or os.environ.get("SKYVERN_API_KEY")
+
+
+def _resolve_base_url() -> str | None:
+ return settings.SKYVERN_BASE_URL or os.environ.get("SKYVERN_BASE_URL")
+
+
+def _build_cloud_client(api_key: str) -> Skyvern:
+ return Skyvern(
+ api_key=api_key,
+ environment=SkyvernEnvironment.CLOUD,
+ base_url=_resolve_base_url(),
+ )
+
+
+def _close_skyvern_instance_best_effort(instance: Skyvern) -> None:
+ """Close a Skyvern instance, regardless of whether an event loop is running."""
+ try:
+ loop = asyncio.get_running_loop()
+ except RuntimeError:
+ try:
+ asyncio.run(instance.aclose())
+ except Exception:
+ LOG.debug("Failed to close evicted Skyvern client", exc_info=True)
+ return
+
+ task = loop.create_task(instance.aclose())
+
+ def _on_done(done: asyncio.Task[None]) -> None:
+ try:
+ done.result()
+ except Exception:
+ LOG.debug("Failed to close evicted Skyvern client", exc_info=True)
+
+ task.add_done_callback(_on_done)
+
+
+def get_active_api_key() -> str | None:
+ """Return the effective API key for this request/context."""
+ return _api_key_override.get() or _resolve_api_key()
+
+
+def set_api_key_override(api_key: str | None) -> Token[str | None]:
+ """Set request-scoped API key override for MCP HTTP requests."""
+ _skyvern_instance.set(None)
+ return _api_key_override.set(api_key)
+
+
+def reset_api_key_override(token: Token[str | None]) -> None:
+ """Reset request-scoped API key override."""
+ _api_key_override.reset(token)
+ _skyvern_instance.set(None)
+
+
def get_skyvern() -> Skyvern:
"""Get or create a Skyvern client instance."""
global _global_skyvern_instance
- instance = _skyvern_instance.get()
- if instance is None:
- instance = _global_skyvern_instance
- if instance is not None:
+ override_api_key = _api_key_override.get()
+ if override_api_key:
+ instance = _skyvern_instance.get()
+ if instance is None:
+ key = _cache_key(override_api_key)
+ evicted_clients: list[Skyvern] = []
+ # Hold lock across lookup + build + insert to prevent two coroutines
+ # from both building a client for the same API key concurrently.
+ with _clients_lock:
+ instance = _api_key_clients.get(key)
+ if instance is not None:
+ _api_key_clients.move_to_end(key)
+ else:
+ instance = _build_cloud_client(override_api_key)
+ _api_key_clients[key] = instance
+ _api_key_clients.move_to_end(key)
+ while len(_api_key_clients) > _API_KEY_CLIENT_CACHE_MAX:
+ _, evicted = _api_key_clients.popitem(last=False)
+ evicted_clients.append(evicted)
+ for evicted in evicted_clients:
+ _close_skyvern_instance_best_effort(evicted)
_skyvern_instance.set(instance)
return instance
- api_key = settings.SKYVERN_API_KEY or os.environ.get("SKYVERN_API_KEY")
- base_url = settings.SKYVERN_BASE_URL or os.environ.get("SKYVERN_BASE_URL")
-
- if api_key:
- instance = Skyvern(
- api_key=api_key,
- environment=SkyvernEnvironment.CLOUD,
- base_url=base_url,
- )
- else:
- instance = Skyvern.local()
-
- _global_skyvern_instance = instance
+ instance = _skyvern_instance.get()
+ if instance is None:
+ with _clients_lock:
+ instance = _global_skyvern_instance
+ if instance is None:
+ api_key = _resolve_api_key()
+ if api_key:
+ instance = _build_cloud_client(api_key)
+ else:
+ instance = Skyvern.local()
+ _global_skyvern_instance = instance
_skyvern_instance.set(instance)
return instance
@@ -48,7 +142,12 @@ async def close_skyvern() -> None:
instances: list[Skyvern] = []
seen: set[int] = set()
- for candidate in (_skyvern_instance.get(), _global_skyvern_instance):
+ with _clients_lock:
+ candidates = (_skyvern_instance.get(), _global_skyvern_instance, *_api_key_clients.values())
+ _api_key_clients.clear()
+ _global_skyvern_instance = None
+
+ for candidate in candidates:
if candidate is None or id(candidate) in seen:
continue
seen.add(id(candidate))
@@ -61,4 +160,3 @@ async def close_skyvern() -> None:
LOG.warning("Failed to close Skyvern client", exc_info=True)
_skyvern_instance.set(None)
- _global_skyvern_instance = None
diff --git a/skyvern/cli/core/mcp_http_auth.py b/skyvern/cli/core/mcp_http_auth.py
new file mode 100644
index 000000000..07a7a1687
--- /dev/null
+++ b/skyvern/cli/core/mcp_http_auth.py
@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections import OrderedDict
+from threading import RLock
+
+import structlog
+from fastapi import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from skyvern.config import settings
+from skyvern.forge.sdk.db.agent_db import AgentDB
+from skyvern.forge.sdk.services.org_auth_service import resolve_org_from_api_key
+
+from .api_key_hash import hash_api_key_for_cache
+from .client import reset_api_key_override, set_api_key_override
+
+LOG = structlog.get_logger(__name__)
+API_KEY_HEADER = "x-api-key"
+HEALTH_PATHS = {"/health", "/healthz"}
+_auth_db: AgentDB | None = None
+_auth_db_lock = RLock()
+_api_key_cache_lock = RLock()
+_api_key_validation_cache: OrderedDict[str, tuple[str | None, float]] = OrderedDict()
+_NEGATIVE_CACHE_TTL_SECONDS = 5.0
+_VALIDATION_RETRY_EXHAUSTED_MESSAGE = "API key validation temporarily unavailable"
+_MAX_VALIDATION_RETRIES = 2
+_RETRY_DELAY_SECONDS = 0.25
+
+
+def _resolve_api_key_cache_ttl_seconds() -> float:
+ raw = os.environ.get("SKYVERN_MCP_API_KEY_CACHE_TTL_SECONDS", "30")
+ try:
+ return max(1.0, float(raw))
+ except ValueError:
+ return 30.0
+
+
+def _resolve_api_key_cache_max_size() -> int:
+ raw = os.environ.get("SKYVERN_MCP_API_KEY_CACHE_MAX_SIZE", "1024")
+ try:
+ return max(1, int(raw))
+ except ValueError:
+ return 1024
+
+
+_API_KEY_CACHE_TTL_SECONDS = _resolve_api_key_cache_ttl_seconds()
+_API_KEY_CACHE_MAX_SIZE = _resolve_api_key_cache_max_size()
+
+
+def _get_auth_db() -> AgentDB:
+ global _auth_db
+ # Guard singleton init in case HTTP transport is served with threaded workers.
+ with _auth_db_lock:
+ if _auth_db is None:
+ _auth_db = AgentDB(settings.DATABASE_STRING, debug_enabled=settings.DEBUG_MODE)
+ return _auth_db
+
+
+async def close_auth_db() -> None:
+ """Dispose the auth DB engine used by HTTP middleware, if initialized."""
+ global _auth_db
+ with _auth_db_lock:
+ db = _auth_db
+ _auth_db = None
+ with _api_key_cache_lock:
+ _api_key_validation_cache.clear()
+ if db is None:
+ return
+
+ try:
+ await db.engine.dispose()
+ except Exception:
+ LOG.warning("Failed to dispose MCP auth DB engine", exc_info=True)
+
+
+def _cache_key(api_key: str) -> str:
+ return hash_api_key_for_cache(api_key)
+
+
+async def validate_mcp_api_key(api_key: str) -> str:
+ """Validate API key and return organization id for observability."""
+ key = _cache_key(api_key)
+
+ # Check cache first.
+ with _api_key_cache_lock:
+ cached = _api_key_validation_cache.get(key)
+ if cached is not None:
+ organization_id, expires_at = cached
+ if expires_at > time.monotonic():
+ _api_key_validation_cache.move_to_end(key)
+ if organization_id is None:
+ raise HTTPException(status_code=401, detail="Invalid API key")
+ return organization_id
+ _api_key_validation_cache.pop(key, None)
+
+ # Cache miss — do the DB lookup with simple retry on transient errors.
+ last_exc: Exception | None = None
+ for attempt in range(_MAX_VALIDATION_RETRIES + 1):
+ if attempt > 0:
+ await asyncio.sleep(_RETRY_DELAY_SECONDS)
+ try:
+ validation = await resolve_org_from_api_key(api_key, _get_auth_db())
+ organization_id = validation.organization.organization_id
+ with _api_key_cache_lock:
+ _api_key_validation_cache[key] = (
+ organization_id,
+ time.monotonic() + _API_KEY_CACHE_TTL_SECONDS,
+ )
+ _api_key_validation_cache.move_to_end(key)
+ while len(_api_key_validation_cache) > _API_KEY_CACHE_MAX_SIZE:
+ _api_key_validation_cache.popitem(last=False)
+ return organization_id
+ except HTTPException as e:
+ if e.status_code in {401, 403}:
+ with _api_key_cache_lock:
+ _api_key_validation_cache[key] = (None, time.monotonic() + _NEGATIVE_CACHE_TTL_SECONDS)
+ _api_key_validation_cache.move_to_end(key)
+ while len(_api_key_validation_cache) > _API_KEY_CACHE_MAX_SIZE:
+ _api_key_validation_cache.popitem(last=False)
+ raise
+ last_exc = e
+ except Exception as e:
+ last_exc = e
+
+ LOG.warning("API key validation retries exhausted", attempts=_MAX_VALIDATION_RETRIES + 1, exc_info=last_exc)
+ raise HTTPException(status_code=503, detail=_VALIDATION_RETRY_EXHAUSTED_MESSAGE)
+
+
+def _unauthorized_response(message: str) -> JSONResponse:
+ return JSONResponse({"error": {"code": "UNAUTHORIZED", "message": message}}, status_code=401)
+
+
+def _internal_error_response() -> JSONResponse:
+ return JSONResponse(
+ {"error": {"code": "INTERNAL_ERROR", "message": "Internal server error"}},
+ status_code=500,
+ )
+
+
+def _service_unavailable_response(message: str) -> JSONResponse:
+ return JSONResponse(
+ {"error": {"code": "SERVICE_UNAVAILABLE", "message": message}},
+ status_code=503,
+ )
+
+
+class MCPAPIKeyMiddleware:
+ """Require x-api-key for MCP HTTP transport and scope requests to that key."""
+
+ def __init__(self, app: ASGIApp) -> None:
+ self.app = app
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+ if scope["type"] != "http":
+ await self.app(scope, receive, send)
+ return
+
+ request = Request(scope, receive=receive)
+ if request.url.path in HEALTH_PATHS:
+ response = JSONResponse({"status": "ok"})
+ await response(scope, receive, send)
+ return
+
+ if request.method == "OPTIONS":
+ await self.app(scope, receive, send)
+ return
+
+ api_key = request.headers.get(API_KEY_HEADER)
+ if not api_key:
+ response = _unauthorized_response("Missing x-api-key header")
+ await response(scope, receive, send)
+ return
+
+ try:
+ organization_id = await validate_mcp_api_key(api_key)
+ scope.setdefault("state", {})
+ scope["state"]["organization_id"] = organization_id
+ except HTTPException as e:
+ if e.status_code in {401, 403}:
+ response = _unauthorized_response("Invalid API key")
+ await response(scope, receive, send)
+ return
+ if e.status_code == 503:
+ response = _service_unavailable_response(e.detail or _VALIDATION_RETRY_EXHAUSTED_MESSAGE)
+ await response(scope, receive, send)
+ return
+ LOG.warning("Unexpected HTTPException during MCP API key validation", status_code=e.status_code)
+ response = _internal_error_response()
+ await response(scope, receive, send)
+ return
+ except Exception:
+ LOG.exception("Unexpected MCP API key validation failure")
+ response = _internal_error_response()
+ await response(scope, receive, send)
+ return
+
+ token = set_api_key_override(api_key)
+ try:
+ await self.app(scope, receive, send)
+ finally:
+ reset_api_key_override(token)
diff --git a/skyvern/cli/core/session_manager.py b/skyvern/cli/core/session_manager.py
index 2b48bbe53..83af92860 100644
--- a/skyvern/cli/core/session_manager.py
+++ b/skyvern/cli/core/session_manager.py
@@ -7,7 +7,8 @@ from typing import TYPE_CHECKING, Any, AsyncIterator
import structlog
-from .client import get_skyvern
+from .api_key_hash import hash_api_key_for_cache
+from .client import get_active_api_key, get_skyvern
from .result import BrowserContext, ErrorCode, make_error
LOG = structlog.get_logger(__name__)
@@ -21,6 +22,7 @@ if TYPE_CHECKING:
class SessionState:
browser: SkyvernBrowser | None = None
context: BrowserContext | None = None
+ api_key_hash: str | None = None
console_messages: list[dict[str, Any]] = field(default_factory=list)
tracing_active: bool = False
har_enabled: bool = False
@@ -28,26 +30,52 @@ class SessionState:
_current_session: ContextVar[SessionState | None] = ContextVar("mcp_session", default=None)
_global_session: SessionState | None = None
+_stateless_http_mode = False
def get_current_session() -> SessionState:
global _global_session
state = _current_session.get()
- if state is None:
- if _global_session is None:
- _global_session = SessionState()
- state = _global_session
+ if state is not None:
+ return state
+
+ # In stateless HTTP mode, avoid process-wide fallback state so requests
+ # cannot inherit session context from other requests.
+ if _stateless_http_mode:
+ state = SessionState()
_current_session.set(state)
+ return state
+
+ if _global_session is None:
+ _global_session = SessionState()
+ state = _global_session
+ _current_session.set(state)
return state
def set_current_session(state: SessionState) -> None:
global _global_session
- _global_session = state
+ if not _stateless_http_mode:
+ _global_session = state
_current_session.set(state)
+def set_stateless_http_mode(enabled: bool) -> None:
+ global _stateless_http_mode
+ _stateless_http_mode = enabled
+
+
+def is_stateless_http_mode() -> bool:
+ return _stateless_http_mode
+
+
+def _api_key_hash(api_key: str | None) -> str | None:
+ if not api_key:
+ return None
+ return hash_api_key_for_cache(api_key)
+
+
def _matches_current(
current: SessionState,
*,
@@ -57,6 +85,8 @@ def _matches_current(
) -> bool:
if current.browser is None or current.context is None:
return False
+ if current.api_key_hash != _api_key_hash(get_active_api_key()):
+ return False
if session_id:
return current.context.mode == "cloud_session" and current.context.session_id == session_id
@@ -84,35 +114,39 @@ async def resolve_browser(
skyvern = get_skyvern()
current = get_current_session()
+ if _stateless_http_mode and not (session_id or cdp_url or local or create_session):
+ raise BrowserNotAvailableError()
+
if _matches_current(current, session_id=session_id, cdp_url=cdp_url, local=local):
- # _matches_current() guarantees both are non-None
- assert current.browser is not None and current.context is not None
+ if current.browser is None or current.context is None:
+ raise RuntimeError("Expected active browser and context for matching session")
return current.browser, current.context
+ active_api_key_hash = _api_key_hash(get_active_api_key())
browser: SkyvernBrowser | None = None
try:
if session_id:
browser = await skyvern.connect_to_cloud_browser_session(session_id)
ctx = BrowserContext(mode="cloud_session", session_id=session_id)
- set_current_session(SessionState(browser=browser, context=ctx))
+ set_current_session(SessionState(browser=browser, context=ctx, api_key_hash=active_api_key_hash))
return browser, ctx
if cdp_url:
browser = await skyvern.connect_to_browser_over_cdp(cdp_url)
ctx = BrowserContext(mode="cdp", cdp_url=cdp_url)
- set_current_session(SessionState(browser=browser, context=ctx))
+ set_current_session(SessionState(browser=browser, context=ctx, api_key_hash=active_api_key_hash))
return browser, ctx
if local:
browser = await skyvern.launch_local_browser(headless=headless)
ctx = BrowserContext(mode="local")
- set_current_session(SessionState(browser=browser, context=ctx))
+ set_current_session(SessionState(browser=browser, context=ctx, api_key_hash=active_api_key_hash))
return browser, ctx
if create_session:
browser = await skyvern.launch_cloud_browser(timeout=timeout)
ctx = BrowserContext(mode="cloud_session", session_id=browser.browser_session_id)
- set_current_session(SessionState(browser=browser, context=ctx))
+ set_current_session(SessionState(browser=browser, context=ctx, api_key_hash=active_api_key_hash))
return browser, ctx
except Exception:
if browser is not None:
diff --git a/skyvern/cli/mcp_tools/session.py b/skyvern/cli/mcp_tools/session.py
index 7b22fa89c..37c2eac03 100644
--- a/skyvern/cli/mcp_tools/session.py
+++ b/skyvern/cli/mcp_tools/session.py
@@ -4,7 +4,11 @@ from typing import Annotated, Any
from pydantic import Field
+from skyvern.cli.core.api_key_hash import hash_api_key_for_cache
+from skyvern.cli.core.client import get_active_api_key
+from skyvern.cli.core.session_manager import is_stateless_http_mode
from skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_list
+from skyvern.schemas.runs import ProxyLocation
from ._common import BrowserContext, ErrorCode, Timer, make_error, make_result
from ._session import (
@@ -16,6 +20,13 @@ from ._session import (
)
+def _session_api_key_hash() -> str | None:
+ api_key = get_active_api_key()
+ if not api_key:
+ return None
+ return hash_api_key_for_cache(api_key)
+
+
async def skyvern_session_create(
timeout: Annotated[int | None, Field(description="Session timeout in minutes (5-1440)")] = 60,
proxy_location: Annotated[str | None, Field(description="Proxy location: RESIDENTIAL, US, etc.")] = None,
@@ -29,7 +40,33 @@ async def skyvern_session_create(
"""
with Timer() as timer:
try:
+ if is_stateless_http_mode() and local:
+ return make_result(
+ "skyvern_session_create",
+ ok=False,
+ error=make_error(
+ ErrorCode.INVALID_INPUT,
+ "Local browser sessions are not supported in stateless HTTP mode",
+ "Use cloud sessions for remote MCP transport",
+ ),
+ )
+
skyvern = get_skyvern()
+ if is_stateless_http_mode():
+ proxy = ProxyLocation(proxy_location) if proxy_location else None
+ session = await skyvern.create_browser_session(timeout=timeout or 60, proxy_location=proxy)
+ timer.mark("sdk")
+ ctx = BrowserContext(mode="cloud_session", session_id=session.browser_session_id)
+ return make_result(
+ "skyvern_session_create",
+ browser_context=ctx,
+ data={
+ "session_id": session.browser_session_id,
+ "timeout_minutes": timeout or 60,
+ },
+ timing_ms=timer.timing_ms,
+ )
+
browser, result = await do_session_create(
skyvern,
timeout=timeout or 60,
@@ -43,7 +80,7 @@ async def skyvern_session_create(
ctx = BrowserContext(mode="local")
else:
ctx = BrowserContext(mode="cloud_session", session_id=result.session_id)
- set_current_session(SessionState(browser=browser, context=ctx))
+ set_current_session(SessionState(browser=browser, context=ctx, api_key_hash=_session_api_key_hash()))
except ValueError as e:
return make_result(
diff --git a/skyvern/cli/run_commands.py b/skyvern/cli/run_commands.py
index 1d48be22b..f9b31826d 100644
--- a/skyvern/cli/run_commands.py
+++ b/skyvern/cli/run_commands.py
@@ -5,7 +5,7 @@ import logging
import os
import shutil
import subprocess
-from typing import Any, List, Optional
+from typing import Annotated, List, Literal, Optional
import psutil
import typer
@@ -13,17 +13,17 @@ import uvicorn
from dotenv import load_dotenv, set_key
from rich.panel import Panel
from rich.prompt import Confirm
+from starlette.middleware import Middleware
from skyvern.cli.console import console
from skyvern.cli.core.client import close_skyvern
-from skyvern.cli.core.session_manager import close_current_session
+from skyvern.cli.core.mcp_http_auth import MCPAPIKeyMiddleware, close_auth_db
+from skyvern.cli.core.session_manager import close_current_session, set_stateless_http_mode
from skyvern.cli.mcp_tools import mcp # Uses standalone fastmcp (v2.x)
from skyvern.cli.utils import start_services
-from skyvern.client import SkyvernEnvironment
from skyvern.config import settings
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.forge_log import setup_logger
-from skyvern.library.skyvern import Skyvern
from skyvern.services.script_service import run_script
from skyvern.utils import detect_os
from skyvern.utils.env_paths import resolve_backend_env_path, resolve_frontend_env_path
@@ -36,7 +36,10 @@ async def _cleanup_mcp_resources() -> None:
try:
await close_current_session()
finally:
- await close_skyvern()
+ try:
+ await close_skyvern()
+ finally:
+ await close_auth_db()
def _cleanup_mcp_resources_blocking() -> None:
@@ -67,39 +70,6 @@ def _cleanup_mcp_resources_sync() -> None:
logger.debug("Skipping MCP cleanup because event loop is still running")
-async def skyvern_run_task(prompt: str, url: str) -> dict[str, Any]:
- """Use Skyvern to execute anything in the browser. Useful for accomplishing tasks that require browser automation.
-
- This tool uses Skyvern's browser automation to navigate websites and perform actions to achieve
- the user's intended outcome. It can handle tasks like form filling, clicking buttons, data extraction,
- and multi-step workflows.
-
- It can even help you find updated data on the internet if your model information is outdated.
-
- Args:
- prompt: A natural language description of what needs to be accomplished (e.g. "Book a flight from
- NYC to LA", "Sign up for the newsletter", "Find the price of item X", "Apply to a job")
- url: The starting URL of the website where the task should be performed
- """
- skyvern_agent = Skyvern(
- environment=SkyvernEnvironment.CLOUD,
- base_url=settings.SKYVERN_BASE_URL,
- api_key=settings.SKYVERN_API_KEY,
- )
- res = await skyvern_agent.run_task(prompt=prompt, url=url, user_agent="skyvern-mcp", wait_for_completion=True)
-
- output = res.model_dump()["output"]
- if res.app_url:
- task_url = res.app_url
- else:
- if res.run_id and res.run_id.startswith("wr_"):
- task_url = f"{settings.SKYVERN_APP_URL.rstrip('/')}/runs/{res.run_id}/overview"
- else:
- task_url = f"{settings.SKYVERN_APP_URL.rstrip('/')}/tasks/{res.run_id}/actions"
- return {"output": output, "task_url": task_url, "run_id": res.run_id}
-
-
def get_pids_on_port(port: int) -> List[int]:
"""Return a list of PIDs listening on the given port."""
pids = []
@@ -295,20 +265,61 @@ def run_dev() -> None:
@run_app.command(name="mcp")
-def run_mcp() -> None:
- """Run the MCP server."""
- # This breaks the MCP processing because it expects json output only
- # console.print(Panel("[bold green]Starting MCP Server...[/bold green]", border_style="green"))
+def run_mcp(
+ transport: Annotated[
+ Literal["stdio", "sse", "streamable-http"],
+ typer.Option(
+ "--transport",
+ help="MCP transport: stdio (default), sse, or streamable-http.",
+ ),
+ ] = "stdio",
+ host: Annotated[str, typer.Option("--host", help="Host for HTTP transports.")] = "0.0.0.0",
+ port: Annotated[int, typer.Option("--port", help="Port for HTTP transports.")] = 8000,
+ path: Annotated[str, typer.Option("--path", help="HTTP endpoint path for MCP transport.")] = "/mcp",
+ stateless_http: Annotated[
+ bool,
+ typer.Option(
+ "--stateless-http/--no-stateless-http",
+ help="Use stateless HTTP semantics for HTTP transports (ignored for stdio).",
+ ),
+ ] = True,
+) -> None:
+ """Run the MCP server with configurable transport for local or remote hosting."""
+ path = _normalize_mcp_path(path)
+ stateless_http_enabled = transport != "stdio" and stateless_http
# atexit covers signal-based exits (SIGTERM); finally covers normal
# mcp.run() completion or unhandled exceptions. Both are needed because
# atexit doesn't fire on normal return and finally doesn't fire on signals.
atexit.register(_cleanup_mcp_resources_sync)
+ set_stateless_http_mode(stateless_http_enabled)
try:
- mcp.run(transport="stdio")
+ if transport == "stdio":
+ mcp.run(transport="stdio")
+ return
+
+ middleware = [Middleware(MCPAPIKeyMiddleware)]
+ mcp.run(
+ transport=transport,
+ host=host,
+ port=port,
+ path=path,
+ middleware=middleware,
+ stateless_http=stateless_http_enabled,
+ )
finally:
+ set_stateless_http_mode(False)
_cleanup_mcp_resources_blocking()
+def _normalize_mcp_path(path: str) -> str:
+ path = path.strip()
+ if not path:
+ return "/mcp"
+ if not path.startswith("/"):
+ return f"/{path}"
+ return path
+
+
@run_app.command(
name="code",
context_settings={"allow_interspersed_args": False},
diff --git a/skyvern/cli/workflow.py b/skyvern/cli/workflow.py
index eb8d6a204..9e9cc2190 100644
--- a/skyvern/cli/workflow.py
+++ b/skyvern/cli/workflow.py
@@ -1,27 +1,80 @@
-"""Workflow-related CLI helpers."""
+"""Workflow-related CLI commands with MCP-parity flags and output."""
from __future__ import annotations
+import asyncio
import json
-import os
+import sys
+from pathlib import Path
+from typing import Any, Callable, Coroutine
import typer
from dotenv import load_dotenv
-from rich.panel import Panel
-from skyvern.client import Skyvern
from skyvern.config import settings
from skyvern.utils.env_paths import resolve_backend_env_path
-from .console import console
-from .tasks import _list_workflow_tasks
+from .commands._output import output, output_error
+from .mcp_tools.workflow import skyvern_workflow_cancel as tool_workflow_cancel
+from .mcp_tools.workflow import skyvern_workflow_create as tool_workflow_create
+from .mcp_tools.workflow import skyvern_workflow_delete as tool_workflow_delete
+from .mcp_tools.workflow import skyvern_workflow_get as tool_workflow_get
+from .mcp_tools.workflow import skyvern_workflow_list as tool_workflow_list
+from .mcp_tools.workflow import skyvern_workflow_run as tool_workflow_run
+from .mcp_tools.workflow import skyvern_workflow_status as tool_workflow_status
+from .mcp_tools.workflow import skyvern_workflow_update as tool_workflow_update
-workflow_app = typer.Typer(help="Manage Skyvern workflows.")
+workflow_app = typer.Typer(help="Manage Skyvern workflows.", no_args_is_help=True)
+
+
+def _emit_tool_result(result: dict[str, Any], *, json_output: bool) -> None:
+ if json_output:
+ json.dump(result, sys.stdout, indent=2, default=str)
+ sys.stdout.write("\n")
+ if not result.get("ok", False):
+ raise SystemExit(1)
+ return
+
+ if result.get("ok", False):
+ output(result.get("data"), action=str(result.get("action", "")), json_mode=False)
+ return
+
+ err = result.get("error") or {}
+ output_error(str(err.get("message", "Unknown error")), hint=str(err.get("hint", "")), json_mode=False)
+
+
+def _run_tool(
+ runner: Callable[[], Coroutine[Any, Any, dict[str, Any]]],
+ *,
+ json_output: bool,
+ hint_on_exception: str,
+) -> None:
+ try:
+ result: dict[str, Any] = asyncio.run(runner())
+ _emit_tool_result(result, json_output=json_output)
+ except typer.BadParameter:
+ raise
+ except Exception as e:
+ output_error(str(e), hint=hint_on_exception, json_mode=json_output)
+
+
+def _resolve_inline_or_file(value: str | None, *, param_name: str) -> str | None:
+ if value is None or not value.startswith("@"):
+ return value
+
+ file_path = value[1:]
+ if not file_path:
+ raise typer.BadParameter(f"{param_name} file path cannot be empty after '@'.")
+
+ path = Path(file_path).expanduser()
+ try:
+ return path.read_text(encoding="utf-8")
+ except OSError as e:
+ raise typer.BadParameter(f"Unable to read {param_name} file '{path}': {e}") from e
@workflow_app.callback()
def workflow_callback(
- ctx: typer.Context,
api_key: str | None = typer.Option(
None,
"--api-key",
@@ -29,86 +82,188 @@ def workflow_callback(
envvar="SKYVERN_API_KEY",
),
) -> None:
- """Store the provided API key in the Typer context."""
- ctx.obj = {"api_key": api_key}
+ """Load workflow CLI environment and optional API key override."""
+ load_dotenv(resolve_backend_env_path())
+ if api_key:
+ settings.SKYVERN_API_KEY = api_key
-def _get_client(api_key: str | None = None) -> Skyvern:
- """Instantiate a Skyvern SDK client using environment variables."""
- load_dotenv(resolve_backend_env_path())
- key = api_key or os.getenv("SKYVERN_API_KEY") or settings.SKYVERN_API_KEY
- return Skyvern(base_url=settings.SKYVERN_BASE_URL, api_key=key)
+@workflow_app.command("list")
+def workflow_list(
+ search: str | None = typer.Option(
+ None,
+ "--search",
+ help="Search across workflow titles, folder names, and parameter metadata.",
+ ),
+ page: int = typer.Option(1, "--page", min=1, help="Page number (1-based)."),
+ page_size: int = typer.Option(10, "--page-size", min=1, max=100, help="Results per page."),
+ only_workflows: bool = typer.Option(
+ False,
+ "--only-workflows",
+ help="Only return multi-step workflows (exclude saved tasks).",
+ ),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """List workflows."""
+ async def _run() -> dict[str, Any]:
+ return await tool_workflow_list(
+ search=search,
+ page=page,
+ page_size=page_size,
+ only_workflows=only_workflows,
+ )
-@workflow_app.command("run")
-def run_workflow(
- ctx: typer.Context,
- workflow_id: str = typer.Argument(..., help="Workflow permanent ID"),
- parameters: str = typer.Option("{}", "--parameters", "-p", help="JSON parameters for the workflow"),
- title: str | None = typer.Option(None, "--title", help="Title for the workflow run"),
- max_steps: int | None = typer.Option(None, "--max-steps", help="Override the workflow max steps"),
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check your API key and workflow list filters.")
+
+
+@workflow_app.command("get")
+def workflow_get(
+ workflow_id: str = typer.Option(..., "--id", help="Workflow permanent ID (wpid_...)."),
+ version: int | None = typer.Option(None, "--version", min=1, help="Specific version to retrieve."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
) -> None:
- """Run a workflow."""
- try:
- params_dict = json.loads(parameters) if parameters else {}
- except json.JSONDecodeError:
- console.print(f"[red]Invalid JSON for parameters: {parameters}[/red]")
- raise typer.Exit(code=1)
-
- client = _get_client(ctx.obj.get("api_key") if ctx.obj else None)
- run_resp = client.run_workflow(
- workflow_id=workflow_id,
- parameters=params_dict,
- title=title,
- max_steps_override=max_steps,
- )
- console.print(
- Panel(
- f"Started workflow run [bold]{run_resp.run_id}[/bold]",
- border_style="green",
+ """Get a workflow definition by ID."""
+
+ async def _run() -> dict[str, Any]:
+ return await tool_workflow_get(workflow_id=workflow_id, version=version)
+
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check your API key and workflow ID.")
+
+
+@workflow_app.command("create")
+def workflow_create(
+ definition: str = typer.Option(
+ ...,
+ "--definition",
+ help="Workflow definition as YAML/JSON string or @file path.",
+ ),
+ definition_format: str = typer.Option(
+ "auto",
+ "--format",
+ help="Definition format: json, yaml, or auto.",
+ ),
+ folder_id: str | None = typer.Option(None, "--folder-id", help="Folder ID (fld_...) for the workflow."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """Create a workflow."""
+
+ async def _run() -> dict[str, Any]:
+ resolved_definition = _resolve_inline_or_file(definition, param_name="definition")
+ assert resolved_definition is not None
+ return await tool_workflow_create(
+ definition=resolved_definition,
+ format=definition_format,
+ folder_id=folder_id,
)
- )
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the workflow definition syntax.")
-@workflow_app.command("cancel")
-def cancel_workflow(
- ctx: typer.Context,
- run_id: str = typer.Argument(..., help="ID of the workflow run"),
+
+@workflow_app.command("update")
+def workflow_update(
+ workflow_id: str = typer.Option(..., "--id", help="Workflow permanent ID (wpid_...)."),
+ definition: str = typer.Option(
+ ...,
+ "--definition",
+ help="Updated workflow definition as YAML/JSON string or @file path.",
+ ),
+ definition_format: str = typer.Option(
+ "auto",
+ "--format",
+ help="Definition format: json, yaml, or auto.",
+ ),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """Update a workflow definition."""
+
+ async def _run() -> dict[str, Any]:
+ resolved_definition = _resolve_inline_or_file(definition, param_name="definition")
+ assert resolved_definition is not None
+ return await tool_workflow_update(
+ workflow_id=workflow_id,
+ definition=resolved_definition,
+ format=definition_format,
+ )
+
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the workflow ID and definition syntax.")
+
+
+@workflow_app.command("delete")
+def workflow_delete(
+ workflow_id: str = typer.Option(..., "--id", help="Workflow permanent ID (wpid_...)."),
+ force: bool = typer.Option(False, "--force", help="Confirm permanent deletion."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
) -> None:
- """Cancel a running workflow."""
- client = _get_client(ctx.obj.get("api_key") if ctx.obj else None)
- client.cancel_run(run_id=run_id)
- console.print(Panel(f"Cancel signal sent for run {run_id}", border_style="red"))
+ """Delete a workflow."""
+
+ async def _run() -> dict[str, Any]:
+ return await tool_workflow_delete(workflow_id=workflow_id, force=force)
+
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the workflow ID and your permissions.")
+
+
+@workflow_app.command("run")
+def workflow_run(
+ workflow_id: str = typer.Option(..., "--id", help="Workflow permanent ID (wpid_...)."),
+ params: str | None = typer.Option(
+ None,
+ "--params",
+ "--parameters",
+ "-p",
+ help="Workflow parameters as JSON string or @file path.",
+ ),
+ session: str | None = typer.Option(None, "--session", help="Browser session ID (pbs_...) to reuse."),
+ webhook: str | None = typer.Option(None, "--webhook", help="Status webhook callback URL."),
+ proxy: str | None = typer.Option(None, "--proxy", help="Proxy location (e.g., RESIDENTIAL)."),
+ wait: bool = typer.Option(False, "--wait", help="Wait for workflow completion before returning."),
+ timeout: int = typer.Option(
+ 300,
+ "--timeout",
+ min=10,
+ max=3600,
+ help="Max wait time in seconds when --wait is set.",
+ ),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+ """Run a workflow."""
+
+ async def _run() -> dict[str, Any]:
+ resolved_params = _resolve_inline_or_file(params, param_name="params")
+ return await tool_workflow_run(
+ workflow_id=workflow_id,
+ parameters=resolved_params,
+ browser_session_id=session,
+ webhook_url=webhook,
+ proxy_location=proxy,
+ wait=wait,
+ timeout_seconds=timeout,
+ )
+
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the workflow ID and run parameters.")
@workflow_app.command("status")
def workflow_status(
- ctx: typer.Context,
- run_id: str = typer.Argument(..., help="ID of the workflow run"),
- tasks: bool = typer.Option(False, "--tasks", help="Show task executions"),
+ run_id: str = typer.Option(..., "--run-id", help="Run ID (wr_... or tsk_v2_...)."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
) -> None:
- """Retrieve status information for a workflow run."""
- client = _get_client(ctx.obj.get("api_key") if ctx.obj else None)
- run = client.get_run(run_id=run_id)
- console.print(Panel(run.model_dump_json(indent=2), border_style="cyan"))
- if tasks:
- task_list = _list_workflow_tasks(client, run_id)
- console.print(Panel(json.dumps(task_list, indent=2), border_style="magenta"))
+ """Get workflow run status."""
+ async def _run() -> dict[str, Any]:
+ return await tool_workflow_status(run_id=run_id)
-@workflow_app.command("list")
-def list_workflows(
- ctx: typer.Context,
- page: int = typer.Option(1, "--page", help="Page number"),
- page_size: int = typer.Option(10, "--page-size", help="Number of workflows to return"),
- template: bool = typer.Option(False, "--template", help="List template workflows"),
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the run ID and API key.")
+
+
+@workflow_app.command("cancel")
+def workflow_cancel(
+ run_id: str = typer.Option(..., "--run-id", help="Run ID (wr_... or tsk_v2_...)."),
+ json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
) -> None:
- """List workflows for the organization."""
- client = _get_client(ctx.obj.get("api_key") if ctx.obj else None)
- resp = client._client_wrapper.httpx_client.request(
- "api/v1/workflows",
- method="GET",
- params={"page": page, "page_size": page_size, "template": template},
- )
- resp.raise_for_status()
- console.print(Panel(json.dumps(resp.json(), indent=2), border_style="cyan"))
+ """Cancel a workflow run."""
+
+ async def _run() -> dict[str, Any]:
+ return await tool_workflow_cancel(run_id=run_id)
+
+ _run_tool(_run, json_output=json_output, hint_on_exception="Check the run ID and API key.")
diff --git a/tests/unit/test_cli_commands.py b/tests/unit/test_cli_commands.py
index 08edf9a78..cc9c4d80c 100644
--- a/tests/unit/test_cli_commands.py
+++ b/tests/unit/test_cli_commands.py
@@ -296,3 +296,175 @@ class TestBrowserCommands:
parsed = json.loads(capsys.readouterr().out)
assert parsed["ok"] is False
assert "Invalid state" in parsed["error"]["message"]
+
+
+# ---------------------------------------------------------------------------
+# Workflow command behavior
+# ---------------------------------------------------------------------------
+
+
+class TestWorkflowCommands:
+ def test_workflow_get_outputs_mcp_envelope_in_json_mode(
+ self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
+ ) -> None:
+ from skyvern.cli import workflow as workflow_cmd
+
+ expected = {
+ "ok": True,
+ "action": "skyvern_workflow_get",
+ "browser_context": {"mode": "none", "session_id": None, "cdp_url": None},
+ "data": {"workflow_permanent_id": "wpid_123"},
+ "artifacts": [],
+ "timing_ms": {},
+ "warnings": [],
+ "error": None,
+ }
+ tool = AsyncMock(return_value=expected)
+ monkeypatch.setattr(workflow_cmd, "tool_workflow_get", tool)
+
+ workflow_cmd.workflow_get(workflow_id="wpid_123", version=2, json_output=True)
+
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed == expected
+ assert tool.await_args.kwargs == {"workflow_id": "wpid_123", "version": 2}
+
+ def test_workflow_create_reads_definition_from_file(
+ self,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture,
+ ) -> None:
+ from skyvern.cli import workflow as workflow_cmd
+
+ definition_file = tmp_path / "workflow.json"
+ definition_text = '{"title": "Example", "workflow_definition": {"blocks": []}}'
+ definition_file.write_text(definition_text)
+
+ tool = AsyncMock(
+ return_value={
+ "ok": True,
+ "action": "skyvern_workflow_create",
+ "browser_context": {"mode": "none", "session_id": None, "cdp_url": None},
+ "data": {"workflow_permanent_id": "wpid_new"},
+ "artifacts": [],
+ "timing_ms": {},
+ "warnings": [],
+ "error": None,
+ }
+ )
+ monkeypatch.setattr(workflow_cmd, "tool_workflow_create", tool)
+
+ workflow_cmd.workflow_create(
+ definition=f"@{definition_file}",
+ definition_format="json",
+ folder_id="fld_123",
+ json_output=True,
+ )
+
+ assert tool.await_args.kwargs == {
+ "definition": definition_text,
+ "format": "json",
+ "folder_id": "fld_123",
+ }
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed["ok"] is True
+ assert parsed["data"]["workflow_permanent_id"] == "wpid_new"
+
+ def test_workflow_run_reads_params_file_and_maps_options(
+ self,
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture,
+ ) -> None:
+ from skyvern.cli import workflow as workflow_cmd
+
+ params_file = tmp_path / "params.json"
+ params_file.write_text('{"company": "Acme"}')
+
+ tool = AsyncMock(
+ return_value={
+ "ok": True,
+ "action": "skyvern_workflow_run",
+ "browser_context": {"mode": "none", "session_id": None, "cdp_url": None},
+ "data": {"run_id": "wr_123", "status": "queued"},
+ "artifacts": [],
+ "timing_ms": {},
+ "warnings": [],
+ "error": None,
+ }
+ )
+ monkeypatch.setattr(workflow_cmd, "tool_workflow_run", tool)
+
+ workflow_cmd.workflow_run(
+ workflow_id="wpid_123",
+ params=f"@{params_file}",
+ session="pbs_456",
+ webhook="https://example.com/webhook",
+ proxy="RESIDENTIAL",
+ wait=True,
+ timeout=450,
+ json_output=True,
+ )
+
+ assert tool.await_args.kwargs == {
+ "workflow_id": "wpid_123",
+ "parameters": '{"company": "Acme"}',
+ "browser_session_id": "pbs_456",
+ "webhook_url": "https://example.com/webhook",
+ "proxy_location": "RESIDENTIAL",
+ "wait": True,
+ "timeout_seconds": 450,
+ }
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed["ok"] is True
+ assert parsed["data"]["run_id"] == "wr_123"
+
+ def test_workflow_status_json_error_exits_nonzero(
+ self, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture
+ ) -> None:
+ from skyvern.cli import workflow as workflow_cmd
+
+ tool = AsyncMock(
+ return_value={
+ "ok": False,
+ "action": "skyvern_workflow_status",
+ "browser_context": {"mode": "none", "session_id": None, "cdp_url": None},
+ "data": None,
+ "artifacts": [],
+ "timing_ms": {},
+ "warnings": [],
+ "error": {
+ "code": "RUN_NOT_FOUND",
+ "message": "Run 'wr_missing' not found",
+ "hint": "Verify the run ID",
+ "details": {},
+ },
+ }
+ )
+ monkeypatch.setattr(workflow_cmd, "tool_workflow_status", tool)
+
+ with pytest.raises(SystemExit, match="1"):
+ workflow_cmd.workflow_status(run_id="wr_missing", json_output=True)
+
+ parsed = json.loads(capsys.readouterr().out)
+ assert parsed["ok"] is False
+ assert parsed["error"]["code"] == "RUN_NOT_FOUND"
+
+ def test_workflow_update_missing_definition_file_raises_bad_parameter(
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ from skyvern.cli import workflow as workflow_cmd
+
+ tool = AsyncMock()
+ monkeypatch.setattr(workflow_cmd, "tool_workflow_update", tool)
+ missing_file = tmp_path / "missing-definition.json"
+
+ with pytest.raises(typer.BadParameter, match="Unable to read definition file"):
+ workflow_cmd.workflow_update(
+ workflow_id="wpid_123",
+ definition=f"@{missing_file}",
+ definition_format="json",
+ json_output=False,
+ )
+
+ tool.assert_not_called()
diff --git a/tests/unit/test_mcp_http_auth.py b/tests/unit/test_mcp_http_auth.py
new file mode 100644
index 000000000..8cfcc4dcf
--- /dev/null
+++ b/tests/unit/test_mcp_http_auth.py
@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from fastapi import HTTPException
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+from skyvern.cli.core import client as client_mod
+from skyvern.cli.core import mcp_http_auth
+
+
[email protected](autouse=True)
+def _reset_auth_context() -> None:
+ client_mod._api_key_override.set(None)
+ mcp_http_auth._auth_db = None
+ mcp_http_auth._api_key_validation_cache.clear()
+ mcp_http_auth._API_KEY_CACHE_TTL_SECONDS = 30.0
+ mcp_http_auth._API_KEY_CACHE_MAX_SIZE = 1024
+ mcp_http_auth._MAX_VALIDATION_RETRIES = 2
+ mcp_http_auth._RETRY_DELAY_SECONDS = 0.0 # no delay in tests
+
+
+async def _echo_request_context(request: Request) -> JSONResponse:
+ return JSONResponse(
+ {
+ "api_key": client_mod.get_active_api_key(),
+ "organization_id": getattr(request.state, "organization_id", None),
+ }
+ )
+
+
+def _build_test_app() -> Starlette:
+ return Starlette(
+ routes=[Route("/mcp", endpoint=_echo_request_context, methods=["POST"])],
+ middleware=[Middleware(mcp_http_auth.MCPAPIKeyMiddleware)],
+ )
+
+
+async def test_mcp_http_auth_rejects_missing_api_key() -> None:
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", json={})
+
+ assert response.status_code == 401
+ assert response.json()["error"]["code"] == "UNAUTHORIZED"
+ assert "x-api-key" in response.json()["error"]["message"]
+
+
+async def test_mcp_http_auth_allows_health_checks_without_api_key() -> None:
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.get("/healthz")
+
+ assert response.status_code == 200
+ assert response.json() == {"status": "ok"}
+
+
+async def test_mcp_http_auth_rejects_invalid_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "validate_mcp_api_key",
+ AsyncMock(side_effect=HTTPException(status_code=403, detail="Invalid credentials")),
+ )
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", headers={"x-api-key": "bad-key"}, json={})
+
+ assert response.status_code == 401
+ assert response.json()["error"]["code"] == "UNAUTHORIZED"
+ assert response.json()["error"]["message"] == "Invalid API key"
+
+
+async def test_mcp_http_auth_returns_500_on_non_auth_http_exception(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "validate_mcp_api_key",
+ AsyncMock(side_effect=HTTPException(status_code=500, detail="db down")),
+ )
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", headers={"x-api-key": "sk_live_abc"}, json={})
+
+ assert response.status_code == 500
+ assert response.json()["error"]["code"] == "INTERNAL_ERROR"
+
+
+async def test_mcp_http_auth_returns_503_on_transient_validation_exhaustion(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "validate_mcp_api_key",
+ AsyncMock(side_effect=HTTPException(status_code=503, detail="API key validation temporarily unavailable")),
+ )
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", headers={"x-api-key": "sk_live_abc"}, json={})
+
+ assert response.status_code == 503
+ assert response.json()["error"]["code"] == "SERVICE_UNAVAILABLE"
+ assert response.json()["error"]["message"] == "API key validation temporarily unavailable"
+
+
+async def test_mcp_http_auth_returns_500_on_unexpected_validation_error(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "validate_mcp_api_key",
+ AsyncMock(side_effect=RuntimeError("boom")),
+ )
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", headers={"x-api-key": "sk_live_abc"}, json={})
+
+ assert response.status_code == 500
+ assert response.json()["error"]["code"] == "INTERNAL_ERROR"
+
+
+async def test_mcp_http_auth_sets_request_scoped_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ mcp_http_auth,
+ "validate_mcp_api_key",
+ AsyncMock(return_value="org_123"),
+ )
+ app = _build_test_app()
+
+ async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://testserver") as client:
+ response = await client.post("/mcp", headers={"x-api-key": "sk_live_abc"}, json={})
+
+ assert response.status_code == 200
+ assert response.json() == {
+ "api_key": "sk_live_abc",
+ "organization_id": "org_123",
+ }
+ assert client_mod.get_active_api_key() != "sk_live_abc"
+
+
+async def test_validate_mcp_api_key_uses_ttl_cache(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ return SimpleNamespace(organization=SimpleNamespace(organization_id="org_cached"))
+
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ first = await mcp_http_auth.validate_mcp_api_key("sk_test_cache")
+ second = await mcp_http_auth.validate_mcp_api_key("sk_test_cache")
+
+ assert first == "org_cached"
+ assert second == "org_cached"
+ assert calls == 1
+
+
+async def test_validate_mcp_api_key_cache_expires(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ return SimpleNamespace(organization=SimpleNamespace(organization_id=f"org_{calls}"))
+
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ first = await mcp_http_auth.validate_mcp_api_key("sk_test_cache_expire")
+ cache_key = mcp_http_auth._cache_key("sk_test_cache_expire")
+ mcp_http_auth._api_key_validation_cache[cache_key] = (first, 0.0)
+ second = await mcp_http_auth.validate_mcp_api_key("sk_test_cache_expire")
+
+ assert first == "org_1"
+ assert second == "org_2"
+ assert calls == 2
+
+
+async def test_validate_mcp_api_key_negative_caches_auth_failures(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ raise HTTPException(status_code=401, detail="Invalid credentials")
+
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ with pytest.raises(HTTPException, match="Invalid credentials"):
+ await mcp_http_auth.validate_mcp_api_key("sk_test_auth_failure")
+
+ with pytest.raises(HTTPException, match="Invalid API key"):
+ await mcp_http_auth.validate_mcp_api_key("sk_test_auth_failure")
+
+ assert calls == 1
+
+
+async def test_validate_mcp_api_key_retries_transient_failure_without_negative_cache(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ raise RuntimeError("transient db error")
+ return SimpleNamespace(organization=SimpleNamespace(organization_id="org_recovered"))
+
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ recovered_org = await mcp_http_auth.validate_mcp_api_key("sk_test_transient")
+
+ cache_key = mcp_http_auth._cache_key("sk_test_transient")
+ assert mcp_http_auth._api_key_validation_cache[cache_key][0] == "org_recovered"
+
+ assert recovered_org == "org_recovered"
+ assert calls == 2
+
+
+async def test_validate_mcp_api_key_concurrent_callers_all_succeed(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Multiple concurrent callers for the same key all succeed; the cache
+ collapses subsequent calls after the first one populates it."""
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ return SimpleNamespace(organization=SimpleNamespace(organization_id="org_concurrent"))
+
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ results = await asyncio.gather(*[mcp_http_auth.validate_mcp_api_key("sk_test_concurrent") for _ in range(5)])
+ assert all(r == "org_concurrent" for r in results)
+ # First call populates cache; remaining may or may not hit DB depending on
+ # scheduling, but all must succeed.
+ assert calls >= 1
+
+
+async def test_validate_mcp_api_key_returns_503_after_retry_exhaustion(monkeypatch: pytest.MonkeyPatch) -> None:
+ calls = 0
+
+ async def _resolve(_api_key: str, _db: object) -> object:
+ nonlocal calls
+ calls += 1
+ raise RuntimeError("persistent db outage")
+
+ monkeypatch.setattr(mcp_http_auth, "_MAX_VALIDATION_RETRIES", 2)
+ monkeypatch.setattr(mcp_http_auth, "resolve_org_from_api_key", _resolve)
+ monkeypatch.setattr(mcp_http_auth, "_get_auth_db", lambda: object())
+
+ with pytest.raises(HTTPException, match="temporarily unavailable") as exc_info:
+ await mcp_http_auth.validate_mcp_api_key("sk_test_transient_exhausted")
+
+ assert exc_info.value.status_code == 503
+ assert calls == 3 # initial + 2 retries
+
+
+async def test_close_auth_db_disposes_engine() -> None:
+ dispose = AsyncMock()
+ mcp_http_auth._auth_db = SimpleNamespace(engine=SimpleNamespace(dispose=dispose))
+ mcp_http_auth._api_key_validation_cache["k"] = ("org", 123.0)
+
+ await mcp_http_auth.close_auth_db()
+
+ dispose.assert_awaited_once()
+ assert mcp_http_auth._auth_db is None
+ assert mcp_http_auth._api_key_validation_cache == {}
+
+
+async def test_close_auth_db_noop_when_uninitialized() -> None:
+ mcp_http_auth._auth_db = None
+ await mcp_http_auth.close_auth_db()
+ assert mcp_http_auth._auth_db is None
diff --git a/tests/unit/test_mcp_session_lifecycle.py b/tests/unit/test_mcp_session_lifecycle.py
index 568fccdac..a26d8a126 100644
--- a/tests/unit/test_mcp_session_lifecycle.py
+++ b/tests/unit/test_mcp_session_lifecycle.py
@@ -1,5 +1,6 @@
from __future__ import annotations
+from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -14,10 +15,13 @@ from skyvern.cli.mcp_tools import session as mcp_session
@pytest.fixture(autouse=True)
def _reset_singletons() -> None:
client_mod._skyvern_instance.set(None)
+ client_mod._api_key_override.set(None)
client_mod._global_skyvern_instance = None
+ client_mod._api_key_clients.clear()
session_manager._current_session.set(None)
session_manager._global_session = None
+ session_manager.set_stateless_http_mode(False)
mcp_session.set_current_session(mcp_session.SessionState())
@@ -47,6 +51,115 @@ def test_get_skyvern_reuses_global_instance_across_contexts(monkeypatch: pytest.
assert len(created) == 1
+def test_get_skyvern_reuses_override_instance_per_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+ created_keys: list[str] = []
+
+ class FakeSkyvern:
+ def __init__(self, *args: object, **kwargs: object) -> None:
+ created_keys.append(kwargs["api_key"])
+
+ @classmethod
+ def local(cls) -> FakeSkyvern:
+ return cls(api_key="local")
+
+ async def aclose(self) -> None:
+ return None
+
+ monkeypatch.setattr(client_mod, "Skyvern", FakeSkyvern)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_API_KEY", None)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_BASE_URL", None)
+
+ token = client_mod.set_api_key_override("sk_key_a")
+ try:
+ first = client_mod.get_skyvern()
+ client_mod._skyvern_instance.set(None)
+ second = client_mod.get_skyvern()
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ assert first is second
+ assert created_keys == ["sk_key_a"]
+
+
+def test_get_skyvern_override_client_cache_uses_lru_eviction(monkeypatch: pytest.MonkeyPatch) -> None:
+ created_keys: list[str] = []
+
+ class FakeSkyvern:
+ def __init__(self, *args: object, **kwargs: object) -> None:
+ created_keys.append(kwargs["api_key"])
+
+ @classmethod
+ def local(cls) -> FakeSkyvern:
+ return cls(api_key="local")
+
+ async def aclose(self) -> None:
+ return None
+
+ monkeypatch.setattr(client_mod, "Skyvern", FakeSkyvern)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_API_KEY", None)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_BASE_URL", None)
+ monkeypatch.setattr(client_mod, "_API_KEY_CLIENT_CACHE_MAX", 2)
+
+ for key in ("sk_key_a", "sk_key_b"):
+ token = client_mod.set_api_key_override(key)
+ try:
+ client_mod.get_skyvern()
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ # Touch key_a so key_b becomes least-recently-used.
+ token = client_mod.set_api_key_override("sk_key_a")
+ try:
+ client_mod._skyvern_instance.set(None)
+ client_mod.get_skyvern()
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ # Adding key_c should evict key_b.
+ token = client_mod.set_api_key_override("sk_key_c")
+ try:
+ client_mod.get_skyvern()
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ assert list(client_mod._api_key_clients.keys()) == [
+ client_mod._cache_key("sk_key_a"),
+ client_mod._cache_key("sk_key_c"),
+ ]
+ # key_a, key_b, key_c were created exactly once each.
+ assert created_keys == ["sk_key_a", "sk_key_b", "sk_key_c"]
+
+
+def test_get_skyvern_override_cache_closes_evicted_client(monkeypatch: pytest.MonkeyPatch) -> None:
+ closed_keys: list[str] = []
+
+ class FakeSkyvern:
+ def __init__(self, *args: object, **kwargs: object) -> None:
+ self.api_key = kwargs["api_key"]
+
+ @classmethod
+ def local(cls) -> FakeSkyvern:
+ return cls(api_key="local")
+
+ async def aclose(self) -> None:
+ closed_keys.append(self.api_key)
+
+ monkeypatch.setattr(client_mod, "Skyvern", FakeSkyvern)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_API_KEY", None)
+ monkeypatch.setattr(client_mod.settings, "SKYVERN_BASE_URL", None)
+ monkeypatch.setattr(client_mod, "_API_KEY_CLIENT_CACHE_MAX", 1)
+
+ for key in ("sk_key_a", "sk_key_b"):
+ token = client_mod.set_api_key_override(key)
+ try:
+ client_mod.get_skyvern()
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ assert list(client_mod._api_key_clients.keys()) == [client_mod._cache_key("sk_key_b")]
+ assert closed_keys == ["sk_key_a"]
+
+
@pytest.mark.asyncio
async def test_close_skyvern_closes_singleton() -> None:
fake = MagicMock()
@@ -75,12 +188,53 @@ def test_get_current_session_falls_back_to_global_state() -> None:
assert recovered is state
+def test_get_current_session_stateless_mode_ignores_global_state() -> None:
+ global_state = session_manager.SessionState(
+ browser=MagicMock(),
+ context=BrowserContext(mode="cloud_session", session_id="pbs_999"),
+ )
+ session_manager._global_session = global_state
+ session_manager._current_session.set(None)
+
+ session_manager.set_stateless_http_mode(True)
+ try:
+ recovered = session_manager.get_current_session()
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+ assert recovered is not global_state
+ assert recovered.browser is None
+ assert recovered.context is None
+
+
+def test_set_current_session_stateless_mode_does_not_override_global_state() -> None:
+ global_state = session_manager.SessionState(
+ browser=MagicMock(),
+ context=BrowserContext(mode="cloud_session", session_id="pbs_global"),
+ )
+ session_manager._global_session = global_state
+ replacement = session_manager.SessionState(
+ browser=MagicMock(),
+ context=BrowserContext(mode="cloud_session", session_id="pbs_request"),
+ )
+
+ session_manager.set_stateless_http_mode(True)
+ try:
+ session_manager.set_current_session(replacement)
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+ assert session_manager._global_session is global_state
+ assert session_manager._current_session.get() is replacement
+
+
@pytest.mark.asyncio
async def test_resolve_browser_reuses_matching_cloud_session(monkeypatch: pytest.MonkeyPatch) -> None:
current_browser = MagicMock()
current_state = session_manager.SessionState(
browser=current_browser,
context=BrowserContext(mode="cloud_session", session_id="pbs_123"),
+ api_key_hash=session_manager._api_key_hash(client_mod.get_active_api_key()),
)
session_manager.set_current_session(current_state)
@@ -95,6 +249,92 @@ async def test_resolve_browser_reuses_matching_cloud_session(monkeypatch: pytest
fake_skyvern.connect_to_cloud_browser_session.assert_not_awaited()
+async def test_resolve_browser_does_not_reuse_session_for_different_api_key(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ current_browser = MagicMock()
+ session_manager.set_current_session(
+ session_manager.SessionState(
+ browser=current_browser,
+ context=BrowserContext(mode="cloud_session", session_id="pbs_123"),
+ api_key_hash=session_manager._api_key_hash("sk_key_a"),
+ )
+ )
+
+ replacement_browser = MagicMock()
+ fake_skyvern = MagicMock()
+ fake_skyvern.connect_to_cloud_browser_session = AsyncMock(return_value=replacement_browser)
+ monkeypatch.setattr(session_manager, "get_skyvern", lambda: fake_skyvern)
+
+ token = client_mod.set_api_key_override("sk_key_b")
+ try:
+ browser, ctx = await session_manager.resolve_browser(session_id="pbs_123")
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ assert browser is replacement_browser
+ assert ctx.session_id == "pbs_123"
+ fake_skyvern.connect_to_cloud_browser_session.assert_awaited_once_with("pbs_123")
+
+
+async def test_resolve_browser_stateless_mode_does_not_write_global_session(monkeypatch: pytest.MonkeyPatch) -> None:
+ global_state = session_manager.SessionState(
+ browser=MagicMock(),
+ context=BrowserContext(mode="cloud_session", session_id="pbs_global"),
+ )
+ session_manager._global_session = global_state
+
+ replacement_browser = MagicMock()
+ fake_skyvern = MagicMock()
+ fake_skyvern.connect_to_cloud_browser_session = AsyncMock(return_value=replacement_browser)
+ monkeypatch.setattr(session_manager, "get_skyvern", lambda: fake_skyvern)
+
+ session_manager.set_stateless_http_mode(True)
+ try:
+ browser, ctx = await session_manager.resolve_browser(session_id="pbs_123")
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+ assert browser is replacement_browser
+ assert ctx.session_id == "pbs_123"
+ assert session_manager._global_session is global_state
+
+
+async def test_resolve_browser_blocks_implicit_session_in_stateless_mode() -> None:
+ session_manager.set_current_session(
+ session_manager.SessionState(
+ browser=MagicMock(),
+ context=BrowserContext(mode="cloud_session", session_id="pbs_123"),
+ api_key_hash=session_manager._api_key_hash("sk_key_a"),
+ )
+ )
+ session_manager.set_stateless_http_mode(True)
+ try:
+ with pytest.raises(session_manager.BrowserNotAvailableError):
+ await session_manager.resolve_browser()
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+
+async def test_resolve_browser_raises_for_invalid_matching_state(monkeypatch: pytest.MonkeyPatch) -> None:
+ session_manager.set_current_session(
+ session_manager.SessionState(
+ browser=None,
+ context=BrowserContext(mode="cloud_session", session_id="pbs_123"),
+ )
+ )
+
+ monkeypatch.setattr(session_manager, "_matches_current", lambda *args, **kwargs: True)
+ monkeypatch.setattr(session_manager, "get_skyvern", lambda: MagicMock())
+
+ with pytest.raises(RuntimeError, match="Expected active browser and context"):
+ await session_manager.resolve_browser(session_id="pbs_123")
+
+
@pytest.mark.asyncio
async def test_session_close_with_matching_session_id_closes_browser_handle(monkeypatch: pytest.MonkeyPatch) -> None:
current_browser = MagicMock()
@@ -262,3 +502,73 @@ async def test_close_current_session_still_closes_browser_when_api_fails(monkeyp
# _browser_session_id should NOT be cleared (API close failed, let browser.close() try)
assert browser._browser_session_id == "pbs_fail"
assert session_manager.get_current_session().browser is None
+
+
+# ---------------------------------------------------------------------------
+# Tests for stateless HTTP mode session creation
+# ---------------------------------------------------------------------------
+
+
+async def test_session_create_stateless_mode_returns_session_without_persisting_browser(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ session_manager.set_stateless_http_mode(True)
+ fake_skyvern = MagicMock()
+ fake_skyvern.create_browser_session = AsyncMock(return_value=SimpleNamespace(browser_session_id="pbs_abc"))
+ monkeypatch.setattr(mcp_session, "get_skyvern", lambda: fake_skyvern)
+ do_session_create = AsyncMock()
+ monkeypatch.setattr(mcp_session, "do_session_create", do_session_create)
+
+ try:
+ result = await mcp_session.skyvern_session_create(timeout=45)
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+ assert result["ok"] is True
+ assert result["data"] == {"session_id": "pbs_abc", "timeout_minutes": 45}
+ do_session_create.assert_not_awaited()
+ assert mcp_session.get_current_session().browser is None
+ assert mcp_session.get_current_session().context is None
+
+
+async def test_session_create_stateless_mode_rejects_local() -> None:
+ session_manager.set_stateless_http_mode(True)
+ try:
+ result = await mcp_session.skyvern_session_create(local=True)
+ finally:
+ session_manager.set_stateless_http_mode(False)
+
+ assert result["ok"] is False
+ assert result["error"]["code"] == mcp_session.ErrorCode.INVALID_INPUT
+
+
+async def test_session_create_persists_active_api_key_hash_in_session_state(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ fake_skyvern = MagicMock()
+ monkeypatch.setattr(mcp_session, "get_skyvern", lambda: fake_skyvern)
+
+ fake_browser = MagicMock()
+ do_session_create = AsyncMock(
+ return_value=(
+ fake_browser,
+ SimpleNamespace(local=False, session_id="pbs_123", timeout_minutes=60, headless=False),
+ )
+ )
+ monkeypatch.setattr(mcp_session, "do_session_create", do_session_create)
+
+ token = client_mod.set_api_key_override("sk_key_create")
+ try:
+ result = await mcp_session.skyvern_session_create(timeout=60)
+ finally:
+ client_mod.reset_api_key_override(token)
+
+ assert result["ok"] is True
+ current = mcp_session.get_current_session()
+ assert current.browser is fake_browser
+ assert current.context == BrowserContext(mode="cloud_session", session_id="pbs_123")
+ assert current.api_key_hash == session_manager._api_key_hash("sk_key_create")
+ assert current.api_key_hash != "sk_key_create"
diff --git a/tests/unit/test_run_commands_cleanup.py b/tests/unit/test_run_commands_cleanup.py
index 74736cfca..34fc79093 100644
--- a/tests/unit/test_run_commands_cleanup.py
+++ b/tests/unit/test_run_commands_cleanup.py
@@ -1,7 +1,7 @@
from __future__ import annotations
import asyncio
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, call
import pytest
@@ -13,6 +13,42 @@ def _reset_cleanup_state() -> None:
run_commands._mcp_cleanup_done = False
+async def test_cleanup_mcp_resources_closes_auth_db(monkeypatch: pytest.MonkeyPatch) -> None:
+ close_current_session = AsyncMock()
+ close_skyvern = AsyncMock()
+ close_auth_db = AsyncMock()
+
+ monkeypatch.setattr(run_commands, "close_current_session", close_current_session)
+ monkeypatch.setattr(run_commands, "close_skyvern", close_skyvern)
+ monkeypatch.setattr(run_commands, "close_auth_db", close_auth_db)
+
+ await run_commands._cleanup_mcp_resources()
+
+ close_current_session.assert_awaited_once()
+ close_skyvern.assert_awaited_once()
+ close_auth_db.assert_awaited_once()
+
+
+async def test_cleanup_mcp_resources_closes_auth_db_on_skyvern_close_error(monkeypatch: pytest.MonkeyPatch) -> None:
+ close_current_session = AsyncMock()
+ close_auth_db = AsyncMock()
+
+ async def _failing_close_skyvern() -> None:
+ raise RuntimeError("close failed")
+
+ monkeypatch.setattr(run_commands, "close_current_session", close_current_session)
+ monkeypatch.setattr(run_commands, "close_skyvern", _failing_close_skyvern)
+ monkeypatch.setattr(run_commands, "close_auth_db", close_auth_db)
+
+ with pytest.raises(RuntimeError, match="close failed"):
+ await run_commands._cleanup_mcp_resources()
+
+ close_current_session.assert_awaited_once()
+ close_auth_db.assert_awaited_once()
+
+
def test_cleanup_mcp_resources_sync_runs_without_running_loop(monkeypatch: pytest.MonkeyPatch) -> None:
cleanup = AsyncMock()
monkeypatch.setattr(run_commands, "_cleanup_mcp_resources", cleanup)
@@ -50,14 +86,56 @@ def test_run_mcp_calls_blocking_cleanup_in_finally(monkeypatch: pytest.MonkeyPat
cleanup_blocking = MagicMock()
register = MagicMock()
run = MagicMock(side_effect=RuntimeError("boom"))
+ set_stateless = MagicMock()
monkeypatch.setattr(run_commands, "_cleanup_mcp_resources_blocking", cleanup_blocking)
monkeypatch.setattr(run_commands.atexit, "register", register)
monkeypatch.setattr(run_commands.mcp, "run", run)
+ monkeypatch.setattr(run_commands, "set_stateless_http_mode", set_stateless)
with pytest.raises(RuntimeError, match="boom"):
run_commands.run_mcp()
register.assert_called_once_with(run_commands._cleanup_mcp_resources_sync)
run.assert_called_once_with(transport="stdio")
+ set_stateless.assert_has_calls([call(False), call(False)])
cleanup_blocking.assert_called_once()
+
+
+def test_run_mcp_http_transport_wires_auth_middleware(monkeypatch: pytest.MonkeyPatch) -> None:
+ cleanup_blocking = MagicMock()
+ register = MagicMock()
+ run = MagicMock()
+ set_stateless = MagicMock()
+
+ monkeypatch.setattr(run_commands, "_cleanup_mcp_resources_blocking", cleanup_blocking)
+ monkeypatch.setattr(run_commands.atexit, "register", register)
+ monkeypatch.setattr(run_commands.mcp, "run", run)
+ monkeypatch.setattr(run_commands, "set_stateless_http_mode", set_stateless)
+
+ run_commands.run_mcp(
+ transport="streamable-http",
+ host="127.0.0.1",
+ port=9010,
+ path="mcp",
+ stateless_http=True,
+ )
+
+ register.assert_called_once_with(run_commands._cleanup_mcp_resources_sync)
+ run.assert_called_once()
+ kwargs = run.call_args.kwargs
+ assert kwargs["transport"] == "streamable-http"
+ assert kwargs["host"] == "127.0.0.1"
+ assert kwargs["port"] == 9010
+ assert kwargs["path"] == "/mcp"
+ assert kwargs["stateless_http"] is True
+ middleware = kwargs["middleware"]
+ assert len(middleware) == 1
+ assert middleware[0].cls is run_commands.MCPAPIKeyMiddleware
+ set_stateless.assert_has_calls([call(True), call(False)])
+ cleanup_blocking.assert_called_once()
+
+
+def test_run_task_tool_registration_points_to_browser_module() -> None:
+ tool = run_commands.mcp._tool_manager._tools["skyvern_run_task"] # type: ignore[attr-defined]
+ assert tool.fn.__module__ == "skyvern.cli.mcp_tools.browser"