mcp2cli 3.3.1__tar.gz → 3.5.0__tar.gz

{mcp2cli-3.3.1 → mcp2cli-3.5.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 3.3.1
+Version: 3.5.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
+Requires-Dist: mcp>=1.26,<3
 Requires-Dist: pyyaml
 Requires-Dist: pytest ; extra == 'test'
 Requires-Dist: pytest-asyncio ; extra == 'test'
@@ -102,6 +102,22 @@ mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list
 Tokens are persisted in `~/.cache/mcp2cli/oauth/` so subsequent calls reuse existing tokens
 and refresh automatically when they expire.
 
+#### Headless hosts — no browser on the machine running mcp2cli
+
+The default authorization-code flow starts a callback server on `127.0.0.1`, which only
+works when the browser runs on the same machine. On a VPS over SSH or in a container,
+add `--oauth-manual-callback`: mcp2cli prints the authorization URL instead of opening a
+browser, and reads the redirect back from stdin.
+
+```bash
+mcp2cli --mcp https://mcp.linear.app/mcp --oauth --oauth-manual-callback --list
+```
+
+Open the printed URL in a browser on any machine, authorize, then paste the URL you land
+on. That page will fail to load — nothing is listening on the loopback port — which is
+expected; only its address matters, because it carries the `code` and `state` parameters.
+PKCE and state verification are unchanged, so paste the URL unmodified.
+
 ### Secrets from environment or files
 
 Sensitive values (`--auth-header` values, `--oauth-client-id`, `--oauth-client-secret`) support
@@ -326,6 +342,8 @@ Options:
   --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
   --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)
   --oauth-scope SCOPE     OAuth scope(s) to request
+  --oauth-manual-callback Print the auth URL and read the redirect from stdin
+                          (for hosts with no reachable browser)
   --cache-key KEY         Custom cache key
   --cache-ttl SECONDS     Cache TTL (default: 3600)
   --refresh               Bypass cache
@@ -365,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.3.1 → mcp2cli-3.5.0}/README.md

@@ -83,6 +83,22 @@ mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list
 Tokens are persisted in `~/.cache/mcp2cli/oauth/` so subsequent calls reuse existing tokens
 and refresh automatically when they expire.
 
+#### Headless hosts — no browser on the machine running mcp2cli
+
+The default authorization-code flow starts a callback server on `127.0.0.1`, which only
+works when the browser runs on the same machine. On a VPS over SSH or in a container,
+add `--oauth-manual-callback`: mcp2cli prints the authorization URL instead of opening a
+browser, and reads the redirect back from stdin.
+
+```bash
+mcp2cli --mcp https://mcp.linear.app/mcp --oauth --oauth-manual-callback --list
+```
+
+Open the printed URL in a browser on any machine, authorize, then paste the URL you land
+on. That page will fail to load — nothing is listening on the loopback port — which is
+expected; only its address matters, because it carries the `code` and `state` parameters.
+PKCE and state verification are unchanged, so paste the URL unmodified.
+
 ### Secrets from environment or files
 
 Sensitive values (`--auth-header` values, `--oauth-client-id`, `--oauth-client-secret`) support
@@ -307,6 +323,8 @@ Options:
   --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
   --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)
   --oauth-scope SCOPE     OAuth scope(s) to request
+  --oauth-manual-callback Print the auth URL and read the redirect from stdin
+                          (for hosts with no reachable browser)
   --cache-key KEY         Custom cache key
   --cache-ttl SECONDS     Cache TTL (default: 3600)
   --refresh               Bypass cache
@@ -346,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.5.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "mcp2cli"
+version = "3.5.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.26,<3",
+    "pyyaml",
+]
+
+[[project.authors]]
+name = "Stephan Fitzpatrick"
+email = "stephan@knowsuchagency.com"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-asyncio",
+    "tiktoken",
+]
+
+[project.urls]
+Homepage = "https://github.com/knowsuchagency/mcp2cli"
+Repository = "https://github.com/knowsuchagency/mcp2cli"
+
+[project.scripts]
+mcp2cli = "mcp2cli:main"
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"

mcp2cli-3.3.1/pyproject.toml → mcp2cli-3.5.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "mcp2cli"
-version = "3.3.1"
+version = "3.5.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",
+    # 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.3.1 → mcp2cli-3.5.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
@@ -85,6 +86,18 @@ class BakeConfig:
     include: list[str] = field(default_factory=list)
     exclude: list[str] = field(default_factory=list)
     methods: list[str] = field(default_factory=list)
