mcp2cli 3.4.0__tar.gz → 3.6.0__tar.gz

mcp2cli-3.4.0/README.md → mcp2cli-3.6.0/PKG-INFO

@@ -1,3 +1,22 @@
+Metadata-Version: 2.4
+Name: mcp2cli
+Version: 3.6.0
+Summary: Turn any MCP server or OpenAPI spec into a CLI
+Author: Stephan Fitzpatrick
+Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
+License-Expression: MIT
+Requires-Dist: httpx
+Requires-Dist: mcp>=1.26,<3
+Requires-Dist: pyyaml
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pytest-asyncio ; extra == 'test'
+Requires-Dist: tiktoken ; extra == 'test'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/knowsuchagency/mcp2cli
+Project-URL: Repository, https://github.com/knowsuchagency/mcp2cli
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/knowsuchagency/mcp2cli/main/assets/hero.png" alt="mcp2cli — one CLI for every API" width="700">
 </p>
@@ -364,13 +383,27 @@ Subcommands and their flags are generated dynamically from the spec or MCP serve
 # Install with test + MCP deps
 uv sync --extra test
 
-# Run tests (96 tests covering OpenAPI, MCP stdio, MCP HTTP, caching, and token savings)
+# Run tests
 uv run pytest tests/ -v
 
 # Run just the token savings tests
 uv run pytest tests/test_token_savings.py -v -s
 ```
 
+### MCP SDK compatibility
+
+mcp2cli works with **both major versions** of the MCP Python SDK (`mcp>=1.26,<3`),
+so it never forces a resolver conflict with other tools in the same environment.
+CI runs the suite against the declared floor, the latest 1.x, and the latest 2.x.
+
+The two majors differ in ways that matter to a client — v2 renamed model fields
+to snake_case, replaced `streamablehttp_client`, moved to `httpx2`, and dropped
+the session-id element from the transport tuple. Those differences are confined
+to a handful of helpers (`_mcp_attr`, `_mcp_dump`, `_streamable_streams`,
+`_list_tools_page`, `_resource_uri`, `_authorization_code_result`); the rest of
+the codebase is version-agnostic. The test fixtures speak the JSON-RPC wire
+protocol directly and import no SDK, so they hold across majors.
+
 ---
 
 ## License

mcp2cli-3.4.0/PKG-INFO → mcp2cli-3.6.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: mcp2cli
-Version: 3.4.0
-Summary: Turn any MCP server or OpenAPI spec into a CLI
-Author: Stephan Fitzpatrick
-Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
-License-Expression: MIT
-Requires-Dist: httpx
-Requires-Dist: mcp>=1.0,<2
-Requires-Dist: pyyaml
-Requires-Dist: pytest ; extra == 'test'
-Requires-Dist: pytest-asyncio ; extra == 'test'
-Requires-Dist: tiktoken ; extra == 'test'
-Requires-Python: >=3.10
-Project-URL: Homepage, https://github.com/knowsuchagency/mcp2cli
-Project-URL: Repository, https://github.com/knowsuchagency/mcp2cli
-Provides-Extra: test
-Description-Content-Type: text/markdown
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/knowsuchagency/mcp2cli/main/assets/hero.png" alt="mcp2cli — one CLI for every API" width="700">
 </p>
@@ -383,13 +364,27 @@ Subcommands and their flags are generated dynamically from the spec or MCP serve
 # Install with test + MCP deps
 uv sync --extra test
 
-# Run tests (96 tests covering OpenAPI, MCP stdio, MCP HTTP, caching, and token savings)
+# Run tests
 uv run pytest tests/ -v
 
 # Run just the token savings tests
 uv run pytest tests/test_token_savings.py -v -s
 ```
 
+### MCP SDK compatibility
+
+mcp2cli works with **both major versions** of the MCP Python SDK (`mcp>=1.26,<3`),
+so it never forces a resolver conflict with other tools in the same environment.
+CI runs the suite against the declared floor, the latest 1.x, and the latest 2.x.
+
+The two majors differ in ways that matter to a client — v2 renamed model fields
+to snake_case, replaced `streamablehttp_client`, moved to `httpx2`, and dropped
+the session-id element from the transport tuple. Those differences are confined
+to a handful of helpers (`_mcp_attr`, `_mcp_dump`, `_streamable_streams`,
+`_list_tools_page`, `_resource_uri`, `_authorization_code_result`); the rest of
+the codebase is version-agnostic. The test fixtures speak the JSON-RPC wire
+protocol directly and import no SDK, so they hold across majors.
+
 ---
 
 ## License

