comate-cli 0.7.2__tar.gz → 0.7.3__tar.gz

{comate_cli-0.7.2 → comate_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.7.2
+Version: 0.7.3
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk
@@ -42,6 +42,18 @@ uv tool install comate-cli
 comate
 ```
 
+## MCP
+
+`comate mcp` supports Claude Code compatible MCP configuration commands for common add/list/get/remove flows.
+
+```bash
+comate mcp add firecrawl npx -y firecrawl-mcp
+comate mcp add -t http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ..."
+comate mcp add-json ctx '{"type":"http","url":"https://example.test/mcp"}'
+```
+
+Supported scopes are `local` (default), `project`, and `user`. Comate stores MCP configuration under `.agent` / `~/.agent`; it does not read or modify Claude Code configuration files.
+
 ## 排错 / Troubleshooting
 
 ### 看不到错误信息但行为异常

{comate_cli-0.7.2 → comate_cli-0.7.3}/README.md

@@ -15,6 +15,18 @@ uv tool install comate-cli
 comate
 ```
 
+## MCP
+
+`comate mcp` supports Claude Code compatible MCP configuration commands for common add/list/get/remove flows.
+
+```bash
+comate mcp add firecrawl npx -y firecrawl-mcp
+comate mcp add -t http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer ..."
+comate mcp add-json ctx '{"type":"http","url":"https://example.test/mcp"}'
+```
+
+Supported scopes are `local` (default), `project`, and `user`. Comate stores MCP configuration under `.agent` / `~/.agent`; it does not read or modify Claude Code configuration files.
+
 ## 排错 / Troubleshooting
 
 ### 看不到错误信息但行为异常

{comate_cli-0.7.2 → comate_cli-0.7.3}/comate_cli/mcp_cli.py

@@ -2,15 +2,19 @@ from __future__ import annotations
 
 import argparse
 import asyncio
+import json
 import sys
+from pathlib import Path
 from typing import Any
 
 from comate_agent_sdk.mcp import (
     McpConfigError,
     collect_mcp_server_health,
     load_effective_servers,
+    load_effective_servers_with_sources,
     load_scope_servers,
     scope_mcp_path,
+    validate_server_config,
     write_mcp_servers_to_path,
 )
 from comate_agent_sdk.mcp.types import McpServerConfig
@@ -22,6 +26,8 @@ from comate_cli.terminal_agent.figures import (
     ELLIPSIS,
 )
 
+_WRITABLE_SCOPES: tuple[str, ...] = ("user", "project", "local")
+
 
 class McpCliError(ValueError):
     def __init__(self, message: str, *, exit_code: int = 2) -> None:
@@ -56,21 +62,24 @@ def _build_parser() -> argparse.ArgumentParser:
 
     add_parser = subparsers.add_parser("add", help="Add an MCP server to comate")
     add_parser.add_argument(
+        "-s",
         "--scope",
-        choices=("user", "project"),
-        default="user",
-        help="Config scope (default: user)",
+        choices=("local", "user", "project"),
+        default="local",
+        help="Config scope (default: local)",
     )
     add_parser.add_argument(
+        "-t",
         "--transport",
-        choices=("http", "stdio"),
+        choices=("stdio", "http", "sse"),
         help="Server transport (default: stdio)",
     )
     add_parser.add_argument(
+        "-H",
         "--header",
         action="append",
         default=[],
-        help='HTTP header in format "Key: Value" (can repeat)',
+        help='HTTP/SSE header in format "Key: Value" (can repeat)',
     )
     add_parser.add_argument(
         "-e",
@@ -79,14 +88,43 @@ def _build_parser() -> argparse.ArgumentParser:
         default=[],
         help='Environment variable in format "KEY=VALUE" (can repeat)',
     )
+    add_parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="Overwrite if server already exists in the same scope",
+    )
+    add_parser.add_argument("--client-id", dest="client_id")
+    add_parser.add_argument("--client-secret", action="store_true", default=False)
+    add_parser.add_argument("--callback-port")
     add_parser.add_argument("name")
     add_parser.add_argument("command_or_url", nargs="?")
 
