mcp2cli 2.2.4__tar.gz → 2.4.0__tar.gz

{mcp2cli-2.2.4 → mcp2cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 2.2.4
+Version: 2.4.0
 Summary: Turn any MCP server or OpenAPI spec into a CLI
 Author: Stephan Fitzpatrick
 Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
@@ -225,6 +225,14 @@ mcp2cli --spec ./spec.json --pretty list-pets
 # Raw response body (no JSON parsing)
 mcp2cli --spec ./spec.json --raw get-data
 
+# Filter JSON with jq (preferred over Python for JSON processing)
+mcp2cli --spec ./spec.json list-pets --jq '.[].name'
+mcp2cli --spec ./spec.json list-pets --jq '[.[] | select(.status == "available")] | length'
+
+# Truncate large responses to first N records
+mcp2cli --spec ./spec.json list-records --head 5
+mcp2cli --spec ./spec.json list-records --head 3 --jq '.'  # preview then filter
+
 # Pipe-friendly (compact JSON when not a TTY)
 mcp2cli --spec ./spec.json list-pets | jq '.[] | .name'
 
@@ -282,6 +290,8 @@ Options:
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body
   --toon                  Encode output as TOON (token-efficient for LLMs)
+  --jq EXPR               Filter JSON output through jq expression
+  --head N                Limit output to first N records (arrays)
   --version               Show version
 
 Bake mode:

{mcp2cli-2.2.4 → mcp2cli-2.4.0}/README.md

@@ -206,6 +206,14 @@ mcp2cli --spec ./spec.json --pretty list-pets
 # Raw response body (no JSON parsing)
 mcp2cli --spec ./spec.json --raw get-data
 
+# Filter JSON with jq (preferred over Python for JSON processing)
+mcp2cli --spec ./spec.json list-pets --jq '.[].name'
+mcp2cli --spec ./spec.json list-pets --jq '[.[] | select(.status == "available")] | length'
+
+# Truncate large responses to first N records
+mcp2cli --spec ./spec.json list-records --head 5
+mcp2cli --spec ./spec.json list-records --head 3 --jq '.'  # preview then filter
+
 # Pipe-friendly (compact JSON when not a TTY)
 mcp2cli --spec ./spec.json list-pets | jq '.[] | .name'
 
@@ -263,6 +271,8 @@ Options:
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body
   --toon                  Encode output as TOON (token-efficient for LLMs)
+  --jq EXPR               Filter JSON output through jq expression
+  --head N                Limit output to first N records (arrays)
   --version               Show version
 
 Bake mode:

{mcp2cli-2.2.4 → mcp2cli-2.4.0}/pyproject.toml

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

{mcp2cli-2.2.4 → mcp2cli-2.4.0}/src/mcp2cli/__init__.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-__version__ = "2.2.1"
+__version__ = "2.4.0"
 
 import argparse
 import copy
 import hashlib
 import json
+import mimetypes
 import os
 import fnmatch
 import re
@@ -64,6 +65,7 @@ class CommandDef:
     # OpenAPI
     method: str | None = None
     path: str | None = None
+    content_type: str | None = None  # None = json, "multipart/form-data", etc.
     # MCP
     tool_name: str | None = None
     # GraphQL
@@ -246,7 +248,48 @@ def _toon_encode(json_str: str) -> str | None:
     return None
 
 
-def output_result(data, *, pretty: bool = False, raw: bool = False, toon: bool = False):
+def _run_jq(json_str: str, expr: str) -> str:
+    """Pipe JSON through jq with the given expression. Exits on failure."""
+    if not shutil.which("jq"):
+        print(
+            "Error: --jq requires jq to be installed. "
+            "See https://jqlang.github.io/jq/",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    try:
+        result = subprocess.run(
+            ["jq", expr],
+            input=json_str,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            print(f"jq error: {result.stderr.strip()}", file=sys.stderr)
+            sys.exit(1)
+        return result.stdout
+    except subprocess.TimeoutExpired:
+        print("Error: jq timed out", file=sys.stderr)
+        sys.exit(1)
+
+
+def _apply_head(data, n: int):
+    """Truncate data to first N elements (array) or return as-is (dict/scalar)."""
+    if isinstance(data, list):
+        return data[:n]
+    return data
+
+
+def output_result(
+    data,
+    *,
+    pretty: bool = False,
+    raw: bool = False,
+    toon: bool = False,
+    jq_expr: str | None = None,
+    head: int | None = None,
+):
     if raw:
         if isinstance(data, str):
             print(data)
@@ -259,6 +302,11 @@ def output_result(data, *, pretty: bool = False, raw: bool = False, toon: bool =
         except (json.JSONDecodeError, TypeError):
             print(data)
             return
+    if head is not None:
+        data = _apply_head(data, head)
+    if jq_expr:
+        print(_run_jq(json.dumps(data), jq_expr), end="")
+        return
     if toon:
         encoded = _toon_encode(json.dumps(data))
         if encoded is not None:
@@ -276,10 +324,11 @@ def output_result(data, *, pretty: bool = False, raw: bool = False, toon: bool =
         print(json.dumps(data))
 
 
-def _build_http_headers(auth_headers: list[tuple[str, str]]) -> dict[str, str]:
+def _build_http_headers(auth_headers: list[tuple[str, str]], multipart: bool = False) -> dict[str, str]:
     """Build HTTP headers dict from auth_headers with a Content-Type default."""
     headers = dict(auth_headers)
-    headers.setdefault("Content-Type", "application/json")
+    if not multipart:
+        headers.setdefault("Content-Type", "application/json")
     return headers
 
 
@@ -616,19 +665,43 @@ def extract_openapi_commands(spec: dict) -> list[CommandDef]:
                 )
                 params.append(p)
 
-            # Request body
-            rb_schema = (
-                details.get("requestBody", {})
-                .get("content", {})
-                .get("application/json", {})
-                .get("schema", {})
+            # Request body — negotiate content type
+            rb_content = details.get("requestBody", {}).get("content", {})
+            multipart_schema = rb_content.get("multipart/form-data", {}).get("schema", {})
+            json_schema = rb_content.get("application/json", {}).get("schema", {})
+
+            mp_props = multipart_schema.get("properties", {})
+            has_binary = any(
+                p.get("format") == "binary" for p in mp_props.values()
             )
+
+            if has_binary:
+                rb_schema = multipart_schema
+                cmd_content_type = "multipart/form-data"
+            elif json_schema:
+                rb_schema = json_schema
+                cmd_content_type = None
+            elif mp_props:
+                rb_schema = multipart_schema
+                cmd_content_type = "multipart/form-data"
+            else:
+                rb_schema = {}
+                cmd_content_type = None
+
             required_fields = set(rb_schema.get("required", []))
             properties = rb_schema.get("properties", {})
             has_body = bool(properties)
 
             for prop_name, prop_schema in properties.items():
-                py_type, suffix = schema_type_to_python(prop_schema)
+                is_binary = (
+                    cmd_content_type == "multipart/form-data"
+                    and prop_schema.get("format") == "binary"
+                )
+                if is_binary:
+                    loc, py_type, suffix = "file", str, " (file path)"
+                else:
+                    py_type, suffix = schema_type_to_python(prop_schema)
+                    loc = "body"
                 p = ParamDef(
                     name=to_kebab(prop_name),
                     original_name=prop_name,
@@ -636,7 +709,7 @@ def extract_openapi_commands(spec: dict) -> list[CommandDef]:
                     required=prop_name in required_fields,
                     description=(prop_schema.get("description") or prop_name) + suffix,
                     choices=prop_schema.get("enum"),
-                    location="body",
+                    location=loc,
                 )
                 params.append(p)
 
@@ -648,6 +721,7 @@ def extract_openapi_commands(spec: dict) -> list[CommandDef]:
                     has_body=has_body,
                     method=method,
                     path=path,
+                    content_type=cmd_content_type,
                 )
             )
 
@@ -1103,6 +1177,8 @@ def execute_graphql(
     toon: bool = False,
     fields_override: str | None = None,
     oauth_provider: "httpx.Auth | None" = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     """Build and execute a GraphQL query/mutation."""
     document, variables, field_name = _build_graphql_document(
@@ -1126,13 +1202,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)
+        output_result(result, pretty=pretty, raw=raw, toon=toon, jq_expr=jq_expr, head=head)
         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)
+    output_result(field_data, pretty=pretty, raw=raw, toon=toon, jq_expr=jq_expr, head=head)
 
 
 def handle_graphql(
@@ -1148,6 +1224,8 @@ def handle_graphql(
     toon: bool = False,
     fields_override: str | None = None,
     oauth_provider: "httpx.Auth | None" = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     """Top-level handler for --graphql mode."""
     schema = load_graphql_schema(url, auth_headers, cache_key, ttl, refresh, oauth_provider=oauth_provider)
@@ -1175,6 +1253,7 @@ def handle_graphql(
     execute_graphql(
         args, cmd, url, schema, auth_headers, pretty, raw, toon=toon,
         fields_override=fields_override, oauth_provider=oauth_provider,
+        jq_expr=jq_expr, head=head,
     )
 
 
@@ -1611,16 +1690,17 @@ def _filter_commands(commands: list[CommandDef], pattern: str) -> list[CommandDe
 def _collect_openapi_params(
     cmd: CommandDef,
     args: argparse.Namespace,
-) -> tuple[str, dict[str, str], dict[str, str], dict | None]:
+) -> tuple[str, dict[str, str], dict[str, str], dict | None, dict | None]:
     """Collect OpenAPI params from parsed args, separated by location.
 
-    Returns (path, query_params, extra_headers, body_or_none) where *path*
-    has ``{param}`` placeholders substituted with actual values.
+    Returns (path, query_params, extra_headers, body_or_none, files_or_none)
+    where *path* has ``{param}`` placeholders substituted with actual values.
     """
     path = cmd.path or ""
     query_params: dict[str, str] = {}
     extra_headers: dict[str, str] = {}
     body: dict | None = None
+    files: dict | None = None
 
     for p in cmd.params:
         if p.location == "path":
@@ -1650,6 +1730,17 @@ def _collect_openapi_params(
                     continue
                 if p.location == "path":
                     continue
+                if p.location == "file":
+                    if val is not None:
+                        fp = Path(val)
+                        if not fp.is_file():
+                            print(f"Error: file not found: {val}", file=sys.stderr)
+                            sys.exit(1)
+                        mime = mimetypes.guess_type(val)[0] or "application/octet-stream"
+                        if files is None:
+                            files = {}
+                        files[p.original_name] = (fp.name, open(fp, "rb"), mime)
+                    continue
                 if val is not None:
                     body[p.original_name] = val
             if not body:
@@ -1661,7 +1752,7 @@ def _collect_openapi_params(
                 if val is not None:
                     query_params[p.original_name] = val
 
-    return path, query_params, extra_headers, body
+    return path, query_params, extra_headers, body, files
 
 
 def execute_openapi(
@@ -1673,22 +1764,48 @@ def execute_openapi(
     raw: bool,
     toon: bool = False,
     oauth_provider: "httpx.Auth | None" = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
-    path, query_params, extra_headers, body = _collect_openapi_params(cmd, args)
+    path, query_params, extra_headers, body, files = _collect_openapi_params(cmd, args)
     url = base_url.rstrip("/") + path
 
-    headers = _build_http_headers(auth_headers)
+    is_multipart = files is not None or cmd.content_type == "multipart/form-data"
+    headers = _build_http_headers(auth_headers, multipart=is_multipart)
     headers.update(extra_headers)
 
-    with httpx.Client(timeout=60, auth=oauth_provider) as client:
-        resp = client.request(
-            (cmd.method or "get").upper(),
-            url,
-            headers=headers,
-            params=query_params or None,
-            json=body,
-        )
-        _handle_http_error(resp)
+    try:
+        with httpx.Client(timeout=60, auth=oauth_provider) as client:
+            if files is not None:
+                resp = client.request(
+                    (cmd.method or "get").upper(),
+                    url,
+                    headers=headers,
+                    params=query_params or None,
+                    data=body,
+                    files=files,
+                )
+            elif cmd.content_type == "multipart/form-data":
+                resp = client.request(
+                    (cmd.method or "get").upper(),
+                    url,
+                    headers=headers,
+                    params=query_params or None,
+                    data=body,
+                )
+            else:
+                resp = client.request(
+                    (cmd.method or "get").upper(),
+                    url,
+                    headers=headers,
+                    params=query_params or None,
+                    json=body,
+                )
+            _handle_http_error(resp)
+    finally:
+        if files:
+            for _, file_tuple in files.items():
+                file_tuple[1].close()
 
     if raw:
         sys.stdout.buffer.write(resp.content)
@@ -1700,7 +1817,7 @@ def execute_openapi(
         print(resp.text)
         return
 
-    output_result(data, pretty=pretty, toon=toon)
+    output_result(data, pretty=pretty, toon=toon, jq_expr=jq_expr, head=head)
 
 
 # ---------------------------------------------------------------------------
@@ -1728,6 +1845,8 @@ def run_mcp_http(
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
     search_pattern: str | None = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     extra = dict(
         resource_action=resource_action,
@@ -1736,6 +1855,8 @@ def run_mcp_http(
         prompt_name=prompt_name,
         prompt_arguments=prompt_arguments,
         search_pattern=search_pattern,
+        jq_expr=jq_expr,
+        head=head,
     )
 
     async def _run():
@@ -1819,6 +1940,8 @@ def run_mcp_stdio(
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
     search_pattern: str | None = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     extra = dict(
         resource_action=resource_action,
@@ -1827,6 +1950,8 @@ def run_mcp_stdio(
         prompt_name=prompt_name,
         prompt_arguments=prompt_arguments,
         search_pattern=search_pattern,
+        jq_expr=jq_expr,
+        head=head,
     )
 
     import anyio
@@ -1876,18 +2001,22 @@ async def _mcp_session(
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
     search_pattern: str | None = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     # Handle resource operations
     if resource_action:
         await _handle_resources(
-            session, resource_action, resource_uri, pretty, raw, toon
+            session, resource_action, resource_uri, pretty, raw, toon,
+            jq_expr=jq_expr, head=head,
         )
         return
 
     # Handle prompt operations
     if prompt_action:
         await _handle_prompts(
-            session, prompt_action, prompt_name, prompt_arguments, pretty, raw, toon
+            session, prompt_action, prompt_name, prompt_arguments, pretty, raw, toon,
+            jq_expr=jq_expr, head=head,
         )
         return
 
@@ -1923,7 +2052,7 @@ async def _mcp_session(
     result = await session.call_tool(tool_name, arguments or {})
 
     text = _extract_content_parts(result.content)
-    output_result(text, pretty=pretty, raw=raw, toon=toon)
+    output_result(text, pretty=pretty, raw=raw, toon=toon, jq_expr=jq_expr, head=head)
 
 
 # ---------------------------------------------------------------------------
@@ -1932,8 +2061,10 @@ async def _mcp_session(
 
 
 async def _handle_resources(
-    session, action: str, uri: str | None, pretty: bool, raw: bool, toon: bool
+    session, action: str, uri: str | None, pretty: bool, raw: bool, toon: bool,
+    jq_expr: str | None = None, head: int | None = None,
 ):
+    _out = dict(pretty=pretty, raw=raw, toon=toon, jq_expr=jq_expr, head=head)
     if action == "list":
         result = await session.list_resources()
         data = [
@@ -1945,7 +2076,7 @@ async def _handle_resources(
             }
             for r in result.resources
         ]
-        output_result(data, pretty=pretty, raw=raw, toon=toon)
+        output_result(data, **_out)
     elif action == "templates":
         result = await session.list_resource_templates()
         data = [
@@ -1957,7 +2088,7 @@ async def _handle_resources(
             }
             for t in result.resourceTemplates
         ]
-        output_result(data, pretty=pretty, raw=raw, toon=toon)
+        output_result(data, **_out)
     elif action == "read":
         from pydantic import AnyUrl
 
@@ -1969,7 +2100,7 @@ async def _handle_resources(
             elif hasattr(content, "blob"):
                 parts.append(content.blob)
         text = "\n".join(parts) if parts else ""
-        output_result(text, pretty=pretty, raw=raw, toon=toon)
+        output_result(text, **_out)
 
 
 # ---------------------------------------------------------------------------
@@ -1985,7 +2116,10 @@ async def _handle_prompts(
     pretty: bool,
     raw: bool,
     toon: bool,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
+    _out = dict(pretty=pretty, raw=raw, toon=toon, jq_expr=jq_expr, head=head)
     if action == "list":
         result = await session.list_prompts()
         data = [
@@ -2003,7 +2137,7 @@ async def _handle_prompts(
             }
             for p in result.prompts
         ]
-        output_result(data, pretty=pretty, raw=raw, toon=toon)
+        output_result(data, **_out)
     elif action == "get":
         result = await session.get_prompt(name, arguments or {})
         messages = []
@@ -2016,7 +2150,7 @@ async def _handle_prompts(
                     {"role": msg.role, "content": json.dumps(content.model_dump())}
                 )
         data = {"description": result.description or "", "messages": messages}
-        output_result(data, pretty=pretty, raw=raw, toon=toon)
+        output_result(data, **_out)
 
 
 # ---------------------------------------------------------------------------
@@ -2521,6 +2655,8 @@ def handle_mcp(
     prompt_arguments: dict | None = None,
     search_pattern: str | None = None,
     bake_config: BakeConfig | None = None,
+    jq_expr: str | None = None,
+    head: int | None = None,
 ):
     key = cache_key_override or cache_key_for(source)
 
@@ -2532,6 +2668,8 @@ def handle_mcp(
             prompt_action=prompt_action,
             prompt_name=prompt_name,
             prompt_arguments=prompt_arguments,
+            jq_expr=jq_expr,
+            head=head,
         )
         _dispatch_mcp_call(
             source, is_stdio, auth_headers, env_vars,
@@ -2560,6 +2698,7 @@ def handle_mcp(
             None, None, True, pretty, raw, key, ttl, refresh,
             toon=toon, transport=transport, oauth_provider=oauth_provider,
             search_pattern=search_pattern,
+            jq_expr=jq_expr, head=head,
         )
         return
 
@@ -2604,6 +2743,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,
+        jq_expr=jq_expr, head=head,
     )
 
 
@@ -2786,6 +2926,19 @@ def _build_main_parser() -> argparse.ArgumentParser:
             "of large result sets. Requires @toon-format/cli (npm install -g @toon-format/cli)."
         ),
     )
+    pre.add_argument(
+        "--jq",
+        default=None,
+        metavar="EXPR",
+        help="Filter JSON output through jq (e.g. '.[] | .name'). Requires jq installed.",
+    )
+    pre.add_argument(
+        "--head",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Limit output to first N records (arrays) or N lines (text)",
+    )
     pre.add_argument(
         "--fields",
         default=None,
@@ -3005,13 +3158,15 @@ def _handle_session_operations(
     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
+            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+            jq_expr=pre_args.jq, head=pre_args.head,
         )
         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
+            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+            jq_expr=pre_args.jq, head=pre_args.head,
         )
         return True
     if pre_args.read_resource:
@@ -3019,13 +3174,15 @@ def _handle_session_operations(
             sess_name, "read_resource", {"uri": pre_args.read_resource}
         )
         output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon
+            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+            jq_expr=pre_args.jq, head=pre_args.head,
         )
         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
+            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+            jq_expr=pre_args.jq, head=pre_args.head,
         )
         return True
     if pre_args.get_prompt:
@@ -3040,7 +3197,8 @@ def _handle_session_operations(
             {"name": pre_args.get_prompt, "arguments": p_args},
         )
         output_result(
-            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon
+            result, pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
+            jq_expr=pre_args.jq, head=pre_args.head,
         )
         return True
     if pre_args.list_commands:
@@ -3202,6 +3360,7 @@ def _handle_openapi_mode(
         args, cmd, base_url, auth_headers,
         pre_args.pretty, pre_args.raw, toon=pre_args.toon,
         oauth_provider=oauth_provider,
+        jq_expr=pre_args.jq, head=pre_args.head,
     )
 
 
@@ -3215,6 +3374,11 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
     pre_args, leftover = pre.parse_known_args(global_argv)
     remaining = leftover + tool_argv
 
+    # Validate mutually exclusive output flags
+    if pre_args.jq and pre_args.toon:
+        print("Error: --jq and --toon are mutually exclusive.", file=sys.stderr)
+        sys.exit(1)
+
     # --search implies --list
     search_pattern = pre_args.search_pattern
     if search_pattern:
@@ -3253,6 +3417,8 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             toon=pre_args.toon,
             fields_override=pre_args.fields,
             oauth_provider=oauth_provider,
+            jq_expr=pre_args.jq,
+            head=pre_args.head,
         )
         return
 
@@ -3282,6 +3448,8 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             prompt_arguments=prompt_arguments,
             search_pattern=search_pattern,
             bake_config=bake_config,
+            jq_expr=pre_args.jq,
+            head=pre_args.head,
         )
         return