mcp2cli 2.7.0__tar.gz → 2.8.1__tar.gz

{mcp2cli-2.7.0 → mcp2cli-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 2.7.0
+Version: 2.8.1
 Summary: Turn any MCP server or OpenAPI spec into a CLI
 Author: Stephan Fitzpatrick
 Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
@@ -216,6 +216,26 @@ Filtering options:
 
 Configs are stored in `~/.config/mcp2cli/baked.json`. Override with `MCP2CLI_CONFIG_DIR`.
 
+### Usage-aware tool ranking
+
+mcp2cli tracks tool invocations locally and uses that data to rank `--list` output, reducing token costs for LLM agents working with large servers.
+
+```bash
+# Default --list: ~1,400 tokens for 96 tools
+mcp2cli @myapi --list
+
+# Top 10 most-used tools, names only: ~20 tokens
+mcp2cli @myapi --list --top 10 --compact
+
+# Sort by most recently used
+mcp2cli @myapi --list --sort recent
+
+# Alphabetical sort
+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`.
+
 ### Output control
 
 ```bash
@@ -286,6 +306,10 @@ Options:
   --refresh               Bypass cache
   --list                  List available subcommands
   --search PATTERN        Search tools by name or description (implies --list)
+  --sort MODE             Sort --list output: usage|recent|alpha|default
+  --top N                 Show only the top N tools in --list output
+  --compact               Space-separated tool names only, no descriptions
+  --verbose               Show full tool descriptions (unwrapped)
   --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body

{mcp2cli-2.7.0 → mcp2cli-2.8.1}/README.md

@@ -197,6 +197,26 @@ Filtering options:
 
 Configs are stored in `~/.config/mcp2cli/baked.json`. Override with `MCP2CLI_CONFIG_DIR`.
 
+### Usage-aware tool ranking
+
+mcp2cli tracks tool invocations locally and uses that data to rank `--list` output, reducing token costs for LLM agents working with large servers.
+
+```bash
+# Default --list: ~1,400 tokens for 96 tools
+mcp2cli @myapi --list
+
+# Top 10 most-used tools, names only: ~20 tokens
+mcp2cli @myapi --list --top 10 --compact
+
+# Sort by most recently used
+mcp2cli @myapi --list --sort recent
+
+# Alphabetical sort
+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`.
+
 ### Output control
 
 ```bash
@@ -267,6 +287,10 @@ Options:
   --refresh               Bypass cache
   --list                  List available subcommands
   --search PATTERN        Search tools by name or description (implies --list)
+  --sort MODE             Sort --list output: usage|recent|alpha|default
+  --top N                 Show only the top N tools in --list output
+  --compact               Space-separated tool names only, no descriptions
+  --verbose               Show full tool descriptions (unwrapped)
   --fields FIELDS         Override GraphQL selection set (e.g. "id name email")
   --pretty                Pretty-print JSON output
   --raw                   Print raw response body

{mcp2cli-2.7.0 → mcp2cli-2.8.1}/pyproject.toml

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

{mcp2cli-2.7.0 → mcp2cli-2.8.1}/src/mcp2cli/__init__.py

@@ -26,6 +26,8 @@ from http.server import HTTPServer, BaseHTTPRequestHandler
 from pathlib import Path
 from urllib.parse import parse_qs, urlparse
 
+from datetime import datetime, timezone
+
 import anyio
 import httpx
 
@@ -33,6 +35,7 @@ CACHE_DIR = Path(
     os.environ.get("MCP2CLI_CACHE_DIR", Path.home() / ".cache" / "mcp2cli")
 )
 DEFAULT_CACHE_TTL = 3600
+USAGE_FILE = CACHE_DIR / "usage.json"
 CONFIG_DIR = Path(
     os.environ.get("MCP2CLI_CONFIG_DIR", Path.home() / ".config" / "mcp2cli")
 )
@@ -387,6 +390,94 @@ def save_cache(key: str, data: dict):
     (CACHE_DIR / f"{key}.json").write_text(json.dumps(data))
 
 
+# ---------------------------------------------------------------------------
+# Usage tracking
+# ---------------------------------------------------------------------------
+
+
+def _load_usage() -> dict:
+    """Load the usage tracking file. Returns empty dict on any failure."""
+    if not USAGE_FILE.exists():
+        return {}
+    try:
+        return json.loads(USAGE_FILE.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _save_usage(data: dict) -> None:
+    """Write usage data. Last-write-wins -- no file locking."""
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    USAGE_FILE.write_text(json.dumps(data, indent=2))
+
+
+def record_usage(source_hash: str, tool_name: str) -> None:
+    """Increment the call count and update last_used for a tool."""
+    usage = _load_usage()
+    bucket = usage.setdefault(source_hash, {})
+    entry = bucket.setdefault(tool_name, {"count": 0, "last_used": ""})
+    entry["count"] += 1
+    entry["last_used"] = datetime.now(timezone.utc).isoformat()
+    _save_usage(usage)
+
+
+def _source_hash_for(source: str) -> str:
+    """Derive a stable hash key from a source URL/command string."""
+    return hashlib.sha256(source.encode()).hexdigest()[:16]
+
+
+def sort_commands(
+    commands: list["CommandDef"],
+    sort_mode: str,
+    source_hash: str,
+) -> list["CommandDef"]:
+    """Sort commands by the given mode using usage data.
+
+    Modes:
+        usage   -- most-called first (default when usage data exists)
+        recent  -- most-recently-used first
+        alpha   -- alphabetical by name
+        default -- original insertion order
+    """
+    if sort_mode == "default":
+        return commands
+    if sort_mode == "alpha":
+        return sorted(commands, key=lambda c: c.name)
+
+    usage = _load_usage().get(source_hash, {})
+    if not usage:
+        return commands  # no data, keep insertion order
+
+    def _usage_key(c: "CommandDef") -> str:
+        return c.tool_name or c.graphql_field_name or c.name
+
+    if sort_mode == "usage":
+        return sorted(
+            commands,
+            key=lambda c: usage.get(_usage_key(c), {}).get("count", 0),
+            reverse=True,
+        )
+    if sort_mode == "recent":
+        return sorted(
+            commands,
+            key=lambda c: usage.get(_usage_key(c), {}).get("last_used", ""),
+            reverse=True,
+        )
+    return commands
+
+
+def _resolve_sort_mode(explicit_sort: str | None, source_hash: str) -> str:
+    """Determine the effective sort mode.
+
+    If the user passed --sort explicitly, use that. Otherwise, default to
+    'usage' when usage data exists for this source, else 'default'.
+    """
+    if explicit_sort is not None:
+        return explicit_sort
+    usage = _load_usage().get(source_hash, {})
+    return "usage" if usage else "default"
+
+
 # ---------------------------------------------------------------------------
 # OAuth support
 # ---------------------------------------------------------------------------
@@ -1225,8 +1316,20 @@ def _wrap_description(description: str, indent: int, total_width: int = 110) ->
     )
 
 
-def list_graphql_commands(commands: list[CommandDef], verbose: bool = False):
+def list_graphql_commands(
+    commands: list[CommandDef],
+    verbose: bool = False,
+    compact: bool = False,
+    source_hash: str = "",
+    sort_mode: str | None = None,
+    top: int | None = None,
+):
     """Group commands by operation type and print."""
+    commands = _apply_list_options(commands, source_hash, sort_mode, top)
+
+    if compact:
+        print(" ".join(cmd.name for cmd in commands))
+        return
 
     groups: dict[str, list[CommandDef]] = {}
     for cmd in commands:
@@ -1364,19 +1467,30 @@ def handle_graphql(
     jq_expr: str | None = None,
     head: int | None = None,
     verbose: bool = False,
+    sort_mode: str | None = None,
+    top: int | None = None,
+    compact: bool = False,
 ):
     """Top-level handler for --graphql mode."""
+    src_hash = _source_hash_for(url)
     schema = load_graphql_schema(url, auth_headers, cache_key, ttl, refresh, oauth_provider=oauth_provider)
     commands = extract_graphql_commands(schema)
 
+    list_kwargs = dict(
+        verbose=verbose, compact=compact,
+        source_hash=src_hash, sort_mode=sort_mode, top=top,
+    )
+
     if list_mode:
-        list_graphql_commands(commands, verbose=verbose)
+        list_graphql_commands(commands, **list_kwargs)
         return
 
     if not remaining:
-        print("Available operations:")
-        list_graphql_commands(commands, verbose=verbose)
-        print("\nUse --list for the same output, or provide a subcommand.")
+        if not compact:
+            print("Available operations:")
+        list_graphql_commands(commands, **list_kwargs)
+        if not compact:
+            print("\nUse --list for the same output, or provide a subcommand.")
         return
 
     pre_for_gql = argparse.ArgumentParser(add_help=False)
@@ -1394,6 +1508,9 @@ def handle_graphql(
         jq_expr=jq_expr, head=head,
     )
 
+    # Record usage after successful execution
+    record_usage(src_hash, cmd.graphql_field_name or cmd.name)
+
 
 # ---------------------------------------------------------------------------
 # Command filtering (bake mode)
@@ -1820,7 +1937,34 @@ def build_argparse(
 # ---------------------------------------------------------------------------
 
 
-def list_openapi_commands(commands: list[CommandDef], verbose: bool = False):
+def _apply_list_options(
+    commands: list[CommandDef],
+    source_hash: str = "",
+    sort_mode: str | None = None,
+    top: int | None = None,
+) -> list[CommandDef]:
+    """Apply sort and top-N filtering to a command list."""
+    effective_sort = _resolve_sort_mode(sort_mode, source_hash)
+    commands = sort_commands(commands, effective_sort, source_hash)
+    if top is not None:
+        commands = commands[:top]
+    return commands
+
+
+def list_openapi_commands(
+    commands: list[CommandDef],
+    verbose: bool = False,
+    compact: bool = False,
+    source_hash: str = "",
+    sort_mode: str | None = None,
+    top: int | None = None,
+):
+    commands = _apply_list_options(commands, source_hash, sort_mode, top)
+
+    if compact:
+        print(" ".join(cmd.name for cmd in commands))
+        return
+
     groups: dict[str, list[CommandDef]] = {}
     for cmd in commands:
         prefix = cmd.name.split("-", 1)[0] if "-" in cmd.name else "other"
@@ -1840,7 +1984,20 @@ def list_openapi_commands(commands: list[CommandDef], verbose: bool = False):
             print(line)
 
 
-def list_mcp_commands(commands: list[CommandDef], verbose: bool = False):
+def list_mcp_commands(
+    commands: list[CommandDef],
+    verbose: bool = False,
+    compact: bool = False,
+    source_hash: str = "",
+    sort_mode: str | None = None,
+    top: int | None = None,
+):
+    commands = _apply_list_options(commands, source_hash, sort_mode, top)
+
+    if compact:
+        print(" ".join(cmd.name for cmd in commands))
+        return
+
     for cmd in commands:
         if cmd.description:
             if verbose:
@@ -2030,6 +2187,10 @@ def run_mcp_http(
     jq_expr: str | None = None,
     head: int | None = None,
     verbose: bool = False,
+    sort_mode: str | None = None,
+    top: int | None = None,
+    compact: bool = False,
+    source_hash: str = "",
 ):
     extra = dict(
         resource_action=resource_action,
@@ -2041,6 +2202,10 @@ def run_mcp_http(
         jq_expr=jq_expr,
         head=head,
         verbose=verbose,
+        sort_mode=sort_mode,
+        top=top,
+        compact=compact,
+        source_hash=source_hash,
     )
 
     async def _run():
@@ -2127,6 +2292,10 @@ def run_mcp_stdio(
     jq_expr: str | None = None,
     head: int | None = None,
     verbose: bool = False,
+    sort_mode: str | None = None,
+    top: int | None = None,
+    compact: bool = False,
+    source_hash: str = "",
 ):
     extra = dict(
         resource_action=resource_action,
@@ -2138,6 +2307,10 @@ def run_mcp_stdio(
         jq_expr=jq_expr,
         head=head,
         verbose=verbose,
+        sort_mode=sort_mode,
+        top=top,
+        compact=compact,
+        source_hash=source_hash,
     )
 
     import anyio
@@ -2190,6 +2363,10 @@ async def _mcp_session(
     jq_expr: str | None = None,
     head: int | None = None,
     verbose: bool = False,
+    sort_mode: str | None = None,
+    top: int | None = None,
+    compact: bool = False,
+    source_hash: str = "",
 ):
     # Handle resource operations
     if resource_action:
@@ -2207,6 +2384,11 @@ async def _mcp_session(
         )
         return
 
+    list_kwargs = dict(
+        verbose=verbose, compact=compact,
+        source_hash=source_hash, sort_mode=sort_mode, top=top,
+    )
+
     if list_mode:
         result = await session.list_tools()
         tools = [
@@ -2223,10 +2405,12 @@ async def _mcp_session(
             if not commands:
                 print(f"\nNo tools matching '{search_pattern}'.")
                 return
-            print(f"\nTools matching '{search_pattern}':")
+            if not compact:
+                print(f"\nTools matching '{search_pattern}':")
         else:
-            print("\nAvailable tools:")
-        list_mcp_commands(commands, verbose=verbose)
+            if not compact:
+                print("\nAvailable tools:")
+        list_mcp_commands(commands, **list_kwargs)
         return
 
     if tool_name is None:
@@ -2845,6 +3029,9 @@ def handle_mcp(
     jq_expr: str | None = None,
     head: int | None = None,
     verbose: bool = False,
+    sort_mode: str | None = None,
+    top: int | None = None,
+    compact: bool = False,
 ):
     # Build a config dict for cache key generation (future-proof)
     config_for_cache = {
@@ -2854,8 +3041,9 @@ def handle_mcp(
         'env_vars': env_vars,
         'is_stdio': is_stdio,
     }
-    
+
     key = cache_key_override or cache_key_for(config_for_cache)
+    src_hash = _source_hash_for(source)
 
     # Resource/prompt operations skip the tool flow entirely
     if resource_action or prompt_action:
@@ -2876,9 +3064,14 @@ def handle_mcp(
         )
         return
 
+    list_kwargs = dict(
+        verbose=verbose, compact=compact,
+        source_hash=src_hash, sort_mode=sort_mode, top=top,
+    )
+
     if list_mode:
         if bake_config and (bake_config.include or bake_config.exclude or bake_config.methods):
-            # Fetch tools, filter, then list — don't delegate to unfiltered path
+            # Fetch tools, filter, then list -- don't delegate to unfiltered path
             tools = _fetch_or_cache_mcp_tools(
                 key, ttl, refresh, source, is_stdio, auth_headers, env_vars,
                 transport=transport, oauth_provider=oauth_provider,
@@ -2887,8 +3080,9 @@ def handle_mcp(
             commands = filter_commands(
                 commands, bake_config.include, bake_config.exclude, bake_config.methods,
             )
-            print("\nAvailable tools:")
-            list_mcp_commands(commands, verbose=verbose)
+            if not compact:
+                print("\nAvailable tools:")
+            list_mcp_commands(commands, **list_kwargs)
             return
         _dispatch_mcp_call(
             source, is_stdio, auth_headers, env_vars,
@@ -2897,6 +3091,8 @@ def handle_mcp(
             search_pattern=search_pattern,
             jq_expr=jq_expr, head=head,
             verbose=verbose,
+            sort_mode=sort_mode, top=top, compact=compact,
+            source_hash=src_hash,
         )
         return
 
@@ -2913,9 +3109,11 @@ def handle_mcp(
         )
 
     if not remaining:
-        print("Available tools:")
-        list_mcp_commands(commands, verbose=verbose)
-        print("\nUse --list for the same output, or provide a subcommand.")
+        if not compact:
+            print("Available tools:")
+        list_mcp_commands(commands, **list_kwargs)
+        if not compact:
+            print("\nUse --list for the same output, or provide a subcommand.")
         return
 
     pre = argparse.ArgumentParser(add_help=False)
@@ -2944,6 +3142,9 @@ def handle_mcp(
         jq_expr=jq_expr, head=head,
     )
 
+    # Record usage after successful execution
+    record_usage(src_hash, cmd.tool_name or cmd.name)
+
 
 def _fetch_mcp_tools(
     source: str,
@@ -3130,6 +3331,30 @@ def _build_main_parser() -> argparse.ArgumentParser:
         dest="verbose",
         help="Show full tool descriptions in --list output, wrapped to terminal width (default: truncated with ...)",
     )
+    pre.add_argument(
+        "--sort",
+        choices=["usage", "recent", "alpha", "default"],
+        default=None,
+        dest="sort_mode",
+        help=(
+            "Sort order for --list output. 'usage' sorts by call frequency, "
+            "'recent' by last-used time, 'alpha' alphabetically, 'default' keeps "
+            "insertion order. When omitted, defaults to 'usage' if usage data "
+            "exists, otherwise 'default'."
+        ),
+    )
+    pre.add_argument(
+        "--top",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Show only the top N tools in --list output (useful for LLM agents)",
+    )
+    pre.add_argument(
+        "--compact",
+        action="store_true",
+        help="Space-separated tool names only, no descriptions (~2 tokens/tool)",
+    )
     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(
@@ -3541,6 +3766,7 @@ def _handle_openapi_mode(
     oauth_provider: "httpx.Auth | None" = None,
 ) -> None:
     """Execute OpenAPI mode: load spec, build parser, execute."""
+    src_hash = _source_hash_for(pre_args.spec)
     spec = load_openapi_spec(
         pre_args.spec,
         auth_headers,
@@ -3555,14 +3781,20 @@ def _handle_openapi_mode(
             commands, bake_config.include, bake_config.exclude, bake_config.methods,
         )
 
+    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,
+    )
+
     if pre_args.list_commands:
         if search_pattern:
             commands = _filter_commands(commands, search_pattern)
             if not commands:
                 print(f"\nNo tools matching '{search_pattern}'.")
                 return
-            print(f"\nTools matching '{search_pattern}':")
-        list_openapi_commands(commands, verbose=pre_args.verbose)
+            if not pre_args.compact:
+                print(f"\nTools matching '{search_pattern}':")
+        list_openapi_commands(commands, **list_kwargs)
         return
 
     if not remaining:
@@ -3608,6 +3840,9 @@ def _handle_openapi_mode(
         jq_expr=pre_args.jq, head=pre_args.head,
     )
 
+    # Record usage after successful execution
+    record_usage(src_hash, cmd.tool_name or cmd.graphql_field_name or cmd.name)
+
 
 def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
     pre = _build_main_parser()
@@ -3665,6 +3900,9 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             jq_expr=pre_args.jq,
             head=pre_args.head,
             verbose=pre_args.verbose,
+            sort_mode=pre_args.sort_mode,
+            top=pre_args.top,
+            compact=pre_args.compact,
         )
         return
 
@@ -3697,6 +3935,9 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             jq_expr=pre_args.jq,
             head=pre_args.head,
             verbose=pre_args.verbose,
+            sort_mode=pre_args.sort_mode,
+            top=pre_args.top,
+            compact=pre_args.compact,
         )
         return