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

cli_mcp/discovery/engine.py

@@ -0,0 +1,238 @@
+"""Recursive help walk: turn help pages into :class:`CommandSpec` definitions.
+
+The generic help strategy and every framework grammar provider share this walk;
+providers only contribute a *preprocess* hook (to normalise their own marker
+spellings) and a *refine* hook (to adjust the resulting command).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo, executable_stem, launch_for
+from cli_mcp.discovery.base import DiscoveryContext, HelpResult
+from cli_mcp.discovery.help_parser import ParsedHelp, is_help_noise, parse_help
+from cli_mcp.models import CommandSpec, DiscoveryResult, Parameter, ParamKind, sanitize_tool_name
+
+SKIP_SUBCOMMANDS = frozenset(
+    {
+        "help",
+        "completion",
+        "completions",
+        "__complete",
+        "__complete_no_color",
+        "--help",
+        "-h",
+        "--version",
+    }
+)
+
+SKIP_PARAMETERS = frozenset({"help", "h", "?", "install_completion", "show_completion", "completion"})
+
+Preprocess = Callable[[str], str]
+Refine = Callable[[CommandSpec, HelpResult], CommandSpec]
+
+
+def coerce_default(type_name: str, value: str | None) -> Any:
+    """Convert a help-text default into the declared JSON Schema type."""
+    if value is None:
+        return None
+    cleaned = value.strip().strip('"').strip("'")
+    lowered = cleaned.lower()
+    if not cleaned or lowered in {"none", "null", "nil"}:
+        return None
+    if type_name == "boolean":
+        if lowered in {"true", "yes", "1", "on"}:
+            return True
+        if lowered in {"false", "no", "0", "off"}:
+            return False
+        return None
+    if type_name == "integer":
+        try:
+            return int(lowered)
+        except ValueError:
+            return None
+    if type_name == "number":
+        try:
+            return float(lowered)
+        except ValueError:
+            return None
+    return cleaned
+
+
+def parameters_from(parsed: ParsedHelp) -> list[Parameter]:
+    """Build parameters from a parsed help page, skipping help boilerplate."""
+    parameters: list[Parameter] = []
+    for option in parsed.options:
+        if option.name.lower() in SKIP_PARAMETERS:
+            continue
+        description = option.description or (f"Value for --{option.name}" if not option.is_flag else "Toggle flag")
+        default = coerce_default(option.type, option.default)
+        parameters.append(
+            Parameter(
+                name=option.name,
+                kind=ParamKind.FLAG if option.is_flag else ParamKind.OPTION,
+                cli_name=option.name,
+                short=option.short,
+                short_only=option.short_only,
+                type=option.type,
+                description=description,
+                required=option.required,
+                default=default,
+                choices=option.choices,
+                metavar=option.metavar,
+            )
+        )
+    for positional in parsed.positionals:
+        parameters.append(
+            Parameter(
+                name=positional.name,
+                kind=ParamKind.POSITIONAL,
+                type=positional.type,
+                description=positional.description or f"Positional argument {positional.name}",
+                required=positional.required,
+            )
+        )
+    return parameters
+
+
+def _publishable_options(parsed: ParsedHelp) -> bool:
+    """Whether a help page advertises options that become MCP arguments."""
+    return any(option.name.lower() not in SKIP_PARAMETERS for option in parsed.options)
+
+
+def tool_base(target: TargetInfo) -> str:
+    """Tool name for the root command: the binary's file name without its suffix."""
+    stem = executable_stem(target.resolved_path) if target.resolved_path else target.binary
+    return sanitize_tool_name(stem or target.binary)
+
+
+def command_for(
+    target: TargetInfo,
+    path: list[str],
+    parsed: ParsedHelp,
+    provider: str,
+    help_result: HelpResult | None = None,
+    refine: Refine | None = None,
+    prefix: str | None = None,
+) -> CommandSpec:
+    """Build one command definition from a parsed help page."""
+    name_parts = ([prefix] if prefix else []) + (path or [tool_base(target)])
+    description = parsed.description.strip()
+    if not description or is_help_noise(description):
+        command_label = " ".join([target.binary, *path])
+        description = f"Run {command_label}"
+    spec = CommandSpec(
+        name="_".join(name_parts),
+        path=list(path),
+        description=description,
+        parameters=parameters_from(parsed),
+        provider=provider,
+        examples=[f"{target.binary} {' '.join(path)}".strip()],
+        has_subcommands=bool(parsed.subcommands),
+    )
+    if refine is not None and help_result is not None:
+        spec = refine(spec, help_result)
+    return spec
+
+
+def discover_from_help(
+    target: TargetInfo,
+    ctx: DiscoveryContext,
+    settings: Settings,
+    provider: str,
+    preprocess: Preprocess | None = None,
+    refine: Refine | None = None,
+    child_suffix: str | None = None,
+) -> DiscoveryResult:
+    """Walk ``--help`` recursively and collect command definitions.
+
+    *child_suffix* is a fallback help flag for subcommands whose ``--help``
+    prints nothing, e.g. ``git status --help`` opens a man pager and ``-h`` does not.
+    """
+    result = DiscoveryResult(
+        binary=target.binary,
+        resolved_path=target.resolved_path,
+        framework=target.framework,
+        strategies=[provider],
+    )
+    prefix = sanitize_tool_name(target.binary) if settings.mcp.tool_prefix else None
+
+    root_result = ctx.help_for(target)
+    if not root_result.ok and not root_result.budget_exhausted and child_suffix is not None:
+        root_result = ctx.help_for(target, suffix=child_suffix)
+    if root_result.budget_exhausted:
+        result.add_warning(root_result.stderr)
+        return result
+    root_text = preprocess_text(target.root_help or root_result.text, preprocess)
+    if not root_result.ok:
+        result.add_warning(f"no help output from {target.binary} --help")
+        return result
+
+    limit = settings.discovery.max_commands
+    seen: set[tuple[str, ...]] = set()
+    queue: list[tuple[list[str], str]] = [([], root_text)]
+    commands: list[CommandSpec] = []
+
+    while queue:
+        path, text = queue.pop(0)
+        if len(commands) >= limit:
+            result.add_warning(f"discovery capped at {limit} commands")
+            break
+        parsed = parse_help(text)
+        help_result = ctx.cache.get(tuple([*launch_for(target.resolved_path), *path, ctx.help_argv_suffix]))
+        if path and len(path) > settings.discovery.max_depth:
+            continue
+        emits_root = not path and (_publishable_options(parsed) or not parsed.subcommands)
+        if path or emits_root:
+            commands.append(command_for(target, path, parsed, provider, help_result, refine, prefix))
+        seen.add(tuple(path))
+        if len(commands) >= limit:
+            if parsed.subcommands or queue:
+                result.add_warning(f"discovery capped at {limit} commands")
+            break
+        _enqueue_children(target, ctx, path, parsed, settings, seen, queue, result, child_suffix, preprocess)
+
+    result.commands = commands
+    return result
+
+
+def _enqueue_children(
+    target: TargetInfo,
+    ctx: DiscoveryContext,
+    path: list[str],
+    parsed: ParsedHelp,
+    settings: Settings,
+    seen: set[tuple[str, ...]],
+    queue: list[tuple[list[str], str]],
+    result: DiscoveryResult,
+    child_suffix: str | None,
+    preprocess: Preprocess | None,
+) -> None:
+    """Fetch and queue the help page of every subcommand below *path*."""
+    if len(path) >= settings.discovery.max_depth:
+        return
+    for subcommand in sorted(parsed.subcommands, key=lambda item: item.name):
+        name = subcommand.name
+        if name.lower() in SKIP_SUBCOMMANDS or (tuple([*path, name]) in seen):
+            continue
+        child = ctx.help_for(target, [*path, name])
+        if child.budget_exhausted:
+            result.add_warning(child.stderr)
+            break
+        if not child.ok and child_suffix is not None:
+            child = ctx.help_for(target, [*path, name], suffix=child_suffix)
+            if child.budget_exhausted:
+                result.add_warning(child.stderr)
+                break
+        if not child.ok:
+            result.add_warning(f"no help output for {target.binary} {' '.join([*path, name])} --help")
+            continue
+        queue.append(([*path, name], preprocess_text(child.text, preprocess)))
+
+
+def preprocess_text(text: str, preprocess: Preprocess | None) -> str:
+    """Apply a provider-specific preprocessing step to help text."""
+    return preprocess(text) if preprocess is not None else text

