cli2mcp 0.1.1__py3-none-any.whl

cli2mcp/scanner.py

@@ -0,0 +1,89 @@
+"""Scan a CLI tool and produce a tools descriptor.
+
+Runs '<command> -h', parses the output, recurses into subcommands,
+and assembles a dictionary that can be written to JSON.
+"""
+
+import json
+import subprocess
+import sys
+
+from cli2mcp.parser import parse_help
+
+
+def _run_help(command_parts):
+    """Run '<command> -h' and return the output text."""
+    cmd = list(command_parts) + ["-h"]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except FileNotFoundError:
+        print(f"Error: command not found: {cmd[0]}", file=sys.stderr)
+        sys.exit(1)
+    except subprocess.TimeoutExpired:
+        return ""
+
+    return result.stdout or result.stderr or ""
+
+
+_MAX_DEPTH = 5
+
+
+def scan(command):
+    """Scan a CLI tool and return a tools descriptor dictionary.
+
+    Recursively descends into subcommands until leaf commands (those
+    without further subcommands) are reached.  Only leaf commands
+    become tool entries.
+    """
+    tools = _scan_recursive([command], command, depth=0)
+    return {"command": command, "tools": tools}
+
+
+def _scan_recursive(command_parts, prefix, depth):
+    """Recursively scan subcommands, returning tools for leaf commands."""
+    if depth > _MAX_DEPTH:
+        return []
+
+    help_text = _run_help(command_parts)
+    parsed = parse_help(help_text)
+
+    tools = []
+    if parsed["subcommands"]:
+        for sub in parsed["subcommands"]:
+            tools.extend(
+                _scan_recursive(command_parts + [sub], f"{prefix}_{sub}", depth + 1)
+            )
+    else:
+        tools.append(
+            {
+                "name": prefix,
+                "description": parsed["description"],
+                "args": _format_args(parsed["args"]),
+            }
+        )
+    return tools
+
+
+def _format_args(args):
+    """Normalise argument dicts for the JSON output."""
+    return [
+        {
+            "name": arg["name"],
+            "description": arg["description"],
+            "type": "string",
+            "required": arg["required"],
+        }
+        for arg in args
+    ]
+
+
+def save(tools_dict, path):
+    """Write a tools descriptor dictionary to a JSON file."""
+    with open(path, "w") as f:
+        json.dump(tools_dict, f, indent=2)
+    print(f"Wrote {path}")

cli2mcp/server.py