+    prog: str | None = None
+    description: str | None = None
+
+
+_DEFAULT_PARSER_DESCRIPTION = "Turn any MCP server or OpenAPI spec into a CLI"
+
+
+def _parser_branding(bake_config: BakeConfig | None) -> tuple[str, str]:
+    if bake_config is not None and bake_config.prog is not None:
+        description = bake_config.description or _DEFAULT_PARSER_DESCRIPTION
+        return bake_config.prog, description
+    return "mcp2cli", _DEFAULT_PARSER_DESCRIPTION
 
 
 # ---------------------------------------------------------------------------
@@ -269,6 +282,149 @@ 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.
+
+    JSON is emitted with ``ensure_ascii=False`` (issue #62), so CJK and emoji
+    reach stdout as real characters instead of ``\\uXXXX``. On a stream whose
+    encoding cannot represent them -- a redirected pipe under a legacy
+    Windows code page such as cp936 -- ``print()`` would raise
+    ``UnicodeEncodeError`` where the old escaped output was merely ugly.
+    Prefer UTF-8; if the stream refuses to be reconfigured, degrade to
+    backslash escapes, i.e. the pre-#62 shape, rather than crashing.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8")
+        except Exception:
+            try:
+                reconfigure(errors="backslashreplace")
+            except Exception:
+                pass
+
+
 
 def _apply_head(data, n: int):
     """Truncate data to first N elements (array) or return as-is (dict/scalar)."""
@@ -280,9 +436,9 @@ def _apply_head(data, n: int):
 def _emit_json(data, pretty: bool = False) -> None:
     """Print *data* as JSON. Indented when *pretty* or stdout is a TTY, else compact."""
     if pretty or sys.stdout.isatty():
-        print(json.dumps(data, indent=2))
+        print(json.dumps(data, indent=2, ensure_ascii=False))
     else:
-        print(json.dumps(data))
+        print(json.dumps(data, ensure_ascii=False))
 
 
 def output_result(
@@ -312,7 +468,7 @@ def output_result(
         if isinstance(data, str):
             print(data)
         else:
-            print(json.dumps(data))
+            print(json.dumps(data, ensure_ascii=False))
         return
     if isinstance(data, str):
         try:
@@ -323,7 +479,7 @@ def output_result(
     if head is not None:
         data = _apply_head(data, head)
     if toon:
-        encoded = _toon_encode(json.dumps(data))
+        encoded = _toon_encode(json.dumps(data, ensure_ascii=False))
         if encoded is not None:
             print(encoded, end="")
             return
@@ -668,6 +824,63 @@ def _find_free_port() -> int:
         return s.getsockname()[1]
 
 
+def _parse_oauth_callback_input(text: str) -> tuple[str, str]:
+    """Extract ``(code, state)`` from a pasted OAuth callback URL.
+
+    Accepts the full redirect target the browser landed on
+    (``http://127.0.0.1:1234/callback?code=...&state=...``) or just its query
+    string. PKCE and CSRF verification stay in the MCP SDK -- we only hand it
+    the two values it asks for. The SDK compares ``state`` against the one it
+    generated with ``secrets.compare_digest`` and treats ``None`` as a
+    mismatch, so a paste missing ``state`` is rejected here with a readable
+    message instead of surfacing as an opaque
+    ``State parameter mismatch: None != ...``.
+    """
+    text = text.strip().strip("'\"")
+    if not text:
+        raise ValueError("No callback URL provided.")
+    params = parse_qs(urlparse(text).query or text)
+    if "error" in params:
+        detail = params.get("error_description", [""])[0]
+        suffix = f" ({detail})" if detail else ""
+        raise RuntimeError(f"OAuth error: {params['error'][0]}{suffix}")
+    if "code" not in params:
+        raise ValueError(
+            "That URL has no 'code' parameter. Paste the entire URL from the "
+            "browser's address bar, including everything after the '?'."
+        )
+    if "state" not in params:
+        raise ValueError(
+            "That URL has no 'state' parameter. Paste the URL unmodified -- "
+            "the MCP SDK verifies state to prevent CSRF and rejects a missing one."
+        )
+    return params["code"][0], params["state"][0]
+
+
+def _prompt_oauth_callback(attempts: int = 3) -> tuple[str, str]:
+    """Read the OAuth callback URL from stdin.
+
+    For hosts with no reachable browser -- a VPS over SSH, a container.
+    Blocking, so callers run it off the event loop via ``anyio.to_thread``.
+    A malformed paste is re-prompted rather than fatal: the authorization
+    code is still live, and losing it would mean restarting the whole flow.
+    """
+    for remaining in reversed(range(attempts)):
+        print("Paste the full callback URL here: ", end="", file=sys.stderr, flush=True)
+        line = sys.stdin.readline()
+        if not line:
+            raise RuntimeError(
+                "stdin closed before an OAuth callback URL was pasted; "
+                "--oauth-manual-callback needs an interactive terminal."
+            )
+        try:
+            return _parse_oauth_callback_input(line)
+        except ValueError as exc:
+            if not remaining:
+                raise
+            print(f"{exc} ({remaining} attempt(s) left)", file=sys.stderr)
+
+
 
 
 def _get_cached_redirect_uri(storage: "FileTokenStorage") -> str | None:
@@ -733,6 +946,7 @@ def build_oauth_provider(
     scope: str | None = None,
     redirect_uri: str | None = None,
     flow: str = "auto",
+    manual_callback: bool = False,
 ) -> "httpx.Auth":
     """Build an OAuth provider for HTTP connections.
 
@@ -751,6 +965,10 @@ def build_oauth_provider(
 
     redirect_uri controls the full callback URL (scheme, host, port, path).
     When None, defaults to http://127.0.0.1:<random-free-port>/callback.
+
+    manual_callback skips the local callback server entirely and reads the
+    redirect URL from stdin instead, for hosts where the browser runs on a
+    different machine (issue #71).
     """
     storage = FileTokenStorage(server_url)
 
@@ -779,12 +997,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
@@ -989,41 +1216,65 @@ def build_oauth_provider(
         )
         storage._client_path.write_text(pre_client_info.model_dump_json())
 
-    # Reset callback handler state
-    _CallbackHandler.auth_code = None
-    _CallbackHandler.state = None
-    _CallbackHandler.error = None
-    _CallbackHandler.done = threading.Event()
+    if manual_callback:
+        # Nothing on this host can receive the redirect (e.g. a VPS reached
+        # over SSH), so print the URL for a browser elsewhere and take the
+        # redirect back by hand. The loopback redirect_uri is still what gets
+        # registered and sent, so the remote browser's final URL carries
+        # code+state even though no listener exists on that port. (Issue #71.)
+        async def redirect_handler(auth_url: str) -> None:
+            print(
+                "Open this URL in a browser on any machine and authorize:",
+                file=sys.stderr,
+            )
+            print(f"\n{auth_url}\n", file=sys.stderr)
+            print(
+                "The page you land on will fail to load -- that is expected, "
+                "nothing is listening there. Only its URL matters.",
+                file=sys.stderr,
+            )
+
+        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
+        _CallbackHandler.state = None
+        _CallbackHandler.error = None
+        _CallbackHandler.done = threading.Event()
 
-    if callback_host == "::1":
-        import socket as _socket
+        if callback_host == "::1":
+            import socket as _socket
 
-        class _IPv6HTTPServer(HTTPServer):
-            address_family = _socket.AF_INET6
+            class _IPv6HTTPServer(HTTPServer):
+                address_family = _socket.AF_INET6
 
-        server = _IPv6HTTPServer((callback_host, port), _CallbackHandler)
-    else:
-        server = HTTPServer((callback_host, port), _CallbackHandler)
-
-    async def redirect_handler(auth_url: str) -> None:
-        print("Opening browser for authorization...", file=sys.stderr)
-        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]:
-        # Run the HTTP server in a thread, wait for the callback
-        thread = threading.Thread(target=server.handle_request, daemon=True)
-        thread.start()
-        # Wait with timeout
-        if not _CallbackHandler.done.wait(timeout=300):
+            server = _IPv6HTTPServer((callback_host, port), _CallbackHandler)
+        else:
+            server = HTTPServer((callback_host, port), _CallbackHandler)
+
+        async def redirect_handler(auth_url: str) -> None:
+            print("Opening browser for authorization...", file=sys.stderr)
+            print(f"If browser doesn't open, visit: {auth_url}", file=sys.stderr)
+            webbrowser.open(auth_url)
+
+        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()
+            # Wait with timeout
+            if not _CallbackHandler.done.wait(timeout=300):
+                server.server_close()
+                raise TimeoutError("OAuth callback timed out after 5 minutes")
             server.server_close()
-            raise TimeoutError("OAuth callback timed out after 5 minutes")
-        server.server_close()
-        if _CallbackHandler.error:
-            raise RuntimeError(f"OAuth error: {_CallbackHandler.error}")
-        if not _CallbackHandler.auth_code:
-            raise RuntimeError("No authorization code received")
-        return (_CallbackHandler.auth_code, _CallbackHandler.state)
+            if _CallbackHandler.error:
+                raise RuntimeError(f"OAuth error: {_CallbackHandler.error}")
+            if not _CallbackHandler.auth_code:
+                raise RuntimeError("No authorization code received")
+            return _authorization_code_result(
+                _CallbackHandler.auth_code, _CallbackHandler.state
+            )
 
     return _RobustOAuthClientProvider(
         server_url=server_url,
@@ -1925,6 +2176,8 @@ def _baked_to_argv(config: dict) -> list[str]:
         argv += ["--oauth-redirect-uri", config["oauth_redirect_uri"]]
     if config.get("oauth_flow") and config["oauth_flow"] != "auto":
         argv += ["--oauth-flow", config["oauth_flow"]]
+    if config.get("oauth_manual_callback"):
+        argv.append("--oauth-manual-callback")
     return argv
 
 
@@ -1982,6 +2235,7 @@ def _bake_create(argv: list[str]) -> None:
     p.add_argument("--oauth-client-name", default="mcp2cli")
     p.add_argument("--oauth-scope", default=None)
     p.add_argument("--oauth-redirect-uri", default=None, metavar="URI")
+    p.add_argument("--oauth-manual-callback", action="store_true")
     p.add_argument(
         "--oauth-flow",
         choices=["auto", "authorization_code", "client_credentials"],
@@ -2049,6 +2303,7 @@ def _bake_create(argv: list[str]) -> None:
         "oauth_scope": args.oauth_scope,
         "oauth_redirect_uri": args.oauth_redirect_uri,
         "oauth_flow": args.oauth_flow,
+        "oauth_manual_callback": args.oauth_manual_callback,
         "include": [x.strip() for x in args.include.split(",") if x.strip()],
         "exclude": [x.strip() for x in args.exclude.split(",") if x.strip()],
         "methods": [x.strip().upper() for x in args.methods.split(",") if x.strip()],
@@ -2093,7 +2348,7 @@ def _bake_show(argv: list[str]) -> None:
             else:
                 masked.append([name, val[:4] + "****" if len(val) > 4 else "****"])
         display["auth_headers"] = masked
-    print(json.dumps(display, indent=2))
+    print(json.dumps(display, indent=2, ensure_ascii=False))
 
 
 def _bake_remove(argv: list[str]) -> None:
@@ -2187,6 +2442,8 @@ def _run_baked(name: str, argv: list[str]) -> None:
         include=cfg.get("include", []),
         exclude=cfg.get("exclude", []),
         methods=cfg.get("methods", []),
+        prog=name,
+        description=cfg.get("description"),
     )
     _main_impl(synthetic_argv, bake_config=bake_config)
 
@@ -2197,11 +2454,15 @@ def _run_baked(name: str, argv: list[str]) -> None:
 
 
 def build_argparse(
-    commands: list[CommandDef], pre_parser: argparse.ArgumentParser
+    commands: list[CommandDef],
+    pre_parser: argparse.ArgumentParser,
+    *,
+    prog: str = "mcp2cli",
+    description: str = _DEFAULT_PARSER_DESCRIPTION,
 ) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="mcp2cli",
-        description="Turn any MCP server or OpenAPI spec into a CLI",
+        prog=prog,
+        description=description,
         parents=[pre_parser],
     )
     subparsers = parser.add_subparsers(dest="_command")
@@ -2552,11 +2813,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(
@@ -2729,14 +2988,14 @@ async def _mcp_session(
     )
 
     if list_mode:
-        result = await session.list_tools()
+        all_tools = await _list_all_tools(session)
         tools = [
             {
                 "name": t.name,
                 "description": t.description or "",
-                "inputSchema": t.inputSchema or {},
+                "inputSchema": _mcp_attr(t, "inputSchema") or {},
             }
-            for t in result.tools
+            for t in all_tools
         ]
         commands = extract_mcp_commands(tools)
         if search_pattern:
@@ -2766,8 +3025,9 @@ 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)
+        # 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)
         return
 
     text = _extract_content_parts(result.content)
@@ -2797,7 +3057,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
         ]
@@ -2807,17 +3067,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"):
@@ -2872,7 +3130,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)
@@ -3032,11 +3290,31 @@ def _extract_content_parts(content_list, *, attrs=("text", "data")) -> str:
     return "\n".join(parts) if parts else ""
 
 
+async def _list_all_tools(session):
+    """Fetch every tool from an MCP session, following `nextCursor` until
+    exhausted. Per the MCP spec, tools/list is paginated and page size is
+    entirely up to the server, so a single call is not guaranteed to return
+    the full tool set: https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/pagination
+    """
+    tools = []
+    cursor = None
+    while True:
+        result = await _list_tools_page(session, cursor)
+        tools.extend(result.tools)
+        cursor = _mcp_attr(result, "nextCursor")
+        if not cursor:
+            return tools
+
+
 async def _dispatch_list_tools(session, params):
-    result = await session.list_tools()
+    tools = await _list_all_tools(session)
     return [
-        {"name": t.name, "description": t.description or "", "inputSchema": t.inputSchema or {}}
-        for t in result.tools
+        {
+            "name": t.name,
+            "description": t.description or "",
+            "inputSchema": _mcp_attr(t, "inputSchema") or {},
+        }
+        for t in tools
     ]
 
 
@@ -3048,23 +3326,31 @@ async def _dispatch_call_tool(session, params):
 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")
     ]
 
 
