pycli-mcp 0.2.0__py3-none-any.whl

pycli_mcp/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from pycli_mcp.metadata.query import CommandQuery
+from pycli_mcp.server import CommandMCPServer
+
+__all__ = ["CommandMCPServer", "CommandQuery"]

pycli_mcp/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from pycli_mcp.cli import main
+
+if __name__ == "__main__":
+    main()

pycli_mcp/cli.py

@@ -0,0 +1,209 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import re
+import shutil
+from importlib import import_module
+from typing import Any
+
+import click
+
+from pycli_mcp import CommandMCPServer, CommandQuery
+
+
+def parse_target_option(specs: dict[str, Any], raw_value: str) -> tuple[str, str]:
+    target_spec, sep, value = raw_value.partition("=")
+
+    if not sep:
+        if len(specs) == 1:
+            return next(iter(specs.keys())), raw_value
+
+        msg = f"Multiple specs provided, but no separator found in option: {raw_value}"
+        raise ValueError(msg)
+
+    if not target_spec:
+        msg = f"No target spec in option: {raw_value}"
+        raise ValueError(msg)
+
+    if target_spec not in specs:
+        msg = f"Unknown target spec `{target_spec}` in option: {raw_value}"
+        raise ValueError(msg)
+
+    return target_spec, value
+
+
+@click.command(
+    context_settings={
+        "help_option_names": ["-h", "--help"],
+        "max_content_width": shutil.get_terminal_size().columns,
+    },
+)
+@click.argument("specs", nargs=-1)
+@click.option(
+    "--aggregate",
+    "-a",
+    "aggregations",
+    type=click.Choice(["root", "group", "none"]),
+    multiple=True,
+    help=(
+        "The level of aggregation to use, with less improving type information at the expense "
+        "of more tools (default: root). Multiple specs make the format: spec=aggregation"
+    ),
+)
+@click.option(
+    "--name",
+    "-n",
+    "names",
+    multiple=True,
+    help=(
+        "The expected name of the executable, overriding the default (name of the callback). "
+        "Multiple specs make the format: spec=name"
+    ),
+)
+@click.option(
+    "--include",
+    "-i",
+    "includes",
+    multiple=True,
+    help="The regular expression filter to include subcommands. Multiple specs make the format: spec=regex",
+)
+@click.option(
+    "--exclude",
+    "-e",
+    "excludes",
+    multiple=True,
+    help="The regular expression filter to exclude subcommands. Multiple specs make the format: spec=regex",
+)
+@click.option("--strict-types", is_flag=True, help="Error on unknown types")
+@click.option("--debug", is_flag=True, help="Enable debug mode")
+@click.option("--host", help="The host used to run the server (default: 127.0.0.1)")
+@click.option("--port", type=int, help="The port used to run the server (default: 8000)")
+@click.option("--log-level", help="The log level used to run the server (default: info)")
+@click.option("--log-config", help="The path to a file passed to the [`logging.config.fileConfig`][] function")
+@click.option(
+    "--option",
+    "-o",
+    "options",
+    type=(str, str),
+    multiple=True,
+    help="Arbitrary server options (multiple allowed) e.g. -o key1 value1 -o key2 value2",
+)
+@click.pass_context
+def pycli_mcp(
+    ctx: click.Context,
+    *,
+    specs: tuple[str, ...],
+    aggregations: tuple[str, ...],
+    names: tuple[str, ...],
+    includes: tuple[str, ...],
+    excludes: tuple[str, ...],
+    strict_types: bool,
+    debug: bool,
+    host: str | None,
+    port: int | None,
+    log_level: str | None,
+    log_config: str | None,
+    options: tuple[tuple[str, str], ...],
+) -> None:
+    """
+    \b
+     ______       _______ _       _    _______ _______ ______
+    (_____ \\     (_______|_)     | |  (_______|_______|_____ \\
+     _____) )   _ _       _      | |   _  _  _ _       _____) )
+    |  ____/ | | | |     | |     | |  | ||_|| | |     |  ____/
+    | |    | |_| | |_____| |_____| |  | |   | | |_____| |
+    |_|     \\__  |\\______)_______)_|  |_|   |_|\\______)_|
+           (____/
+
+    Run an MCP server using a list of import paths to commands:
+
+    \b
+    ```
+    pycli-mcp pkg1.cli:foo pkg2.cli:bar
+    ```
+
+    Filtering is supported. For example, if you have a CLI named `foo` and you only want to expose the
+    subcommands `bar` and `baz`, excluding the `baz` subcommands `sub2` and `sub3`, you can do:
+
+    \b
+    ```
+    pycli-mcp pkg.cli:foo -i "bar|baz" -e "baz (sub2|sub3)"
+    ```
+    """
+    if not specs:
+        click.echo(ctx.get_help())
+        return
+
+    # Deduplicate
+    command_specs: dict[str, dict[str, Any]] = {spec: {} for spec in dict.fromkeys(specs)}
+
+    for aggregation_entry in aggregations:
+        target_spec, aggregation = parse_target_option(command_specs, aggregation_entry)
+        command_specs[target_spec]["aggregate"] = aggregation
+
+    for name_entry in names:
+        target_spec, name = parse_target_option(command_specs, name_entry)
+        command_specs[target_spec]["name"] = name
+
+    for include_entry in includes:
+        target_spec, include_pattern = parse_target_option(command_specs, include_entry)
+        command_specs[target_spec]["include"] = re.compile(include_pattern)
+
+    for exclude_entry in excludes:
+        target_spec, exclude_pattern = parse_target_option(command_specs, exclude_entry)
+        command_specs[target_spec]["exclude"] = re.compile(exclude_pattern)
+
+    command_queries: list[CommandQuery] = []
+    spec_pattern = re.compile(r"^(?P<spec>(?P<module>[\w.]+):(?P<attr>[\w.]+))$")
+    for spec, data in command_specs.items():
+        match = spec_pattern.search(spec)
+        if match is None:
+            msg = f"Invalid spec: {spec}"
+            raise ValueError(msg)
+
+        obj = import_module(match.group("module"))
+        for attr in match.group("attr").split("."):
+            obj = getattr(obj, attr)
+
+        command_query = CommandQuery(
+            obj,
+            aggregate=data.get("aggregate"),
+            name=data.get("name"),
+            include=data.get("include"),
+            exclude=data.get("exclude"),
+            strict_types=strict_types,
+        )
+        command_queries.append(command_query)
+
+    app_settings: dict[str, Any] = {}
+    if debug:
+        app_settings["debug"] = True
+
+    server = CommandMCPServer(command_queries, stateless=True, **app_settings)
+    if debug:
+        from pprint import pprint
+
+        pprint({c.metadata.path: c.metadata.schema for c in server.commands.values()})
+    else:
+        for command in server.commands.values():
+            print(f"Serving: {command.metadata.path}")
+
+    server_settings: dict[str, Any] = {}
+    if host is not None:
+        server_settings["host"] = host
+    if port is not None:
+        server_settings["port"] = port
+    if log_level is not None:
+        server_settings["log_level"] = log_level
+    if log_config is not None:
+        server_settings["log_config"] = log_config
+
+    for key, value in options:
+        server_settings.setdefault(key, value)
+
+    server.run(**server_settings)
+
+
+def main() -> None:
+    pycli_mcp(windows_expand_args=False)

