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

cli_mcp/config/settings.py

@@ -0,0 +1,171 @@
+"""Typed configuration for cli-mcp.
+
+Everything the tool needs is expressed here: which binary to expose, how to
+discover it, how to execute it and how to publish it over MCP.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+TransportName = Literal["stdio", "http", "streamable-http", "sse"]
+ApprovalMode = Literal["auto", "prompt", "explicit"]
+DEFAULT_STRATEGIES: tuple[str, ...] = ("reflection", "help", "manifest")
+
+
+class SandboxSettings(BaseModel):
+    """Run the exposed CLI inside a container runtime."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    backend: Literal["docker", "podman"] = "docker"
+    image: str = "alpine:3.20"
+    workdir_mount: bool = Field(True, description="Mount the current directory into the container")
+    container_workdir: str = "/work"
+    network: bool = False
+    extra_args: list[str] = Field(default_factory=list)
+
+    @field_validator("image")
+    @classmethod
+    def _non_empty(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("sandbox image must be non-empty")
+        return value.strip()
+
+
+class SecuritySettings(BaseModel):
+    """Allow list, read-only mode, approval gate and execution limits."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    allowlist: list[str] = Field(default_factory=list, description="Binaries that may be exposed")
+    readonly: bool = False
+    readonly_argv: list[list[str]] = Field(
+        default_factory=list,
+        description="Exact complete argv vectors explicitly approved by the operator for read-only execution",
+    )
+    approval: bool = False
+    approval_mode: ApprovalMode = "auto"
+    block_patterns: list[str] = Field(default_factory=list, description="Extra regexes rejected in argv")
+    allow_patterns: list[str] = Field(default_factory=list, description="Regexes that re-admit blocked verbs")
+    timeout_seconds: float = Field(60.0, gt=0)
+    max_output_bytes: int = Field(200_000, gt=0)
+    sandbox: SandboxSettings | None = None
+
+    @field_validator("readonly_argv")
+    @classmethod
+    def _readonly_argv(cls, value: list[list[str]]) -> list[list[str]]:
+        if any(not argv or any("\0" in token for token in argv) for argv in value):
+            raise ValueError("readonly_argv entries must be non-empty argv vectors without NUL bytes")
+        return value
+
+    @field_validator("allowlist")
+    @classmethod
+    def _normalise_allowlist(cls, value: list[str]) -> list[str]:
+        return [item.strip().lower() for item in value if item.strip()]
+
+    @field_validator("block_patterns", "allow_patterns")
+    @classmethod
+    def _strip_patterns(cls, value: list[str]) -> list[str]:
+        return [item for item in value if item.strip()]
+
+
+class DiscoverySettings(BaseModel):
+    """Strategy order and limits for CLI discovery."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    strategies: list[str] = Field(default_factory=lambda: list(DEFAULT_STRATEGIES))
+    include: list[str] | None = None
+    exclude: list[str] | None = None
+    max_depth: int = Field(2, ge=0, le=6)
+    max_commands: int = Field(120, ge=1, le=1000)
+    allow_import_reflection: bool = Field(
+        False,
+        description="Allow Python/Node reflection, which imports the target module and may run code",
+    )
+    help_timeout_seconds: float = Field(10.0, gt=0)
+
+    @field_validator("strategies")
+    @classmethod
+    def _ordered(cls, value: list[str]) -> list[str]:
+        seen: list[str] = []
+        for item in value:
+            name = item.strip().lower()
+            if name and name not in seen:
+                seen.append(name)
+        return seen or list(DEFAULT_STRATEGIES)
+
+
+class ServerSettings(BaseModel):
+    """MCP server identity and transport choice."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str | None = None
+    title: str | None = None
+    description: str | None = None
+    instructions: str | None = None
+    version: str = Field("0.1.0", description="Server version reported over MCP")
+    transport: TransportName = "stdio"
+    host: str = "127.0.0.1"
+    port: int = Field(8801, ge=1, le=65535)
+    path: str = "/mcp"
+    json_response: bool = False
+    stateless_http: bool = False
+    include_docs_tool: bool = True
+    tool_prefix: bool = Field(
+        False,
+        description="Prefix tool names with the binary name, to avoid collisions when exposing several CLIs",
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _leading_slash(cls, value: str) -> str:
+        return value if value.startswith("/") else f"/{value}"
+
+
+class ExecutionSettings(BaseModel):
+    """Explicit working directory for target discovery and execution."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cwd: Path | None = None
+
+    @field_validator("cwd")
+    @classmethod
+    def _cwd(cls, value: Path | None) -> Path | None:
+        if value is not None and (not value.is_absolute() or not value.is_dir()):
+            raise ValueError("execution.cwd must be an absolute path to an existing directory")
+        return value
+
+
+class Settings(BaseModel):
+    """Complete configuration for one exposed binary."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    binary: str
+    security: SecuritySettings = Field(default_factory=SecuritySettings)
+    discovery: DiscoverySettings = Field(default_factory=DiscoverySettings)
+    mcp: ServerSettings = Field(default_factory=ServerSettings)
+    execution: ExecutionSettings = Field(default_factory=ExecutionSettings)
+    manifest: str | None = Field(None, description="Optional manifest file that overrides discovery")
+
+    @field_validator("binary")
+    @classmethod
+    def _binary_name(cls, value: str) -> str:
+        cleaned = value.strip()
+        if not cleaned:
+            raise ValueError("binary must be non-empty")
+        return cleaned
+
+    @property
+    def server_name(self) -> str:
+        """Default MCP server name derived from the binary."""
+        from cli_mcp.models import sanitize_tool_name
+
+        return self.mcp.name or sanitize_tool_name(self.binary)

cli_mcp/core.py

@@ -0,0 +1,133 @@
+"""End-to-end orchestration: config, binary detection, discovery, schemas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from cli_mcp.config.loader import load_settings
+from cli_mcp.config.settings import ApprovalMode, Settings
+from cli_mcp.detect import TargetInfo, fingerprint, launch_for, resolve_binary
+from cli_mcp.discovery.base import DiscoveryContext
+from cli_mcp.discovery.pipeline import discover
+from cli_mcp.models import DiscoveryResult
+from cli_mcp.plugins import registry_with_plugins
+from cli_mcp.security.policy import AccessPolicy
+
+
+@dataclass(frozen=True)
+class PreparedCli:
+    """Everything needed to publish one binary as an MCP server."""
+
+    settings: Settings
+    target: TargetInfo
+    result: DiscoveryResult
+
+    @property
+    def binary_path(self) -> str:
+        """Absolute path of the resolved CLI binary."""
+        return self.result.resolved_path or self.target.resolved_path
+
+    @property
+    def launch(self) -> list[str]:
+        """Command that runs the CLI: interpreter plus script path when needed."""
+        return launch_for(self.binary_path)
+
+
+def _apply_server_overrides(settings: Settings, flags: dict[str, Any]) -> None:
+    """Apply transport and publishing flags."""
+    if flags.get("transport"):
+        settings.mcp.transport = str(flags["transport"])  # type: ignore[assignment]
+    if flags.get("host"):
+        settings.mcp.host = str(flags["host"])
+    if flags.get("port"):
+        settings.mcp.port = int(flags["port"])
+    if flags.get("tool_prefix") is not None:
+        settings.mcp.tool_prefix = bool(flags["tool_prefix"])
+    if flags.get("docs") is not None:
+        settings.mcp.include_docs_tool = bool(flags["docs"])
+
+
+def _apply_security_overrides(settings: Settings, flags: dict[str, Any]) -> None:
+    """Apply allow list, read-only, approval and timeout flags."""
+    if flags.get("readonly") is not None:
+        settings.security.readonly = bool(flags["readonly"])
+    if flags.get("approval") is not None:
+        settings.security.approval = bool(flags["approval"])
+    if flags.get("approval_mode"):
+        settings.security.approval_mode = str(flags["approval_mode"])  # type: ignore[assignment]
+    allow = flags.get("allow")
+    if allow:
+        settings.security.allowlist = [item.strip() for item in allow if item.strip()]
+    if flags.get("timeout"):
+        settings.security.timeout_seconds = float(flags["timeout"])
+
+
+def _apply_discovery_overrides(settings: Settings, flags: dict[str, Any]) -> None:
+    """Apply strategy, filter and depth flags."""
+    if flags.get("strategies"):
+        settings.discovery.strategies = list(flags["strategies"])
+    if flags.get("include"):
+        settings.discovery.include = list(flags["include"])
+    if flags.get("exclude"):
+        settings.discovery.exclude = list(flags["exclude"])
+    if flags.get("max_depth") is not None:
+        settings.discovery.max_depth = int(flags["max_depth"])
+    if flags.get("allow_reflection") is not None:
+        settings.discovery.allow_import_reflection = bool(flags["allow_reflection"])
+
+
+def apply_overrides(settings: Settings, **flags: Any) -> Settings:
+    """Apply command-line overrides onto a settings object."""
+    _apply_server_overrides(settings, flags)
+    _apply_security_overrides(settings, flags)
+    _apply_discovery_overrides(settings, flags)
+    return settings
+
+
+def prepare(
+    binary: str | None = None,
+    config: str | Path | None = None,
+    cwd: Path | None = None,
+    overrides: dict[str, Any] | None = None,
+    *,
+    load_plugins: bool = True,
+) -> PreparedCli:
+    """Resolve *binary*, discover its commands and build the settings for it."""
+    working_dir = cwd or Path.cwd()
+    config_path = Path(config) if isinstance(config, str) else config
+    settings = load_settings(path=config_path, binary=binary, cwd=working_dir)
+    if overrides:
+        apply_overrides(settings, **overrides)
+
+    working_dir = settings.execution.cwd or working_dir
+    AccessPolicy(settings.security).authorize_binary(settings.binary)
+    target = resolve_binary(settings.binary)
+    help_suffix = "-h" if Path(target.resolved_path).stem.casefold() == "git" else "--help"
+    context = DiscoveryContext(settings.discovery, cwd=working_dir, help_argv_suffix=help_suffix)
+
+    if target.framework is None:
+        root_help = context.help_for(target)
+        if root_help.ok:
+            detected = fingerprint(root_help.text)
+            if detected:
+                target = target.with_help(root_help.text)
+
+    registry = registry_with_plugins(settings, load_plugins=load_plugins)
+    result = discover(target, settings, context, registry)
+    return PreparedCli(settings=settings, target=target, result=result)
+
+
+def transport_endpoint(settings: Settings) -> str:
+    """Where the server listens, for user-facing output."""
+    if settings.mcp.transport == "stdio":
+        return "stdio"
+    if settings.mcp.transport == "sse":
+        return f"http://{settings.mcp.host}:{settings.mcp.port}{settings.mcp.path} (SSE, deprecated)"
+    return f"http://{settings.mcp.host}:{settings.mcp.port}{settings.mcp.path}"
+
+
+def approval_mode(settings: Settings) -> ApprovalMode:
+    """Return the active approval mode."""
+    return settings.security.approval_mode

cli_mcp/detect.py

@@ -0,0 +1,143 @@
+"""Binary resolution and CLI framework fingerprinting.
+
+Resolution answers *where* the binary is; fingerprinting answers *which
+framework* produced its help output, so the matching grammar provider can be
+picked before the generic parser is used.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path, PureWindowsPath
+from typing import Literal
+
+from cli_mcp.errors import BinaryNotFoundError, SecurityViolation
+
+Origin = Literal["native", "python", "node"]
+
+_PY_SUFFIXES = {".py", ".pyw"}
+_NODE_SUFFIXES = {".js", ".mjs", ".cjs"}
+
+#: Markers that identify a framework from its help output, in the casing each
+#: framework emits. The framework with the most matched markers wins.
+_FINGERPRINTS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("git", ("usage: git", "These are common Git commands", "git help")),
+    ("cobra", ("Available Commands:", "Flags:", "(default")),
+    ("clap", ("Commands:", "Options:", "possible values:", "[default:")),
+    ("dotnet", ("Direct commands:", "Show help and usage", "Usage:")),
+    ("typer", ("Usage:", "Options:", "--install-completion", "--show-completion")),
+    ("click", ("Usage:", "Options:", "Commands:", "Show this message and exit.")),
+    ("yargs", ("Options:", "[string]", "[boolean]", "[required]")),
+    ("commander", ("Usage:", "[options]", "[command]", "Commands:")),
+    ("argparse", ("usage:", "options:", "-h, --help", "positional arguments:")),
+)
+
+_MIN_FINGERPRINT_SCORE = 2
+_ANSI_SEQUENCE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI CSI sequences before interpreting help text."""
+    return _ANSI_SEQUENCE.sub("", text)
+
+
+def executable_stem(path: str) -> str:
+    """Extract a display name from Windows or POSIX paths on either platform."""
+    return PureWindowsPath(path).stem if "\\" in path else Path(path).stem
+
+
+@dataclass(frozen=True)
+class TargetInfo:
+    """What cli-mcp knows about the binary it is about to expose."""
+
+    binary: str
+    resolved_path: str
+    origin: Origin
+    framework: str | None = None
+    root_help: str | None = None
+
+    @property
+    def is_script(self) -> bool:
+        """Whether the target is an interpretable script rather than a native binary."""
+        return self.origin != "native"
+
+    def with_help(self, help_text: str | None) -> TargetInfo:
+        """Return a copy carrying the root help text and its fingerprint."""
+        return replace(self, root_help=help_text, framework=self.framework or fingerprint(help_text))
+
+
+def classify(resolved_path: Path) -> Origin:
+    """Detect whether the target is a native binary, a Python script or a Node script."""
+    suffix = resolved_path.suffix.lower()
+    if suffix in _PY_SUFFIXES:
+        return "python"
+    if suffix in _NODE_SUFFIXES:
+        return "node"
+    try:
+        first_line = resolved_path.open("rb").readline()
+    except OSError:
+        return "native"
+    if not first_line.startswith(b"#!"):
+        return "native"
+    shebang = first_line.decode("utf-8", errors="replace").strip().lower()
+    if "python" in shebang:
+        return "python"
+    if "node" in shebang:
+        return "node"
+    return "native"
+
+
+def reject_batch_target(path: str) -> None:
+    """Reject Windows batch files, which can invoke a shell despite shell=False."""
+    if Path(path).suffix.lower() in {".bat", ".cmd"}:
+        raise SecurityViolation("Windows .bat/.cmd targets are not supported; use the underlying executable")
+
+
+def resolve_binary(binary: str) -> TargetInfo:
+    """Locate *binary* as a path or on ``PATH`` and classify it."""
+    candidate = Path(binary)
+    if candidate.is_file():
+        resolved: Path | None = candidate
+    else:
+        found = shutil.which(binary)
+        resolved = Path(found) if found else None
+    if resolved is None:
+        raise BinaryNotFoundError(
+            f"binary {binary!r} not found. Install it, pass an absolute path, or add it to PATH."
+        )
+    reject_batch_target(str(resolved))
+    return TargetInfo(binary=binary, resolved_path=str(resolved), origin=classify(resolved))
+
+
+def launch_for(path: str) -> list[str]:
+    """Command that runs *path*: an interpreter prefix when it is a script."""
+    reject_batch_target(path)
+    origin = classify(Path(path))
+    if origin == "python":
+        return [sys.executable, path]
+    if origin == "node":
+        return [shutil.which("node") or "node", path]
+    return [path]
+
+
+def launch_command(target: TargetInfo) -> list[str]:
+    """Command line for *target*, without subcommand arguments."""
+    return launch_for(target.resolved_path)
+
+
+def fingerprint(help_text: str | None) -> str | None:
+    """Identify the CLI framework from help output, if a known one matches."""
+    if not help_text:
+        return None
+    help_text = strip_ansi(help_text)
+    best_framework: str | None = None
+    best_score = 0
+    for framework, markers in _FINGERPRINTS:
+        score = sum(1 for marker in markers if marker in help_text)
+        if score > best_score:
+            best_framework = framework
+            best_score = score
+    return best_framework if best_score >= _MIN_FINGERPRINT_SCORE else None

cli_mcp/discovery/__init__.py

@@ -0,0 +1,49 @@
+"""Discovery package: strategies, providers, registry and pipeline."""
+
+from __future__ import annotations
+
+from cli_mcp.discovery.base import DiscoveryContext, DiscoveryProvider, HelpResult
+from cli_mcp.discovery.engine import coerce_default, command_for, discover_from_help, parameters_from, tool_base
+from cli_mcp.discovery.grammars import GRAMMAR_PROVIDERS, GenericHelpProvider
+from cli_mcp.discovery.help_parser import parse_help
+from cli_mcp.discovery.manifest import (
+    ManifestDocument,
+    ManifestProvider,
+    apply_filters,
+    read_manifest,
+)
+from cli_mcp.discovery.node_reflection import NodeReflectionProvider
+from cli_mcp.discovery.pipeline import discover, merge_manifest
+from cli_mcp.discovery.python_reflection import PythonReflectionProvider
+from cli_mcp.discovery.registry import (
+    ENTRY_POINT_GROUP,
+    ProviderRegistry,
+    Registration,
+    plugin_providers,
+)
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "GRAMMAR_PROVIDERS",
+    "DiscoveryContext",
+    "DiscoveryProvider",
+    "GenericHelpProvider",
+    "HelpResult",
+    "ManifestDocument",
+    "ManifestProvider",
+    "NodeReflectionProvider",
+    "ProviderRegistry",
+    "PythonReflectionProvider",
+    "Registration",
+    "apply_filters",
+    "coerce_default",
+    "command_for",
+    "discover",
+    "discover_from_help",
+    "merge_manifest",
+    "parameters_from",
+    "parse_help",
+    "plugin_providers",
+    "read_manifest",
+    "tool_base",
+]