cli_mcp/discovery/grammars.py

@@ -0,0 +1,170 @@
+"""Framework-specific help grammars.
+
+Each provider reads the help dialect of a specific CLI framework. They reuse the
+generic parser and add the few framework-specific spellings that the generic
+marker vocabulary does not cover (cobra's `(default "x")`, yargs aliases, clap
+possible values, System.CommandLine command sections).
+"""
+
+from __future__ import annotations
+
+import re
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.detect import TargetInfo
+from cli_mcp.discovery.base import DiscoveryContext, HelpResult
+from cli_mcp.discovery.engine import discover_from_help
+from cli_mcp.models import CommandSpec, DiscoveryResult
+
+_COBRA_DEFAULT = re.compile(r"\((default(?: value)?\s+([^)]*))\)")
+_COBRA_REQUIRED = re.compile(r"\((required)\)", re.IGNORECASE)
+
+
+class GenericHelpProvider:
+    """Strategy 2: parse ``--help`` output of any CLI, recursively."""
+
+    name = "help"
+    strategy = "help"
+    frameworks: tuple[str, ...] = ()
+
+    def __init__(self, settings: Settings) -> None:
+        """Store the settings that bound the recursive help walk."""
+        self.settings = settings
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Report whether the generic parser can attempt any binary."""
+        return True
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Discover commands with the generic grammar."""
+        result = discover_from_help(target, ctx, self.settings, self.name)
+        return result if result.commands else None
+
+
+class _GrammarProvider:
+    """Base for framework grammars that only activate on a matching fingerprint."""
+
+    name = "grammar"
+    strategy = "help"
+    frameworks: tuple[str, ...] = ()
+    #: Fallback help flag for subcommands whose ``--help`` prints nothing.
+    child_suffix: str | None = None
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    def supports(self, target: TargetInfo) -> bool:
+        """Activate only when the fingerprint identified one of our frameworks."""
+        return target.framework in self.frameworks
+
+    def preprocess(self, text: str) -> str:
+        """Normalise framework marker spellings before the generic parser runs."""
+        return text
+
+    def refine(self, spec: CommandSpec, help_result: HelpResult) -> CommandSpec:
+        """Adjust the command after generic parsing."""
+        return spec
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        """Discover commands with this framework's grammar."""
+        result = discover_from_help(
+            target,
+            ctx,
+            self.settings,
+            self.name,
+            preprocess=self.preprocess,
+            refine=self.refine,
+            child_suffix=self.child_suffix,
+        )
+        return result if result.commands else None
+
+
+_GIT_NEGATION = re.compile(r"--\[no-\]")
+_GIT_OPTION_VALUE = re.compile(r"\[=<([^>\]]*)>\]")
+
+
+class GitProvider(_GrammarProvider):
+    """Git's own help dialect: grouped command lists and ``--[no-]option`` flags."""
+
+    name = "git"
+    frameworks = ("git",)
+    child_suffix = "-h"
+
+    def preprocess(self, text: str) -> str:
+        """Rewrite git's negated flags and inline value placeholders into plain spellings."""
+        text = _GIT_NEGATION.sub("--", text)
+        return _GIT_OPTION_VALUE.sub(lambda match: f" <{match.group(1)}>", text)
+
+
+class CobraProvider(_GrammarProvider):
+    """Go/cobra help grammar."""
+
+    name = "cobra"
+    frameworks = ("cobra",)
+
+    def preprocess(self, text: str) -> str:
+        """Rewrite cobra's ``(default "x")`` and ``(required)`` into bracket markers."""
+        text = _COBRA_DEFAULT.sub(lambda match: f"[default: {match.group(2).strip().strip(chr(34))}]", text)
+        return _COBRA_REQUIRED.sub("[required]", text)
+
+
+class ClapProvider(_GrammarProvider):
+    """Rust/clap help grammar."""
+
+    name = "clap"
+    frameworks = ("clap",)
+
+
+class DotnetProvider(_GrammarProvider):
+    """.NET System.CommandLine help grammar."""
+
+    name = "dotnet"
+    frameworks = ("dotnet",)
+
+
+class YargsProvider(_GrammarProvider):
+    """Node.js/yargs help grammar."""
+
+    name = "yargs"
+    frameworks = ("yargs",)
+
+
+class CommanderProvider(_GrammarProvider):
+    """Node.js/commander.js help grammar."""
+
+    name = "commander"
+    frameworks = ("commander",)
+
+
+class ClickProvider(_GrammarProvider):
+    """Python/click help grammar."""
+
+    name = "click"
+    frameworks = ("click",)
+
+
+class TyperProvider(_GrammarProvider):
+    """Python/typer help grammar."""
+
+    name = "typer"
+    frameworks = ("typer",)
+
+
+class ArgparseProvider(_GrammarProvider):
+    """Python/argparse help grammar."""
+
+    name = "argparse"
+    frameworks = ("argparse",)
+
+
+GRAMMAR_PROVIDERS: tuple[type[_GrammarProvider], ...] = (
+    GitProvider,
+    CobraProvider,
+    ClapProvider,
+    DotnetProvider,
+    YargsProvider,
+    CommanderProvider,
+    ClickProvider,
+    TyperProvider,
+    ArgparseProvider,
+)