mcp2cli 3.1.0__tar.gz → 3.3.0__tar.gz

{mcp2cli-3.1.0 → mcp2cli-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 3.1.0
+Version: 3.3.0
 Summary: Turn any MCP server or OpenAPI spec into a CLI
 Author: Stephan Fitzpatrick
 Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
@@ -236,6 +236,36 @@ mcp2cli @myapi --list --sort alpha
 
 When usage data exists for a source, `--list` defaults to sorting by call frequency. Otherwise insertion order is preserved. Usage data is stored in `~/.cache/mcp2cli/usage.json`.
 
+### JSON output
+
+`--json` forces **valid JSON on stdout for every command**, in every mode. It is the
+machine-readable counterpart to the human-formatted default output, designed for LLM
+agents and scripts that need to parse results reliably.
+
+```bash
+# --list emits a JSON array of command objects (name, description, parameters, ...)
+mcp2cli --mcp https://mcp.example.com/sse --list --json
+mcp2cli --spec ./openapi.json --list --json
+mcp2cli --graphql https://api.example.com/graphql --list --json
+
+# --list --json --compact emits a JSON array of names only
+mcp2cli --mcp https://mcp.example.com/sse --list --json --compact
+
+# MCP tool calls emit the FULL CallToolResult envelope — including
+# structuredContent and isError, not just the flattened text. This surfaces the
+# machine-readable result that modern MCP tools put in structuredContent.
+mcp2cli --mcp https://mcp.example.com/sse --json search --query "test"
+# { "content": [...], "structuredContent": {...}, "isError": false }
+
+# OpenAPI / GraphQL calls emit the response as JSON (non-JSON bodies become a JSON string)
+mcp2cli --spec ./openapi.json --json list-pets
+mcp2cli --graphql https://api.example.com/graphql --json users
+```
+
+`--json` takes precedence over `--raw` and `--toon` (both of which can produce
+non-JSON), so it always wins — that is what makes it a reliable "force JSON" switch.
+Indentation follows the usual rule: pretty on a TTY or with `--pretty`, compact when piped.
+
 ### Output control
 
 ```bash
@@ -308,6 +338,9 @@ Options:
   --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body
+  --json                  Force valid JSON output for every command (--list and tool
+                          calls). MCP calls emit the full result envelope including
+                          structuredContent. Takes precedence over --raw and --toon.
   --toon                  Encode output as TOON (token-efficient for LLMs)
   --head N                Limit output to first N records (arrays)
   --version               Show version

{mcp2cli-3.1.0 → mcp2cli-3.3.0}/README.md

@@ -217,6 +217,36 @@ mcp2cli @myapi --list --sort alpha
 
 When usage data exists for a source, `--list` defaults to sorting by call frequency. Otherwise insertion order is preserved. Usage data is stored in `~/.cache/mcp2cli/usage.json`.
 
+### JSON output
+
+`--json` forces **valid JSON on stdout for every command**, in every mode. It is the
+machine-readable counterpart to the human-formatted default output, designed for LLM
+agents and scripts that need to parse results reliably.
+
+```bash
+# --list emits a JSON array of command objects (name, description, parameters, ...)
+mcp2cli --mcp https://mcp.example.com/sse --list --json
+mcp2cli --spec ./openapi.json --list --json
+mcp2cli --graphql https://api.example.com/graphql --list --json
+
+# --list --json --compact emits a JSON array of names only
+mcp2cli --mcp https://mcp.example.com/sse --list --json --compact
+
+# MCP tool calls emit the FULL CallToolResult envelope — including
+# structuredContent and isError, not just the flattened text. This surfaces the
+# machine-readable result that modern MCP tools put in structuredContent.
+mcp2cli --mcp https://mcp.example.com/sse --json search --query "test"
+# { "content": [...], "structuredContent": {...}, "isError": false }
+
+# OpenAPI / GraphQL calls emit the response as JSON (non-JSON bodies become a JSON string)
+mcp2cli --spec ./openapi.json --json list-pets
+mcp2cli --graphql https://api.example.com/graphql --json users
+```
+
+`--json` takes precedence over `--raw` and `--toon` (both of which can produce
+non-JSON), so it always wins — that is what makes it a reliable "force JSON" switch.
+Indentation follows the usual rule: pretty on a TTY or with `--pretty`, compact when piped.
+
 ### Output control
 
 ```bash
@@ -289,6 +319,9 @@ Options:
   --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body
+  --json                  Force valid JSON output for every command (--list and tool
+                          calls). MCP calls emit the full result envelope including
+                          structuredContent. Takes precedence over --raw and --toon.
   --toon                  Encode output as TOON (token-efficient for LLMs)
   --head N                Limit output to first N records (arrays)
   --version               Show version

{mcp2cli-3.1.0 → mcp2cli-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp2cli"
-version = "3.1.0"
+version = "3.3.0"
 description = "Turn any MCP server or OpenAPI spec into a CLI"
 readme = "README.md"
 license = "MIT"

{mcp2cli-3.1.0 → mcp2cli-3.3.0}/src/mcp2cli/__init__.py

@@ -277,6 +277,14 @@ def _apply_head(data, n: int):
     return data
 
 
+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))
+    else:
+        print(json.dumps(data))
+
+
 def output_result(
     data,
     *,
@@ -284,7 +292,22 @@ def output_result(
     raw: bool = False,
     toon: bool = False,
     head: int | None = None,
+    json_output: bool = False,
 ):
+    # --json forces valid JSON for every command, overriding --raw and --toon
+    # (both of which can produce non-JSON). Strings that contain JSON are
+    # unwrapped; everything else is emitted as a JSON value (e.g. a string
+    # literal for plain prose), guaranteeing parseable stdout.
+    if json_output:
+        if isinstance(data, str):
+            try:
+                data = json.loads(data)
+            except (json.JSONDecodeError, TypeError, ValueError):
+                pass
+        if head is not None:
+            data = _apply_head(data, head)
+        _emit_json(data, pretty)
+        return
     if raw:
         if isinstance(data, str):
             print(data)
@@ -310,10 +333,53 @@ def output_result(
             file=sys.stderr,
         )
         # Fall through to normal output
-    if pretty or sys.stdout.isatty():
-        print(json.dumps(data, indent=2))
+    _emit_json(data, pretty)
+
+
+def _python_type_name(t: type | None) -> str:
+    """Human/JSON-friendly type label for a ParamDef.python_type (None = boolean flag)."""
+    if t is None:
+        return "boolean"
+    return getattr(t, "__name__", str(t))
+
+
+def _param_to_dict(p: "ParamDef") -> dict:
+    d = {
+        "name": p.name,
+        "type": _python_type_name(p.python_type),
+        "required": p.required,
+        "description": p.description,
+        "location": p.location,
+    }
+    if p.choices:
+        d["choices"] = p.choices
+    return d
+
+
+def command_to_dict(cmd: "CommandDef") -> dict:
+    """Serialize a CommandDef to a JSON-friendly dict for `--list --json`."""
+    d: dict = {"name": cmd.name, "description": cmd.description or ""}
+    if cmd.method:
+        d["method"] = cmd.method.upper()
+    if cmd.path:
+        d["path"] = cmd.path
+    if cmd.tool_name:
+        d["toolName"] = cmd.tool_name
+    if cmd.graphql_operation_type:
+        d["operationType"] = cmd.graphql_operation_type
+    d["parameters"] = [_param_to_dict(p) for p in cmd.params]
+    return d
+
+
+def print_commands_json(
+    commands: "list[CommandDef]", compact: bool = False, pretty: bool = False
+) -> None:
+    """Emit a command list as JSON (array of objects, or names when *compact*)."""
+    if compact:
+        payload = [cmd.name for cmd in commands]
     else:
-        print(json.dumps(data))
+        payload = [command_to_dict(cmd) for cmd in commands]
+    _emit_json(payload, pretty)
 
 
 def _build_http_headers(auth_headers: list[tuple[str, str]], multipart: bool = False) -> dict[str, str]:
@@ -602,6 +668,62 @@ def _find_free_port() -> int:
         return s.getsockname()[1]
 
 
+
+
+def _get_cached_redirect_uri(storage: "FileTokenStorage") -> str | None:
+    """Return the cached client's redirect_uri, if any.
+
+    Reads client.json from disk without async. Returns None when
+    no cached client exists or the redirect_uri cannot be parsed.
+
+    Used by build_oauth_provider to reuse the registered redirect
+    port from a prior DCR run (issue #54).
+    """
+    if not storage._client_path.exists():
+        return None
+    try:
+        data = json.loads(storage._client_path.read_text())
+        uris = data.get("redirect_uris") or []
+        if uris:
+            return uris[0]
+    except Exception:
+        pass
+    return None
+
+
+def _port_available(host: str, port: int) -> bool:
+    """Check whether *port* is free on *host*.
+
+    Note: this is a best-effort probe — a TOCTOU race exists where another
+    process could bind the port between this check and the caller's use.
+    Callers must handle bind failures gracefully.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind((host, port))
+            return True
+    except OSError:
+        return False
+
+
+def _restore_token_expiry_from_sidecar(context) -> None:
+    """Recompute ``token_expiry_time`` from the persisted ``expires_at`` sidecar.
+
+    The upstream SDK's ``_initialize`` reloads ``current_tokens`` from disk but
+    never restores ``token_expiry_time`` — the persisted ``OAuthToken`` only
+    carries the relative ``expires_in``. Without this, ``is_token_valid()``
+    treats an already-expired access token as valid on a fresh process and
+    sends a stale Bearer, wasting a 401 round-trip before re-auth (issues #50
+    and #57). Shared by the authorization-code and client-credentials
+    providers.
+    """
+    storage = context.storage
+    if isinstance(storage, FileTokenStorage) and context.current_tokens:
+        expires_at = storage.get_expires_at()
+        if expires_at is not None:
+            context.token_expiry_time = expires_at
+
+
 def build_oauth_provider(
     server_url: str,
     *,
@@ -642,7 +764,22 @@ def build_oauth_provider(
             ClientCredentialsOAuthProvider,
         )
 
-        return ClientCredentialsOAuthProvider(
+        class _RobustClientCredentialsProvider(ClientCredentialsOAuthProvider):
+            """Client-credentials provider that restores expiry across restarts.
+
+            Issue #57: the upstream ``_initialize`` reloads tokens from disk
+            without recomputing ``token_expiry_time``, so an expired access
+            token looks valid after a process restart and a stale Bearer is
+            sent — triggering a 401 before the provider re-authenticates.
+            Restore the expiry from the sidecar so expired tokens are detected
+            proactively.
+            """
+
+            async def _initialize(self) -> None:
+                await super()._initialize()
+                _restore_token_expiry_from_sidecar(self.context)
+
+        return _RobustClientCredentialsProvider(
             server_url=server_url,
             storage=storage,
             client_id=client_id,
@@ -680,13 +817,19 @@ def build_oauth_provider(
 
         async def _initialize(self) -> None:
             await super()._initialize()
-            storage = self.context.storage
-            if isinstance(storage, FileTokenStorage) and self.context.current_tokens:
-                expires_at = storage.get_expires_at()
-                if expires_at is not None:
-                    self.context.token_expiry_time = expires_at
+            _restore_token_expiry_from_sidecar(self.context)
 
         async def _handle_refresh_response(self, response) -> bool:
+            # Issue #58: RFC 6749 §5.1 permits a refresh response to omit
+            # refresh_token, in which case the previously issued one stays
+            # valid. The upstream SDK replaces current_tokens wholesale, so
+            # refresh_token becomes None and every later refresh fails for
+            # the lack of one. Remember the old token to carry it forward.
+            old_refresh_token = (
+                self.context.current_tokens.refresh_token
+                if self.context.current_tokens
+                else None
+            )
             ok = await super()._handle_refresh_response(response)
             if not ok:
                 # Refresh failed. The cached DCR client_id may have been
@@ -698,6 +841,16 @@ def build_oauth_provider(
                 if isinstance(storage, FileTokenStorage):
                     storage.clear_client_info()
                     storage.clear_tokens()
+                return ok
+            # Carry the prior refresh token forward when the server did not
+            # issue a new one, then re-persist so it survives a restart.
+            tokens = self.context.current_tokens
+            if tokens is not None and not tokens.refresh_token and old_refresh_token:
+                tokens = tokens.model_copy(update={"refresh_token": old_refresh_token})
+                self.context.current_tokens = tokens
+                storage = self.context.storage
+                if isinstance(storage, FileTokenStorage):
+                    await storage.set_tokens(tokens)
             return ok
 
     _LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "::1"}
@@ -728,9 +881,36 @@ def build_oauth_provider(
         callback_host = parsed.hostname
         port = parsed.port
     else:
-        port = _find_free_port()
-        callback_host = "127.0.0.1"
-        redirect_uri = f"http://127.0.0.1:{port}/callback"
+        # Issue #54: When DCR is used without an explicit redirect_uri,
+        # _find_free_port() picks a new random port on every run.  If a
+        # cached client.json already exists (from a prior run), its
+        # registered redirect_uris[0] carries the ORIGINAL port.  Sending
+        # an auth request with a different port causes the auth server to
+        # reject the mismatch ("callback URL is invalid").
+        #
+        # Fix: reuse the cached redirect_uri if its port is still available.
+        # If the cached port is occupied (unlikely for loopback), clear the
+        # stale client so DCR re-registers with the fresh port.
+        cached_uri = _get_cached_redirect_uri(storage)
+        if cached_uri is not None:
+            from urllib.parse import urlparse as _urlparse
+            _parsed = _urlparse(cached_uri)
+            _cached_port = _parsed.port
+            _cached_host = _parsed.hostname or "127.0.0.1"
+            if _cached_port and _port_available(_cached_host, _cached_port):
+                callback_host = _cached_host
+                port = _cached_port
+                redirect_uri = cached_uri
+            else:
+                # Port no longer free — clear stale client and re-register
+                storage.clear_client_info()
+                port = _find_free_port()
+                callback_host = "127.0.0.1"
+                redirect_uri = f"http://127.0.0.1:{port}/callback"
+        else:
+            port = _find_free_port()
+            callback_host = "127.0.0.1"
+            redirect_uri = f"http://127.0.0.1:{port}/callback"
 
     client_metadata = OAuthClientMetadata(
         client_name=client_name,
@@ -780,7 +960,7 @@ def build_oauth_provider(
         server = HTTPServer((callback_host, port), _CallbackHandler)
 
     async def redirect_handler(auth_url: str) -> None:
-        print(f"Opening browser for authorization...", file=sys.stderr)
+        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)
 
@@ -1407,10 +1587,16 @@ def list_graphql_commands(
     source_hash: str = "",
     sort_mode: str | None = None,
     top: int | None = None,
+    json_output: bool = False,
+    pretty: bool = False,
 ):
     """Group commands by operation type and print."""
     commands = _apply_list_options(commands, source_hash, sort_mode, top)
 
+    if json_output:
+        print_commands_json(commands, compact=compact, pretty=pretty)
+        return
+
     if compact:
         print(" ".join(cmd.name for cmd in commands))
         return
@@ -1502,6 +1688,7 @@ def execute_graphql(
     fields_override: str | None = None,
     oauth_provider: "httpx.Auth | None" = None,
     head: int | None = None,
+    json_output: bool = False,
 ):
     """Build and execute a GraphQL query/mutation."""
     document, variables, field_name = _build_graphql_document(
@@ -1525,13 +1712,13 @@ def execute_graphql(
             print(f"GraphQL error: {msgs}", file=sys.stderr)
             sys.exit(1)
         # Partial errors — include them in output
-        output_result(result, pretty=pretty, raw=raw, toon=toon, head=head)
+        output_result(result, pretty=pretty, raw=raw, toon=toon, head=head, json_output=json_output)
         return
 
     data = result.get("data", {})
     # Extract the specific field's data
     field_data = data.get(field_name, data)
-    output_result(field_data, pretty=pretty, raw=raw, toon=toon, head=head)
+    output_result(field_data, pretty=pretty, raw=raw, toon=toon, head=head, json_output=json_output)
 
 
 def handle_graphql(
@@ -1552,6 +1739,7 @@ def handle_graphql(
     sort_mode: str | None = None,
     top: int | None = None,
     compact: bool = False,
+    json_output: bool = False,
 ):
     """Top-level handler for --graphql mode."""
     src_hash = _source_hash_for(url)
@@ -1561,6 +1749,7 @@ def handle_graphql(
     list_kwargs = dict(
         verbose=verbose, compact=compact,
         source_hash=src_hash, sort_mode=sort_mode, top=top,
+        json_output=json_output, pretty=pretty,
     )
 
     if list_mode:
@@ -1568,10 +1757,10 @@ def handle_graphql(
         return
 
     if not remaining:
-        if not compact:
+        if not compact and not json_output:
             print("Available operations:")
         list_graphql_commands(commands, **list_kwargs)
-        if not compact:
+        if not compact and not json_output:
             print("\nUse --list for the same output, or provide a subcommand.")
         return
 
@@ -1587,6 +1776,7 @@ def handle_graphql(
     execute_graphql(
         args, cmd, url, schema, auth_headers, pretty, raw, toon=toon,
         fields_override=fields_override, oauth_provider=oauth_provider,
+        json_output=json_output,
     )
 
     # Record usage after successful execution
@@ -2040,9 +2230,15 @@ def list_openapi_commands(
     source_hash: str = "",
     sort_mode: str | None = None,
     top: int | None = None,
+    json_output: bool = False,
+    pretty: bool = False,
 ):
     commands = _apply_list_options(commands, source_hash, sort_mode, top)
 
+    if json_output:
+        print_commands_json(commands, compact=compact, pretty=pretty)
+        return
+
     if compact:
         print(" ".join(cmd.name for cmd in commands))
         return
@@ -2073,9 +2269,15 @@ def list_mcp_commands(
     source_hash: str = "",
     sort_mode: str | None = None,
     top: int | None = None,
+    json_output: bool = False,
+    pretty: bool = False,
 ):
     commands = _apply_list_options(commands, source_hash, sort_mode, top)
 
+    if json_output:
+        print_commands_json(commands, compact=compact, pretty=pretty)
+        return
+
     if compact:
         print(" ".join(cmd.name for cmd in commands))
         return
@@ -2186,6 +2388,7 @@ def execute_openapi(
     toon: bool = False,
     oauth_provider: "httpx.Auth | None" = None,
     head: int | None = None,
+    json_output: bool = False,
 ):
     path, query_params, extra_headers, body, files = _collect_openapi_params(cmd, args)
     url = base_url.rstrip("/") + path
@@ -2227,6 +2430,14 @@ def execute_openapi(
             for _, file_tuple in files.items():
                 file_tuple[1].close()
 
+    if json_output:
+        try:
+            data = resp.json()
+        except Exception:
+            data = resp.text
+        output_result(data, pretty=pretty, head=head, json_output=True)
+        return
+
     if raw:
         sys.stdout.buffer.write(resp.content)
         return
@@ -2271,6 +2482,7 @@ def run_mcp_http(
     top: int | None = None,
     compact: bool = False,
     source_hash: str = "",
+    json_output: bool = False,
 ):
     extra = dict(
         resource_action=resource_action,
@@ -2285,6 +2497,7 @@ def run_mcp_http(
         top=top,
         compact=compact,
         source_hash=source_hash,
+        json_output=json_output,
     )
 
     async def _run():
@@ -2374,6 +2587,7 @@ def run_mcp_stdio(
     top: int | None = None,
     compact: bool = False,
     source_hash: str = "",
+    json_output: bool = False,
 ):
     extra = dict(
         resource_action=resource_action,
@@ -2388,6 +2602,7 @@ def run_mcp_stdio(
         top=top,
         compact=compact,
         source_hash=source_hash,
+        json_output=json_output,
     )
 
     import anyio
@@ -2443,11 +2658,13 @@ async def _mcp_session(
     top: int | None = None,
     compact: bool = False,
     source_hash: str = "",
+    json_output: bool = False,
 ):
     # Handle resource operations
     if resource_action:
         await _handle_resources(
             session, resource_action, resource_uri, pretty, raw, toon, head=head,
+            json_output=json_output,
         )
         return
 
@@ -2455,13 +2672,14 @@ async def _mcp_session(
     if prompt_action:
         await _handle_prompts(
             session, prompt_action, prompt_name, prompt_arguments,
-            pretty, raw, toon, head=head,
+            pretty, raw, toon, head=head, json_output=json_output,
         )
         return
 
     list_kwargs = dict(
         verbose=verbose, compact=compact,
         source_hash=source_hash, sort_mode=sort_mode, top=top,
+        json_output=json_output, pretty=pretty,
     )
 
     if list_mode:
@@ -2478,12 +2696,15 @@ async def _mcp_session(
         if search_pattern:
             commands = _filter_commands(commands, search_pattern)
             if not commands:
-                print(f"\nNo tools matching '{search_pattern}'.")
+                if json_output:
+                    list_mcp_commands(commands, **list_kwargs)
+                else:
+                    print(f"\nNo tools matching '{search_pattern}'.")
                 return
-            if not compact:
+            if not compact and not json_output:
                 print(f"\nTools matching '{search_pattern}':")
         else:
-            if not compact:
+            if not compact and not json_output:
                 print("\nAvailable tools:")
         list_mcp_commands(commands, **list_kwargs)
         return
@@ -2497,6 +2718,12 @@ async def _mcp_session(
 
     result = await session.call_tool(tool_name, arguments or {})
 
+    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
+
     text = _extract_content_parts(result.content)
     output_result(text, pretty=pretty, raw=raw, toon=toon, head=head)
 
@@ -2514,8 +2741,9 @@ async def _handle_resources(
     raw: bool,
     toon: bool,
     head: int | None = None,
+    json_output: bool = False,
 ):
-    _out = dict(pretty=pretty, raw=raw, toon=toon, head=head)
+    _out = dict(pretty=pretty, raw=raw, toon=toon, head=head, json_output=json_output)
     if action == "list":
         result = await session.list_resources()
         data = [
@@ -2568,8 +2796,9 @@ async def _handle_prompts(
     raw: bool,
     toon: bool,
     head: int | None = None,
+    json_output: bool = False,
 ):
-    _out = dict(pretty=pretty, raw=raw, toon=toon, head=head)
+    _out = dict(pretty=pretty, raw=raw, toon=toon, head=head, json_output=json_output)
     if action == "list":
         result = await session.list_prompts()
         data = [
@@ -2617,6 +2846,8 @@ def _session_meta_path(name: str) -> Path:
 def _session_sock_path(name: str) -> Path:
     return SESSIONS_DIR / f"{name}.sock"
 
+def _session_log_path(name: str) -> Path:
+    return SESSIONS_DIR / f"{name}.log"
 
 def _session_is_alive(meta: dict) -> bool:
     pid = meta.get("pid")
@@ -2650,6 +2881,7 @@ def session_stop(name: str):
     """Stop a named session."""
     meta_path = _session_meta_path(name)
     sock_path = _session_sock_path(name)
+    log_path = _session_log_path(name)
     if meta_path.exists():
         try:
             meta = json.loads(meta_path.read_text())
@@ -2667,6 +2899,7 @@ def session_stop(name: str):
             pass
         meta_path.unlink(missing_ok=True)
     sock_path.unlink(missing_ok=True)
+    log_path.unlink(missing_ok=True)
 
 
 def session_start(
@@ -2709,6 +2942,7 @@ def session_start(
         }
     )
 
+    log_path = _session_log_path(name)
     proc = subprocess.Popen(
         [
             sys.executable,
@@ -2717,7 +2951,7 @@ def session_start(
         ],
         start_new_session=True,
         stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
+        stderr=open(log_path, "a"),
         stdin=subprocess.DEVNULL,
     )
 
@@ -3110,6 +3344,7 @@ def handle_mcp(
     sort_mode: str | None = None,
     top: int | None = None,
     compact: bool = False,
+    json_output: bool = False,
 ):
     # Build a config dict for cache key generation (future-proof)
     config_for_cache = {
@@ -3132,6 +3367,7 @@ def handle_mcp(
             prompt_name=prompt_name,
             prompt_arguments=prompt_arguments,
             head=head,
+            json_output=json_output,
         )
         _dispatch_mcp_call(
             source, is_stdio, auth_headers, env_vars,
@@ -3144,6 +3380,7 @@ def handle_mcp(
     list_kwargs = dict(
         verbose=verbose, compact=compact,
         source_hash=src_hash, sort_mode=sort_mode, top=top,
+        json_output=json_output, pretty=pretty,
     )
 
     if list_mode:
@@ -3157,7 +3394,7 @@ def handle_mcp(
             commands = filter_commands(
                 commands, bake_config.include, bake_config.exclude, bake_config.methods,
             )
-            if not compact:
+            if not compact and not json_output:
                 print("\nAvailable tools:")
             list_mcp_commands(commands, **list_kwargs)
             return
@@ -3169,6 +3406,7 @@ def handle_mcp(
             verbose=verbose,
             sort_mode=sort_mode, top=top, compact=compact,
             source_hash=src_hash,
+            json_output=json_output,
         )
         return
 
@@ -3185,10 +3423,10 @@ def handle_mcp(
         )
 
     if not remaining:
-        if not compact:
+        if not compact and not json_output:
             print("Available tools:")
         list_mcp_commands(commands, **list_kwargs)
-        if not compact:
+        if not compact and not json_output:
             print("\nUse --list for the same output, or provide a subcommand.")
         return
 
@@ -3215,6 +3453,7 @@ def handle_mcp(
         source, is_stdio, auth_headers, env_vars,
         cmd.tool_name, arguments, False, pretty, raw, key, ttl, refresh,
         toon=toon, transport=transport, oauth_provider=oauth_provider,
+        json_output=json_output,
     )
 
     # Record usage after successful execution
@@ -3432,6 +3671,16 @@ def _build_main_parser() -> argparse.ArgumentParser:
     )
     pre.add_argument("--pretty", action="store_true", help="Pretty-print JSON output")
     pre.add_argument("--raw", action="store_true", help="Print raw response body")
+    pre.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help=(
+            "Force valid JSON output for every command. --list emits a JSON array of "
+            "commands; MCP tool calls emit the full result envelope including "
+            "structuredContent and isError. Takes precedence over --raw and --toon."
+        ),
+    )
     pre.add_argument(
         "--toon",
         action="store_true",
@@ -3693,32 +3942,28 @@ def _handle_session_operations(
 
     # --- Session client mode ---
     sess_name = pre_args.session
+    _sess_out = dict(
+        pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+        json_output=pre_args.json_output,
+    )
 
     if pre_args.list_resources:
         result = _session_request(sess_name, "list_resources")
-        output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
-        )
+        output_result(result, **_sess_out)
         return True
     if pre_args.list_resource_templates:
         result = _session_request(sess_name, "list_resource_templates")
-        output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
-        )
+        output_result(result, **_sess_out)
         return True
     if pre_args.read_resource:
         result = _session_request(
             sess_name, "read_resource", {"uri": pre_args.read_resource}
         )
-        output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
-        )
+        output_result(result, **_sess_out)
         return True
     if pre_args.list_prompts:
         result = _session_request(sess_name, "list_prompts")
-        output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
-        )
+        output_result(result, **_sess_out)
         return True
     if pre_args.get_prompt:
         p_args = {}
@@ -3731,9 +3976,7 @@ def _handle_session_operations(
             "get_prompt",
             {"name": pre_args.get_prompt, "arguments": p_args},
         )
-        output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
-        )
+        output_result(result, **_sess_out)
         return True
     if pre_args.list_commands:
         result = _session_request(sess_name, "list_tools")
@@ -3741,21 +3984,36 @@ def _handle_session_operations(
         if search_pattern:
             commands = _filter_commands(commands, search_pattern)
             if not commands:
-                print(f"\nNo tools matching '{search_pattern}'.")
+                if pre_args.json_output:
+                    list_mcp_commands(
+                        commands, verbose=pre_args.verbose,
+                        json_output=True, pretty=pre_args.pretty,
+                    )
+                else:
+                    print(f"\nNo tools matching '{search_pattern}'.")
                 return True
-            print(f"\nTools matching '{search_pattern}':")
-        else:
+            if not pre_args.json_output:
+                print(f"\nTools matching '{search_pattern}':")
+        elif not pre_args.json_output:
             print("\nAvailable tools:")
-        list_mcp_commands(commands, verbose=pre_args.verbose)
+        list_mcp_commands(
+            commands, verbose=pre_args.verbose,
+            json_output=pre_args.json_output, pretty=pre_args.pretty,
+        )
         return True
 
     # Tool call via session
     if not remaining:
         result = _session_request(sess_name, "list_tools")
         commands = extract_mcp_commands(result)
-        print("Available tools:")
-        list_mcp_commands(commands, verbose=pre_args.verbose)
-        print("\nUse --list for the same output, or provide a subcommand.")
+        if not pre_args.json_output:
+            print("Available tools:")
+        list_mcp_commands(
+            commands, verbose=pre_args.verbose,
+            json_output=pre_args.json_output, pretty=pre_args.pretty,
+        )
+        if not pre_args.json_output:
+            print("\nUse --list for the same output, or provide a subcommand.")
         return True
 
     tools = _session_request(sess_name, "list_tools")
@@ -3781,9 +4039,7 @@ def _handle_session_operations(
     result = _session_request(
         sess_name, "call_tool", {"name": cmd.tool_name, "arguments": arguments}
     )
-    output_result(
-        result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon
-    )
+    output_result(result, **_sess_out)
     return True
 
 
@@ -3848,15 +4104,19 @@ def _handle_openapi_mode(
     list_kwargs = dict(
         verbose=pre_args.verbose, compact=pre_args.compact,
         source_hash=src_hash, sort_mode=pre_args.sort_mode, top=pre_args.top,
+        json_output=pre_args.json_output, pretty=pre_args.pretty,
     )
 
     if pre_args.list_commands:
         if search_pattern:
             commands = _filter_commands(commands, search_pattern)
             if not commands:
-                print(f"\nNo tools matching '{search_pattern}'.")
+                if not pre_args.json_output:
+                    print(f"\nNo tools matching '{search_pattern}'.")
+                else:
+                    list_openapi_commands(commands, **list_kwargs)
                 return
-            if not pre_args.compact:
+            if not pre_args.compact and not pre_args.json_output:
                 print(f"\nTools matching '{search_pattern}':")
         list_openapi_commands(commands, **list_kwargs)
         return
@@ -3900,7 +4160,7 @@ def _handle_openapi_mode(
     execute_openapi(
         args, cmd, base_url, auth_headers,
         pre_args.pretty, pre_args.raw, toon=pre_args.toon,
-        oauth_provider=oauth_provider,
+        oauth_provider=oauth_provider, json_output=pre_args.json_output,
     )
 
     # Record usage after successful execution
@@ -3960,6 +4220,7 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             sort_mode=pre_args.sort_mode,
             top=pre_args.top,
             compact=pre_args.compact,
+            json_output=pre_args.json_output,
         )
         return
 
@@ -3994,6 +4255,7 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             sort_mode=pre_args.sort_mode,
             top=pre_args.top,
             compact=pre_args.compact,
+            json_output=pre_args.json_output,
         )
         return