cli_mcp/discovery/base.py

@@ -0,0 +1,129 @@
+"""Discovery provider contract and the capabilities providers may use."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from cli_mcp.config.settings import DiscoverySettings, SecuritySettings
+from cli_mcp.detect import TargetInfo, launch_for
+from cli_mcp.errors import ExecutionError
+from cli_mcp.executor.runner import run
+from cli_mcp.models import DiscoveryResult
+
+MAX_HELP_BYTES = 400_000
+
+
+@dataclass(frozen=True)
+class HelpResult:
+    """Captured output of a help invocation."""
+
+    argv: list[str]
+    exit_code: int
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    budget_exhausted: bool = False
+
+    @property
+    def ok(self) -> bool:
+        """Return whether the invocation produced usable output."""
+        if self.timed_out or self.budget_exhausted:
+            return False
+        return bool(self.stdout.strip() or self.stderr.strip())
+
+    @property
+    def text(self) -> str:
+        """Help text, preferring stdout with a stderr fallback."""
+        return self.stdout if self.stdout.strip() else self.stderr
+
+
+@dataclass
+class DiscoveryContext:
+    """Runtime capabilities handed to providers: run help commands, read sources."""
+
+    settings: DiscoverySettings
+    cwd: Path | None = None
+    help_argv_suffix: str = "--help"
+    cache: dict[tuple[str, ...], HelpResult] = field(default_factory=dict)
+    _help_calls: int = field(default=0, init=False)
+
+    def run(self, argv: list[str], timeout: float | None = None, env: dict[str, str] | None = None) -> HelpResult:
+        """Run *argv* without a shell and capture its output."""
+        limit = timeout if timeout is not None else self.settings.help_timeout_seconds
+        environment = os.environ.copy()
+        if env:
+            environment.update(env)
+        try:
+            completed = run(
+                argv, SecuritySettings(timeout_seconds=limit, max_output_bytes=MAX_HELP_BYTES),
+                self.cwd, env=environment,
+            )
+        except ExecutionError as exc:
+            return HelpResult(argv=list(argv), exit_code=-1, stdout="", stderr=str(exc))
+        return HelpResult(
+            argv=list(argv),
+            exit_code=completed.exit_code,
+            stdout=completed.stdout,
+            stderr=completed.stderr,
+            timed_out=completed.exit_code == -1 and "[cli-mcp] timed out after" in completed.stderr,
+        )
+
+    def help_for(self, target: TargetInfo, path: list[str] | None = None, suffix: str | None = None) -> HelpResult:
+        """Run cached help queries with a shared budget checked before spawning."""
+        argv = [*launch_for(target.resolved_path), *(path or []), suffix or self.help_argv_suffix]
+        key = tuple(argv)
+        cached = self.cache.get(key)
+        if cached is not None:
+            return cached
+        if self._help_calls >= self.settings.max_commands:
+            return HelpResult(
+                argv=argv,
+                exit_code=-1,
+                stdout="",
+                stderr=f"discovery help invocation budget exhausted ({self.settings.max_commands} calls)",
+                budget_exhausted=True,
+            )
+        self._help_calls += 1
+        result = self.run(argv)
+        self.cache[key] = result
+        return result
+
+    def read_source(self, target: TargetInfo, max_bytes: int = 200_000) -> str:
+        """Read a script target's source, or return an empty string for binaries."""
+        try:
+            return Path(target.resolved_path).read_text(encoding="utf-8", errors="replace")[:max_bytes]
+        except OSError:
+            return ""
+
+    def interpreter(self, origin: str) -> str | None:
+        """Return the executable that can run a script target of the given origin."""
+        if origin == "python":
+            import sys
+
+            return sys.executable
+        if origin == "node":
+            import shutil
+
+            return shutil.which("node")
+        return None
+
+
+class DiscoveryProvider(Protocol):
+    """A discovery strategy. Third parties implement this and register it."""
+
+    name: str
+    #: Strategy bucket this provider belongs to: "reflection", "help" or "manifest".
+    strategy: str
+    #: Framework fingerprints this provider understands.
+    frameworks: tuple[str, ...]
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Whether this provider can handle *target*."""
+        ...
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Return command definitions, or ``None`` when this provider yields nothing."""
+        ...