cli2mcp 0.1.1__py3-none-any.whl

cli2mcp/__init__.py

@@ -0,0 +1,3 @@
+"""cli2mcp -- Turn any CLI tool into an MCP server."""
+
+__version__ = "0.1.0"

cli2mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running cli2mcp as ``python -m cli2mcp``."""
+
+from cli2mcp.cli import main
+
+main()

cli2mcp/cli.py

@@ -0,0 +1,94 @@
+"""Command-line entry point for cli2mcp.
+
+Usage::
+
+    cli2mcp scan <command> [-o tools.json]
+    cli2mcp serve <tools.json>
+"""
+
+import argparse
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="cli2mcp",
+        description="Turn any CLI tool into an MCP server.",
+    )
+    subparsers = parser.add_subparsers(dest="action")
+
+    # --- scan ---
+    scan_parser = subparsers.add_parser(
+        "scan",
+        help="Scan a CLI tool's --help and generate a tools JSON file.",
+    )
+    scan_parser.add_argument(
+        "command",
+        help="The CLI command to scan (e.g. git, curl, docker).",
+    )
+    scan_parser.add_argument(
+        "-o",
+        "--output",
+        default=None,
+        help="Output JSON file path (default: <command>.tools.json).",
+    )
+
+    # --- serve ---
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start an MCP server from a tools JSON file.",
+    )
+    serve_parser.add_argument(
+        "tools_file",
+        help="Path to the tools JSON file.",
+    )
+    serve_parser.add_argument(
+        "-t",
+        "--transport",
+        choices=["stdio", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio).",
+    )
+
+    args = parser.parse_args()
+
+    if args.action is None:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.action == "scan":
+        from cli2mcp.scanner import scan, save
+
+        output = args.output or f"{args.command}.tools.json"
+        tools = scan(args.command)
+        save(tools, output)
+
+    elif args.action == "serve":
+        import json
+        import signal
+        from cli2mcp.server import create_server
+
+        with open(args.tools_file) as f:
+            data = json.load(f)
+
+        tool_count = len(data.get("tools", []))
+        command = data.get("command", "unknown")
+
+        print("cli2mcp server starting")
+        print(f"  Command:   {command}")
+        print(f"  Tools:     {tool_count}")
+        print(f"  File:      {args.tools_file}")
+        print(f"  Transport: {args.transport}")
+        print()
+        print("Press Ctrl+C to stop the server.")
+        sys.stdout.flush()
+
+        def _shutdown(signum, frame):
+            print("\nShutting down.")
+            sys.exit(0)
+
+        signal.signal(signal.SIGINT, _shutdown)
+        signal.signal(signal.SIGTERM, _shutdown)
+
+        server = create_server(args.tools_file)
+        server.run(transport=args.transport)

cli2mcp/parser.py

@@ -0,0 +1,30 @@
+"""Auto-detect CLI help style and delegate to the right parser.
+
+Detection order: Cobra first (most distinctive), then GNU, then Plain
+(catch-all).
+"""
+
+from cli2mcp.parsers.cobra import can_parse as _is_cobra, parse as _parse_cobra
+from cli2mcp.parsers.gnu import can_parse as _is_gnu, parse as _parse_gnu
+from cli2mcp.parsers.plain import parse as _parse_plain
+
+_PARSERS = [
+    ("cobra", _is_cobra, _parse_cobra),
+    ("gnu", _is_gnu, _parse_gnu),
+]
+
+
+def detect_style(text):
+    """Return 'cobra', 'gnu', or 'plain'."""
+    for name, can_parse, _ in _PARSERS:
+        if can_parse(text):
+            return name
+    return "plain"
+
+
+def parse_help(text):
+    """Parse --help output into {description, args, subcommands}."""
+    for _, can_parse, parse_fn in _PARSERS:
+        if can_parse(text):
+            return parse_fn(text)
+    return _parse_plain(text)

cli2mcp/parsers/__init__.py

@@ -0,0 +1,6 @@
+"""Help-text parsers for different CLI styles.
+
+- ``plain`` -- curl, busybox (no section headers)
+- ``gnu``   -- argparse, click (section headers, single-line flags)
+- ``cobra`` -- kubectl, oc, docker (multi-line flags)
+"""

cli2mcp/parsers/cobra.py

@@ -0,0 +1,175 @@
+"""Parser for Go Cobra style help text (kubectl, oc, docker, gh, ...).
+
+Flags span two lines: name + default on line 1, description on line 2.
+Subcommands are listed under category headers.
+
+    Manage your cluster:
+      get             Display one or many resources
+      describe        Show details of a resource
+
+    Options:
+        --all-namespaces=false:
+            If present, list across all namespaces.
+
+        -o, --output='':
+            Output format.  One of: json|yaml|wide|name.
+"""
+
+import re
+
+from cli2mcp.parsers.common import extract_positional_args, make_description
+
+
+def can_parse(text):
+    """True if text has Cobra-style multi-line flags or the Cobra footer."""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("-") and "=" in stripped and stripped.endswith(":"):
+            return True
+        if re.match(r'Use ".+ <command> --help"', stripped):
+            return True
+    return False
+
+
+def parse(text):
+    """Parse Cobra-style help using a state machine.
+
+    States: description, options, subcommands, skip.
+    The key pattern is "pending flag": when we see '--flag=default:',
+    we store the name and read the next line as its description.
+    """
+    description_lines = []
+    args = []
+    subcommands = []
+    state = "description"
+    pending_flag = None
+
+    for line in text.splitlines():
+        # If the previous line was a flag header, this line is its description.
+        if pending_flag is not None:
+            desc = line.strip()
+            if desc:
+                args.append(
+                    {
+                        "name": pending_flag,
+                        "description": desc,
+                        "required": False,
+                    }
+                )
+            pending_flag = None
+            continue
+
+        header = _detect_header(line)
+        if header is not None:
+            if header in ("options", "flags"):
+                state = "options"
+            elif header in ("examples", "usage", "global flags"):
+                state = "skip"
+            else:
+                state = "subcommands"
+            continue
+
+        if state == "description":
+            stripped = line.strip()
+            if stripped.lower().startswith("usage"):
+                state = "skip"
+                continue
+            if stripped:
+                description_lines.append(stripped)
+            elif description_lines:
+                state = "skip"
+
+        elif state == "options":
+            flag_name = _parse_flag_header(line)
+            if flag_name is not None:
+                pending_flag = flag_name
+            else:
+                arg = _parse_single_line_flag(line)
+                if arg is not None:
+                    args.append(arg)
+
+        elif state == "subcommands":
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if stripped.startswith("-"):
+                flag_name = _parse_flag_header(line)
+                if flag_name is not None:
+                    pending_flag = flag_name
+            else:
+                name = _parse_subcommand_line(line)
+                if name is not None:
+                    subcommands.append(name)
+
+    args.extend(extract_positional_args(text))
+
+    return {
+        "description": make_description(description_lines, text),
+        "args": args,
+        "subcommands": subcommands,
+    }
+
+
+def _detect_header(line):
+    """Return section name if line is a header like 'Options:', else None."""
+    stripped = line.strip()
+    if not stripped.endswith(":") or stripped.startswith("-"):
+        return None
+    if len(line) - len(line.lstrip()) > 4:
+        return None
+    return stripped[:-1].strip().lower()
+
+
+def _parse_flag_header(line):
+    """Parse '--output=default:' and return the flag name."""
+    stripped = line.strip()
+    if not stripped.startswith("-"):
+        return None
+
+    match = re.match(
+        r"(-\S+(?:,\s*-\S+)*)"  # flag name(s)
+        r"(?:=\S*)?"  # optional default
+        r":$",  # trailing colon
+        stripped,
+    )
+    if not match:
+        return None
+
+    flags = match.group(1)
+    names = [f.strip() for f in flags.split(",")]
+    return max(names, key=len)
+
+
+def _parse_single_line_flag(line):
+    """Parse '--output string  Output format' (single-line modern Cobra flags)."""
+    stripped = line.strip()
+    if not stripped or not stripped.startswith("-"):
+        return None
+
+    match = re.match(
+        r"(-\S+(?:,\s*-\S+)*)"  # flag name(s)
+        r"(?:\s+\S+)?"  # optional type/metavar
+        r"\s{2,}"  # gap (2+ spaces)
+        r"(.+)",  # description
+        stripped,
+    )
+    if match:
+        flags = match.group(1)
+        names = [f.strip() for f in flags.split(",")]
+        return {
+            "name": max(names, key=len),
+            "description": match.group(2).strip(),
+            "required": False,
+        }
+    return None
+
+
+def _parse_subcommand_line(line):
+    """Parse '  get  Display one or many resources' into the name."""
+    stripped = line.strip()
+    if not stripped:
+        return None
+    match = re.match(r"(\w[\w-]*)\s{2,}(.+)", stripped)
+    if match:
+        return match.group(1)
+    return None

cli2mcp/parsers/common.py

@@ -0,0 +1,42 @@
+"""Shared helpers used by all parsers."""
+
+import re
+
+
+def make_description(description_lines, text):
+    """Join description lines, or fall back to the command name from Usage."""
+    if description_lines:
+        return " ".join(description_lines)
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.lower().startswith("usage"):
+            # Capture "git commit" from "usage: git commit [-a] ..."
+            match = re.match(r"[Uu]sage:\s*([\w][\w.-]*(?:\s+[\w][\w.-]*)*)", stripped)
+            if match:
+                return f"{match.group(1)} command"
+    return ""
+
+
+def extract_positional_args(text):
+    """Extract positional args from the Usage line (e.g. <url>)."""
+    args = []
+    seen = set()
+
+    for line in text.splitlines():
+        if not line.strip().lower().startswith("usage"):
+            continue
+
+        for match in re.finditer(r"<(\w[\w-]*)>", line):
+            name = match.group(1).lower()
+            if name not in seen:
+                args.append(
+                    {
+                        "name": name,
+                        "description": name,
+                        "required": True,
+                    }
+                )
+                seen.add(name)
+
+    return args

cli2mcp/parsers/gnu.py

@@ -0,0 +1,142 @@
+"""Parser for GNU / Python argparse style help text.
+
+These tools have section headers like "Options:" and "Commands:".
+Flags and descriptions sit on the same line:
+
+    usage: mytool [-v] [-o FILE] filename
+
+    My awesome tool for processing files.
+
+    Options:
+      -v, --verbose     Enable verbose output
+      -o, --output FILE Output file path
+
+    Commands:
+      run               Run the tool
+      check             Check the input
+"""
+
+import re
+
+from cli2mcp.parsers.common import extract_positional_args, make_description
+
+_POSITIONAL_HEADERS = {"positional arguments", "positional"}
+_OPTION_HEADERS = {"options", "optional arguments", "flags"}
+_SUBCOMMAND_HEADERS = {"commands", "subcommands", "available commands"}
+
+
+def can_parse(text):
+    """True if text has at least one known section header."""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped.endswith(":") or stripped.startswith("-"):
+            continue
+        name = stripped[:-1].strip().lower()
+        if name in _POSITIONAL_HEADERS | _OPTION_HEADERS | _SUBCOMMAND_HEADERS:
+            return True
+    return False
+
+
+def parse(text):
+    """Parse GNU-style help using a simple state machine.
+
+    States: description, positional, options, subcommands, skip.
+    Transitions happen when we hit a section header.
+    """
+    description_lines = []
+    args = []
+    subcommands = []
+    state = "description"
+
+    for line in text.splitlines():
+        header = _detect_header(line)
+        if header is not None:
+            if header in _POSITIONAL_HEADERS:
+                state = "positional"
+            elif header in _OPTION_HEADERS:
+                state = "options"
+            elif header in _SUBCOMMAND_HEADERS:
+                state = "subcommands"
+            else:
+                state = "skip"
+            continue
+
+        if state == "description":
+            stripped = line.strip()
+            if stripped.lower().startswith("usage"):
+                state = "skip"
+                continue
+            if stripped:
+                description_lines.append(stripped)
+            elif description_lines:
+                state = "skip"
+
+        elif state == "positional":
+            arg = _parse_flag_line(line)
+            if arg is not None:
+                arg["required"] = True
+                args.append(arg)
+
+        elif state == "options":
+            arg = _parse_flag_line(line)
+            if arg is not None:
+                arg["required"] = False
+                args.append(arg)
+
+        elif state == "subcommands":
+            name = _parse_subcommand_line(line)
+            if name is not None:
+                subcommands.append(name)
+
+    args.extend(extract_positional_args(text))
+
+    return {
+        "description": make_description(description_lines, text),
+        "args": args,
+        "subcommands": subcommands,
+    }
+
+
+def _detect_header(line):
+    """Return section name if line is a header like 'Options:', else None."""
+    stripped = line.strip()
+    if not stripped.endswith(":") or stripped.startswith("-"):
+        return None
+    if len(line) - len(line.lstrip()) > 4:
+        return None
+    return stripped[:-1].strip().lower()
+
+
+def _parse_flag_line(line):
+    """Parse '-v, --verbose  Enable verbose output' into a dict."""
+    stripped = line.strip()
+    if not stripped or stripped.startswith("---"):
+        return None
+
+    match = re.match(
+        r"(-\S+(?:,\s*-\S+)*)"  # flag name(s)
+        r"(?:\s+\S+)?"  # optional metavar
+        r"\s{2,}"  # gap
+        r"(.+)",  # description
+        stripped,
+    )
+    if match:
+        flags = match.group(1)
+        names = [f.strip() for f in flags.split(",")]
+        return {
+            "name": max(names, key=len),
+            "description": match.group(2).strip(),
+            "required": False,
+        }
+    return None
+
+
+def _parse_subcommand_line(line):
+    """Parse '  commit  Record changes' into the subcommand name."""
+    stripped = line.strip()
+    if not stripped:
+        return None
+    match = re.match(r"(\w[\w-]*)\s{2,}(.+)", stripped)
+    if match:
+        return match.group(1)
+    return None

cli2mcp/parsers/plain.py

@@ -0,0 +1,112 @@
+"""Parser for plain / minimal help text (curl, busybox, ...).
+
+These tools print flags directly after a Usage: line with no
+section headers like "Options:" or "Commands:".
+
+    Usage: curl [options...] <url>
+     -d, --data <data>           HTTP POST data
+     -f, --fail                  Fail fast with no output on HTTP errors
+"""
+
+import re
+
+from cli2mcp.parsers.common import extract_positional_args, make_description
+
+
+def can_parse(text):
+    """True if text has flag lines but no section headers."""
+    has_flags = False
+    has_headers = False
+
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("-") and "  " in stripped:
+            has_flags = True
+        if (
+            stripped.endswith(":")
+            and not stripped.startswith("-")
+            and len(line) - len(line.lstrip()) <= 4
+        ):
+            name = stripped[:-1].strip().lower()
+            if name in (
+                "options",
+                "commands",
+                "positional arguments",
+                "optional arguments",
+                "subcommands",
+                "flags",
+            ):
+                has_headers = True
+
+    return has_flags and not has_headers
+
+
+def parse(text):
+    """Parse plain-style help text.
+
+    1. Collect description lines before "Usage:"
+    2. After Usage:, parse "-" lines as flags and "word  desc" as subcommands
+    """
+    description_lines = []
+    args = []
+    subcommands = []
+    past_usage = False
+
+    for line in text.splitlines():
+        stripped = line.strip()
+
+        if not past_usage:
+            if stripped.lower().startswith("usage"):
+                past_usage = True
+                continue
+            if stripped:
+                description_lines.append(stripped)
+            continue
+
+        if not stripped:
+            continue
+
+        if stripped.startswith("-"):
+            arg = _parse_flag_line(stripped)
+            if arg is not None:
+                args.append(arg)
+        else:
+            name = _parse_subcommand_line(stripped)
+            if name is not None:
+                subcommands.append(name)
+
+    args.extend(extract_positional_args(text))
+
+    return {
+        "description": make_description(description_lines, text),
+        "args": args,
+        "subcommands": subcommands,
+    }
+
+
+def _parse_flag_line(stripped):
+    """Parse '-d, --data <data>  HTTP POST data' into a dict."""
+    match = re.match(
+        r"(-\S+(?:,\s*-\S+)*)"  # flag name(s)
+        r"(?:\s+\S+)?"  # optional metavar
+        r"\s{2,}"  # gap
+        r"(.+)",  # description
+        stripped,
+    )
+    if match:
+        flags = match.group(1)
+        names = [f.strip() for f in flags.split(",")]
+        return {
+            "name": max(names, key=len),
+            "description": match.group(2).strip(),
+            "required": False,
+        }
+    return None
+
+
+def _parse_subcommand_line(stripped):
+    """Parse '  clone  Clone a repository' into the subcommand name."""
+    match = re.match(r"(\w[\w-]*)\s{2,}(.+)", stripped)
+    if match:
+        return match.group(1)
+    return None