pycli_mcp/metadata/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT

pycli_mcp/metadata/interface.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class CommandMetadata(ABC):
+    def __init__(self, *, path: str, schema: dict[str, Any]) -> None:
+        self.__path = path
+        self.__schema = schema
+
+    @property
+    def path(self) -> str:
+        return self.__path
+
+    @property
+    def schema(self) -> dict[str, Any]:
+        return self.__schema
+
+    @abstractmethod
+    def construct(self, arguments: dict[str, Any] | None = None) -> list[str]: ...

pycli_mcp/metadata/query.py

@@ -0,0 +1,94 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Iterator
+
+    from pycli_mcp.metadata.interface import CommandMetadata
+
+
+class CommandQuery:
+    """
+    A wrapper around a root command object that influences the collection behavior. Example usage:
+
+    ```python
+    from pycli_mcp import CommandMCPServer, CommandQuery
+
+    from mypkg.cli import cmd
+
+    # Only expose the `foo` subcommand
+    query = CommandQuery(cmd, include=r"^foo$")
+    server = CommandMCPServer(commands=[query])
+    server.run()
+    ```
+
+    Parameters:
+        command: The command to inspect.
+        aggregate: The level of aggregation to use.
+        name: The expected name of the root command.
+        include: A regular expression to include in the query.
+        exclude: A regular expression to exclude in the query.
+        strict_types: Whether to error on unknown types.
+    """
+
+    __slots__ = ("__aggregate", "__command", "__exclude", "__include", "__name", "__strict_types")
+
+    def __init__(
+        self,
+        command: Any,
+        *,
+        aggregate: Literal["root", "group", "none"] | None = None,
+        name: str | None = None,
+        include: str | re.Pattern | None = None,
+        exclude: str | re.Pattern | None = None,
+        strict_types: bool = False,
+    ) -> None:
+        self.__command = command
+        self.__aggregate = aggregate
+        self.__name = name
+        self.__include = include
+        self.__exclude = exclude
+        self.__strict_types = strict_types
+
+    def __iter__(self) -> Iterator[CommandMetadata]:
+        yield from walk_commands(
+            self.__command,
+            aggregate=self.__aggregate,
+            name=self.__name,
+            include=self.__include,
+            exclude=self.__exclude,
+            strict_types=self.__strict_types,
+        )
+
+
+def walk_commands(
+    command: Any,
+    *,
+    aggregate: Literal["root", "group", "none"] | None = None,
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+    strict_types: bool = False,
+) -> Iterator[CommandMetadata]:
+    if aggregate is None:
+        aggregate = "root"
+
+    # Click
+    if hasattr(command, "context_class"):
+        from pycli_mcp.metadata.types.click import walk_commands
+
+        yield from walk_commands(
+            command,
+            aggregate=aggregate,
+            name=name,
+            include=include,
+            exclude=exclude,
+            strict_types=strict_types,
+        )
+    else:
+        msg = f"Unsupported command type: {type(command)}"
+        raise NotImplementedError(msg)

