maxc-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{maxc_cli-0.6.0 → maxc_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9

{maxc_cli-0.6.0 → maxc_cli-0.7.0}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{maxc_cli-0.6.0 → maxc_cli-0.7.0}/src/maxc_cli/_samples.py

@@ -84,6 +84,22 @@ SAMPLES: dict[str, str] = {
         "maxc meta search orders\n"
         "maxc meta search user --project my_proj --json"
     ),
+    # ── kb ─────────────────────────────────────────────────────────────────
+    "kb": "maxc kb ask \"How do I set a split size hint?\" --json\nmaxc kb search \"dynamic filter\" --json",
+    "kb.ask": (
+        "maxc kb ask \"How do I set a split size hint?\"\n"
+        "maxc kb ask \"What does ODPS-0123144 mean?\" --max-docs 3 --json"
+    ),
+    "kb.search": (
+        "maxc kb search \"clustered table bucket\"\n"
+        "maxc kb search \"dynamic filter\" --limit 5 --context-lines 3 --json"
+    ),
+    # ── mcp ────────────────────────────────────────────────────────────────
+    "mcp": 'maxc mcp serve   # point an MCP client at {"command": "maxc", "args": ["mcp", "serve"]}',
+    "mcp.serve": (
+        'maxc mcp serve\n'
+        '# MCP client config: {"command": "maxc", "args": ["mcp", "serve"]}'
+    ),
     "meta.search-columns": (
         "maxc meta search-columns user_id\n"
         "maxc meta search-columns dt --project my_proj --json"

{maxc_cli-0.6.0 → maxc_cli-0.7.0}/src/maxc_cli/app.py

@@ -3836,6 +3836,288 @@ class MaxCApp:
         self.log("meta.list-projects", envelope.status, envelope.metadata)
         return envelope
 
+    # --- Knowledge base (public MCP) ------------------------------------
+
+    def _mcp_client(self):
+        """Build a stateless MCP client authorized by the already-resolved credentials.
+
+        Raises ``FeatureUnavailableError`` rather than silently falling back: an agent
+        that reads "no results" and "KB unreachable" as the same signal would conclude
+        the documentation does not cover its question.
+        """
+        from .backend.mcp import (
+            CatalogMcpTokenProvider,
+            McpError,
+            McpHttpClient,
+            build_catalog_mint,
+            default_endpoint,
+        )
+
+        if not self.config.mcp.enabled:
+            raise FeatureUnavailableError(
+                "Knowledge-base commands need the MaxCompute MCP endpoint enabled.",
+                suggestion=(
+                    "Set `mcp.enabled: true` in the maxc config. The bearer is minted "
+                    "from your existing MaxCompute credentials, so no separate login "
+                    "is required."
+                ),
+            )
+        if self.backend is None or not hasattr(self.backend, "_catalog_rest"):
+            raise FeatureUnavailableError(
+                "Knowledge-base commands need an authenticated backend to mint an MCP token.",
+                suggestion="Configure credentials first: `maxc auth whoami --json`.",
+            )
+        catalog_rest = self.backend._catalog_rest
+        if catalog_rest is None:
+            raise BackendConnectionError(
+                "Could not reach CatalogAPI, which mints the MCP access token.",
+                suggestion=(
+                    "Verify connectivity and identity: `maxc agent doctor --online --json`."
+                ),
+            )
+        endpoint = (self.config.mcp.endpoint or "").strip() or default_endpoint(
+            self.config.default_region
+        )
+        try:
+            tokens = CatalogMcpTokenProvider(
+                build_catalog_mint(catalog_rest, catalog_rest.endpoint or "")
+            )
+            return McpHttpClient(
+                endpoint,
+                tokens,
+                timeout=self.config.mcp.timeout_seconds,
+                client_version=__version__,
+            )
+        except McpError as exc:
+            raise BackendConnectionError(str(exc)) from exc
+
+    @staticmethod
+    def _kb_structured(result: 'dict[str, Any]') -> 'dict[str, Any]':
+        structured = result.get("structuredContent")
+        if not isinstance(structured, dict):
+            raise BackendConnectionError(
+                "The knowledge-base tool returned no structured content.",
+                suggestion="Retry, or fall back to `maxc meta search` for metadata lookups.",
+            )
+        return structured
+
+    @staticmethod
+    def _kb_payload(
+        structured: 'dict[str, Any]',
+        *,
+        answer_from: 'tuple[str, ...] | None' = None,
+        nested_citation: bool = False,
+        package: bool = False,
+    ) -> 'dict[str, Any]':
+        """Carry the server's fields through rather than rebuilding them.
+
+        Only two transformations happen here: citations are flattened to a stable
+        ``uri`` key (the server nests it under ``source`` for search and puts it
+        top-level for ask), and an answer string is wrapped so its provenance is
+        explicit. Everything else is passed by reference on purpose — a field the
+        service adds starts appearing in maxc output with no CLI change, which is
+        the behaviour worth having when the upstream schema is not ours to pin.
+        """
+        data = structured.get("data") if isinstance(structured.get("data"), dict) else {}
+        payload: dict[str, Any] = {}
+        if answer_from is not None:
+            text = next(
+                (data[key] for key in answer_from if data.get(key) is not None), None
+            )
+            payload["answer"] = {"query": data.get("query"), "text": text}
+        else:
+            search: dict[str, Any] = {
+                "query": data.get("query"),
+                "matches": [],
+            }
+            if package:
+                search["package"] = data.get("package")
+            raw_items = data.get("results") or data.get("matches") or []
+            matches = []
+            for item in raw_items:
+                if not isinstance(item, dict):
+                    continue
+                entry = dict(item)
+                uri = entry.get("uri") or entry.get("url")
+                if uri is None and nested_citation:
+                    source = entry.get("source")
+                    if isinstance(source, dict):
+                        uri = source.get("uri") or source.get("url")
+                    elif isinstance(source, str):
+                        uri = source
+                if uri is not None:
+                    entry["uri"] = uri
+                matches.append(entry)
+            search["matches"] = matches
+            payload["search"] = search
+        raw_citations = structured.get("citations")
+        if isinstance(raw_citations, list):
+            flattened = []
+            for item in raw_citations:
+                if not isinstance(item, dict):
+                    continue
+                entry = dict(item)
+                uri = entry.get("uri") or entry.get("url")
+                if uri is not None:
+                    entry["uri"] = uri
+                flattened.append(entry)
+            payload["citations"] = flattened
+        payload["pagination"] = {
+            "has_more": bool(structured.get("has_more", False)),
+            "next_cursor": structured.get("next_cursor"),
+        }
+        # `request_id` is the only handle for correlating a metered model call with
+        # a service-side incident, so keep it at a predictable location.
+        payload["request_id"] = structured.get("request_id")
+        return payload
+
+    def kb_ask(
+        self,
+        question: 'str',
+        *,
+        max_docs: 'int | None' = None,
+        region: 'str | None' = None,
+    ) -> 'Envelope':
+        """Answer from retrieved documentation, with citations kept as first-class output.
+
+        The two kb tools return different shapes (ask yields ``data.answer`` plus a
+        top-level ``citations[]``; search yields ``data.results[]`` with the URI nested
+        under ``source``), so each is projected explicitly instead of sharing one guess.
+        """
+        started = monotonic()
+        arguments: dict[str, Any] = {"question": question}
+        if max_docs is not None:
+            arguments["max_docs"] = max_docs
+        effective_region = region or self.config.default_region
+        if effective_region:
+            arguments["region"] = effective_region
+        structured = self._call_kb_tool("maxcompute_kb_ask", arguments)
+        payload = self._kb_payload(
+            structured,
+            answer_from=("answer", "text"),
+        )
+        envelope = self._kb_envelope(
+            "kb.ask",
+            payload,
+            started,
+            effective_region,
+            follow_up="kb.search",
+            warnings=self._kb_warnings(structured),
+            insights=[
+                "The answer text is model-generated from the cited documents; attribute "
+                "product claims to `citations[].uri` rather than restating them as fact.",
+                "An empty or thin citation list means retrieval found little, which is "
+                "not evidence that the behaviour is undocumented.",
+            ],
+        )
+        self.log("kb.ask", envelope.status, envelope.metadata)
+        return envelope
+
+    def kb_search(
+        self,
+        query: 'str',
+        *,
+        limit: 'int' = 5,
+        context_lines: 'int | None' = None,
+        region: 'str | None' = None,
+    ) -> 'Envelope':
+        started = monotonic()
+        arguments: dict[str, Any] = {"query": query, "limit": limit}
+        if context_lines is not None:
+            arguments["before_lines"] = context_lines
+            arguments["after_lines"] = context_lines
+        effective_region = region or self.config.default_region
+        if effective_region:
+            arguments["region"] = effective_region
+        structured = self._call_kb_tool("maxcompute_kb_search", arguments)
+        payload = self._kb_payload(
+            structured,
+            nested_citation=True,
+            package=True,
+        )
+        envelope = self._kb_envelope(
+            "kb.search",
+            payload,
+            started,
+            effective_region,
+            follow_up="kb.ask",
+            warnings=self._kb_warnings(structured),
+            insights=[
+                "Snippets are truncated server-side; open the cited `uri` before quoting "
+                "a passage as complete.",
+            ],
+        )
+        self.log("kb.search", envelope.status, envelope.metadata)
+        return envelope
+
+    @staticmethod
+    def _kb_warnings(structured: 'dict[str, Any]') -> 'list[str]':
+        """Surface retrieval degradation that still answered HTTP 200 and ok=true-looking.
+
+        Negative inference is the specific risk here: an agent reading an empty result
+        as "the platform cannot do this" produces a confident, wrong answer.
+        """
+        warnings = [str(item) for item in (structured.get("warnings") or [])]
+        if structured.get("ok") is False:
+            warnings.append(
+                "The knowledge-base tool reported ok=false; treat this response as unverified."
+            )
+        return warnings
+
+    def _kb_envelope(
+        self,
+        command: 'str',
+        payload: 'dict[str, Any]',
+        started: float,
+        region: 'str | None',
+        *,
+        follow_up: 'str',
+        warnings: 'list[str]',
+        insights: 'list[str]',
+    ) -> 'Envelope':
+        metadata = {
+            "elapsed_ms": int((monotonic() - started) * 1000),
+            "region": region or None,
+            "backend": "mcp",
+        }
+        return Envelope(
+            command=command,
+            status="success",
+            data=payload,
+            metadata=metadata,
+            agent_hints=AgentHints(
+                actions=[action(follow_up, data=payload, metadata=metadata)],
+                warnings=warnings,
+                insights=insights,
+            ),
+        )
+
+    def _call_kb_tool(self, tool: 'str', arguments: 'dict[str, Any]') -> 'dict[str, Any]':
+        from .backend.mcp import McpError
+
+        client = self._mcp_client()
+        try:
+            result = client.call_tool(tool, arguments)
+        except McpError as exc:
+            raise BackendConnectionError(
+                str(exc),
+                suggestion=(
+                    "Confirm the MCP endpoint is reachable for your region, then retry. "
+                    "Do not conclude from this failure that the documentation lacks an answer."
+                ),
+            ) from exc
+        # A tool-level error still answers HTTP 200, so it must not read as success.
+        if result.get("isError"):
+            content = result.get("content") or []
+            detail = ""
+            if content and isinstance(content[0], dict):
+                detail = str(content[0].get("text") or "")
+            raise BackendConnectionError(
+                "The knowledge-base tool failed: "
+                + (detail[:300] or "no detail returned")
+            )
+        return self._kb_structured(result)
+
     def meta_list_schemas(self, *, project: 'str | None' = None) -> 'Envelope':
         """List all schemas in a project."""
         target_project = project or self.config.default_project
@@ -5677,6 +5959,9 @@ class MaxCApp:
             "remote_jobs": getattr(self.backend, "supports_remote_jobs", True) if self.backend else True,
             "cost_check": getattr(self.backend, "supports_cost_check", True) if self.backend else True,
             "lineage": False,  # Always false for current ODPS backend
+            # Reported from configuration only; probing the MCP endpoint would make
+            # this local command reach the network.
+            "knowledge_base": bool(self.config.mcp.enabled),
         }
 
         # Keep agent.context strictly local. Report Catalog search capability

{maxc_cli-0.6.0 → maxc_cli-0.7.0}/src/maxc_cli/auth_providers.py

@@ -66,8 +66,12 @@ class ResolvedAuthConnection:
     _MINIMUM_PYODPS = "0.12.0"
 
     def create_client(self):
+        from .enterprise_tls import configure_enterprise_tls_env
         from .odps_runtime import configure_user_agent
 
+        # requests resolves SSL_CERT_FILE when a Session is constructed, so
+        # this must run before ODPS builds its REST and tunnel clients.
+        configure_enterprise_tls_env()
         configure_user_agent()
         try:
             from odps import ODPS

maxc_cli-0.7.0/src/maxc_cli/backend/mcp.py

@@ -0,0 +1,320 @@
+"""MaxCompute Remote MCP access: token minting and a stateless JSON-RPC client.
+
+Two responsibilities live here, deliberately separated because they fail differently:
+
+``CatalogMcpTokenProvider``
+    Trades the caller's *already resolved* MaxCompute credentials for a short-lived
+    ``mcpc_`` bearer by issuing an authenticated CatalogAPI call. No browser, no OAuth
+    redirect, no refresh token: renewal means calling the mint endpoint again. Reference
+    implementation: ``remote_auth.py`` in aliyun/alibabacloud-maxcompute-mcp-server.
+
+``McpHttpClient``
+    Minimal Streamable-HTTP JSON-RPC client for ``tools/list`` and ``tools/call``. The
+    deployed server is stateless today (it returns no ``mcp-session-id``), so nothing here
+    caches a session; see ``docs/mcp-kb-access-research.md`` §6.2 before assuming that holds.
+
+Only stdlib HTTP is used, so this module adds no runtime dependency.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable
+
+# --- CatalogAPI token issuance ------------------------------------------------
+# Verified against the live service on 2026-09-20.
+
+_MCP_ACCESS_TOKEN_PATH = "/api/catalog/v1alpha/mcpAccessToken"
+_EXPECTED_SCOPES = ["maxcompute:read", "maxcompute:sql"]
+_TOKEN_LIFETIME_SECONDS = 300
+# Renew this long before real expiry so a request never starts on a doomed token.
+_EXPIRY_SKEW_SECONDS = 60.0
+_MAX_TOKEN_CHARS = 16 * 1024
+_TOKEN_PREFIX = "mcpc_"
+# Tea sends a bodyless stream as application/octet-stream and CatalogAPI signs the
+# received Content-Type into its canonical string. Declaring anything else here
+# produces a signature error that reads like an authentication failure.
+_EMPTY_BODY_CONTENT_TYPE = "application/octet-stream"
+_MINT_TIMEOUT_SECONDS = 10.0
+
+DEFAULT_PROTOCOL_VERSION = "2025-06-18"
+
+
+class McpError(RuntimeError):
+    """Base class for MCP access failures safe to show to a user."""
+
+
+class TokenUnavailableError(McpError):
+    """The bearer could not be minted, usually missing or unusable credentials."""
+
+
+class McpRequestError(McpError):
+    """The MCP endpoint rejected or failed a JSON-RPC call."""
+
+    def __init__(self, message: str, *, status: int | None = None,
+                 request_id: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.request_id = request_id
+
+
+def _strip_api_suffix(endpoint: str) -> str:
+    text = (endpoint or "").rstrip("/")
+    return text[: -len("/api")] if text.endswith("/api") else text
+
+
+class CatalogMcpTokenProvider:
+    """Mint and cache CatalogAPI MCP bearers, single-flighting renewals.
+
+    ``mint`` is injected rather than hard-wired so tests never touch the network and
+    so the signing path stays whatever pyodps already does correctly.
+    """
+
+    def __init__(
+        self,
+        mint: Callable[[], dict[str, Any]],
+        *,
+        expiry_skew: float = _EXPIRY_SKEW_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if not 0 <= expiry_skew < _TOKEN_LIFETIME_SECONDS:
+            raise ValueError("expiry skew must be within the token lifetime")
+        self._mint = mint
+        self._expiry_skew = expiry_skew
+        self._clock = clock
+        self._token = ""
+        self._expires_at = 0.0
+        self._lock = threading.Lock()
+
+    def get(self) -> str:
+        """Return a usable bearer, minting at most once for concurrent callers."""
+        with self._lock:
+            if self._token and self._clock() + self._expiry_skew < self._expires_at:
+                return self._token
+            value = self._parse(self._mint())
+            self._token = value
+            self._expires_at = self._clock() + _TOKEN_LIFETIME_SECONDS
+            return value
+
+    def invalidate(self) -> None:
+        """Drop the cached bearer so the next ``get`` re-mints."""
+        with self._lock:
+            self._token = ""
+            self._expires_at = 0.0
+
+    @staticmethod
+    def _parse(payload: Any) -> str:
+        """Validate every field the reference implementation asserts, then return the token.
+
+        Strictness is intentional: a silently different lifetime or scope would turn a
+        working call into an intermittent 401 that is expensive to diagnose from a CLI.
+        """
+        if not isinstance(payload, dict):
+            raise TokenUnavailableError("MCP token response was not a JSON object.")
+        missing = {"accessToken", "tokenType", "expiresIn", "scope"} - set(payload)
+        if missing:
+            raise TokenUnavailableError(
+                "MCP token response missing field(s): " + ", ".join(sorted(missing)) + "."
+            )
+        # A refresh token here means the service changed contract; caching one would
+        # imply a renewal path this provider deliberately does not have.
+        if any("refresh" in key.lower() for key in payload):
+            raise TokenUnavailableError(
+                "MCP token response carried a refresh token, which this client does not support."
+            )
+        value = payload.get("accessToken")
+        if (
+            not isinstance(value, str)
+            or not value.startswith(_TOKEN_PREFIX)
+            or len(value) <= len(_TOKEN_PREFIX)
+            or len(value) > _MAX_TOKEN_CHARS
+        ):
+            raise TokenUnavailableError("MCP token response carried an unexpected access token.")
+        if payload.get("tokenType") != "Bearer":
+            raise TokenUnavailableError("MCP token response carried an unexpected tokenType.")
+        expires_in = payload.get("expiresIn")
+        if isinstance(expires_in, bool) or expires_in != _TOKEN_LIFETIME_SECONDS:
+            raise TokenUnavailableError(
+                f"MCP token lifetime {expires_in!r} differs from the expected "
+                f"{_TOKEN_LIFETIME_SECONDS}s; caching assumptions would be invalid."
+            )
+        if payload.get("scope") != _EXPECTED_SCOPES:
+            raise TokenUnavailableError("MCP token response carried an unexpected scope.")
+        return value
+
+
+def build_catalog_mint(catalog_rest: Any, catalog_endpoint: str) -> Callable[[], dict[str, Any]]:
+    """Return a callable that mints a bearer through an authenticated Catalog rest client.
+
+    Reuses the same signed transport as catalog search, so whatever credential chain
+    ``auth whoami`` resolved is what authorizes the MCP call.
+    """
+    base = _strip_api_suffix(catalog_endpoint)
+    if not base.startswith(("https://", "http://")):
+        raise TokenUnavailableError("Catalog endpoint is not an HTTP(S) URL.")
+    url = base + _MCP_ACCESS_TOKEN_PATH
+
+    def mint() -> dict[str, Any]:
+        try:
+            response = catalog_rest.request(
+                url,
+                "post",
+                data=b"",
+                headers={"content-type": _EMPTY_BODY_CONTENT_TYPE},
+                timeout=_MINT_TIMEOUT_SECONDS,
+            )
+        except Exception as exc:  # noqa: BLE001 -- credential/transport SDK errors vary
+            raise TokenUnavailableError(
+                "Could not request an MCP access token from CatalogAPI. "
+                "Check that MaxCompute credentials resolve (try `maxc auth whoami --json`)."
+            ) from exc
+        body = getattr(response, "content", None)
+        if body is None:
+            reader = getattr(response, "read", None)
+            body = reader() if callable(reader) else response
+        if isinstance(body, bytes):
+            body = body.decode("utf-8", "replace")
+        if isinstance(body, dict):
+            # Some transports hand back an already-decoded mapping; re-encoding keeps
+            # the parse path single rather than branching twice.
+            return body
+        try:
+            return json.loads(body)
+        except (TypeError, ValueError) as exc:
+            raise TokenUnavailableError("CatalogAPI returned a non-JSON MCP token response.") from exc
+
+    return mint
+
+
+# --- Stateless JSON-RPC over Streamable HTTP ---------------------------------
+
+class McpHttpClient:
+    """Call MCP tools over Streamable HTTP without assuming a server session."""
+
+    def __init__(
+        self,
+        url: str,
+        token_provider: CatalogMcpTokenProvider,
+        *,
+        timeout: float = 120.0,
+        client_name: str = "maxc-cli",
+        client_version: str = "0",
+        opener: Any = None,
+    ) -> None:
+        if not url.startswith("https://"):
+            # The bearer is a credential; never send it over plaintext.
+            raise ValueError("MCP endpoint must be an https:// URL.")
+        self._url = url
+        self._tokens = token_provider
+        self._timeout = timeout
+        self._client = (client_name, client_version)
+        self._opener = opener or urllib.request.build_opener()
+        self._next_id = 0
+
+    @property
+    def url(self) -> str:
+        """The endpoint this client talks to, for surfacing in startup output."""
+        return self._url
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        result = self._request("tools/list", {})
+        tools = result.get("tools") if isinstance(result, dict) else None
+        return list(tools or [])
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """Invoke one tool, retrying exactly once after a token expiry."""
+        payload = {"name": name, "arguments": arguments}
+        try:
+            return self._request("tools/call", payload)
+        except McpRequestError as exc:
+            if exc.status != 401:
+                raise
+            # Observed behaviour: an expired bearer answers 401 "invalid token".
+            self._tokens.invalidate()
+            return self._request("tools/call", payload)
+
+    def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        self._next_id += 1
+        envelope = {"jsonrpc": "2.0", "id": self._next_id, "method": method, "params": params}
+        raw = self._post(json.dumps(envelope).encode("utf-8"))
+        decoded = self._decode(raw)
+        if "error" in decoded:
+            err = decoded["error"] or {}
+            raise McpRequestError(
+                f"MCP {method} failed: {err.get('message', 'unknown error')}",
+                request_id=str(err.get("code")) if err.get("code") is not None else None,
+            )
+        result = decoded.get("result")
+        if not isinstance(result, dict):
+            raise McpRequestError(f"MCP {method} returned no result object.")
+        return result
+
+    def _post(self, body: bytes, *, retry_on_expiry: bool = True) -> bytes:
+        token = self._tokens.get()
+        request = urllib.request.Request(self._url, data=body, method="POST")
+        request.add_header("Content-Type", "application/json")
+        # Streamable HTTP servers may answer either shape; accepting both keeps the
+        # client working if the gateway switches to event-stream responses.
+        request.add_header("Accept", "application/json, text/event-stream")
+        request.add_header("MCP-Protocol-Version", DEFAULT_PROTOCOL_VERSION)
+        request.add_header("Authorization", f"Bearer {token}")
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                return response.read()
+        except urllib.error.HTTPError as exc:
+            detail = b""
+            try:
+                detail = exc.read()
+            except Exception:  # noqa: BLE001 -- body is best-effort context only
+                pass
+            text = detail.decode("utf-8", "replace").strip()
+            if exc.code == 401:
+                raise McpRequestError(
+                    "MCP endpoint rejected the access token.", status=401
+                ) from exc
+            raise McpRequestError(
+                f"MCP endpoint returned HTTP {exc.code}" + (f": {text[:200]}" if text else ""),
+                status=exc.code,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise McpRequestError(f"Could not reach the MCP endpoint: {exc.reason}") from exc
+
+    @staticmethod
+    def _decode(raw: bytes) -> dict[str, Any]:
+        """Accept plain JSON or an SSE body carrying a single JSON data frame."""
+        text = (raw or b"").decode("utf-8", "replace").strip()
+        if not text:
+            raise McpRequestError("MCP endpoint returned an empty response body.")
+        if not text.lstrip().startswith("{"):
+            frames = [
+                line[len("data:"):].strip()
+                for line in text.splitlines()
+                if line.startswith("data:")
+            ]
+            for frame in reversed(frames):
+                if frame and frame != "[DONE]":
+                    text = frame
+                    break
+        try:
+            decoded = json.loads(text)
+        except ValueError as exc:
+            raise McpRequestError("MCP endpoint returned a non-JSON response.") from exc
+        if not isinstance(decoded, dict):
+            raise McpRequestError("MCP endpoint returned an unexpected response shape.")
+        return decoded
+
+
+def default_endpoint(region: str | None, *, site: str = "CN") -> str:
+    """Build the public MCP host for a region, falling back to dynamic routing."""
+    if not region:
+        host = "mcp.maxcompute.aliyun.com" if site.upper() != "INTL" else "mcp-intl.maxcompute.aliyun.com"
+        return f"https://{host}/mcp"
+    cleaned = str(region).strip().lower()
+    if not cleaned.replace("-", "").isalnum():
+        raise ValueError("region must be an alphanumeric region id")
+    prefix = "mcp" if site.upper() != "INTL" else "mcp-intl"
+    return f"https://{prefix}.{cleaned}.maxcompute.aliyun.com/mcp"