@@ -0,0 +1,164 @@
+"""MCP server that exposes CLI tools described in a JSON file.
+
+This module loads a ``tools.json`` file produced by the scanner, registers
+every tool entry with FastMCP, and -- when a tool is called -- translates
+the MCP arguments back into a CLI command and runs it.
+
+**The core challenge:**
+
+FastMCP inspects Python function *signatures* to build the JSON Schema
+that tells MCP clients which parameters a tool accepts.  But our tools
+are defined at runtime (from JSON), not at coding time.  So we
+dynamically build a function whose signature matches the args listed in
+the JSON -- giving FastMCP the type information it needs.
+"""
+
+import inspect
+import json
+import subprocess
+
+from mcp.server.fastmcp import FastMCP
+
+
+def _to_param_name(arg_name):
+    """Convert a CLI arg name to a valid Python parameter name.
+
+    Strips leading dashes and replaces hyphens with underscores,
+    because Python identifiers cannot contain hyphens::
+
+        "--upload-file"  ->  "upload_file"
+        "pathspec"       ->  "pathspec"
+        "-v"             ->  "v"
+    """
+    return arg_name.lstrip("-").replace("-", "_")
+
+
+def _build_command(base_command, tool, call_args):
+    """Turn MCP tool-call arguments back into a CLI command list.
+
+    Flags (args whose name starts with ``-``) are emitted as
+    ``--flag value`` pairs.  Positional args are appended at the end
+    in the order they appear in the tool definition.
+
+    Example::
+
+        tool  = {"name": "git_commit", "args": [
+            {"name": "--message", ...},
+            {"name": "pathspec", ...},
+        ]}
+        call_args = {"message": "fix bug", "pathspec": "main.py"}
+
+        result = ["git", "commit", "--message", "fix bug", "main.py"]
+    """
+    cmd = [base_command]
+
+    # Derive subcommand path from tool name (e.g. "kubectl-mtv_get_plan" -> ["get", "plan"]).
+    prefix = base_command + "_"
+    if tool["name"].startswith(prefix):
+        subcommand = tool["name"][len(prefix) :]
+        cmd.extend(subcommand.split("_"))
+
+    positionals = []
+
+    for arg_def in tool["args"]:
+        arg_name = arg_def["name"]  # e.g. "--upload-file"
+        key = _to_param_name(arg_name)  # e.g. "upload_file"
+
+        if key not in call_args:
+            continue
+
+        value = str(call_args[key])
+
+        if arg_name.startswith("-"):
+            cmd.extend([arg_name, value])
+        else:
+            positionals.append(value)
+
+    cmd.extend(positionals)
+    return cmd
+
+
+def _make_handler(base_command, tool):
+    """Build an async handler function with a proper signature.
+
+    FastMCP reads the function's parameter list to generate the tool's
+    JSON Schema.  A plain ``**kwargs`` handler would produce a useless
+    schema.  Instead, we create a function whose parameters match the
+    args defined in the JSON file.
+
+    For example, if the JSON says the tool has args ``--output`` and
+    ``url``, we produce a function equivalent to::
+
+        async def curl(output: str = "", url: str = "") -> str:
+            ...
+
+    We use ``inspect.Parameter`` to build the signature dynamically.
+    """
+    tool_args = tool["args"]
+
+    # Sort so required params come first (Python requires this).
+    sorted_args = sorted(tool_args, key=lambda a: not a.get("required"))
+
+    params = []
+    for arg_def in sorted_args:
+        key = _to_param_name(arg_def["name"])
+        if arg_def.get("required"):
+            # Required args have no default value.
+            param = inspect.Parameter(
+                key,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                annotation=str,
+            )
+        else:
+            # Optional args default to empty string.
+            param = inspect.Parameter(
+                key,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default="",
+                annotation=str,
+            )
+        params.append(param)
+
+    # The actual handler that runs the CLI command.
+    async def handler(**kwargs):
+        # Remove args the caller left at their default (empty string).
+        call_args = {k: v for k, v in kwargs.items() if v != ""}
+        cmd = _build_command(base_command, tool, call_args)
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        output = result.stdout
+        if result.returncode != 0:
+            output += result.stderr
+        return output or "(no output)"
+
+    # Attach the proper signature so FastMCP can inspect it.
+    handler.__signature__ = inspect.Signature(params)
+    handler.__name__ = tool["name"]
+    handler.__doc__ = tool["description"]
+
+    return handler
+
+
+def create_server(tools_file):
+    """Create a FastMCP server from a tools JSON file.
+
+    Reads the JSON, then registers one MCP tool per entry.  Each tool,
+    when called, translates the MCP arguments back into a CLI command
+    and runs it with ``subprocess.run()``.
+
+    Returns the FastMCP server instance (call ``.run()`` to start it).
+    """
+    with open(tools_file) as f:
+        data = json.load(f)
+
+    base_command = data["command"]
+    server = FastMCP(base_command)
+
+    for tool in data["tools"]:
+        handler = _make_handler(base_command, tool)
+        server.add_tool(
+            handler,
+            name=tool["name"],
+            description=tool["description"],
+        )
+
+    return server