pycli_mcp/metadata/types/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT

pycli_mcp/metadata/types/click.py

@@ -0,0 +1,479 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import inspect
+import re
+from typing import TYPE_CHECKING, Any, Literal
+
+import click
+
+from pycli_mcp.metadata.interface import CommandMetadata
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+class ClickCommandMetadata(CommandMetadata):
+    def __init__(self, *, path: str, schema: dict[str, Any], options: dict[str, ClickCommandOption]) -> None:
+        super().__init__(path=path, schema=schema)
+
+        self.__options = options
+
+    @property
+    def options(self) -> dict[str, ClickCommandOption]:
+        return self.__options
+
+    def construct(self, arguments: dict[str, Any] | None = None) -> list[str]:
+        command = self.path.split()
+        if arguments and self.options:
+            args: list[Any] = []
+            opts: list[Any] = []
+            flags: list[str] = []
+            for option_name, value in arguments.items():
+                option = self.options[option_name]
+                if option.type == "argument":
+                    if isinstance(value, list):
+                        args.extend(value)
+                    else:
+                        args.append(value)
+
+                    continue
+
+                if option.flag:
+                    if value:
+                        flags.append(option.flag_name)
+                elif option.multiple:
+                    if option.container:
+                        for v in value:
+                            opts.append(option.flag_name)
+                            opts.extend(v)
+                    else:
+                        for v in value:
+                            opts.extend((option.flag_name, v))
+                elif option.container:
+                    opts.append(option.flag_name)
+                    opts.extend(value)
+                else:
+                    opts.extend((option.flag_name, value))
+
+            command.extend(flags)
+            command.extend(map(str, opts))
+            if args:
+                command.append("--")
+                command.extend(map(str, args))
+
+        return command
+
+
+class ClickCommandOption:
+    __slots__ = ("__container", "__description", "__flag", "__flag_name", "__multiple", "__required", "__type")
+
+    def __init__(
+        self,
+        *,
+        type: Literal["argument", "option"],  # noqa: A002
+        required: bool,
+        description: str,
+        multiple: bool = False,
+        container: bool = False,
+        flag: bool = False,
+        flag_name: str = "",
+    ) -> None:
+        self.__type = type
+        self.__required = required
+        self.__description = description
+        self.__multiple = multiple
+        self.__container = container
+        self.__flag = flag
+        self.__flag_name = flag_name
+
+    @property
+    def type(self) -> Literal["argument", "option"]:
+        return self.__type
+
+    @property
+    def required(self) -> bool:
+        return self.__required
+
+    @property
+    def description(self) -> str:
+        return self.__description
+
+    @property
+    def multiple(self) -> bool:
+        return self.__multiple
+
+    @property
+    def container(self) -> bool:
+        return self.__container
+
+    @property
+    def flag(self) -> bool:
+        return self.__flag
+
+    @property
+    def flag_name(self) -> str:
+        return self.__flag_name
+
+
+def get_longest_flag(flags: list[str]) -> str:
+    return sorted(flags, key=len)[-1]  # noqa: FURB192
+
+
+def get_command_description(command: click.Command) -> str:
+    # Truncate the help text to the first form feed
+    return inspect.cleandoc(command.help or command.short_help or "").split("\f")[0].strip()
+
+
+def get_command_options_block(ctx: click.Context) -> str:
+    import textwrap
+
+    options = ""
+    for param in ctx.command.get_params(ctx):
+        info = param.to_info_dict()
+        if info.get("hidden", False) or "--help" in info["opts"]:
+            continue
+
+        help_record = param.get_help_record(ctx)
+        if help_record is None:
+            continue
+
+        metadata, help_text = help_record
+        options += f"\n{metadata}"
+        help_text = textwrap.dedent(help_text).strip()
+        if help_text:
+            separator = " " * 2
+            options += separator
+            options += textwrap.indent(help_text, " " * (len(metadata) + len(separator))).strip()
+
+    return options.lstrip()
+
+
+def get_command_full_usage(ctx: click.Context) -> str:
+    usage_pieces = [f"Usage: {ctx.command_path}"]
+    usage_pieces.extend(ctx.command.collect_usage_pieces(ctx))
+    usage = " ".join(usage_pieces)
+
+    if description := get_command_description(ctx.command):
+        usage += f"\n\n{description}"
+
+    if options := get_command_options_block(ctx):
+        usage += f"\n\nOptions:\n{options}"
+
+    return usage
+
+
+def walk_command_tree(
+    command: click.Command,
+    *,
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+    parent: click.Context | None = None,
+) -> Iterator[click.Context]:
+    if command.hidden:
+        return
+
+    ctx = command.context_class(command, parent=parent, info_name=name, **command.context_settings)
+    if not isinstance(command, click.Group):
+        subcommand_path = " ".join(ctx.command_path.split()[1:])
+        if exclude is not None and re.search(exclude, subcommand_path):
+            return
+        if include is not None and not re.search(include, subcommand_path):
+            return
+
+        yield ctx
+        return
+
+    for subcommand_name in command.list_commands(ctx):
+        subcommand = command.get_command(ctx, subcommand_name)
+        if subcommand is None:
+            continue
+        yield from walk_command_tree(subcommand, name=subcommand_name, include=include, exclude=exclude, parent=ctx)
+
+
+def walk_commands_no_aggregation(
+    command: click.Command,
+    *,
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+    strict_types: bool = False,
+) -> Iterator[ClickCommandMetadata]:
+    for ctx in walk_command_tree(command, name=name or command.name, include=include, exclude=exclude):
+        properties: dict[str, Any] = {}
+        options: dict[str, ClickCommandOption] = {}
+        for param in ctx.command.get_params(ctx):
+            info = param.to_info_dict()
+            flags = info["opts"]
+            if info.get("hidden", False) or "--help" in flags:
+                continue
+
+            flag_name = get_longest_flag(flags)
+            option_name = flag_name.lstrip("-").replace("-", "_")
+
+            option_data = {
+                "type": info["param_type_name"],
+                "required": info["required"],
+                "multiple": info["multiple"],
+            }
+            if info["param_type_name"] == "option":
+                option_data["flag_name"] = flag_name
+
+            prop: dict[str, Any] = {"title": option_name}
+            if help_text := (info.get("help") or "").strip():
+                prop["description"] = help_text
+
+            type_data = info["type"]
+            type_name = type_data["param_type"]
+
+            # Some types are just strings
+            if type_name in {"Path", "File"}:
+                type_name = "String"
+
+            if type_name == "String":
+                if info["nargs"] == -1 or info["multiple"]:
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "string"}
+                else:
+                    prop["type"] = "string"
+            elif type_name == "Bool":
+                option_data["flag"] = True
+                prop["type"] = "boolean"
+            elif type_name == "Int":
+                if info["multiple"]:
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "integer"}
+                else:
+                    prop["type"] = "integer"
+            elif type_name == "Float":
+                if info["multiple"]:
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "number"}
+                else:
+                    prop["type"] = "number"
+            elif type_name == "Choice":
+                prop["type"] = "string"
+                prop["enum"] = list(type_data["choices"])
+            elif type_name == "Tuple":
+                option_data["container"] = True
+                if info["multiple"]:
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "array", "items": {"type": "string"}}
+                else:
+                    prop["type"] = "array"
+                    prop["items"] = {"type": "string"}
+            elif strict_types:
+                msg = f"Unknown type: {type_data}\n{info}"
+                raise ValueError(msg)
+            else:
+                prop["type"] = "string"
+
+            if not info["required"]:
+                prop["default"] = None if callable(info["default"]) else info["default"]
+
+            properties[option_name] = prop
+            option_data["description"] = prop.get("description", "")
+            options[option_name] = ClickCommandOption(**option_data)
+
+        schema = {
+            "type": "object",
+            "properties": properties,
+            "title": ctx.command_path,
+            "description": get_command_description(ctx.command),
+        }
+        required = [option_name for option_name, option in options.items() if option.required]
+        if required:
+            schema["required"] = required
+
+        yield ClickCommandMetadata(path=ctx.command_path, schema=schema, options=options)
+
+
+def walk_commands_group_aggregation(
+    command: click.Command,
+    *,
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+) -> Iterator[ClickCommandMetadata]:
+    groups: dict[str, dict[str, click.Context]] = {}
+    for ctx in walk_command_tree(command, name=name or command.name, include=include, exclude=exclude):
+        if ctx.parent is None:
+            group_path = ctx.command_path
+            command_name = ""
+        else:
+            group_path = ctx.parent.command_path
+            command_name = ctx.command_path.split()[-1]
+
+        groups.setdefault(group_path, {})[command_name] = ctx
+
+    for group_path, commands in groups.items():
+        # Root is a command rather than a group
+        if "" in commands:
+            yield ClickCommandMetadata(
+                path=group_path,
+                schema={
+                    "type": "object",
+                    "properties": {
+                        "args": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                            },
+                            "title": "args",
+                            "description": "The arguments to pass to the command",
+                        },
+                    },
+                    "title": group_path,
+                    "description": f"{get_command_full_usage(ctx)}\n",
+                },
+                options={
+                    "args": ClickCommandOption(
+                        type="argument",
+                        required=False,
+                        description="The arguments to pass to the command",
+                    ),
+                },
+            )
+            continue
+
+        description = f"""\
+Usage: {group_path} SUBCOMMAND [ARGS]...
+
+# Available subcommands
+"""
+        for command_name, ctx in commands.items():
+            description += f"""
+## {command_name}
+
+{get_command_full_usage(ctx)}
+"""
+
+        yield ClickCommandMetadata(
+            path=group_path,
+            schema={
+                "type": "object",
+                "properties": {
+                    "subcommand": {
+                        "type": "string",
+                        "enum": list(commands.keys()),
+                        "title": "subcommand",
+                        "description": "The subcommand to execute",
+                    },
+                    "args": {
+                        "type": "array",
+                        "items": {
+                            "type": "string",
+                        },
+                        "title": "args",
+                        "description": "The arguments to pass to the subcommand",
+                    },
+                },
+                "title": group_path,
+                "description": description.lstrip(),
+            },
+            options={
+                "subcommand": ClickCommandOption(
+                    type="argument",
+                    required=True,
+                    description="The subcommand to execute",
+                ),
+                "args": ClickCommandOption(
+                    type="argument",
+                    required=False,
+                    description="The arguments to pass to the subcommand",
+                ),
+            },
+        )
+
+
+def walk_commands_root_aggregation(
+    command: click.Command,
+    *,
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+) -> Iterator[ClickCommandMetadata]:
+    root_command_name = name or command.name
+    description = ""
+    if isinstance(command, click.Group):
+        ctx = command.context_class(command, info_name=root_command_name, **command.context_settings)
+        description += f"""\
+# {root_command_name}
+
+Usage: {root_command_name} [OPTIONS] SUBCOMMAND [ARGS]...
+"""
+        if root_command_description := get_command_description(command):
+            description += f"\n{root_command_description}\n"
+        if root_command_options := get_command_options_block(ctx):
+            description += f"\nOptions:\n{root_command_options}\n"
+
+    for ctx in walk_command_tree(command, name=root_command_name, include=include, exclude=exclude):
+        description += f"""
+## {ctx.command_path}
+
+{get_command_full_usage(ctx)}
+"""
+
+    yield ClickCommandMetadata(
+        path=root_command_name,  # type: ignore[arg-type]
+        schema={
+            "type": "object",
+            "properties": {
+                "args": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                    },
+                    "title": "args",
+                    "description": "The arguments to pass to the root command",
+                },
+            },
+            "title": root_command_name,
+            "description": description.lstrip(),
+        },
+        options={
+            "args": ClickCommandOption(
+                type="argument",
+                required=False,
+                description="The arguments to pass to the root command",
+            ),
+        },
+    )
+
+
+def walk_commands(
+    command: click.Command,
+    *,
+    aggregate: Literal["root", "group", "none"],
+    name: str | None = None,
+    include: str | re.Pattern | None = None,
+    exclude: str | re.Pattern | None = None,
+    strict_types: bool = False,
+) -> Iterator[ClickCommandMetadata]:
+    if aggregate == "root":
+        yield from walk_commands_root_aggregation(
+            command,
+            name=name,
+            include=include,
+            exclude=exclude,
+        )
+    elif aggregate == "group":
+        yield from walk_commands_group_aggregation(
+            command,
+            name=name,
+            include=include,
+            exclude=exclude,
+        )
+    elif aggregate == "none":
+        yield from walk_commands_no_aggregation(
+            command,
+            name=name,
+            include=include,
+            exclude=exclude,
+            strict_types=strict_types,
+        )
+    else:
+        msg = f"Invalid aggregate value: {aggregate}"
+        raise ValueError(msg)

