mcp2cli 3.3.1__tar.gz → 3.4.0__tar.gz

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

@@ -1,3 +1,22 @@
+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>
@@ -83,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
@@ -307,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

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

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: mcp2cli
-Version: 3.3.1
-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: 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>
@@ -102,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
@@ -326,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

mcp2cli-3.4.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "mcp2cli"
+version = "3.4.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",
+    "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.4.0/pyproject.toml.orig

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

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

@@ -85,6 +85,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 +281,30 @@ def _toon_encode(json_str: str) -> str | None:
     return None
 
 
+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 +316,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 +348,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 +359,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 +704,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 +826,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 +845,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)
 
@@ -989,41 +1087,62 @@ 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,
+            )
 
-    if callback_host == "::1":
-        import socket as _socket
+        async def callback_handler() -> tuple[str, str | None]:
+            return await anyio.to_thread.run_sync(_prompt_oauth_callback)
+    else:
+        # Reset callback handler state
+        _CallbackHandler.auth_code = None
+        _CallbackHandler.state = None
+        _CallbackHandler.error = None
+        _CallbackHandler.done = threading.Event()
 
-        class _IPv6HTTPServer(HTTPServer):
-            address_family = _socket.AF_INET6
+        if callback_host == "::1":
+            import socket as _socket
 
-        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):
+            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.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 (_CallbackHandler.auth_code, _CallbackHandler.state)
 
     return _RobustOAuthClientProvider(
         server_url=server_url,
@@ -1925,6 +2044,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 +2103,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 +2171,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 +2216,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 +2310,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 +2322,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")
@@ -2729,14 +2858,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 {},
             }
-            for t in result.tools
+            for t in all_tools
         ]
         commands = extract_mcp_commands(tools)
         if search_pattern:
@@ -3032,11 +3161,27 @@ 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 session.list_tools(cursor=cursor)
+        tools.extend(result.tools)
+        cursor = 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
+        for t in tools
     ]
 
 
@@ -3477,7 +3622,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 +3663,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 {},
             }
-            for t in result.tools
+            for t in all_tools
         )
 
     async def _run():
@@ -3630,6 +3776,7 @@ def _split_at_subcommand(
 
 
 def main():
+    _ensure_utf8_output()
     if len(sys.argv) > 1:
         first = sys.argv[1]
         if first == "bake":
@@ -3805,6 +3952,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 +4088,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 +4350,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"):