mcp2cli 3.5.0__tar.gz → 3.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp2cli
-Version: 3.5.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.5.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.5.0 → mcp2cli-3.7.0}/pyproject.toml

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

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

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

{mcp2cli-3.5.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")
@@ -61,6 +63,7 @@ class ParamDef:
     choices: list | None = None
     location: str = "body"  # path|query|header|body|tool_input
     schema: dict = field(default_factory=dict)
+    cli_name: str | None = None  # collision-free argparse flag name
 
 
 @dataclass
@@ -178,8 +181,17 @@ def read_stdin_json(context: str):
         sys.exit(1)
 
 
+def _normalize_schema_type(t):
+    """JSON Schema allows "type": ["integer", "null"] (array form). Reduce it
+    to the single concrete type, dropping "null"; anything else passes through."""
+    if isinstance(t, list):
+        concrete = [x for x in t if x != "null"]
+        return concrete[0] if len(concrete) == 1 else None
+    return t
+
+
 def schema_type_to_python(schema: dict) -> tuple[type | None, str]:
-    t = schema.get("type")
+    t = _normalize_schema_type(schema.get("type"))
     if t == "integer":
         return int, ""
     if t == "number":
@@ -190,6 +202,16 @@ def schema_type_to_python(schema: dict) -> tuple[type | None, str]:
         return str, " (JSON array)"
     if t == "object":
         return str, " (JSON object)"
+    if t is None:
+        # No "type" but an enum: infer the argparse type from the values, so
+        # numeric enums stay callable (otherwise argparse parses the flag as a
+        # string and rejects it against numeric choices).
+        enum = schema.get("enum")
+        if enum and not any(isinstance(v, bool) for v in enum):
+            if all(isinstance(v, int) for v in enum):
+                return int, ""
+            if all(isinstance(v, (int, float)) for v in enum):
+                return float, ""
     return str, ""
 
 
@@ -207,7 +229,7 @@ def _coerce_item(value: str, item_type: str | None):
 def coerce_value(value, schema: dict):
     if value is None:
         return None
-    t = schema.get("type")
+    t = _normalize_schema_type(schema.get("type"))
     if t == "array":
         if isinstance(value, list):
             return value
@@ -218,7 +240,7 @@ def coerce_value(value, schema: dict):
                     return parsed
             except (json.JSONDecodeError, TypeError):
                 pass
-            item_type = schema.get("items", {}).get("type")
+            item_type = _normalize_schema_type(schema.get("items", {}).get("type"))
             if "," in value:
                 return [_coerce_item(v.strip(), item_type) for v in value.split(",")]
             return [_coerce_item(value, item_type)]
@@ -252,13 +274,16 @@ def to_kebab(name: str) -> str:
     return s.replace("_", "-").lower()
 
 
-def _find_toon_cli() -> str | None:
-    """Return the command to invoke the TOON CLI, or None if unavailable."""
+def _find_toon_cli() -> tuple[str, ...] | None:
+    """Return argv for the TOON CLI, or None if unavailable."""
     if shutil.which("toon"):
-        return "toon"
-    # Check for npx (ships with Node.js)
+        return ("toon",)
+    # npx ships with Node.js, but having it says nothing about the package.
+    # `--no` forbids npx's implicit registry download, so a missing package
+    # fails in about a second instead of turning --toon into a network fetch
+    # racing the timeout in _toon_encode.
     if shutil.which("npx"):
-        return "npx @toon-format/cli"
+        return ("npx", "--no", "@toon-format/cli")
     return None
 
 
@@ -269,7 +294,7 @@ def _toon_encode(json_str: str) -> str | None:
         return None
     try:
         result = subprocess.run(
-            cmd.split(),
+            cmd,
             input=json_str,
             capture_output=True,
             text=True,
@@ -299,6 +324,7 @@ _MCP_RENAMED_FIELDS = {
     "mimeType": "mime_type",
     "structuredContent": "structured_content",
     "isError": "is_error",
+    "hasMore": "has_more",
 }
 
 
@@ -499,9 +525,34 @@ def _python_type_name(t: type | None) -> str:
     return getattr(t, "__name__", str(t))
 
 
+def _param_dest(p: "ParamDef") -> str:
+    """Return the argparse destination allocated for a parameter."""
+    return (p.cli_name or p.name).replace("-", "_")
+
+
+def _allocate_param_cli_names(cmd: "CommandDef") -> None:
+    """Assign unique parameter flags without shadowing built-in options."""
+    natural_names = {p.name for p in cmd.params}
+    used = {"help"}
+    if cmd.has_body:
+        used.add("stdin")
+
+    for p in cmd.params:
+        name = p.name
+        if name in used:
+            stem = f"arg-{name}"
+            name = stem
+            suffix = 2
+            while name in used or name in natural_names:
+                name = f"{stem}-{suffix}"
+                suffix += 1
+        p.cli_name = name
+        used.add(name)
+
+
 def _param_to_dict(p: "ParamDef") -> dict:
     d = {
-        "name": p.name,
+        "name": p.cli_name or p.name,
         "type": _python_type_name(p.python_type),
         "required": p.required,
         "description": p.description,
@@ -1494,8 +1545,34 @@ def extract_openapi_commands(spec: dict) -> list[CommandDef]:
 
 def extract_mcp_commands(tools: list[dict]) -> list[CommandDef]:
     commands: list[CommandDef] = []
-    for tool in tools:
-        name = to_kebab(tool.get("name", "unknown"))
+    base_names = [to_kebab(tool.get("name", "unknown")) for tool in tools]
+    reserved_names = set(base_names)
+    cli_names = [""] * len(tools)
+    used_names: set[str] = set()
+    groups: dict[str, list[int]] = {}
+    for index, base_name in enumerate(base_names):
+        groups.setdefault(base_name, []).append(index)
+
+    # Assign aliases from the complete tool-name set so a generated suffix can
+    # never shadow another tool's natural name. Sorting each collision group by
+    # wire name keeps aliases stable when a server reorders tools/list.
+    for base_name in sorted(groups):
+        indices = sorted(
+            groups[base_name],
+            key=lambda index: (tools[index].get("name", "unknown"), index),
+        )
+        for rank, index in enumerate(indices):
+            name = base_name
+            if rank:
+                suffix = 2
+                name = f"{base_name}-{suffix}"
+                while name in reserved_names or name in used_names:
+                    suffix += 1
+                    name = f"{base_name}-{suffix}"
+            cli_names[index] = name
+            used_names.add(name)
+
+    for tool, name in zip(tools, cli_names):
         desc = tool.get("description", "")
         schema = tool.get("inputSchema", {})
         required_fields = set(schema.get("required", []))
@@ -1934,12 +2011,12 @@ def _build_graphql_document(
     types_by_name = {t["name"]: t for t in schema.get("types", []) if t.get("name")}
 
     # Build variables dict from args
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         variables = read_stdin_json("GraphQL variables")
     else:
         variables = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 variables[p.original_name] = coerce_value(val, p.schema)
 
@@ -2473,6 +2550,7 @@ def build_argparse(
             help=escape_argparse_help(cmd.description),
             description=escape_argparse_help(cmd.description),
         )
+        _allocate_param_cli_names(cmd)
         sub.set_defaults(_cmd=cmd)
 
         if cmd.has_body:
@@ -2483,12 +2561,8 @@ def build_argparse(
                 help="Read JSON body/arguments from stdin",
             )
 
-        seen_flags: set[str] = set()
         for p in cmd.params:
-            flag = f"--{p.name}"
-            if flag in seen_flags:
-                continue  # skip duplicate param names (e.g. path + body both have same name)
-            seen_flags.add(flag)
+            flag = f"--{p.cli_name or p.name}"
             kwargs: dict = {}
             if p.python_type is not None:
                 kwargs["type"] = p.python_type
@@ -2506,6 +2580,7 @@ def build_argparse(
             kwargs["help"] = escape_argparse_help(p.description)
             if p.choices:
                 kwargs["choices"] = p.choices
+            kwargs["dest"] = _param_dest(p)
             sub.add_argument(flag, **kwargs)
 
     return parser
@@ -2634,13 +2709,13 @@ def _collect_openapi_params(
 
     for p in cmd.params:
         if p.location == "path":
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 path = path.replace(f"{{{p.original_name}}}", str(val))
 
     if cmd.method == "get":
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is None:
                 continue
             if p.location == "query":
@@ -2648,12 +2723,12 @@ def _collect_openapi_params(
             elif p.location == "header":
                 extra_headers[p.original_name] = str(val)
     else:
-        if getattr(args, "stdin", False):
+        if getattr(args, "stdin", False) is True:
             body = read_stdin_json("OpenAPI request body")
         else:
             body = {}
             for p in cmd.params:
-                val = getattr(args, p.name.replace("-", "_"), None)
+                val = getattr(args, _param_dest(p), None)
                 if p.location == "header":
                     if val is not None:
                         extra_headers[p.original_name] = str(val)
@@ -2678,7 +2753,7 @@ def _collect_openapi_params(
         # Also collect query params for non-GET
         for p in cmd.params:
             if p.location == "query":
-                val = getattr(args, p.name.replace("-", "_"), None)
+                val = getattr(args, _param_dest(p), None)
                 if val is not None:
                     query_params[p.original_name] = coerce_value(val, p.schema)
 
@@ -2763,6 +2838,95 @@ def execute_openapi(
 # ---------------------------------------------------------------------------
 
 
+def _exc_leaves(exc: BaseException) -> list[BaseException]:
+    """Flatten nested exception groups into their leaf exceptions."""
+    nested = getattr(exc, "exceptions", None)
+    if not nested:
+        return [exc]
+    return [leaf for child in nested for leaf in _exc_leaves(child)]
+
+
+def _exc_message(exc: BaseException) -> str:
+    """Flatten an exception group into one terminal-safe line."""
+    parts = []
+    for leaf in _exc_leaves(exc):
+        message = str(leaf) or leaf.__class__.__name__
+        parts.append("; ".join(line.strip() for line in message.splitlines() if line.strip()))
+    return "; ".join(part for part in parts if part) or exc.__class__.__name__
+
+
+def _run_mcp_clean(fn, source: str):
+    """Run an MCP coroutine, reporting failures as one clean error line.
+
+    Transport failures (bad URL, refused connection, 401/403) otherwise reach
+    the terminal as a multi-level anyio ExceptionGroup traceback with the
+    actual cause buried at the bottom. Set MCP2CLI_DEBUG=1 for the traceback.
+    """
+    try:
+        return anyio.run(fn)
+    except SystemExit:
+        raise
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        raise
+    except BaseException as exc:
+        leaves = _exc_leaves(exc)
+        if len(leaves) == 1 and isinstance(leaves[0], (SystemExit, KeyboardInterrupt)):
+            raise leaves[0]
+        if os.environ.get("MCP2CLI_DEBUG"):
+            raise
+        message = _exc_message(exc)
+        lowered = message.lower()
+        if "401" in lowered or "403" in lowered:
+            hint = (
+                " — the server rejected the request; pass credentials with "
+                "--auth-header 'Name:Value' or use the --oauth-* options"
+            )
+        else:
+            hint = ""
+        print(f"Error: cannot use MCP server at {source}: {message}{hint}", file=sys.stderr)
+        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]],
@@ -2782,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,
@@ -2797,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,
@@ -2816,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,
@@ -2839,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,
@@ -2865,7 +3031,9 @@ def run_mcp_http(
             except Exception:
                 return await _with_sse()
 
-    anyio.run(_run)
+    rc = _run_mcp_clean(_run, url)
+    if rc:
+        sys.exit(rc)
 
 
 def run_mcp_stdio(
@@ -2885,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,
@@ -2900,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,
@@ -2921,9 +3091,9 @@ 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()
-                await _mcp_session(
+                return await _mcp_session(
                     session,
                     tool_name,
                     arguments,
@@ -2937,7 +3107,9 @@ def run_mcp_stdio(
                     **extra,
                 )
 
-    anyio.run(_run)
+    rc = _run_mcp_clean(_run, command_str)
+    if rc:
+        sys.exit(rc)
 
 
 async def _mcp_session(
@@ -2956,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,
@@ -2965,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(
@@ -3028,10 +3209,26 @@ async def _mcp_session(
         # isError) with the camelCase wire names, so the envelope does not
         # change shape with the installed SDK major.
         output_result(_mcp_dump(result), pretty=pretty, head=head, json_output=True)
-        return
+        # A failed tool still exits non-zero under --json so callers can detect
+        # it; the envelope on stdout already carries isError for machines.
+        return 1 if _mcp_attr(result, "isError") else 0
 
     text = _extract_content_parts(result.content)
-    output_result(text, pretty=pretty, raw=raw, toon=toon, head=head)
+    payload = text
+    if not payload:
+        # A tool may return only structuredContent with an empty content list.
+        structured = _mcp_attr(result, "structuredContent")
+        if structured is not None:
+            payload = structured
+
+    if _mcp_attr(result, "isError"):
+        # Return the code instead of raising inside the anyio task group, which
+        # would wrap SystemExit in a BaseExceptionGroup traceback.
+        error = payload if isinstance(payload, str) else json.dumps(payload, ensure_ascii=False)
+        print(f"Error: {error or f'tool {tool_name!r} reported an error'}", file=sys.stderr)
+        return 1
+    output_result(payload, pretty=pretty, raw=raw, toon=toon, head=head)
+    return 0
 
 
 # ---------------------------------------------------------------------------
@@ -3091,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,
@@ -3213,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)
@@ -3243,6 +3502,7 @@ def session_start(
             "auth_headers": auth_headers,
             "env_vars": env_vars,
             "transport": transport,
+            "roots": list(roots or []),
         }
     )
 
@@ -3280,13 +3540,25 @@ def session_start(
 
 
 def _extract_content_parts(content_list, *, attrs=("text", "data")) -> str:
-    """Extract text/data/blob from MCP content objects, joined by newline."""
+    """Extract text/data/blob from MCP content objects, joined by newline.
+
+    ``resource_link`` blocks carry neither ``text`` nor ``data`` — only
+    ``uri``/``name`` — so they used to be dropped silently. Render them as
+    ``name: uri`` (or just the URI) instead.
+    """
     parts = []
-    for c in content_list:
+    for content in content_list:
+        is_mapping = isinstance(content, dict)
         for attr in attrs:
-            if hasattr(c, attr):
-                parts.append(getattr(c, attr))
+            value = content.get(attr) if is_mapping else getattr(content, attr, None)
+            if value is not None:
+                parts.append(value)
                 break
+        else:
+            uri = content.get("uri") if is_mapping else getattr(content, "uri", None)
+            if uri is not None:
+                name = content.get("name") if is_mapping else getattr(content, "name", None)
+                parts.append(f"{name}: {uri}" if name else str(uri))
     return "\n".join(parts) if parts else ""
 
 
@@ -3320,7 +3592,7 @@ async def _dispatch_list_tools(session, params):
 
 async def _dispatch_call_tool(session, params):
     result = await session.call_tool(params["name"], params.get("arguments", {}))
-    return _extract_content_parts(result.content)
+    return _mcp_dump(result)
 
 
 async def _dispatch_list_resources(session, params):
@@ -3383,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,
@@ -3391,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,
 }
 
 
@@ -3403,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)
@@ -3523,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
@@ -3533,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":
@@ -3668,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,
@@ -3689,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,
         )
@@ -3772,12 +4052,12 @@ def handle_mcp(
 
     cmd: CommandDef = args._cmd
 
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         arguments = read_stdin_json("MCP tool arguments")
     else:
         arguments = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 arguments[p.original_name] = coerce_value(val, p.schema)
 
@@ -3824,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:
@@ -3836,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)
 
@@ -3847,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)
 
@@ -3861,7 +4141,7 @@ def _fetch_mcp_tools(
                 except Exception:
                     await _via_sse()
 
-    anyio.run(_run)
+    _run_mcp_clean(_run, source)
     return tools_result
 
 
@@ -4046,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",
@@ -4273,6 +4573,7 @@ def _handle_session_operations(
             auth_headers,
             env_vars,
             transport=pre_args.transport,
+            roots=_ROOTS,
         )
         return True
 
@@ -4285,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")
@@ -4366,18 +4674,41 @@ def _handle_session_operations(
         sys.exit(1)
 
     cmd: CommandDef = args._cmd
-    if getattr(args, "stdin", False):
+    if getattr(args, "stdin", False) is True:
         arguments = read_stdin_json(f"session {sess_name} tool arguments")
     else:
         arguments = {}
         for p in cmd.params:
-            val = getattr(args, p.name.replace("-", "_"), None)
+            val = getattr(args, _param_dest(p), None)
             if val is not None:
                 arguments[p.original_name] = coerce_value(val, p.schema)
 
     result = _session_request(
         sess_name, "call_tool", {"name": cmd.tool_name, "arguments": arguments}
     )
+    if isinstance(result, dict) and "isError" in result:
+        content = result.get("content") or []
+        text = _extract_content_parts(content) if isinstance(content, list) else content
+        payload = text or result.get("structuredContent") or ""
+
+        if pre_args.json_output:
+            output_result(result, **_sess_out)
+            if result.get("isError"):
+                sys.exit(1)
+            return True
+
+        if result.get("isError"):
+            error = (
+                payload
+                if isinstance(payload, str)
+                else json.dumps(payload, ensure_ascii=False)
+            )
+            print(
+                f"Error: {error or f'tool {cmd.tool_name!r} reported an error'}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        result = payload
     output_result(result, **_sess_out)
     return True
 
@@ -4517,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:
@@ -4588,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,