pycli_mcp/server.py

@@ -0,0 +1,202 @@
+# SPDX-FileCopyrightText: 2025-present Ofek Lev <oss@ofek.dev>
+# SPDX-License-Identifier: MIT
+from __future__ import annotations
+
+import subprocess
+from contextlib import asynccontextmanager
+from functools import cached_property
+from typing import TYPE_CHECKING, Any
+
+import uvicorn
+from mcp.server.lowlevel import Server
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.types import (
+    CallToolRequest,
+    CallToolResult,
+    ListToolsRequest,
+    ListToolsResult,
+    ServerResult,
+    TextContent,
+    Tool,
+)
+from starlette.applications import Starlette
+from starlette.routing import Mount
+
+from pycli_mcp.metadata.query import CommandQuery
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Sequence
+
+    from mcp.server.streamable_http import EventStore
+
+    from pycli_mcp.metadata.interface import CommandMetadata
+
+
+class Command:
+    __slots__ = ("__metadata", "__tool")
+
+    def __init__(self, metadata: CommandMetadata, tool: Tool):
+        self.__metadata = metadata
+        self.__tool = tool
+
+    @property
+    def metadata(self) -> CommandMetadata:
+        return self.__metadata
+
+    @property
+    def tool(self) -> Tool:
+        return self.__tool
+
+
+class CommandMCPServer:
+    """
+    An MCP server that can be used to run Python CLIs, backed by [Starlette](https://github.com/encode/starlette)
+    and [Uvicorn](https://github.com/encode/uvicorn). Example usage:
+
+    ```python
+    from pycli_mcp import CommandMCPServer
+
+    from mypkg.cli import cmd
+
+    server = CommandMCPServer(commands=[cmd], stateless=True)
+    server.run()
+    ```
+
+    Parameters:
+        commands: The commands to expose as MCP tools.
+
+    Other parameters:
+        event_store: Optional [event store](https://github.com/modelcontextprotocol/python-sdk/blob/v1.9.4/src/mcp/server/streamable_http.py#L79)
+            that allows clients to reconnect and receive missed events. If `None`, sessions are still tracked but not
+            resumable.
+        stateless: Whether to create a completely fresh transport for each request with no session tracking or state
+            persistence between requests.
+        **app_settings: Additional settings to pass to the Starlette [application][starlette.applications.Starlette].
+    """
+
+    def __init__(
+        self,
+        commands: Sequence[Any],
+        *,
+        event_store: EventStore | None = None,
+        stateless: bool = False,
+        **app_settings: Any,
+    ) -> None:
+        self.__command_queries = [c if isinstance(c, CommandQuery) else CommandQuery(c) for c in commands]
+        self.__app_settings = app_settings
+        self.__server: Server = Server("pycli_mcp")
+        self.__session_manager = StreamableHTTPSessionManager(
+            app=self.__server,
+            event_store=event_store,
+            stateless=stateless,
+            json_response=True,
+        )
+
+        # Register handlers
+        self.__server.request_handlers[ListToolsRequest] = self.list_tools_handler
+        self.__server.request_handlers[CallToolRequest] = self.call_tool_handler
+
+    @property
+    def server(self) -> Server:
+        """
+        Returns:
+            The underlying [low-level server](https://github.com/modelcontextprotocol/python-sdk/blob/v1.9.4/src/mcp/server/lowlevel/server.py)
+                instance. You can use this to register additional handlers.
+        """
+        return self.__server
+
+    @property
+    def session_manager(self) -> StreamableHTTPSessionManager:
+        """
+        Returns:
+            The underlying [session manager](https://github.com/modelcontextprotocol/python-sdk/blob/v1.9.4/src/mcp/server/streamable_http_manager.py#L29)
+                instance. You only need to use this if you want to override the `lifetime` context manager
+        """
+        return self.__session_manager
+
+    @cached_property
+    def commands(self) -> dict[str, Command]:
+        """
+        Returns:
+            Dictionary used internally to store metadata about the exposed commands. Although it should not be modified,
+                the keys are the available MCP tool names and useful to know when overriding the default handlers.
+        """
+        commands: dict[str, Command] = {}
+        for query in self.__command_queries:
+            for metadata in query:
+                tool_name = metadata.path.replace(" ", ".").replace("-", "_")
+                tool = Tool(
+                    name=tool_name,
+                    description=metadata.schema["description"],
+                    inputSchema=metadata.schema,
+                )
+                commands[tool_name] = Command(metadata, tool)
+
+        return commands
+
+    @cached_property
+    def routes(self) -> list[Mount]:
+        """
+        This would only be used directly if you want to add more routes in addition to the default `/mcp` route.
+
+        Returns:
+            The [routes](https://www.starlette.io/routing/#http-routing) to mount in the Starlette
+                [application][starlette.applications.Starlette].
+        """
+        return [Mount("/mcp", app=self.session_manager.handle_request)]
+
+    @asynccontextmanager
+    async def lifespan(self, app: Starlette) -> AsyncIterator[None]:  # noqa: ARG002
+        """
+        The default lifespan context manager used by the Starlette [application][starlette.applications.Starlette].
+        """
+        async with self.session_manager.run():
+            yield
+
+    def list_command_tools(self) -> list[Tool]:
+        """
+        This would only be used directly if you want to override the handler for the `ListToolsRequest`.
+
+        Returns:
+            The MCP tools for the commands.
+        """
+        return [command.tool for command in self.commands.values()]
+
+    async def list_tools_handler(self, _: ListToolsRequest) -> ServerResult:
+        """
+        The default handler for the `ListToolsRequest`.
+        """
+        return ServerResult(ListToolsResult(tools=self.list_command_tools()))
+
+    async def call_tool_handler(self, req: CallToolRequest) -> ServerResult:
+        """
+        The default handler for the `CallToolRequest`.
+        """
+        command = self.commands[req.params.name].metadata.construct(req.params.arguments)
+        try:
+            process = subprocess.run(  # noqa: PLW1510
+                command,
+                encoding="utf-8",
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+            )
+        # This can happen if the command is not found
+        except subprocess.CalledProcessError as e:
+            return ServerResult(CallToolResult(content=[TextContent(type="text", text=str(e))], isError=True))
+
+        if process.returncode:
+            msg = f"{process.stdout}\nThis command exited with non-zero exit code `{process.returncode}`: {command}"
+            return ServerResult(CallToolResult(content=[TextContent(type="text", text=msg)], isError=True))
+
+        return ServerResult(CallToolResult(content=[TextContent(type="text", text=process.stdout)]))
+
+    def run(self, **kwargs: Any) -> None:
+        """
+        Other parameters:
+            **kwargs: Additional settings to pass to the [`uvicorn.run`](https://www.uvicorn.org/#uvicornrun) function.
+        """
+        app_settings = self.__app_settings.copy()
+        app_settings["routes"] = self.routes
+        app_settings.setdefault("lifespan", self.lifespan)
+        app = Starlette(**app_settings)
+        uvicorn.run(app, **kwargs)