@@ -3091,7 +3377,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}
 
 
@@ -3241,12 +3529,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)
@@ -3477,7 +3762,8 @@ def handle_mcp(
         return
 
     pre = argparse.ArgumentParser(add_help=False)
-    parser = build_argparse(commands, pre)
+    prog, description = _parser_branding(bake_config)
+    parser = build_argparse(commands, pre, prog=prog, description=description)
     args = parser.parse_args(remaining)
 
     if not hasattr(args, "_cmd"):
@@ -3517,14 +3803,14 @@ def _fetch_mcp_tools(
     tools_result: list[dict] = []
 
     async def _extract_tools(session):
-        result = await session.list_tools()
+        all_tools = await _list_all_tools(session)
         tools_result.extend(
             {
                 "name": t.name,
                 "description": t.description or "",
-                "inputSchema": t.inputSchema or {},
+                "inputSchema": _mcp_attr(t, "inputSchema") or {},
             }
-            for t in result.tools
+            for t in all_tools
         )
 
     async def _run():
@@ -3547,11 +3833,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)
@@ -3630,6 +3914,7 @@ def _split_at_subcommand(
 
 
 def main():
+    _ensure_utf8_output()
     if len(sys.argv) > 1:
         first = sys.argv[1]
         if first == "bake":
@@ -3805,6 +4090,13 @@ def _build_main_parser() -> argparse.ArgumentParser:
             "client secret (required for confidential-client servers like Slack)."
         ),
     )
+    pre.add_argument(
+        "--oauth-manual-callback",
+        action="store_true",
+        help="Don't run a local callback server; print the authorization URL and read "
+             "the redirect URL back from stdin. For hosts with no reachable browser, "
+             "e.g. a VPS over SSH.",
+    )
     # Resource flags
     pre.add_argument(
         "--list-resources", action="store_true", help="List available resources"
@@ -3934,6 +4226,7 @@ def _setup_oauth(pre_args):
         scope=pre_args.oauth_scope,
         redirect_uri=pre_args.oauth_redirect_uri,
         flow=flow,
+        manual_callback=getattr(pre_args, "oauth_manual_callback", False),
     )
 
 
@@ -4195,7 +4488,8 @@ def _handle_openapi_mode(
                 )
                 sys.exit(1)
 
-    parser = build_argparse(commands, pre)
+    prog, description = _parser_branding(bake_config)
+    parser = build_argparse(commands, pre, prog=prog, description=description)
     args = parser.parse_args(remaining)
 
     if not hasattr(args, "_cmd"):