universal-cli-mcp-server 0.1.0__py3-none-any.whl

cli_mcp/discovery/python_reflection.py

@@ -0,0 +1,54 @@
+"""Strategy 1 for Python CLIs: reflect on click, typer and argparse objects."""
+
+from __future__ import annotations
+
+import os
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext
+from cli_mcp.discovery.reflection_payload import commands_from_payload, parse_payload
+from cli_mcp.models import DiscoveryResult
+
+MODULE = "cli_mcp.discovery.introspect"
+
+
+class PythonReflectionProvider:
+    """Import a Python CLI in a subprocess and read its declared command objects."""
+
+    name = "reflection-python"
+    strategy = "reflection"
+    frameworks: tuple[str, ...] = ("python", "click", "typer", "argparse")
+
+    def __init__(self, settings: Settings) -> None:
+        """Store the settings that gate reflection."""
+        self.settings = settings
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Reflection imports the target, so it needs a Python target and explicit opt-in."""
+        if not self.settings.discovery.allow_import_reflection:
+            return False
+        return target.origin == "python"
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Run the introspection helper and convert its JSON document."""
+        interpreter = os.environ.get("CLI_MCP_PYTHON") or ctx.interpreter("python")
+        if not interpreter:
+            return None
+        argv = [interpreter, "-m", MODULE, "--target", target.resolved_path]
+        help_result = ctx.run(argv, timeout=self.settings.discovery.help_timeout_seconds)
+        payload = parse_payload(help_result.stdout)
+        if payload is None:
+            return None
+        commands = commands_from_payload(payload, target, self.settings.mcp.tool_prefix)
+        if not commands:
+            return None
+        warnings = [f"reflection error: {payload['error']}"] if payload.get("error") else []
+        return DiscoveryResult(
+            binary=target.binary,
+            resolved_path=target.resolved_path,
+            framework=payload.get("framework") or target.framework,
+            commands=commands,
+            strategies=[self.name],
+            warnings=warnings,
+        )

cli_mcp/discovery/reflection_payload.py