cli2mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: cli2mcp
+Version: 0.1.1
+Summary: Turn any CLI tool into an MCP server
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]
+Description-Content-Type: text/markdown
+
+# cli2mcp -- Turn any CLI into an MCP Server
+
+An educational Python library that bridges the gap between traditional
+command-line tools and the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+**cli2mcp** scans a CLI tool's `--help` output, extracts its arguments and
+subcommands, and generates a JSON descriptor file.  It can then serve that
+file as a fully functional MCP server -- letting AI assistants call the CLI
+tool through a standard protocol.
+
+## Quick start
+
+```bash
+uv sync
+```
+
+### 1. Scan a CLI tool
+
+```bash
+uv run cli2mcp scan curl
+```
+
+This runs `curl --help`, parses the output, and writes `curl.tools.json`.
+
+For tools with subcommands (like `git`):
+
+```bash
+uv run cli2mcp scan git -o git.tools.json
+```
+
+Each subcommand becomes its own MCP tool.
+
+### 2. Serve as an MCP server
+
+```bash
+uv run cli2mcp serve curl.tools.json
+```
+
+This starts an MCP server (stdio transport) that exposes every entry in
+the JSON file as a callable tool.
+
+To use HTTP transport instead:
+
+```bash
+uv run cli2mcp serve curl.tools.json -t streamable-http
+```
+
+### 3. Connect to an AI assistant
+
+Add the server to your assistant's MCP configuration.
+
+```json
+{
+  "mcpServers": {
+    "curl": {
+      "command": "cli2mcp",
+      "args": ["serve", "curl.tools.json"]
+    }
+  }
+}
+```
+
+## How it works
+
+```
+                                        MCP client
+                                            |
+cli2mcp scan curl   -->  curl.tools.json    |
+                              |             |
+                         cli2mcp serve  <---+
+                              |
+                         subprocess.run(["curl", ...])
+```
+
+### The JSON schema
+
+The generated file looks like this:
+
+```json
+{
+  "command": "curl",
+  "tools": [
+    {
+      "name": "curl",
+      "description": "transfer a URL",
+      "args": [
+        {
+          "name": "url",
+          "description": "URL to transfer",
+          "type": "string",
+          "required": true
+        },
+        {
+          "name": "--output",
+          "description": "Write output to file instead of stdout",
+          "type": "string",
+          "required": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+- **`command`** -- the base CLI binary to run.
+- **`tools`** -- one entry per tool (or per subcommand).
+- **`args`** -- each argument has a `name`, `description`, `type` (always
+  `"string"`), and `required` flag.
+- Argument names starting with `--` are flags; others are positional.
+- You can hand-edit this file to add, remove, or rename tools.
+
+### How arguments map back to CLI commands
+
+When the MCP server receives a tool call like:
+
+```json
+{"name": "git_commit", "arguments": {"message": "fix bug", "all": "true"}}
+```
+
+It reconstructs the CLI command:
+
+```bash
+git commit --message "fix bug" --all true
+```
+
+Flags (names starting with `--`) are emitted as `--flag value`.
+Positional arguments are appended at the end.
+
+## Supported help styles
+
+Different CLI frameworks produce different `--help` formats.
+cli2mcp auto-detects the style and uses the right parser:
+
+| Style     | Frameworks              | Flag format                          |
+|-----------|-------------------------|--------------------------------------|
+| **GNU**   | argparse, click, GNU    | `--flag  description` (one line)     |
+| **Cobra** | kubectl, oc, docker, gh | `--flag=default:` + next line        |
+| **Plain** | curl, busybox           | flags listed without section headers |
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+- `mcp[cli]` (the official MCP Python SDK, installed automatically)

cli2mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+cli2mcp/__init__.py,sha256=XZQBMBINEPCzbQ-vMBn2GWMhCItK_F7d45ZjyFZFdug,78
+cli2mcp/__main__.py,sha256=fbJVELr1ik3yGNBtUvx3aZTVYdvpC7UxeSz6Q26PlXQ,92
+cli2mcp/cli.py,sha256=Y6XDFyNb6i4lEbGp71Y7Z6QF0ROB9q6ESEpaBL6AUlc,2461
+cli2mcp/parser.py,sha256=1ei1mFeZqytedsY5eelNyP1ihSX1iYzthfggc_THs0w,864
+cli2mcp/scanner.py,sha256=yXMXDW-dO0T-WoM-1KH5HoG-WGHO53Hi6t8iHiJcCNo,2318
+cli2mcp/server.py,sha256=JR3cfbBrkJ2ITBkEflxIWvUae5Uw8YOnbdmn2Z6zdak,5300
+cli2mcp/parsers/__init__.py,sha256=JRWfTDc9W838xcOtiDcI7sAViYDUlr7ymNEdOJodsBs,224
+cli2mcp/parsers/cobra.py,sha256=t9C1vpvFYSU6uqO6YoG8bKh5a8n8axh9COBlXXklv2M,5243
+cli2mcp/parsers/common.py,sha256=-6zY5W0jfTpBqvK9IFaAWOCCsIIqT1Ew6YZvTHL9BQw,1258
+cli2mcp/parsers/gnu.py,sha256=Rjzl3OnUVkoXAzIJHmjDS5rXVHJpG7Ps6z9E7t7IFU8,4157
+cli2mcp/parsers/plain.py,sha256=JMs1oRxBdu-mHEPSW_snu_MfU_9aCe21Gzj5DfrgEmY,3112
+cli2mcp-0.1.1.dist-info/METADATA,sha256=J1KG-3xJ_R3imgroKjUvzgBCV2EgWu_rziLe_0goInA,3805
+cli2mcp-0.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cli2mcp-0.1.1.dist-info/entry_points.txt,sha256=b13fSNFMlSP7lpmNhVIVawGZdTrt-CmgCdwJ-oVvsUg,45
+cli2mcp-0.1.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+cli2mcp-0.1.1.dist-info/RECORD,,

cli2mcp-0.1.1.dist-info/WHEEL

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

cli2mcp-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cli2mcp = cli2mcp.cli:main