Skip to content

Automate browser based workflows with AI

[SKY-8327] Default MCP workflow proxy to residential (#5080)

Marc Kelechava4ddc81fcbd9c
diff --git a/skyvern/cli/mcp_tools/workflow.py b/skyvern/cli/mcp_tools/workflow.py
index 43715495f..3ccc710ab 100644
--- a/skyvern/cli/mcp_tools/workflow.py
+++ b/skyvern/cli/mcp_tools/workflow.py
@@ -9,9 +9,11 @@ from __future__ import annotations
import asyncio
import json
+from enum import Enum
from typing import Annotated, Any
import structlog
+import yaml
from pydantic import Field
from skyvern.client.errors import BadRequestError, NotFoundError
@@ -206,6 +208,7 @@ _CODE_V2_DEFAULTS: dict[str, Any] = {
"adaptive_caching": True,
"run_with": "code",
}
+_DEFAULT_MCP_PROXY_LOCATION = ProxyLocation.RESIDENTIAL
def _deep_merge(base: Any, override: Any) -> Any:
@@ -265,6 +268,70 @@ def _make_invalid_json_definition_error(exc: Exception) -> dict[str, Any]:
)
+def _load_definition_dict(definition: str, fmt: str) -> tuple[dict[str, Any] | None, str | None]:
+ """Best-effort parse of a workflow definition into a mutable dict.
+
+ Used only for tool-side default injection. On parse failure, returns
+ ``(None, None)`` so the caller can preserve existing server-side validation
+ behavior.
+ """
+
+ def _as_dict(value: Any, parsed_format: str) -> tuple[dict[str, Any] | None, str | None]:
+ return (value, parsed_format) if isinstance(value, dict) else (None, None)
+
+ if fmt == "json":
+ try:
+ return _as_dict(json.loads(definition), "json")
+ except (json.JSONDecodeError, TypeError):
+ return None, None
+
+ if fmt == "yaml":
+ try:
+ return _as_dict(yaml.safe_load(definition), "yaml")
+ except yaml.YAMLError:
+ return None, None
+
+ try:
+ return _as_dict(json.loads(definition), "json")
+ except (json.JSONDecodeError, TypeError):
+ try:
+ return _as_dict(yaml.safe_load(definition), "yaml")
+ except yaml.YAMLError:
+ return None, None
+
+
+def _dump_definition_dict(raw: dict[str, Any], parsed_format: str) -> str:
+ def _coerce_enums(value: Any) -> Any:
+ if isinstance(value, Enum):
+ return value.value
+ if isinstance(value, dict):
+ return {key: _coerce_enums(item) for key, item in value.items()}
+ if isinstance(value, list):
+ return [_coerce_enums(item) for item in value]
+ return value
+
+ raw = _coerce_enums(raw)
+ if parsed_format == "json":
+ return json.dumps(raw)
+ return yaml.safe_dump(raw, sort_keys=False)
+
+
+def _inject_missing_top_level_defaults(definition: str, fmt: str, defaults: dict[str, Any]) -> str:
+ """Inject missing top-level keys for JSON or YAML workflow definitions."""
+
+ raw, parsed_format = _load_definition_dict(definition, fmt)
+ if raw is None or parsed_format is None:
+ return definition
+
+ changed = False
+ for key, value in defaults.items():
+ if key not in raw:
+ raw[key] = value
+ changed = True
+
+ return _dump_definition_dict(raw, parsed_format) if changed else definition
+
+
def _inject_code_v2_defaults(definition: str, fmt: str) -> str:
"""Inject Code 2.0 defaults into a JSON definition string when not explicitly set.
@@ -287,6 +354,18 @@ def _inject_code_v2_defaults(definition: str, fmt: str) -> str:
return json.dumps(raw) if changed else definition
+async def _inject_workflow_update_proxy_default(definition: str, fmt: str, workflow_id: str) -> str:
+ """Preserve or default workflow proxy location when MCP update omits it."""
+
+ raw, parsed_format = _load_definition_dict(definition, fmt)
+ if raw is None or parsed_format is None or "proxy_location" in raw:
+ return definition
+
+ existing_workflow = await _get_workflow_by_id(workflow_id)
+ raw["proxy_location"] = existing_workflow.get("proxy_location") or _DEFAULT_MCP_PROXY_LOCATION
+ return _dump_definition_dict(raw, parsed_format)
+
+
def _parse_definition(
definition: str, fmt: str
) -> tuple[WorkflowCreateYamlRequest | None, str | None, dict[str, Any] | None]:
@@ -473,9 +552,14 @@ async def skyvern_workflow_create(
),
)
- # Default to Code 2.0 for MCP-created workflows (create only, not update).
- # Inject defaults into the raw JSON before parsing so explicit user values are preserved.
+ # Default MCP-created workflows to the same editor defaults while preserving
+ # any explicit user-supplied values.
definition = _inject_code_v2_defaults(definition, format)
+ definition = _inject_missing_top_level_defaults(
+ definition,
+ format,
+ {"proxy_location": _DEFAULT_MCP_PROXY_LOCATION},
+ )
json_def, yaml_def, parse_err = _parse_definition(definition, format)
if parse_err is not None:
@@ -538,6 +622,30 @@ async def skyvern_workflow_update(
),
)
+ try:
+ definition = await _inject_workflow_update_proxy_default(definition, format, workflow_id)
+ except NotFoundError:
+ return make_result(
+ "skyvern_workflow_update",
+ ok=False,
+ error=make_error(
+ ErrorCode.WORKFLOW_NOT_FOUND,
+ f"Workflow {workflow_id!r} not found",
+ "Verify the workflow ID with skyvern_workflow_list",
+ ),
+ )
+ except Exception as e:
+ LOG.warning("workflow_update_proxy_default_injection_failed", workflow_id=workflow_id, error=str(e))
+ return make_result(
+ "skyvern_workflow_update",
+ ok=False,
+ error=make_error(
+ ErrorCode.API_ERROR,
+ str(e),
+ "Check the workflow ID and Skyvern connection before retrying the update",
+ ),
+ )
+
json_def, yaml_def, parse_err = _parse_definition(definition, format)
if parse_err is not None:
return make_result("skyvern_workflow_update", ok=False, error=parse_err)
diff --git a/tests/unit/test_mcp_workflow_create_defaults.py b/tests/unit/test_mcp_workflow_create_defaults.py
index 980871f1d..9cd1fd0d6 100644
--- a/tests/unit/test_mcp_workflow_create_defaults.py
+++ b/tests/unit/test_mcp_workflow_create_defaults.py
@@ -2,7 +2,14 @@
import json
-from skyvern.cli.mcp_tools.workflow import _inject_code_v2_defaults, _parse_definition
+import yaml
+
+from skyvern.cli.mcp_tools.workflow import (
+ _inject_code_v2_defaults,
+ _inject_missing_top_level_defaults,
+ _parse_definition,
+)
+from skyvern.schemas.runs import ProxyLocation
def _minimal_workflow_json(**overrides: object) -> str:
@@ -63,11 +70,51 @@ def test_explicit_null_run_with_preserved() -> None:
assert parsed["adaptive_caching"] is True
-def test_yaml_passthrough_unchanged() -> None:
- """YAML definitions are passed through without modification."""
- yaml_str = "title: Test\nworkflow_definition:\n blocks: []"
- result = _inject_code_v2_defaults(yaml_str, "yaml")
- assert result == yaml_str
+def test_proxy_default_injected_when_not_specified_json() -> None:
+ """MCP create should default omitted proxy_location to residential US."""
+ definition = _minimal_workflow_json()
+ result = _inject_missing_top_level_defaults(
+ definition,
+ "json",
+ {"proxy_location": ProxyLocation.RESIDENTIAL},
+ )
+ parsed = json.loads(result)
+ assert parsed["proxy_location"] == ProxyLocation.RESIDENTIAL
+
+
+def test_explicit_null_proxy_location_preserved_json() -> None:
+ """An explicit null proxy_location should not be overwritten by the default injector."""
+ definition = _minimal_workflow_json(proxy_location=None)
+ result = _inject_missing_top_level_defaults(
+ definition,
+ "json",
+ {"proxy_location": ProxyLocation.RESIDENTIAL},
+ )
+ parsed = json.loads(result)
+ assert "proxy_location" in parsed
+ assert parsed["proxy_location"] is None
+
+
+def test_proxy_default_injected_for_yaml() -> None:
+ """YAML definitions should receive the same omitted proxy default."""
+ yaml_str = """
+title: Test
+workflow_definition:
+ parameters: []
+ blocks:
+ - block_type: navigation
+ label: step1
+ url: https://example.com
+ title: Step 1
+ navigation_goal: Click the button
+"""
+ result = _inject_missing_top_level_defaults(
+ yaml_str,
+ "yaml",
+ {"proxy_location": ProxyLocation.RESIDENTIAL},
+ )
+ parsed = yaml.safe_load(result)
+ assert parsed["proxy_location"] == ProxyLocation.RESIDENTIAL
def test_invalid_json_passthrough() -> None:
diff --git a/tests/unit/test_mcp_workflow_tools.py b/tests/unit/test_mcp_workflow_tools.py
index 793a3ff1d..2ec94b0c3 100644
--- a/tests/unit/test_mcp_workflow_tools.py
+++ b/tests/unit/test_mcp_workflow_tools.py
@@ -186,6 +186,34 @@ async def test_workflow_create_preserves_unknown_fields(monkeypatch: pytest.Monk
assert wd_dict.get("some_nested_future_field") == "also_survives"
+async def test_workflow_create_defaults_proxy_location_when_omitted(monkeypatch: pytest.MonkeyPatch) -> None:
+ fake_client = SimpleNamespace(create_workflow=AsyncMock(return_value=_fake_workflow_response()))
+ monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+
+ definition = {
+ "title": "Default proxy workflow",
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": [
+ {
+ "block_type": "navigation",
+ "label": "visit",
+ "url": "https://example.com",
+ "title": "Visit",
+ "navigation_goal": "Open the page",
+ }
+ ],
+ },
+ }
+
+ result = await workflow_tools.skyvern_workflow_create(definition=json.dumps(definition), format="json")
+
+ sent_definition = fake_client.create_workflow.await_args.kwargs["json_definition"]
+ assert result["ok"] is True
+ assert sent_definition.proxy_location == "RESIDENTIAL"
+
+
@pytest.mark.asyncio
async def test_workflow_create_preserves_block_level_unknown_fields(monkeypatch: pytest.MonkeyPatch) -> None:
"""Unknown fields inside individual block dicts survive normalization via deep merge."""
@@ -216,6 +244,84 @@ async def test_workflow_create_preserves_block_level_unknown_fields(monkeypatch:
assert block_dict.get("some_future_block_field") == 42
+async def test_workflow_update_preserves_existing_proxy_when_omitted(monkeypatch: pytest.MonkeyPatch) -> None:
+ fake_client = SimpleNamespace(update_workflow=AsyncMock(return_value=_fake_workflow_response()))
+ monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+
+ async def fake_get_workflow_by_id(workflow_id: str, version: int | None = None) -> dict[str, object]:
+ assert workflow_id == "wpid_test"
+ assert version is None
+ return {"proxy_location": "RESIDENTIAL_AU"}
+
+ monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+
+ definition = {
+ "title": "Updated workflow",
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": [
+ {
+ "block_type": "navigation",
+ "label": "visit",
+ "url": "https://example.com",
+ "title": "Visit",
+ "navigation_goal": "Open the page",
+ }
+ ],
+ },
+ }
+
+ result = await workflow_tools.skyvern_workflow_update(
+ workflow_id="wpid_test",
+ definition=json.dumps(definition),
+ format="json",
+ )
+
+ sent_definition = fake_client.update_workflow.await_args.kwargs["json_definition"]
+ assert result["ok"] is True
+ assert sent_definition.proxy_location == "RESIDENTIAL_AU"
+
+
+async def test_workflow_update_defaults_proxy_when_existing_is_null(monkeypatch: pytest.MonkeyPatch) -> None:
+ fake_client = SimpleNamespace(update_workflow=AsyncMock(return_value=_fake_workflow_response()))
+ monkeypatch.setattr(workflow_tools, "get_skyvern", lambda: fake_client)
+
+ async def fake_get_workflow_by_id(workflow_id: str, version: int | None = None) -> dict[str, object]:
+ assert workflow_id == "wpid_test"
+ assert version is None
+ return {"proxy_location": None}
+
+ monkeypatch.setattr(workflow_tools, "_get_workflow_by_id", fake_get_workflow_by_id)
+
+ definition = {
+ "title": "Updated workflow",
+ "workflow_definition": {
+ "parameters": [],
+ "blocks": [
+ {
+ "block_type": "navigation",
+ "label": "visit",
+ "url": "https://example.com",
+ "title": "Visit",
+ "navigation_goal": "Open the page",
+ }
+ ],
+ },
+ }
+
+ result = await workflow_tools.skyvern_workflow_update(
+ workflow_id="wpid_test",
+ definition=json.dumps(definition),
+ format="json",
+ )
+
+ sent_definition = fake_client.update_workflow.await_args.kwargs["json_definition"]
+ assert result["ok"] is True
+ assert sent_definition.proxy_location == "RESIDENTIAL"
+
+
@pytest.mark.asyncio
async def test_workflow_create_falls_back_on_schema_validation_error(monkeypatch: pytest.MonkeyPatch) -> None:
"""If the internal schema rejects the payload, normalization is skipped and the raw dict is forwarded."""