+    add_json_parser = subparsers.add_parser("add-json", help="Add an MCP server from a JSON config")
+    add_json_parser.add_argument(
+        "-s",
+        "--scope",
+        choices=("local", "user", "project"),
+        default="local",
+        help="Config scope (default: local)",
+    )
+    add_json_parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="Overwrite if server already exists in the same scope",
+    )
+    add_json_parser.add_argument("--client-id", dest="client_id")
+    add_json_parser.add_argument("--client-secret", action="store_true", default=False)
+    add_json_parser.add_argument("--callback-port")
+    add_json_parser.add_argument("name")
+    add_json_parser.add_argument("json")
+
     get_parser = subparsers.add_parser("get", help="Get details about an MCP server")
     get_parser.add_argument("name")
     get_parser.add_argument(
         "--scope",
-        choices=("user", "project", "effective"),
+        choices=("local", "user", "project", "effective"),
         default="effective",
         help="Read from specific scope or merged effective view (default: effective)",
     )
@@ -94,7 +132,7 @@ def _build_parser() -> argparse.ArgumentParser:
     list_parser = subparsers.add_parser("list", help="List configured MCP servers")
     list_parser.add_argument(
         "--scope",
-        choices=("user", "project", "effective"),
+        choices=("local", "user", "project", "effective"),
         default="effective",
         help="List specific scope or merged effective view (default: effective)",
     )
@@ -103,24 +141,24 @@ def _build_parser() -> argparse.ArgumentParser:
     remove_parser.add_argument("name")
     remove_parser.add_argument(
         "--scope",
-        choices=("user", "project"),
-        default="user",
-        help="Delete from scope (default: user)",
+        choices=("local", "user", "project"),
+        default=None,
+        help="Delete from scope; omitted means auto-detect",
     )
 
     return parser
 
 
 def _scope_label(scope: str) -> str:
+    if scope == "local":
+        return "Local config (private to you in this project)"
     if scope == "project":
         return "Project config (private to this project)"
     return "User config (~/.agent/.mcp.json)"
 
 
 def _effective_source_label(source: str) -> str:
-    if source == "project":
-        return "Project config (private to this project)"
-    return "User config (~/.agent/.mcp.json)"
+    return _scope_label(source)
 
 
 def _parse_header_entries(entries: list[str]) -> dict[str, str]:
@@ -161,6 +199,102 @@ def _split_trailing_command_args(argv: list[str]) -> tuple[list[str], list[str]]
     return list(argv[:separator_index]), list(argv[separator_index + 1 :])
 
 