@@ -0,0 +1,92 @@
+"""Shared conversion from an introspection JSON payload into canonical commands.
+
+Both reflection providers (Python and Node.js) emit the same JSON document, so
+the conversion lives here rather than in each provider.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.engine import coerce_default, tool_base
+from cli_mcp.models import CommandSpec, Parameter, ParamKind
+
+
+def parse_payload(stdout: str) -> dict[str, Any] | None:
+    """Parse an introspection JSON document, or ``None`` when nothing usable came back."""
+    try:
+        payload = json.loads(stdout)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(payload, dict) or not isinstance(payload.get("commands"), list):
+        return None
+    return payload
+
+
+def parameter_from(raw: dict[str, Any]) -> Parameter:
+    """Convert one introspected parameter into the canonical model."""
+    kind_raw = raw.get("kind") or "option"
+    kind = (
+        ParamKind.POSITIONAL
+        if kind_raw == "positional"
+        else ParamKind.FLAG
+        if kind_raw == "flag"
+        else ParamKind.OPTION
+    )
+    declared = str(raw.get("type") or "string")
+    default = raw.get("default")
+    if default is not None:
+        expected: dict[str, type | tuple[type, ...]] = {
+            "boolean": bool,
+            "integer": int,
+            "number": (int, float),
+            "string": str,
+            "array": list,
+        }
+        if not isinstance(default, expected.get(declared, object)):
+            default = coerce_default(declared, str(default))
+    choices = raw.get("choices")
+    return Parameter(
+        name=str(raw.get("name") or "arg"),
+        kind=kind,
+        cli_name=raw.get("cli_name"),
+        short=raw.get("short"),
+        short_only=bool(raw.get("short_only", False)),
+        type=declared,
+        description=raw.get("description") or None,
+        required=bool(raw.get("required", False)),
+        default=default,
+        choices=list(choices) if choices else None,
+        repeatable=bool(raw.get("repeatable", False)),
+        metavar=raw.get("metavar"),
+    )
+
+
+def commands_from_payload(payload: dict[str, Any], target: TargetInfo, prefix: bool) -> list[CommandSpec]:
+    """Convert introspected command entries into :class:`CommandSpec` objects."""
+    commands: list[CommandSpec] = []
+    for raw in payload.get("commands", []):
+        if not isinstance(raw, dict):
+            continue
+        path = [str(part) for part in raw.get("path", [])]
+        parameters = [parameter_from(item) for item in raw.get("parameters", []) if isinstance(item, dict)]
+        has_subcommands = bool(raw.get("has_subcommands"))
+        if not path and has_subcommands and not parameters:
+            continue  # a bare group is not executable
+        binary_name = tool_base(target)
+        name_parts = ([binary_name] if prefix else []) + (path or [binary_name])
+        description = str(raw.get("description") or "").strip() or f"Run {' '.join([target.binary, *path])}".strip()
+        commands.append(
+            CommandSpec(
+                name="_".join(name_parts),
+                path=path,
+                description=description,
+                parameters=parameters,
+                provider=f"reflection-{target.origin}",
+                examples=[f"{target.binary} {' '.join(path)}".strip()],
+                has_subcommands=has_subcommands,
+            )
+        )
+    return commands

cli_mcp/discovery/registry.py

@@ -0,0 +1,124 @@
+"""Provider registry: built-in providers plus third-party plugins."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+from typing import Literal, cast
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext, DiscoveryProvider
+from cli_mcp.discovery.grammars import GRAMMAR_PROVIDERS, GenericHelpProvider
+from cli_mcp.discovery.manifest import ManifestProvider
+from cli_mcp.discovery.node_reflection import NodeReflectionProvider
+from cli_mcp.discovery.python_reflection import PythonReflectionProvider
+from cli_mcp.models import DiscoveryResult
+
+ENTRY_POINT_GROUP = "cli_mcp.discovery"
+ProviderSource = Literal["core", "plugin"]
+
+
+@dataclass(frozen=True)
+class Registration:
+    """A provider together with where it came from."""
+
+    provider: DiscoveryProvider
+    source: ProviderSource
+
+
+class ProviderRegistry:
+    """The provider set used by one discovery run."""
+
+    def __init__(self, settings: Settings, *, load_plugins: bool = True) -> None:
+        """Register the built-in providers, plus installed plugins when asked."""
+        self.settings = settings
+        self._registrations: list[Registration] = []
+        for provider in _builtin_providers(settings):
+            self._registrations.append(Registration(provider=provider, source="core"))
+        if load_plugins:
+            for provider in plugin_providers(settings):
+                self._registrations.append(Registration(provider=provider, source="plugin"))
+
+    def register(self, provider: DiscoveryProvider, source: ProviderSource = "plugin") -> None:
+        """Add a provider programmatically, for tests and embedders."""
+        self._registrations.append(Registration(provider=provider, source=source))
+
+    @property
+    def registrations(self) -> list[Registration]:
+        """Return every registered provider in priority order."""
+        return list(self._registrations)
+
+    def for_target(self, target: TargetInfo) -> list[DiscoveryProvider]:
+        """Return the providers that accept *target*, plugins last so built-ins win."""
+        return [
+            registration.provider for registration in self._registrations if registration.provider.supports(target)
+        ]
+
+    def for_strategy(self, strategy: str, target: TargetInfo) -> list[DiscoveryProvider]:
+        """Return the providers that accept *target* and implement *strategy*."""
+        return [provider for provider in self.for_target(target) if provider.strategy == strategy]
+
+    def describe(self) -> list[tuple[str, str, str, ProviderSource]]:
+        """Build the rows shown by ``cli-mcp providers``: name, strategy, frameworks, source."""
+        return [
+            (
+                registration.provider.name,
+                registration.provider.strategy,
+                ", ".join(registration.provider.frameworks),
+                registration.source,
+            )
+            for registration in self._registrations
+        ]
+
+    def run(self, strategy: str, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Try every provider for *strategy* and return the first non-empty result."""
+        for provider in self.for_strategy(strategy, target):
+            result = provider.discover(target, ctx)
+            if result is not None and result.commands:
+                return result
+        return None
+
+
+def _builtin_providers(settings: Settings) -> list[DiscoveryProvider]:
+    """Built-ins ordered so specific grammars beat the generic parser."""
+    return [
+        PythonReflectionProvider(settings),
+        NodeReflectionProvider(settings),
+        *(provider(settings) for provider in GRAMMAR_PROVIDERS),
+        GenericHelpProvider(settings),
+        ManifestProvider(settings),
+    ]
+
+
+def plugin_providers(settings: Settings) -> list[DiscoveryProvider]:
+    """Load providers from the ``cli_mcp.discovery`` entry-point group."""
+    providers: list[DiscoveryProvider] = []
+    try:
+        found = entry_points(group=ENTRY_POINT_GROUP)
+    except Exception:
+        return providers
+    for entry_point in found:
+        try:
+            loaded = entry_point.load()
+        except Exception:
+            continue
+        provider = _instantiate(loaded, settings)
+        if provider is not None:
+            providers.append(provider)
+    return providers
+
+
+def _instantiate(loaded: object, settings: Settings) -> DiscoveryProvider | None:
+    """Turn an entry-point target into a provider instance."""
+    if isinstance(loaded, type):
+        parameters = inspect.signature(loaded).parameters
+        try:
+            instance = loaded(settings) if "settings" in parameters else loaded()
+        except Exception:
+            return None
+        return cast("DiscoveryProvider", instance)
+    if loaded is None or not hasattr(loaded, "supports") or not hasattr(loaded, "discover"):
+        return None
+    return cast("DiscoveryProvider", loaded)

cli_mcp/errors.py

@@ -0,0 +1,37 @@
+"""Errors raised across cli-mcp layers."""
+
+
+class CliMcpError(Exception):
+    """Base class for every cli-mcp failure."""
+
+
+class ConfigError(CliMcpError):
+    """Configuration could not be read or is invalid."""
+
+
+class BinaryNotFoundError(CliMcpError):
+    """The requested binary is not installed or not on the allow list."""
+
+
+class DiscoveryError(CliMcpError):
+    """Discovery produced no usable command definitions."""
+
+
+class SchemaError(CliMcpError):
+    """A tool definition or argument payload failed validation."""
+
+
+class SecurityViolation(CliMcpError):
+    """A request was rejected by the security policy."""
+
+
+class ApprovalRequired(SecurityViolation):
+    """The request needs a human decision before it can run."""
+
+
+class ExecutionError(CliMcpError):
+    """The underlying process could not be started or failed unexpectedly."""
+
+
+class TransportError(CliMcpError):
+    """The requested MCP transport is unavailable."""

cli_mcp/executor/__init__.py

@@ -0,0 +1,19 @@
+"""Execution layer: argv building, subprocess runner, approval gate and sandbox."""
+
+from __future__ import annotations
+
+from cli_mcp.executor.approval import EXPLICIT_HINT, ApprovalGate
+from cli_mcp.executor.argv import build_argv, format_value
+from cli_mcp.executor.runner import ExecutionResult, run
+from cli_mcp.executor.sandbox import sandbox_argv, sandbox_available
+
+__all__ = [
+    "EXPLICIT_HINT",
+    "ApprovalGate",
+    "ExecutionResult",
+    "build_argv",
+    "format_value",
+    "run",
+    "sandbox_argv",
+    "sandbox_available",
+]

cli_mcp/executor/approval.py

@@ -0,0 +1,64 @@
+"""Approval gate for risky tool invocations."""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+from typing import TextIO
+
+from cli_mcp.config.settings import SecuritySettings
+from cli_mcp.errors import ApprovalRequired
+from cli_mcp.security.policy import Decision
+
+EXPLICIT_HINT = "Local terminal approval is required; client-supplied approval is not accepted."
+
+
+class ApprovalGate:
+    """Decides whether a risky invocation may proceed.
+
+    Over stdio the process' stdin is the MCP protocol channel, so prompting is
+    only possible when stdin is a terminal; otherwise the client has to approve
+    through a trusted local terminal. Client arguments cannot grant approval.
+    """
+
+    def __init__(
+        self,
+        settings: SecuritySettings,
+        stdin: TextIO | None = None,
+        stdout: TextIO | None = None,
+    ) -> None:
+        """Bind the gate to the security settings and the streams it prompts on."""
+        self.settings = settings
+        self._stdin = stdin or sys.stdin
+        self._stdout = stdout or sys.stderr
+        self._prompt_lock = threading.Lock()
+
+    def prompt_available(self) -> bool:
+        """Return whether an interactive approval prompt is possible."""
+        try:
+            return bool(self._stdin.isatty())
+        except (ValueError, OSError):
+            return False
+
+    def approve(self, tool_name: str, argv: list[str], decision: Decision) -> None:
+        """Raise :class:`ApprovalRequired` unless *decision* is approved."""
+        if not decision.requires_approval:
+            return
+        display = json.dumps(argv, ensure_ascii=True)
+        if self.settings.approval_mode == "explicit" or not self.prompt_available():
+            raise ApprovalRequired(
+                f"tool {tool_name!r} needs approval: {display}. {EXPLICIT_HINT}"
+            )
+        with self._prompt_lock:
+            self._stdout.write(f"Tool Request: {display}\n")
+            if decision.reason:
+                self._stdout.write(f"Reason: {decision.reason}\n")
+            self._stdout.write("Approve? [y/N] ")
+            self._stdout.flush()
+            try:
+                answer = self._stdin.readline().strip().lower()
+            except (OSError, ValueError) as exc:
+                raise ApprovalRequired(f"could not read local approval for tool {tool_name!r}: {exc}") from exc
+        if answer not in {"y", "yes"}:
+            raise ApprovalRequired(f"approval denied for tool {tool_name!r} ({display})")

cli_mcp/executor/argv.py

@@ -0,0 +1,63 @@
+"""Turning validated tool arguments back into a CLI argv."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_mcp.models import CommandSpec, Parameter, ParamKind
+
+
+def format_value(param: Parameter, value: Any) -> str:
+    """Render one argument value as a CLI token."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _tokens_for(param: Parameter, value: Any) -> list[str]:
+    """CLI tokens contributed by one parameter value."""
+    flag = param.cli_flag
+    if param.kind is ParamKind.FLAG:
+        if isinstance(value, bool):
+            return [flag] if value else []
+        if value in (1, "true", "yes", "on"):
+            return [flag]
+        return []
+    if isinstance(value, list):
+        tokens: list[str] = []
+        for item in value:
+            tokens.append(flag)
+            rendered = format_value(param, item)
+            if rendered:
+                tokens.append(rendered)
+        return tokens
+    return [flag, format_value(param, value)]
+
+
+def build_argv(command: list[str], spec: CommandSpec, arguments: dict[str, Any]) -> list[str]:
+    """Build the argv that runs *command* with the validated arguments.
+
+    Options and flags come first, positional values afterwards in declaration
+    order, which every supported framework accepts.
+    """
+    argv = [*command, *spec.argv_path]
+    for param in spec.parameters:
+        if param.kind is ParamKind.POSITIONAL:
+            continue
+        value = arguments.get(param.name)
+        if value is None:
+            continue
+        argv.extend(_tokens_for(param, value))
+    for param in spec.ordered_positionals():
+        value = arguments.get(param.name)
+        if value is None:
+            continue
+        if isinstance(value, list):
+            argv.extend(format_value(param, item) for item in value)
+        else:
+            argv.append(format_value(param, value))
+    return argv