mcp2cli 3.6.0__tar.gz → 3.7.0__tar.gz

{mcp2cli-3.6.0 → mcp2cli-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 3.6.0
+Version: 3.7.0
 Summary: Turn any MCP server or OpenAPI spec into a CLI
 Author: Stephan Fitzpatrick
 Author-email: Stephan Fitzpatrick <stephan@knowsuchagency.com>
@@ -158,6 +158,30 @@ mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 \
   search --query "test"
 ```
 
+### MCP roots and completion
+
+Expose one or more filesystem roots when a server scopes operations to a
+workspace. Paths are converted to `file://` URIs; explicit roots must also use
+the `file://` scheme.
+
+```bash
+mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
+  --root "$PWD" --root file:///var/shared --list
+```
+
+Request prompt-argument or resource-template completions with
+`REF:ARG=PREFIX`:
+
+```bash
+mcp2cli --mcp https://example.com/mcp \
+  --complete "greeting:name=San"
+mcp2cli --mcp https://example.com/mcp \
+  --complete "file:///docs/{topic}:topic=api"
+```
+
+Both options work when starting a persistent session; roots are retained by
+the session daemon and completion requests can be sent through `--session`.
+
 ### OpenAPI mode
 
 ```bash
@@ -338,6 +362,8 @@ Options:
   --base-url URL          Override base URL from spec
   --transport TYPE        MCP HTTP transport: auto|sse|streamable (default: auto)
   --env KEY=VALUE         Env var for MCP stdio server (repeatable)
+  --root PATH|FILE_URI    Expose a filesystem root to an MCP server (repeatable)
+  --complete SPEC         Complete an MCP prompt or resource-template argument
   --oauth                 Enable OAuth (authorization code + PKCE flow)
   --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
   --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)

{mcp2cli-3.6.0 → mcp2cli-3.7.0}/README.md

@@ -139,6 +139,30 @@ mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 \
   search --query "test"
 ```
 
+### MCP roots and completion
+
+Expose one or more filesystem roots when a server scopes operations to a
+workspace. Paths are converted to `file://` URIs; explicit roots must also use
+the `file://` scheme.
+
+```bash
+mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
+  --root "$PWD" --root file:///var/shared --list
+```
+
+Request prompt-argument or resource-template completions with
+`REF:ARG=PREFIX`:
+
+```bash
+mcp2cli --mcp https://example.com/mcp \
+  --complete "greeting:name=San"
+mcp2cli --mcp https://example.com/mcp \
+  --complete "file:///docs/{topic}:topic=api"
+```
+
+Both options work when starting a persistent session; roots are retained by
+the session daemon and completion requests can be sent through `--session`.
+
 ### OpenAPI mode
 
 ```bash
@@ -319,6 +343,8 @@ Options:
   --base-url URL          Override base URL from spec
   --transport TYPE        MCP HTTP transport: auto|sse|streamable (default: auto)
   --env KEY=VALUE         Env var for MCP stdio server (repeatable)
+  --root PATH|FILE_URI    Expose a filesystem root to an MCP server (repeatable)
+  --complete SPEC         Complete an MCP prompt or resource-template argument
   --oauth                 Enable OAuth (authorization code + PKCE flow)
   --oauth-client-id ID    OAuth client ID (supports env:/file: prefixes)
   --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)

{mcp2cli-3.6.0 → mcp2cli-3.7.0}/pyproject.toml

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

{mcp2cli-3.6.0 → mcp2cli-3.7.0}/pyproject.toml.orig

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

{mcp2cli-3.6.0 → mcp2cli-3.7.0}/src/mcp2cli/__init__.py

@@ -38,6 +38,8 @@ CACHE_DIR = Path(
     os.environ.get("MCP2CLI_CACHE_DIR", Path.home() / ".cache" / "mcp2cli")
 )
 DEFAULT_CACHE_TTL = 3600
+# Client-side capability the user opted into (see --root).
+_ROOTS: list[str] = []
 USAGE_FILE = CACHE_DIR / "usage.json"
 CONFIG_DIR = Path(
     os.environ.get("MCP2CLI_CONFIG_DIR", Path.home() / ".config" / "mcp2cli")
@@ -322,6 +324,7 @@ _MCP_RENAMED_FIELDS = {
     "mimeType": "mime_type",
     "structuredContent": "structured_content",
     "isError": "is_error",
+    "hasMore": "has_more",
 }
 
 
@@ -2884,6 +2887,46 @@ def _run_mcp_clean(fn, source: str):
         sys.exit(1)
 
 
+def _normalize_root(raw: str) -> str:
+    """Return a validated file URI for one ``--root`` value."""
+    if "://" in raw:
+        if not raw.casefold().startswith("file://"):
+            raise ValueError(
+                f"--root expects a filesystem path or file:// URI, got {raw!r}"
+            )
+        uri = raw
+    else:
+        uri = Path(raw).expanduser().resolve().as_uri()
+
+    from mcp import types
+
+    try:
+        return str(types.Root(uri=uri).uri)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"invalid --root value {raw!r}: {exc}") from exc
+
+
+def _roots_callback(root_uris: list[str] | None = None):
+    """Answer ``roots/list`` from validated file URIs, if any were given."""
+    configured_roots = tuple(_ROOTS if root_uris is None else root_uris)
+    if not configured_roots:
+        return None
+
+    from mcp import types
+
+    async def list_roots(context=None):
+        roots = [
+            types.Root(
+                uri=uri,
+                name=Path(urlparse(uri).path).name or uri,
+            )
+            for uri in configured_roots
+        ]
+        return types.ListRootsResult(roots=roots)
+
+    return list_roots
+
+
 def run_mcp_http(
     url: str,
     auth_headers: list[tuple[str, str]],
@@ -2903,6 +2946,7 @@ def run_mcp_http(
     prompt_action: str | None = None,
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
+    complete_spec: str | None = None,
     search_pattern: str | None = None,
     head: int | None = None,
     verbose: bool = False,
@@ -2918,6 +2962,7 @@ def run_mcp_http(
         prompt_action=prompt_action,
         prompt_name=prompt_name,
         prompt_arguments=prompt_arguments,
+        complete_spec=complete_spec,
         search_pattern=search_pattern,
         head=head,
         verbose=verbose,
@@ -2937,7 +2982,7 @@ def run_mcp_http(
             async with _streamable_streams(
                 url, headers=headers, auth=oauth_provider
             ) as (read, write):
-                async with ClientSession(read, write) as session:
+                async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                     await session.initialize()
                     return await _mcp_session(
                         session,
@@ -2960,7 +3005,7 @@ def run_mcp_http(
                 read,
                 write,
             ):
-                async with ClientSession(read, write) as session:
+                async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                     await session.initialize()
                     return await _mcp_session(
                         session,
@@ -3008,6 +3053,7 @@ def run_mcp_stdio(
     prompt_action: str | None = None,
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
+    complete_spec: str | None = None,
     search_pattern: str | None = None,
     head: int | None = None,
     verbose: bool = False,
@@ -3023,6 +3069,7 @@ def run_mcp_stdio(
         prompt_action=prompt_action,
         prompt_name=prompt_name,
         prompt_arguments=prompt_arguments,
+        complete_spec=complete_spec,
         search_pattern=search_pattern,
         head=head,
         verbose=verbose,
@@ -3044,7 +3091,7 @@ def run_mcp_stdio(
         params = StdioServerParameters(command=parts[0], args=parts[1:], env=env)
 
         async with stdio_client(params) as (read, write):
-            async with ClientSession(read, write) as session:
+            async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                 await session.initialize()
                 return await _mcp_session(
                     session,
@@ -3081,6 +3128,7 @@ async def _mcp_session(
     prompt_action: str | None = None,
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
+    complete_spec: str | None = None,
     search_pattern: str | None = None,
     head: int | None = None,
     verbose: bool = False,
@@ -3090,6 +3138,14 @@ async def _mcp_session(
     source_hash: str = "",
     json_output: bool = False,
 ):
+    # Handle completion requests
+    if complete_spec:
+        await _handle_completion(
+            session, complete_spec, pretty, raw, toon, head=head,
+            json_output=json_output,
+        )
+        return
+
     # Handle resource operations
     if resource_action:
         await _handle_resources(
@@ -3232,6 +3288,67 @@ async def _handle_resources(
 # ---------------------------------------------------------------------------
 
 
+def parse_complete_spec(spec: str) -> tuple[str, str, str]:
+    """Parse ``REF:ARG=PREFIX`` into (ref, argument, prefix).
+
+    ``REF`` is a prompt name, or a resource URI template when it contains
+    ``://`` — in which case the scheme's own colons must not be mistaken for
+    the ref/arg separator.
+    """
+    ref_part, sep, prefix = spec.partition("=")
+    if not sep:
+        print(
+            "Error: --complete expects REF:ARG=PREFIX (e.g. 'my-prompt:city=San')",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    ref, sep, argument = ref_part.rpartition(":")
+    if not sep or not ref or not argument:
+        print(
+            f"Error: --complete could not split {ref_part!r} into REF:ARG",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return ref, argument, prefix
+
+
+async def _completion_data(session, spec: str) -> dict:
+    """Run ``completion/complete`` and return its stable wire-shaped payload."""
+    from mcp import types
+
+    ref_name, argument, prefix = parse_complete_spec(spec)
+    if "://" in ref_name or "{" in ref_name:
+        ref = types.ResourceTemplateReference(
+            type="ref/resource", uri=ref_name
+        )
+    else:
+        ref = types.PromptReference(type="ref/prompt", name=ref_name)
+
+    result = await session.complete(ref, {"name": argument, "value": prefix})
+    completion = result.completion
+    return {
+        "values": list(completion.values or []),
+        "total": completion.total,
+        "hasMore": _mcp_attr(completion, "hasMore"),
+    }
+
+
+async def _handle_completion(
+    session,
+    spec: str,
+    pretty: bool,
+    raw: bool,
+    toon: bool,
+    head: int | None = None,
+    json_output: bool = False,
+):
+    """Run ``completion/complete`` for a prompt or resource-template argument."""
+    data = await _completion_data(session, spec)
+    output_result(
+        data, pretty=pretty, raw=raw, toon=toon, head=head, json_output=json_output
+    )
+
+
 async def _handle_prompts(
     session,
     action: str,
@@ -3354,6 +3471,7 @@ def session_start(
     auth_headers: list[tuple[str, str]],
     env_vars: dict[str, str],
     transport: str = "auto",
+    roots: list[str] | None = None,
 ):
     """Start a persistent session daemon."""
     SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
@@ -3384,6 +3502,7 @@ def session_start(
             "auth_headers": auth_headers,
             "env_vars": env_vars,
             "transport": transport,
+            "roots": list(roots or []),
         }
     )
 
@@ -3536,6 +3655,10 @@ async def _dispatch_get_prompt(session, params):
     return {"description": result.description or "", "messages": messages}
 
 
+async def _dispatch_complete(session, params):
+    return await _completion_data(session, params["spec"])
+
+
 _SESSION_DISPATCH = {
     "list_tools": _dispatch_list_tools,
     "call_tool": _dispatch_call_tool,
@@ -3544,6 +3667,7 @@ _SESSION_DISPATCH = {
     "list_resource_templates": _dispatch_list_resource_templates,
     "list_prompts": _dispatch_list_prompts,
     "get_prompt": _dispatch_get_prompt,
+    "complete": _dispatch_complete,
 }
 
 
@@ -3556,6 +3680,7 @@ def _run_session_daemon(config_json: str):
     auth_headers = [tuple(h) for h in config["auth_headers"]]
     env_vars = config["env_vars"]
     transport = config["transport"]
+    roots = config.get("roots", [])
 
     sock_path = _session_sock_path(name)
     meta_path = _session_meta_path(name)
@@ -3676,7 +3801,7 @@ def _run_session_daemon(config_json: str):
             env = {**os.environ, **env_vars}
             params = StdioServerParameters(command=parts[0], args=parts[1:], env=env)
             async with stdio_client(params) as (read, write):
-                async with ClientSession(read, write) as session:
+                async with ClientSession(read, write, list_roots_callback=_roots_callback(roots)) as session:
                     await _run_with_session(session)
         else:
             headers = dict(auth_headers) if auth_headers else None
@@ -3686,14 +3811,14 @@ def _run_session_daemon(config_json: str):
                     read,
                     write,
                 ):
-                    async with ClientSession(read, write) as session:
+                    async with ClientSession(read, write, list_roots_callback=_roots_callback(roots)) as session:
                         await _run_with_session(session)
 
             async def _via_sse():
                 from mcp.client.sse import sse_client
 
                 async with sse_client(source, headers=headers) as (read, write):
-                    async with ClientSession(read, write) as session:
+                    async with ClientSession(read, write, list_roots_callback=_roots_callback(roots)) as session:
                         await _run_with_session(session)
 
             if transport == "sse":
@@ -3821,6 +3946,7 @@ def handle_mcp(
     prompt_action: str | None = None,
     prompt_name: str | None = None,
     prompt_arguments: dict | None = None,
+    complete_spec: str | None = None,
     search_pattern: str | None = None,
     bake_config: BakeConfig | None = None,
     head: int | None = None,
@@ -3842,14 +3968,15 @@ def handle_mcp(
     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:
+    # Resource/prompt/completion operations skip the tool flow entirely
+    if resource_action or prompt_action or complete_spec:
         extra = dict(
             resource_action=resource_action,
             resource_uri=resource_uri,
             prompt_action=prompt_action,
             prompt_name=prompt_name,
             prompt_arguments=prompt_arguments,
+            complete_spec=complete_spec,
             head=head,
             json_output=json_output,
         )
@@ -3977,7 +4104,7 @@ def _fetch_mcp_tools(
             env = {**os.environ, **env_vars}
             params = StdioServerParameters(command=parts[0], args=parts[1:], env=env)
             async with stdio_client(params) as (read, write):
-                async with ClientSession(read, write) as session:
+                async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                     await session.initialize()
                     await _extract_tools(session)
         else:
@@ -3989,7 +4116,7 @@ def _fetch_mcp_tools(
                 async with _streamable_streams(
                     source, headers=headers, auth=oauth_provider
                 ) as (read, write):
-                    async with ClientSession(read, write) as session:
+                    async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                         await session.initialize()
                         await _extract_tools(session)
 
@@ -4000,7 +4127,7 @@ def _fetch_mcp_tools(
                     read,
                     write,
                 ):
-                    async with ClientSession(read, write) as session:
+                    async with ClientSession(read, write, list_roots_callback=_roots_callback()) as session:
                         await session.initialize()
                         await _extract_tools(session)
 
@@ -4199,6 +4326,26 @@ def _build_main_parser() -> argparse.ArgumentParser:
         default=[],
         help="Environment variable KEY=VALUE for MCP stdio (repeatable)",
     )
+    pre.add_argument(
+        "--root",
+        action="append",
+        default=[],
+        metavar="PATH|FILE_URI",
+        help=(
+            "Expose a filesystem path or file:// URI to the server (repeatable). "
+            "Workspace-scoped servers request these via roots/list."
+        ),
+    )
+    pre.add_argument(
+        "--complete",
+        default=None,
+        metavar="REF:ARG=PREFIX",
+        help=(
+            "Ask the server to complete an argument value, e.g. "
+            "--complete 'my-prompt:city=San'. REF is a prompt name, or a "
+            "resource URI template when it contains '://'."
+        ),
+    )
     pre.add_argument(
         "--oauth",
         action="store_true",
@@ -4426,6 +4573,7 @@ def _handle_session_operations(
             auth_headers,
             env_vars,
             transport=pre_args.transport,
+            roots=_ROOTS,
         )
         return True
 
@@ -4438,6 +4586,13 @@ def _handle_session_operations(
         pretty=pre_args.pretty, raw=pre_args.raw, toon=pre_args.toon,
         json_output=pre_args.json_output,
     )
+    if pre_args.complete:
+        result = _session_request(
+            sess_name, "complete", {"spec": pre_args.complete}
+        )
+        output_result(result, head=pre_args.head, **_sess_out)
+        return True
+
 
     if pre_args.list_resources:
         result = _session_request(sess_name, "list_resources")
@@ -4693,6 +4848,12 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
     pre_args, leftover = pre.parse_known_args(global_argv)
     remaining = leftover + tool_argv
 
+    try:
+        _ROOTS[:] = [_normalize_root(raw) for raw in pre_args.root]
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
     # --search implies --list
     search_pattern = pre_args.search_pattern
     if search_pattern:
@@ -4764,6 +4925,7 @@ def _main_impl(argv: list[str], bake_config: BakeConfig | None = None):
             prompt_action=prompt_action,
             prompt_name=prompt_name,
             prompt_arguments=prompt_arguments,
+            complete_spec=pre_args.complete,
             search_pattern=search_pattern,
             bake_config=bake_config,
             head=pre_args.head,