pycli_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: pycli-mcp
+Version: 0.2.0
+Summary: MCP server for any Python command line application
+Project-URL: Homepage, https://ofek.dev/pycli-mcp/
+Project-URL: Sponsor, https://github.com/sponsors/ofek
+Project-URL: Changelog, https://ofek.dev/pycli-mcp/changelog/
+Project-URL: Tracker, https://github.com/ofek/pycli-mcp/issues
+Project-URL: Source, https://github.com/ofek/pycli-mcp
+Author-email: Ofek Lev <oss@ofek.dev>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: ai,cli,click,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: mcp
+Description-Content-Type: text/markdown
+
+# PyCLI MCP
+
+| | |
+| --- | --- |
+| CI/CD | [![CI - Test](https://github.com/ofek/pycli-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/ofek/pycli-mcp/actions/workflows/test.yml) [![CD - Build](https://github.com/ofek/pycli-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/ofek/pycli-mcp/actions/workflows/build.yml) |
+| Docs | [![Docs](https://github.com/ofek/pycli-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/ofek/pycli-mcp/actions/workflows/docs.yml) |
+| Package | [![PyPI - Version](https://img.shields.io/pypi/v/pycli-mcp.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/pycli-mcp/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pycli-mcp.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/pycli-mcp/) |
+| Meta | [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/ofek/pycli-mcp) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) [![GitHub Sponsors](https://img.shields.io/github/sponsors/ofek?logo=GitHub%20Sponsors&style=social)](https://github.com/sponsors/ofek) |
+
+-----
+
+This provides an extensible [MCP](https://modelcontextprotocol.io) server that is compatible with any Python command line application.
+
+Supported frameworks:
+
+- [Click](https://github.com/pallets/click)
+
+## Installation
+
+```console
+pip install pycli-mcp
+```
+
+## Documentation
+
+The [documentation](https://ofek.dev/pycli-mcp/) is made with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material) and is hosted by [GitHub Pages](https://docs.github.com/en/pages).
+
+## License
+
+`pycli-mcp` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

pycli_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pycli_mcp/__init__.py,sha256=0Zk8fHsXlkL4T05OOuveQDYIlHXPzDY160Iw6_d66vA,238
+pycli_mcp/__main__.py,sha256=U6VwYYMGbUUvvJoOj-P1W1PldA5uqF6k332Rl2iP4ew,200
+pycli_mcp/cli.py,sha256=LH7j3yuOQRx3SlWEQlp_9FYOXBRERCB9FhAw8UyjnI4,6647
+pycli_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycli_mcp/server.py,sha256=tO4FaBqwsTZ0zui-FxL4ENxxBhWfaUz2eu5JgCGB4X0,7464
+pycli_mcp/metadata/__init__.py,sha256=PnnoAlXqi2DRI8VBmupkhbjtp3TvAxUVNz43PUhjw1c,94
+pycli_mcp/metadata/interface.py,sha256=0n4gLE33kcjuf7WaFpmNkeJ3TdW0NwqLmM_CW0EqDB0,604
+pycli_mcp/metadata/query.py,sha256=xWmD4GqJLMORZNGANIFZtrDoQGFbEbkdBfa3jwzfeDI,2787
+pycli_mcp/metadata/types/__init__.py,sha256=PnnoAlXqi2DRI8VBmupkhbjtp3TvAxUVNz43PUhjw1c,94
+pycli_mcp/metadata/types/click.py,sha256=XAo3UCEHATnO5LWO6ABcRrGaRHfIOxbp-KpvKP4T_nQ,15779
+pycli_mcp-0.2.0.dist-info/METADATA,sha256=WRhXvEkkT1Oq_OuD8uHDrkGRAajxCskuhUME-y9CgKc,3036
+pycli_mcp-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pycli_mcp-0.2.0.dist-info/entry_points.txt,sha256=gE9XVHPk2schyTKuRhzXxosPR9zKf2konk2__iDp0lI,49
+pycli_mcp-0.2.0.dist-info/licenses/LICENSE.txt,sha256=3Eg4UX5X6MAcpfSmIoNHKBV2JCXPPAUjitjT86t3evQ,1088
+pycli_mcp-0.2.0.dist-info/RECORD,,

pycli_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pycli_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pycli-mcp = pycli_mcp.cli:main

pycli_mcp-0.2.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Ofek Lev <oss@ofek.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.