{mcp2cli-3.4.0 → mcp2cli-3.6.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mcp2cli"
-version = "3.4.0"
+version = "3.6.0"
 description = "Turn any MCP server or OpenAPI spec into a CLI"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
 dependencies = [
     "httpx",
-    "mcp>=1.0,<2",
+    "mcp>=1.26,<3",
     "pyyaml",
 ]
 

{mcp2cli-3.4.0 → mcp2cli-3.6.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "mcp2cli"
-version = "3.4.0"
+version = "3.6.0"
 description = "Turn any MCP server or OpenAPI spec into a CLI"
 readme = "README.md"
 license = "MIT"
@@ -10,7 +10,9 @@ authors = [
 requires-python = ">=3.10"
 dependencies = [
     "httpx",
-    "mcp>=1.0,<2",
+    # Works on both SDK majors; 1.26 is the floor we verify in CI, and the one
+    # where `streamable_http_client` + `create_mcp_http_client` are both present.
+    "mcp>=1.26,<3",
     "pyyaml",
 ]
 

{mcp2cli-3.4.0 → mcp2cli-3.6.0}/src/mcp2cli/__init__.py

@@ -23,6 +23,7 @@ import sys
 import threading
 import time
 import webbrowser
+from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from http.server import HTTPServer, BaseHTTPRequestHandler
 from pathlib import Path
@@ -60,6 +61,7 @@ class ParamDef:
     choices: list | None = None
     location: str = "body"  # path|query|header|body|tool_input
     schema: dict = field(default_factory=dict)
+    cli_name: str | None = None  # collision-free argparse flag name
 
 
 @dataclass
@@ -177,8 +179,17 @@ def read_stdin_json(context: str):
         sys.exit(1)
 
 
+def _normalize_schema_type(t):
+    """JSON Schema allows "type": ["integer", "null"] (array form). Reduce it
+    to the single concrete type, dropping "null"; anything else passes through."""
+    if isinstance(t, list):
+        concrete = [x for x in t if x != "null"]
+        return concrete[0] if len(concrete) == 1 else None
+    return t
+
+
 def schema_type_to_python(schema: dict) -> tuple[type | None, str]:
-    t = schema.get("type")
+    t = _normalize_schema_type(schema.get("type"))
     if t == "integer":
         return int, ""
     if t == "number":
@@ -189,6 +200,16 @@ def schema_type_to_python(schema: dict) -> tuple[type | None, str]:
         return str, " (JSON array)"
     if t == "object":
         return str, " (JSON object)"
+    if t is None:
+        # No "type" but an enum: infer the argparse type from the values, so
+        # numeric enums stay callable (otherwise argparse parses the flag as a
+        # string and rejects it against numeric choices).
+        enum = schema.get("enum")
+        if enum and not any(isinstance(v, bool) for v in enum):
+            if all(isinstance(v, int) for v in enum):
+                return int, ""
+            if all(isinstance(v, (int, float)) for v in enum):
+                return float, ""
     return str, ""
 
 
@@ -206,7 +227,7 @@ def _coerce_item(value: str, item_type: str | None):
 def coerce_value(value, schema: dict):
     if value is None:
         return None
-    t = schema.get("type")
+    t = _normalize_schema_type(schema.get("type"))
     if t == "array":
         if isinstance(value, list):
             return value
@@ -217,7 +238,7 @@ def coerce_value(value, schema: dict):
                     return parsed
             except (json.JSONDecodeError, TypeError):
                 pass
-            item_type = schema.get("items", {}).get("type")
+            item_type = _normalize_schema_type(schema.get("items", {}).get("type"))
             if "," in value:
                 return [_coerce_item(v.strip(), item_type) for v in value.split(",")]
             return [_coerce_item(value, item_type)]
@@ -251,13 +272,16 @@ def to_kebab(name: str) -> str:
     return s.replace("_", "-").lower()
 
 
-def _find_toon_cli() -> str | None:
-    """Return the command to invoke the TOON CLI, or None if unavailable."""
+def _find_toon_cli() -> tuple[str, ...] | None:
+    """Return argv for the TOON CLI, or None if unavailable."""
     if shutil.which("toon"):
-        return "toon"
-    # Check for npx (ships with Node.js)
+        return ("toon",)
+    # npx ships with Node.js, but having it says nothing about the package.
+    # `--no` forbids npx's implicit registry download, so a missing package
+    # fails in about a second instead of turning --toon into a network fetch
+    # racing the timeout in _toon_encode.
     if shutil.which("npx"):
-        return "npx @toon-format/cli"
+        return ("npx", "--no", "@toon-format/cli")
     return None
 
 
@@ -268,7 +292,7 @@ def _toon_encode(json_str: str) -> str | None:
         return None
     try:
         result = subprocess.run(
-            cmd.split(),
+            cmd,
             input=json_str,
             capture_output=True,
             text=True,
@@ -281,6 +305,125 @@ def _toon_encode(json_str: str) -> str | None:
     return None
 
 
+# ---------------------------------------------------------------------------
+# MCP SDK compatibility (v1 and v2)
+# ---------------------------------------------------------------------------
+
+# SDK 2.0 renamed model fields from camelCase to snake_case, keeping camelCase
+# only as serialization aliases -- so attribute access has to use the new name
+# while the wire format is unchanged. A name missing from this map is an
+# unhandled rename and raises KeyError rather than silently reading None.
+_MCP_RENAMED_FIELDS = {
+    "inputSchema": "input_schema",
+    "outputSchema": "output_schema",
+    "nextCursor": "next_cursor",
+    "resourceTemplates": "resource_templates",
+    "uriTemplate": "uri_template",
+    "mimeType": "mime_type",
+    "structuredContent": "structured_content",
+    "isError": "is_error",
+}
+
+
+def _mcp_attr(obj, name: str):
+    """Read an SDK model field across the v1/v2 camelCase -> snake_case rename."""
+    try:
+        return getattr(obj, name)
+    except AttributeError:
+        return getattr(obj, _MCP_RENAMED_FIELDS[name])
+
+
+def _demote_meta_alias(node: dict) -> None:
+    """Emit the SDK's ``_meta`` alias as ``meta``, the spelling mcp2cli ships."""
+    if "_meta" in node:
+        node["meta"] = node.pop("_meta")
+
+
+def _mcp_dump(model) -> dict:
+    """Serialize an SDK model using the camelCase wire names on either major.
+
+    v2 renamed model attributes to snake_case, so a plain ``model_dump()``
+    would silently change mcp2cli's ``--json`` envelope from ``isError`` to
+    ``is_error`` depending on which SDK happened to be installed. ``by_alias``
+    pins the wire spelling on both.
+
+    ``meta`` is aliased to ``_meta`` in both majors, and mcp2cli has always
+    emitted it as ``meta``, so it is mapped back -- but only on the envelope
+    and its content items, which the SDK owns. ``structuredContent`` is the
+    tool's own payload and is never rewritten, so a tool that legitimately
+    returns a ``_meta`` key keeps it.
+    """
+    data = model.model_dump(mode="json", by_alias=True)
+    _demote_meta_alias(data)
+    for item in data.get("content") or ():
+        if isinstance(item, dict):
+            _demote_meta_alias(item)
+    return data
+
+
+def _resource_uri(uri: str):
+    """Coerce a resource URI to what ``resources/read`` expects.
+
+    v1 types the request param as a pydantic ``AnyUrl``; v2 takes a plain
+    string and rejects an ``AnyUrl``.
+    """
+    from mcp.types import ReadResourceRequestParams
+
+    if ReadResourceRequestParams.model_fields["uri"].annotation is str:
+        return uri
+    from pydantic import AnyUrl
+
+    return AnyUrl(uri)
+
+
+@asynccontextmanager
+async def _streamable_streams(url: str, headers=None, auth=None):
+    """Open a streamable-http transport, yielding ``(read, write)``.
+
+    Three things differ across SDK majors here, which is why this is the only
+    place that talks to that transport (issues #68, #74):
+
+    * v2 dropped the ``streamablehttp_client`` alias, keeping only
+      ``streamable_http_client`` -- the original break.
+    * that surviving function takes a pre-built ``http_client`` instead of
+      ``headers``/``auth``, and v2 is built on **httpx2**, not httpx, so the
+      client has to come from the SDK's own factory to be the right flavour.
+    * v1 yields a third element (a get-session-id callback) that v2 dropped.
+      mcp2cli never used it, so both shapes collapse to ``(read, write)``.
+    """
+    from mcp.client.streamable_http import streamable_http_client
+    from mcp.shared._httpx_utils import create_mcp_http_client
+
+    async with create_mcp_http_client(headers=headers, auth=auth) as client:
+        async with streamable_http_client(url, http_client=client) as streams:
+            yield streams[0], streams[1]
+
+
+async def _list_tools_page(session, cursor: str | None):
+    """Request one page of ``tools/list``.
+
+    Both majors accept ``params``; v1's ``cursor=`` shorthand is deprecated
+    there and gone in v2, so this is the one spelling that works on both.
+    """
+    from mcp.types import PaginatedRequestParams
+
+    params = PaginatedRequestParams(cursor=cursor) if cursor else None
+    return await session.list_tools(params=params)
+
+
+def _authorization_code_result(code: str, state: str | None):
+    """Wrap a callback result in whatever ``callback_handler`` must return.
+
+    v1 expects a plain ``(code, state)`` tuple; v2 expects an
+    ``AuthorizationCodeResult`` model.
+    """
+    try:
+        from mcp.shared.auth import AuthorizationCodeResult
+    except ImportError:
+        return (code, state)
+    return AuthorizationCodeResult(code=code, state=state)
+
+
 def _ensure_utf8_output() -> None:
     """Make non-ASCII output safe on consoles that cannot encode it.
 
@@ -379,9 +522,34 @@ def _python_type_name(t: type | None) -> str:
     return getattr(t, "__name__", str(t))
 
 
+def _param_dest(p: "ParamDef") -> str:
+    """Return the argparse destination allocated for a parameter."""
+    return (p.cli_name or p.name).replace("-", "_")
+
+
+def _allocate_param_cli_names(cmd: "CommandDef") -> None:
+    """Assign unique parameter flags without shadowing built-in options."""
+    natural_names = {p.name for p in cmd.params}
+    used = {"help"}
+    if cmd.has_body:
+        used.add("stdin")
+
+    for p in cmd.params:
+        name = p.name
+        if name in used:
+            stem = f"arg-{name}"
+            name = stem
+            suffix = 2
+            while name in used or name in natural_names:
+                name = f"{stem}-{suffix}"
+                suffix += 1
+        p.cli_name = name
+        used.add(name)
+
+
 def _param_to_dict(p: "ParamDef") -> dict:
     d = {
-        "name": p.name,
+        "name": p.cli_name or p.name,
         "type": _python_type_name(p.python_type),
         "required": p.required,
         "description": p.description,
@@ -877,12 +1045,21 @@ def build_oauth_provider(
                 await super()._initialize()
                 _restore_token_expiry_from_sidecar(self.context)
 
+        # v2 renamed the `scopes` argument to `scope`.
+        import inspect
+
+        scope_kwarg = (
+            "scope"
+            if "scope"
+            in inspect.signature(ClientCredentialsOAuthProvider.__init__).parameters
+            else "scopes"
+        )
         return _RobustClientCredentialsProvider(
             server_url=server_url,
             storage=storage,
             client_id=client_id,
             client_secret=client_secret,
-            scopes=scope,
+            **{scope_kwarg: scope},
         )
 
     from mcp.client.auth.oauth2 import OAuthClientProvider
@@ -1105,8 +1282,9 @@ def build_oauth_provider(
                 file=sys.stderr,
             )
 
-        async def callback_handler() -> tuple[str, str | None]:
-            return await anyio.to_thread.run_sync(_prompt_oauth_callback)
+        async def callback_handler():
+            code, state = await anyio.to_thread.run_sync(_prompt_oauth_callback)
+            return _authorization_code_result(code, state)
     else:
         # Reset callback handler state
         _CallbackHandler.auth_code = None
@@ -1129,7 +1307,7 @@ def build_oauth_provider(
             print(f"If browser doesn't open, visit: {auth_url}", file=sys.stderr)
             webbrowser.open(auth_url)
 
-        async def callback_handler() -> tuple[str, str | None]:
+        async def callback_handler():
             # Run the HTTP server in a thread, wait for the callback
             thread = threading.Thread(target=server.handle_request, daemon=True)
             thread.start()
@@ -1142,7 +1320,9 @@ def build_oauth_provider(
                 raise RuntimeError(f"OAuth error: {_CallbackHandler.error}")
             if not _CallbackHandler.auth_code:
                 raise RuntimeError("No authorization code received")
-            return (_CallbackHandler.auth_code, _CallbackHandler.state)
+            return _authorization_code_result(
+                _CallbackHandler.auth_code, _CallbackHandler.state
+            )
 
     return _RobustOAuthClientProvider(
         server_url=server_url,
@@ -1362,8 +1542,34 @@ def extract_openapi_commands(spec: dict) -> list[CommandDef]:
 
 def extract_mcp_commands(tools: list[dict]) -> list[CommandDef]:
     commands: list[CommandDef] = []
-    for tool in tools:
-        name = to_kebab(tool.get("name", "unknown"))
+    base_names = [to_kebab(tool.get("name", "unknown")) for tool in tools]
+    reserved_names = set(base_names)
+    cli_names = [""] * len(tools)
+    used_names: set[str] = set()
+    groups: dict[str, list[int]] = {}
+    for index, base_name in enumerate(base_names):
+        groups.setdefault(base_name, []).append(index)
+
+    # Assign aliases from the complete tool-name set so a generated suffix can
+    # never shadow another tool's natural name. Sorting each collision group by
+    # wire name keeps aliases stable when a server reorders tools/list.
+    for base_name in sorted(groups):
+        indices = sorted(
+            groups[base_name],
+            key=lambda index: (tools[index].get("name", "unknown"), index),
+        )
+        for rank, index in enumerate(indices):
+            name = base_name
+            if rank:
+                suffix = 2
+                name = f"{base_name}-{suffix}"
+                while name in reserved_names or name in used_names:
+                    suffix += 1
+                    name = f"{base_name}-{suffix}"
+            cli_names[index] = name
+            used_names.add(name)
+
+    for tool, name in zip(tools, cli_names):
         desc = tool.get("description", "")
         schema = tool.get("inputSchema", {})
         required_fields = set(schema.get("required", []))
@@ -1802,12 +2008,12 @@ def _build_graphql_document(
     types_by_name = {t["name"]: t for t in schema.get("types", []) if t.get("name")}
 
     # Build variables dict from args
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         variables = read_stdin_json("GraphQL variables")
     else:
         variables = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 variables[p.original_name] = coerce_value(val, p.schema)
 
@@ -2341,6 +2547,7 @@ def build_argparse(
             help=escape_argparse_help(cmd.description),
             description=escape_argparse_help(cmd.description),
         )
+        _allocate_param_cli_names(cmd)
         sub.set_defaults(_cmd=cmd)
 
         if cmd.has_body:
@@ -2351,12 +2558,8 @@ def build_argparse(
                 help="Read JSON body/arguments from stdin",
             )
 
-        seen_flags: set[str] = set()
         for p in cmd.params:
-            flag = f"--{p.name}"
-            if flag in seen_flags:
-                continue  # skip duplicate param names (e.g. path + body both have same name)
-            seen_flags.add(flag)
+            flag = f"--{p.cli_name or p.name}"
             kwargs: dict = {}
             if p.python_type is not None:
                 kwargs["type"] = p.python_type
@@ -2374,6 +2577,7 @@ def build_argparse(
             kwargs["help"] = escape_argparse_help(p.description)
             if p.choices:
                 kwargs["choices"] = p.choices
+            kwargs["dest"] = _param_dest(p)
             sub.add_argument(flag, **kwargs)
 
     return parser
@@ -2502,13 +2706,13 @@ def _collect_openapi_params(
 
     for p in cmd.params:
         if p.location == "path":
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 path = path.replace(f"{{{p.original_name}}}", str(val))
 
     if cmd.method == "get":
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is None:
                 continue
             if p.location == "query":
@@ -2516,12 +2720,12 @@ def _collect_openapi_params(
             elif p.location == "header":
                 extra_headers[p.original_name] = str(val)
     else:
-        if getattr(args, "stdin", False):
+        if getattr(args, "stdin", False) is True:
             body = read_stdin_json("OpenAPI request body")
         else:
             body = {}
             for p in cmd.params:
-                val = getattr(args, p.name.replace("-", "_"), None)
+                val = getattr(args, _param_dest(p), None)
                 if p.location == "header":
                     if val is not None:
                         extra_headers[p.original_name] = str(val)
@@ -2546,7 +2750,7 @@ def _collect_openapi_params(
         # Also collect query params for non-GET
         for p in cmd.params:
             if p.location == "query":
-                val = getattr(args, p.name.replace("-", "_"), None)
+                val = getattr(args, _param_dest(p), None)
                 if val is not None:
                     query_params[p.original_name] = coerce_value(val, p.schema)
 
@@ -2631,6 +2835,55 @@ def execute_openapi(
 # ---------------------------------------------------------------------------
 
 
+def _exc_leaves(exc: BaseException) -> list[BaseException]:
+    """Flatten nested exception groups into their leaf exceptions."""
+    nested = getattr(exc, "exceptions", None)
+    if not nested:
+        return [exc]
+    return [leaf for child in nested for leaf in _exc_leaves(child)]
+
+
+def _exc_message(exc: BaseException) -> str:
+    """Flatten an exception group into one terminal-safe line."""
+    parts = []
+    for leaf in _exc_leaves(exc):
+        message = str(leaf) or leaf.__class__.__name__
+        parts.append("; ".join(line.strip() for line in message.splitlines() if line.strip()))
+    return "; ".join(part for part in parts if part) or exc.__class__.__name__
+
+
+def _run_mcp_clean(fn, source: str):
+    """Run an MCP coroutine, reporting failures as one clean error line.
+
+    Transport failures (bad URL, refused connection, 401/403) otherwise reach
+    the terminal as a multi-level anyio ExceptionGroup traceback with the
+    actual cause buried at the bottom. Set MCP2CLI_DEBUG=1 for the traceback.
+    """
+    try:
+        return anyio.run(fn)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        raise
+    except BaseException as exc:
+        leaves = _exc_leaves(exc)
+        if len(leaves) == 1 and isinstance(leaves[0], (SystemExit, KeyboardInterrupt)):
+            raise leaves[0]
+        if os.environ.get("MCP2CLI_DEBUG"):
+            raise
+        message = _exc_message(exc)
+        lowered = message.lower()
+        if "401" in lowered or "403" in lowered:
+            hint = (
+                " — the server rejected the request; pass credentials with "
+                "--auth-header 'Name:Value' or use the --oauth-* options"
+            )
+        else:
+            hint = ""
+        print(f"Error: cannot use MCP server at {source}: {message}{hint}", file=sys.stderr)
+        sys.exit(1)
+
+
 def run_mcp_http(
     url: str,
     auth_headers: list[tuple[str, str]],
@@ -2681,11 +2934,9 @@ def run_mcp_http(
         headers = dict(auth_headers) if auth_headers else None
 
         async def _with_streamable():
-            from mcp.client.streamable_http import streamablehttp_client
-
-            async with streamablehttp_client(
+            async with _streamable_streams(
                 url, headers=headers, auth=oauth_provider
-            ) as (read, write, _):
+            ) as (read, write):
                 async with ClientSession(read, write) as session:
                     await session.initialize()
                     return await _mcp_session(
@@ -2735,7 +2986,9 @@ def run_mcp_http(
             except Exception:
                 return await _with_sse()
 
-    anyio.run(_run)
+    rc = _run_mcp_clean(_run, url)
+    if rc:
+        sys.exit(rc)
 
 
 def run_mcp_stdio(
@@ -2793,7 +3046,7 @@ def run_mcp_stdio(
         async with stdio_client(params) as (read, write):
             async with ClientSession(read, write) as session:
                 await session.initialize()
-                await _mcp_session(
+                return await _mcp_session(
                     session,
                     tool_name,
                     arguments,
@@ -2807,7 +3060,9 @@ def run_mcp_stdio(
                     **extra,
                 )
 
-    anyio.run(_run)
+    rc = _run_mcp_clean(_run, command_str)
+    if rc:
+        sys.exit(rc)
 
 
 async def _mcp_session(
@@ -2863,7 +3118,7 @@ async def _mcp_session(
             {
                 "name": t.name,
                 "description": t.description or "",
-                "inputSchema": t.inputSchema or {},
+                "inputSchema": _mcp_attr(t, "inputSchema") or {},
             }
             for t in all_tools
         ]
@@ -2895,12 +3150,29 @@ async def _mcp_session(
 
     if json_output:
         # Emit the full MCP CallToolResult envelope (content, structuredContent,
-        # isError) using the SDK's own serializer — 100% MCP-compatible.
-        output_result(result.model_dump(mode="json"), pretty=pretty, head=head, json_output=True)
-        return
+        # isError) with the camelCase wire names, so the envelope does not
+        # change shape with the installed SDK major.
+        output_result(_mcp_dump(result), pretty=pretty, head=head, json_output=True)
+        # A failed tool still exits non-zero under --json so callers can detect
+        # it; the envelope on stdout already carries isError for machines.
+        return 1 if _mcp_attr(result, "isError") else 0
 
     text = _extract_content_parts(result.content)
-    output_result(text, pretty=pretty, raw=raw, toon=toon, head=head)
+    payload = text
+    if not payload:
+        # A tool may return only structuredContent with an empty content list.
+        structured = _mcp_attr(result, "structuredContent")
+        if structured is not None:
+            payload = structured
+
+    if _mcp_attr(result, "isError"):
+        # Return the code instead of raising inside the anyio task group, which
+        # would wrap SystemExit in a BaseExceptionGroup traceback.
+        error = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False)
+        print(f"Error: {error or f'tool {tool_name!r} reported an error'}", file=sys.stderr)
+        return 1
+    output_result(payload, pretty=pretty, raw=raw, toon=toon, head=head)
+    return 0
 
 
 # ---------------------------------------------------------------------------
@@ -2926,7 +3198,7 @@ async def _handle_resources(
                 "name": r.name,
                 "uri": str(r.uri),
                 "description": r.description or "",
-                "mimeType": r.mimeType or "",
+                "mimeType": _mcp_attr(r, "mimeType") or "",
             }
             for r in result.resources
         ]
@@ -2936,17 +3208,15 @@ async def _handle_resources(
         data = [
             {
                 "name": t.name,
-                "uriTemplate": str(t.uriTemplate),
+                "uriTemplate": str(_mcp_attr(t, "uriTemplate")),
                 "description": t.description or "",
-                "mimeType": t.mimeType or "",
+                "mimeType": _mcp_attr(t, "mimeType") or "",
             }
-            for t in result.resourceTemplates
+            for t in _mcp_attr(result, "resourceTemplates")
         ]
         output_result(data, **_out)
     elif action == "read":
-        from pydantic import AnyUrl
-
-        result = await session.read_resource(AnyUrl(uri))
+        result = await session.read_resource(_resource_uri(uri))
         parts = []
         for content in result.contents:
             if hasattr(content, "text"):
@@ -3001,7 +3271,7 @@ async def _handle_prompts(
                 messages.append({"role": msg.role, "content": content.text})
             else:
                 messages.append(
-                    {"role": msg.role, "content": json.dumps(content.model_dump())}
+                    {"role": msg.role, "content": json.dumps(_mcp_dump(content))}
                 )
         data = {"description": result.description or "", "messages": messages}
         output_result(data, **_out)
@@ -3151,13 +3421,25 @@ def session_start(
 
 
 def _extract_content_parts(content_list, *, attrs=("text", "data")) -> str:
-    """Extract text/data/blob from MCP content objects, joined by newline."""
+    """Extract text/data/blob from MCP content objects, joined by newline.
+
+    ``resource_link`` blocks carry neither ``text`` nor ``data`` — only
+    ``uri``/``name`` — so they used to be dropped silently. Render them as
+    ``name: uri`` (or just the URI) instead.
+    """
     parts = []
-    for c in content_list:
+    for content in content_list:
+        is_mapping = isinstance(content, dict)
         for attr in attrs:
-            if hasattr(c, attr):
-                parts.append(getattr(c, attr))
+            value = content.get(attr) if is_mapping else getattr(content, attr, None)
+            if value is not None:
+                parts.append(value)
                 break
+        else:
+            uri = content.get("uri") if is_mapping else getattr(content, "uri", None)
+            if uri is not None:
+                name = content.get("name") if is_mapping else getattr(content, "name", None)
+                parts.append(f"{name}: {uri}" if name else str(uri))
     return "\n".join(parts) if parts else ""
 
 
@@ -3170,9 +3452,9 @@ async def _list_all_tools(session):
     tools = []
     cursor = None
     while True:
-        result = await session.list_tools(cursor=cursor)
+        result = await _list_tools_page(session, cursor)
         tools.extend(result.tools)
-        cursor = result.nextCursor
+        cursor = _mcp_attr(result, "nextCursor")
         if not cursor:
             return tools
 
@@ -3180,36 +3462,48 @@ async def _list_all_tools(session):
 async def _dispatch_list_tools(session, params):
     tools = await _list_all_tools(session)
     return [
-        {"name": t.name, "description": t.description or "", "inputSchema": t.inputSchema or {}}
+        {
+            "name": t.name,
+            "description": t.description or "",
+            "inputSchema": _mcp_attr(t, "inputSchema") or {},
+        }
         for t in tools
     ]
 
 
 async def _dispatch_call_tool(session, params):
     result = await session.call_tool(params["name"], params.get("arguments", {}))
-    return _extract_content_parts(result.content)
+    return _mcp_dump(result)
 
 
 async def _dispatch_list_resources(session, params):
     result = await session.list_resources()
     return [
-        {"name": r.name, "uri": str(r.uri), "description": r.description or "", "mimeType": r.mimeType or ""}
+        {
+            "name": r.name,
+            "uri": str(r.uri),
+            "description": r.description or "",
+            "mimeType": _mcp_attr(r, "mimeType") or "",
+        }
         for r in result.resources
     ]
 
 
 async def _dispatch_read_resource(session, params):
-    from pydantic import AnyUrl
-
-    result = await session.read_resource(AnyUrl(params["uri"]))
+    result = await session.read_resource(_resource_uri(params["uri"]))
     return _extract_content_parts(result.contents, attrs=("text", "blob"))
 
 
 async def _dispatch_list_resource_templates(session, params):
     result = await session.list_resource_templates()
     return [
-        {"name": t.name, "uriTemplate": str(t.uriTemplate), "description": t.description or "", "mimeType": t.mimeType or ""}
-        for t in result.resourceTemplates
+        {
+            "name": t.name,
+            "uriTemplate": str(_mcp_attr(t, "uriTemplate")),
+            "description": t.description or "",
+            "mimeType": _mcp_attr(t, "mimeType") or "",
+        }
+        for t in _mcp_attr(result, "resourceTemplates")
     ]
 
 
@@ -3236,7 +3530,9 @@ async def _dispatch_get_prompt(session, params):
         if hasattr(content, "text"):
             messages.append({"role": msg.role, "content": content.text})
         else:
-            messages.append({"role": msg.role, "content": json.dumps(content.model_dump())})
+            messages.append(
+                {"role": msg.role, "content": json.dumps(_mcp_dump(content))}
+            )
     return {"description": result.description or "", "messages": messages}
 
 
@@ -3386,12 +3682,9 @@ def _run_session_daemon(config_json: str):
             headers = dict(auth_headers) if auth_headers else None
 
             async def _via_streamable():
-                from mcp.client.streamable_http import streamablehttp_client
-
-                async with streamablehttp_client(source, headers=headers) as (
+                async with _streamable_streams(source, headers=headers) as (
                     read,
                     write,
-                    _,
                 ):
                     async with ClientSession(read, write) as session:
                         await _run_with_session(session)
@@ -3632,12 +3925,12 @@ def handle_mcp(
 
     cmd: CommandDef = args._cmd
 
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         arguments = read_stdin_json("MCP tool arguments")
     else:
         arguments = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 arguments[p.original_name] = coerce_value(val, p.schema)
 
@@ -3668,7 +3961,7 @@ def _fetch_mcp_tools(
             {
                 "name": t.name,
                 "description": t.description or "",
-                "inputSchema": t.inputSchema or {},
+                "inputSchema": _mcp_attr(t, "inputSchema") or {},
             }
             for t in all_tools
         )
@@ -3693,11 +3986,9 @@ def _fetch_mcp_tools(
             headers = dict(auth_headers) if auth_headers else None
 
             async def _via_streamable():
-                from mcp.client.streamable_http import streamablehttp_client
-
-                async with streamablehttp_client(
+                async with _streamable_streams(
                     source, headers=headers, auth=oauth_provider
-                ) as (read, write, _):
+                ) as (read, write):
                     async with ClientSession(read, write) as session:
                         await session.initialize()
                         await _extract_tools(session)
@@ -3723,7 +4014,7 @@ def _fetch_mcp_tools(
                 except Exception:
                     await _via_sse()
 
-    anyio.run(_run)
+    _run_mcp_clean(_run, source)
     return tools_result
 
 
@@ -4228,18 +4519,41 @@ def _handle_session_operations(
         sys.exit(1)
 
     cmd: CommandDef = args._cmd
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         arguments = read_stdin_json(f"session {sess_name} tool arguments")
     else:
         arguments = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 arguments[p.original_name] = coerce_value(val, p.schema)
 
     result = _session_request(
         sess_name, "call_tool", {"name": cmd.tool_name, "arguments": arguments}
     )
+    if isinstance(result, dict) and "isError" in result:
+        content = result.get("content") or []
+        text = _extract_content_parts(content) if isinstance(content, list) else content
+        payload = text or result.get("structuredContent") or ""
+
+        if pre_args.json_output:
+            output_result(result, **_sess_out)
+            if result.get("isError"):
+                sys.exit(1)
+            return True
+
+        if result.get("isError"):
+            error = (
+                payload
+                if isinstance(payload, str)
+                else json.dumps(payload, ensure_ascii=False)
+            )
+            print(
+                f"Error: {error or f'tool {cmd.tool_name!r} reported an error'}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        result = payload
     output_result(result, **_sess_out)
     return True