+def _normalize_add_unknown_args(unknown: list[str]) -> list[str]:
+    if unknown and unknown[0] == "--":
+        return unknown[1:]
+    return list(unknown)
+
+
+def _split_add_args(argv: list[str]) -> tuple[list[str], list[str]]:
+    if not argv or argv[0] != "add":
+        return list(argv), []
+
+    tokens = list(argv[1:])
+    if "--" in tokens:
+        separator_index = tokens.index("--")
+        before_separator = tokens[:separator_index]
+        after_separator = tokens[separator_index + 1 :]
+    else:
+        before_separator = tokens
+        after_separator = []
+
+    option_args: list[str] = []
+    positional_args: list[str] = []
+    extra_args: list[str] = []
+    positional_count = 0
+    value_options = {
+        "-s",
+        "--scope",
+        "-t",
+        "--transport",
+        "-H",
+        "--header",
+        "-e",
+        "--env",
+        "--client-id",
+        "--callback-port",
+    }
+    flag_options = {"--force", "--client-secret"}
+    remote_tail_value_options = {"-H", "--header", "--client-id", "--callback-port"}
+    remote_tail_flag_options = {"--client-secret"}
+    transport = "stdio"
+
+    index = 0
+    while index < len(before_separator):
+        token = before_separator[index]
+        if positional_count >= 2:
+            if transport in {"http", "sse"} and token in remote_tail_value_options:
+                option_args.append(token)
+                if index + 1 < len(before_separator):
+                    option_args.append(before_separator[index + 1])
+                index += 2
+                continue
+            if transport in {"http", "sse"} and token in remote_tail_flag_options:
+                option_args.append(token)
+                index += 1
+                continue
+            if transport in {"http", "sse"} and any(
+                token.startswith(f"{option}=")
+                for option in remote_tail_value_options
+                if option.startswith("--")
+            ):
+                option_args.append(token)
+                index += 1
+                continue
+            extra_args.extend(before_separator[index:])
+            break
+
+        if positional_count < 2:
+            if token in value_options:
+                option_args.append(token)
+                if index + 1 < len(before_separator):
+                    option_args.append(before_separator[index + 1])
+                    if token in {"-t", "--transport"}:
+                        transport = before_separator[index + 1].strip().lower()
+                index += 2
+                continue
+            if any(token.startswith(f"{option}=") for option in value_options if option.startswith("--")):
+                option_args.append(token)
+                if token.startswith("--transport="):
+                    transport = token.split("=", 1)[1].strip().lower()
+                index += 1
+                continue
+            if token in flag_options:
+                option_args.append(token)
+                index += 1
+                continue
+            if token.startswith("-"):
+                option_args.extend(before_separator[index:])
+                return ["add", *option_args, *positional_args], [*extra_args, *after_separator]
+
+        positional_args.append(token)
+        positional_count += 1
+        index += 1
+
+    extra_args.extend(after_separator)
+    return ["add", *option_args, *positional_args], extra_args
+
+
 def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
     transport = str(args.transport or "stdio").strip().lower()
     header_entries = [str(item) for item in list(args.header or [])]
@@ -168,16 +302,26 @@ def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
     command_or_url = str(args.command_or_url or "").strip()
     remainder = [str(item) for item in list(getattr(args, "extra_args", []) or [])]
 
-    if transport == "http":
+    if (
+        getattr(args, "client_id", None)
+        or bool(getattr(args, "client_secret", False))
+        or getattr(args, "callback_port", None)
+    ):
+        raise McpCliError(
+            "OAuth flags are not supported by comate mcp add yet. "
+            "Use headers for token-based HTTP/SSE MCP servers, or add a Comate-native oauth object via .mcp.json."
+        )
+
+    if transport in {"http", "sse"}:
         if env_entries:
             raise McpCliError("--env is only supported for stdio transport")
         if not command_or_url:
-            raise McpCliError("HTTP transport requires <commandOrUrl> as URL")
+            raise McpCliError(f"{transport.upper()} transport requires <commandOrUrl> as URL")
         if remainder:
-            raise McpCliError("HTTP transport does not accept trailing command args")
+            raise McpCliError(f"{transport.upper()} transport does not accept trailing command args")
         headers = _parse_header_entries(header_entries)
         cfg: dict[str, Any] = {
-            "type": "http",
+            "type": transport,
             "url": command_or_url,
         }
         if headers:
@@ -185,7 +329,7 @@ def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
         return cfg  # type: ignore[return-value]
 
     if header_entries:
-        raise McpCliError("--header is only supported for http transport")
+        raise McpCliError("--header is only supported for http/sse transport")
     stdio_args = list(remainder)
     if not command_or_url and stdio_args:
         command_or_url = stdio_args.pop(0)
@@ -194,6 +338,7 @@ def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
 
     env = _parse_env_entries(env_entries)
     cfg = {
+        "type": "stdio",
         "command": command_or_url,
     }
     if stdio_args:
@@ -203,6 +348,14 @@ def _build_add_server_config(args: argparse.Namespace) -> McpServerConfig:
     return cfg  # type: ignore[return-value]
 
 
+def _has_oauth_flags(args: argparse.Namespace) -> bool:
+    return bool(
+        getattr(args, "client_id", None)
+        or bool(getattr(args, "client_secret", False))
+        or getattr(args, "callback_port", None)
+    )
+
+
 def _load_servers_by_scope(*, scope: str, project_root: PathInput | None) -> dict[str, McpServerConfig]:
     if scope == "effective":
         return load_effective_servers(project_root=project_root)
@@ -214,13 +367,7 @@ def _read_effective_server_with_source(
     name: str,
     project_root: PathInput | None,
 ) -> tuple[McpServerConfig, str] | None:
-    user_servers = load_scope_servers(scope="user", project_root=project_root)
-    project_servers = load_scope_servers(scope="project", project_root=project_root)
-    if name in project_servers:
-        return project_servers[name], "project"
-    if name in user_servers:
-        return user_servers[name], "user"
-    return None
+    return load_effective_servers_with_sources(project_root=project_root).get(name)
 
 
 def _render_health_status(
@@ -250,6 +397,49 @@ def _format_server_endpoint(cfg: McpServerConfig) -> str:
     return " ".join([command, *str_args]).strip()
 
 
+def _write_server_to_scope(
+    *,
+    name: str,
+    config: McpServerConfig,
+    scope: str,
+    project_root: PathInput | None,
+    force: bool = False,
+) -> tuple[Path, bool]:
+    servers = load_scope_servers(
+        scope=scope,
+        project_root=project_root,
+        include_disabled=True,
+    )  # type: ignore[arg-type]
+    existed = name in servers
+    if existed and not force:
+        raise McpCliError(
+            f"MCP server '{name}' already exists in {scope} scope. "
+            f"Use --force to overwrite.",
+            exit_code=1,
+        )
+    servers[name] = config
+    path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
+    write_mcp_servers_to_path(path=path, servers=servers)
+    return path, existed
+
+
+def _find_scopes_containing_server(
+    *,
+    name: str,
+    project_root: PathInput | None,
+) -> list[str]:
+    found: list[str] = []
+    for scope in _WRITABLE_SCOPES:
+        servers = load_scope_servers(
+            scope=scope,
+            project_root=project_root,
+            include_disabled=True,
+        )  # type: ignore[arg-type]
+        if name in servers:
+            found.append(scope)
+    return found
+
+
 def _cmd_add(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
     scope = str(args.scope)
     name = str(args.name).strip()
@@ -257,12 +447,48 @@ def _cmd_add(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
         raise McpCliError("Server name cannot be empty")
 
     config = _build_add_server_config(args)
-    servers = load_scope_servers(scope=scope, project_root=project_root)  # type: ignore[arg-type]
-    existed = name in servers
-    servers[name] = config
+    path, existed = _write_server_to_scope(
+        name=name,
+        config=config,
+        scope=scope,
+        project_root=project_root,
+        force=bool(getattr(args, "force", False)),
+    )
 
-    path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
-    write_mcp_servers_to_path(path=path, servers=servers)
+    action = "Updated" if existed else "Added"
+    sys.stdout.write(
+        f"{action} MCP server '{name}' in {scope} scope: {path.expanduser()}\n"
+    )
+
+
+def _cmd_add_json(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
+    if _has_oauth_flags(args):
+        raise McpCliError(
+            "OAuth flags are not supported by comate mcp add-json yet. "
+            "Use headers for token-based HTTP/SSE MCP servers, or add a Comate-native oauth object via .mcp.json."
+        )
+
+    scope = str(args.scope)
+    name = str(args.name).strip()
+    if not name:
+        raise McpCliError("Server name cannot be empty")
+
+    try:
+        raw = json.loads(str(args.json))
+    except json.JSONDecodeError as exc:
+        raise McpCliError(f"Invalid JSON: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise McpCliError("MCP server JSON must be an object")
+
+    target_path = scope_mcp_path(scope=scope, project_root=project_root)  # type: ignore[arg-type]
+    config = validate_server_config(alias=name, cfg=raw, path=target_path)
+    path, existed = _write_server_to_scope(
+        name=name,
+        config=config,
+        scope=scope,
+        project_root=project_root,
+        force=bool(getattr(args, "force", False)),
+    )
 
     action = "Updated" if existed else "Added"
     sys.stdout.write(
@@ -271,12 +497,34 @@ def _cmd_add(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
 
 
 def _cmd_remove(args: argparse.Namespace, *, project_root: PathInput | None) -> None:
-    scope = str(args.scope)
     name = str(args.name).strip()
     if not name:
         raise McpCliError("Server name cannot be empty")
 
-    servers = load_scope_servers(scope=scope, project_root=project_root)  # type: ignore[arg-type]
+    explicit_scope = getattr(args, "scope", None)
+    if explicit_scope is None:
+        found = _find_scopes_containing_server(name=name, project_root=project_root)
+        if not found:
+            raise McpCliError(f"MCP server '{name}' not found.", exit_code=1)
+        if len(found) > 1:
+            scope_list = ", ".join(found)
+            suggestions = "; ".join(
+                f"comate mcp remove {name!r} --scope {scope}" for scope in found
+            )
+            raise McpCliError(
+                f"MCP server '{name}' exists in multiple scopes: {scope_list}. "
+                f"Specify one: {suggestions}",
+                exit_code=1,
+            )
+        scope = found[0]
+    else:
+        scope = str(explicit_scope)
+
+    servers = load_scope_servers(
+        scope=scope,
+        project_root=project_root,
+        include_disabled=True,
+    )  # type: ignore[arg-type]
     if name not in servers:
         raise McpCliError(
             f"MCP server '{name}' not found in {scope} scope.",
@@ -334,6 +582,7 @@ def _cmd_get(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
             raise McpCliError(f"MCP server '{name}' not found.", exit_code=1)
         cfg, source = resolved
         scope_line = _effective_source_label(source)
+        remove_scope = source
     else:
         servers = load_scope_servers(scope=scope, project_root=project_root)  # type: ignore[arg-type]
         cfg = servers.get(name)
@@ -343,6 +592,7 @@ def _cmd_get(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
                 exit_code=1,
             )
         scope_line = _scope_label(scope)
+        remove_scope = scope
 
     health_rows = asyncio.run(collect_mcp_server_health(servers={name: cfg}))
     status = f"{CROSS_MARK} Not connected"
@@ -380,10 +630,6 @@ def _cmd_get(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
             for key in sorted(env.keys()):
                 lines.append(f"    {key}: {env[key]}")
 
-    if scope == "effective":
-        remove_scope = "project" if "Project config" in scope_line else "user"
-    else:
-        remove_scope = scope
     lines.append("")
     lines.append(
         f'To remove this server, run: comate mcp remove "{name}" --scope {remove_scope}'
@@ -393,8 +639,14 @@ def _cmd_get(args: argparse.Namespace, *, project_root: PathInput | None) -> Non
 
 def run_mcp_command(argv: list[str], *, project_root: PathInput | None = None) -> None:
     parser = _build_parser()
-    parser_argv, trailing_args = _split_trailing_command_args(argv)
-    parsed = parser.parse_args(parser_argv)
+    if argv and argv[0] == "add":
+        parser_argv, extra_args = _split_add_args(argv)
+        parsed = parser.parse_args(parser_argv)
+        setattr(parsed, "extra_args", _normalize_add_unknown_args(extra_args))
+        trailing_args: list[str] = []
+    else:
+        parser_argv, trailing_args = _split_trailing_command_args(argv)
+        parsed = parser.parse_args(parser_argv)
     command = str(getattr(parsed, "command", "") or "").strip()
     if not command:
         parser.print_help(sys.stdout)
@@ -402,11 +654,10 @@ def run_mcp_command(argv: list[str], *, project_root: PathInput | None = None) -
     if command != "add" and trailing_args:
         joined = " ".join(["--", *trailing_args])
         raise McpCliError(f"Unrecognized arguments: {joined}")
-    if command == "add":
-        setattr(parsed, "extra_args", list(trailing_args))
 
     handlers = {
         "add": _cmd_add,
+        "add-json": _cmd_add_json,
         "list": _cmd_list,
         "get": _cmd_get,
         "remove": _cmd_remove,