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

cli_mcp/security/policy.py

@@ -0,0 +1,91 @@
+"""Access policy: the single place that decides whether a command may run."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cli_mcp.config.settings import SecuritySettings
+from cli_mcp.errors import SecurityViolation
+from cli_mcp.models import CommandSpec
+from cli_mcp.security.readonly import (
+    RiskAssessment,
+    allowed_by_override,
+    assess,
+    binary_basename,
+    is_blocked_binary,
+    matches_block_patterns,
+    scan_argv,
+)
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Result of evaluating a request against the policy."""
+
+    allowed: bool
+    requires_approval: bool
+    reason: str | None = None
+
+
+class AccessPolicy:
+    """Enforce the allow list, read-only mode and approval requirements."""
+
+    def __init__(self, settings: SecuritySettings) -> None:
+        """Bind the policy to its security settings."""
+        self.settings = settings
+
+    def authorize_binary(self, binary: str) -> None:
+        """Reject binaries that are never allowed or not on the allow list."""
+        name = binary_basename(binary)
+        if is_blocked_binary(binary):
+            raise SecurityViolation(f"binary {binary!r} is on the never-expose list")
+        if self.settings.allowlist and name not in self.settings.allowlist:
+            raise SecurityViolation(
+                f"binary {binary!r} is not on the allow list ({', '.join(self.settings.allowlist)})"
+            )
+
+    def evaluate(self, binary: str, spec: CommandSpec, argv: list[str]) -> Decision:
+        """Decide whether *argv* for *spec* may run, and whether approval is needed."""
+        assessment: RiskAssessment = assess(binary, spec)
+        blocked_reason = matches_block_patterns(argv, self.settings.block_patterns)
+        override = not self.settings.readonly and allowed_by_override(argv, self.settings.allow_patterns)
+        if blocked_reason and not override:
+            return Decision(False, False, blocked_reason)
+
+        dangerous = scan_argv(argv)
+        if dangerous and self.settings.readonly:
+            return Decision(False, False, f"read-only mode: {dangerous}")
+
+        if self.settings.readonly and assessment.destructive:
+            return Decision(False, False, f"read-only mode: {assessment.reason}")
+
+        if self.settings.readonly and argv not in self.settings.readonly_argv:
+            return Decision(False, False, "read-only mode: exact invocation is not in security.readonly_argv")
+
+        requires_approval = self.settings.approval or assessment.destructive
+        return Decision(True, requires_approval, None)
+
+    def assess(self, binary: str, spec: CommandSpec) -> RiskAssessment:
+        """Risk classification of a command, before arguments are built."""
+        return assess(binary, spec)
+
+    def authorize_execution(self, binary: str, spec: CommandSpec, argv: list[str]) -> None:
+        """Raise :class:`SecurityViolation` when the request is not allowed."""
+        decision = self.evaluate(binary, spec, argv)
+        if not decision.allowed:
+            raise SecurityViolation(decision.reason or "command rejected by security policy")
+
+    @property
+    def summary(self) -> str:
+        """Human-readable description of the active policy."""
+        parts = []
+        if self.settings.allowlist:
+            parts.append(f"allow list: {', '.join(self.settings.allowlist)}")
+        if self.settings.readonly:
+            parts.append(f"read-only ({len(self.settings.readonly_argv)} exact invocations)")
+        if self.settings.approval:
+            parts.append(f"approval: {self.settings.approval_mode}")
+        if self.settings.sandbox:
+            parts.append(f"sandbox: {self.settings.sandbox.backend} ({self.settings.sandbox.image})")
+        parts.append(f"timeout {self.settings.timeout_seconds:g}s")
+        return "; ".join(parts) or "no restrictions"

cli_mcp/security/readonly.py

@@ -0,0 +1,173 @@
+"""Read-only rules: which binaries and verbs are considered dangerous.
+
+The tables are intentionally explicit and overridable from configuration
+(``security.block_patterns`` adds checks, ``security.allow_patterns`` re-admits
+rules that would otherwise reject a legitimate command).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from cli_mcp.models import CommandSpec
+
+#: Binaries that must never be exposed as tools.
+BLOCKED_BINARIES: frozenset[str] = frozenset(
+    {
+        "rm",
+        "rmdir",
+        "del",
+        "erase",
+        "rd",
+        "mkfs",
+        "format",
+        "diskpart",
+        "dd",
+        "shutdown",
+        "reboot",
+        "halt",
+        "poweroff",
+        "init",
+        "sudo",
+        "su",
+        "runas",
+        "kill",
+        "killall",
+        "pkill",
+        "chmod",
+        "chown",
+        "reg",
+        "netsh",
+        "iptables",
+        "systemctl",
+        "sc",
+    }
+)
+
+#: Subcommand verbs that mutate state and are rejected in read-only mode.
+DESTRUCTIVE_VERBS: frozenset[str] = frozenset(
+    {
+        "rm",
+        "del",
+        "delete",
+        "remove",
+        "destroy",
+        "purge",
+        "prune",
+        "drop",
+        "uninstall",
+        "shutdown",
+        "reboot",
+        "reset",
+        "clean",
+        "push",
+        "apply",
+        "destroy-all",
+        "deregister",
+        "kill",
+        "stop",
+        "rm-rf",
+    }
+)
+
+#: Flags that turn a benign command into a destructive one.
+DESTRUCTIVE_FLAGS: frozenset[str] = frozenset(
+    {
+        "--force",
+        "-f",
+        "--hard",
+        "--no-preserve-root",
+        "--destroy",
+        "--dangerously",
+        "--yes-all",
+        "-rf",
+        "-fr",
+        "--recurse-remove",
+    }
+)
+
+#: Regexes matched against the fully assembled argv.
+DANGEROUS_PATTERNS: tuple[re.Pattern[str], ...] = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"\brm\s+-[a-z]*[rf]",
+        r"\brm\b",
+        r"\bdd\b.*of=",
+        r"\bmkfs\b",
+        r"\bformat\b",
+        r"\bdiskpart\b",
+        r"\bshutdown\b",
+        r"\breboot\b",
+        r"of=/dev/(sd|hd|nvme)",
+        r"\bdel\b\s+[a-z]:",
+        r"\bchmod\b\s+-[a-z]*R",
+    )
+)
+
+
+@dataclass(frozen=True)
+class RiskAssessment:
+    """Why a command is considered risky, if it is."""
+
+    destructive: bool
+    reason: str | None = None
+
+
+def binary_basename(name: str) -> str:
+    """Strip paths and Windows extensions so allow lists can use plain names."""
+    cleaned = name.replace("\\", "/").split("/")[-1]
+    if cleaned.lower().endswith((".exe", ".cmd", ".bat", ".com")):
+        cleaned = cleaned[:-4]
+    return cleaned.lower()
+
+
+def is_blocked_binary(name: str) -> bool:
+    """Whether the binary itself is on the never-expose list."""
+    return binary_basename(name) in BLOCKED_BINARIES
+
+
+def is_destructive_verb(verb: str) -> bool:
+    """Whether a subcommand verb mutates state."""
+    return verb.lower().strip() in DESTRUCTIVE_VERBS
+
+
+def scan_argv(argv: list[str]) -> str | None:
+    """Return a reason if the assembled argv matches a dangerous pattern."""
+    joined = " ".join(argv)
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(joined):
+            return f"matches dangerous pattern {pattern.pattern}"
+    return None
+
+
+def assess(binary: str, spec: CommandSpec) -> RiskAssessment:
+    """Classify a discovered command for read-only and approval decisions."""
+    if is_blocked_binary(binary):
+        return RiskAssessment(True, f"binary {binary} is on the never-expose list")
+    for verb in spec.path:
+        if is_destructive_verb(verb):
+            return RiskAssessment(True, f"subcommand {verb!r} is a destructive verb")
+    for param in spec.parameters:
+        flag = param.cli_flag.lower()
+        short = f"-{param.short}".lower() if param.short else ""
+        if flag in DESTRUCTIVE_FLAGS or short in DESTRUCTIVE_FLAGS:
+            return RiskAssessment(True, f"parameter {param.cli_flag} is a destructive flag")
+    if spec.destructive:
+        return RiskAssessment(True, "the manifest marked this command as destructive")
+    return RiskAssessment(False, None)
+
+
+def allowed_by_override(argv: list[str], allow_patterns: list[str]) -> bool:
+    """Whether a user-supplied allow pattern re-admits the command."""
+    joined = " ".join(argv)
+    return any(re.search(pattern, joined, re.IGNORECASE) for pattern in allow_patterns)
+
+
+def matches_block_patterns(argv: list[str], block_patterns: list[str]) -> str | None:
+    """Return a reason if a user-supplied block pattern matches."""
+    joined = " ".join(argv)
+    for pattern in block_patterns:
+        if re.search(pattern, joined, re.IGNORECASE):
+            return f"matches security.block_patterns entry {pattern!r}"
+    return None

cli_mcp/transport/__init__.py

@@ -0,0 +1,49 @@
+"""Transport selection: stdio, Streamable HTTP, JSON-over-HTTP and SSE."""
+
+from __future__ import annotations
+
+from mcp.server.mcpserver import MCPServer
+
+from cli_mcp.config.settings import ServerSettings
+from cli_mcp.errors import TransportError
+
+SSE_MESSAGE_PATH = "/messages/"
+
+
+def run_server(server: MCPServer, settings: ServerSettings) -> None:
+    """Start *server* on the configured transport and block until it exits."""
+    if settings.transport == "stdio":
+        server.run("stdio")
+        return
+    if settings.transport == "streamable-http":
+        server.run(
+            "streamable-http",
+            host=settings.host,
+            port=settings.port,
+            streamable_http_path=settings.path,
+            json_response=settings.json_response,
+            stateless_http=settings.stateless_http,
+        )
+        return
+    if settings.transport == "http":
+        # Plain HTTP clients get JSON responses; MCP clients use the same endpoint.
+        server.run(
+            "streamable-http",
+            host=settings.host,
+            port=settings.port,
+            streamable_http_path=settings.path,
+            json_response=True,
+            stateless_http=settings.stateless_http,
+        )
+        return
+    if settings.transport == "sse":
+        # Server-Sent Events is deprecated in the MCP spec; prefer streamable-http.
+        server.run(
+            "sse",
+            host=settings.host,
+            port=settings.port,
+            sse_path=settings.path,
+            message_path=SSE_MESSAGE_PATH,
+        )
+        return
+    raise TransportError(f"unknown transport {settings.transport!r}; use stdio, http, streamable-http or sse")

cli_mcp/version.py

@@ -0,0 +1,3 @@
+"""Package version, kept in one place so tests and the CLI agree on it."""
+
+__version__ = "0.1.0"

universal_cli_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,381 @@
+Metadata-Version: 2.5
+Name: universal-cli-mcp-server
+Version: 0.1.0
+Summary: Swagger for command line tools — expose any CLI as a fully compliant MCP server
+Project-URL: Homepage, https://github.com/AndreasHeine/cli-mcp
+Project-URL: Repository, https://github.com/AndreasHeine/cli-mcp
+Project-URL: Issues, https://github.com/AndreasHeine/cli-mcp/issues
+Author: Andreas Heine
+License: Apache-2.0
+License-File: LICENSE
+Keywords: cli,discovery,json-schema,mcp,model-context-protocol,openapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.9
+Requires-Dist: pydantic>=2.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.9
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cli-mcp
+
+**Swagger for Command Line Tools**
+
+`cli-mcp` exposes command-line applications through a
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP) server — without you
+writing a single line of MCP code.
+
+Like Swagger/OpenAPI describes an HTTP API, cli-mcp describes CLI commands, their arguments,
+and their results as structured tools. It also executes those tools with argument validation
+and configured execution controls, and can export OpenAPI documentation.
+Automatic discovery depends on the CLI's help format or supported framework; use a manifest
+when explicit metadata is needed. Windows `.bat`/`.cmd` targets are not supported.
+
+```text
+Today:      CLI Tool  ->  custom MCP wrapper  ->  MCP client
+With cli-mcp: CLI Tool ->  cli-mcp             ->  MCP client
+```
+
+```bash
+cli-mcp expose git
+cli-mcp expose kubectl
+cli-mcp expose docker
+cli-mcp expose opcua-nodeset-linker
+```
+
+```text
+✓ Binary detected
+✓ Commands discovered
+✓ Schemas generated
+✓ MCP tools published
+✓ MCP server started
+```
+
+Works with Claude, Copilot, Cursor, VS Code, Cline, Roo Code, Open WebUI and any other
+MCP-compatible client.
+
+---
+
+## Install
+
+Requires Python 3.13 or newer. CI covers Windows and Linux with Python 3.13 and 3.14.
+
+```bash
+pip install cli-mcp
+```
+
+or, for development:
+
+```bash
+git clone https://github.com/AndreasHeine/cli-mcp
+cd cli-mcp
+uv sync --extra dev
+uv run cli-mcp --help
+```
+
+## Quick start
+
+Only expose trusted programs. These quick-start examples do **not** enable read-only mode
+or sandboxing; discovery itself runs help commands on the host.
+
+```bash
+# Discover commands and serve them over stdio (the default transport)
+cli-mcp expose git
+
+# Look at the generated tools without starting a server
+cli-mcp inspect kubectl
+
+# Serve over Streamable HTTP
+cli-mcp serve docker --transport streamable-http --port 8801
+
+# Export machine-readable artefacts
+cli-mcp export git -o tools.md
+cli-mcp export-schema git -o schemas.json
+cli-mcp export-openapi git -o openapi.json
+
+# Validate discovery quality
+cli-mcp doctor git
+
+# Generate a configuration template
+cli-mcp init opcua-nodeset-linker -o cli-mcp.yaml
+```
+
+Client configuration (`.mcp.json`, Claude Desktop, Cursor, VS Code, …):
+
+The following is a common client configuration shape; VS Code and other clients may use
+different keys. See [clients.md](docs/clients.md) for client-specific recipes.
+
+```json
+{
+  "mcpServers": {
+    "git": {
+      "command": "cli-mcp",
+      "args": ["serve", "git"]
+    },
+    "docker": {
+      "url": "http://127.0.0.1:8801/mcp"
+    }
+  }
+}
+```
+
+---
+
+## Working directory and Windows shells
+
+Some CLIs resolve paths inside their input configuration relative to the process working
+directory, not relative to that configuration file. Configure an absolute existing directory
+for both discovery and execution:
+
+```yaml
+binary: my-cli
+execution:
+  cwd: 'C:\projects\my-cli'
+```
+
+Without `execution.cwd`, the launch directory is used. Use an absolute manifest path when
+changing the discovery directory. Configuration and tool definitions are loaded at startup:
+restart the server and reconnect the client after changes.
+
+PowerShell:
+
+```powershell
+$env:PYTHONDONTWRITEBYTECODE = '1'
+& 'C:\projects\cli-mcp\.venv\Scripts\python.exe' -B -m cli_mcp.cli.main expose --config 'C:\projects\cli-mcp\cli-mcp.yaml'
+```
+
+cmd.exe (run these as two separate commands):
+
+```bat
+set PYTHONDONTWRITEBYTECODE=1
+"C:\projects\cli-mcp\.venv\Scripts\python.exe" -B -m cli_mcp.cli.main expose --config "C:\projects\cli-mcp\cli-mcp.yaml"
+```
+
+These examples assume an existing development environment at the shown location.
+
+---
+
+## How discovery works
+
+`cli-mcp` tries discovery strategies in order. The first strategy that yields usable commands
+wins; manifest entries then add tools or replace discovered tools with the same name.
+The final include/exclude filters select which tools are published, not which help commands
+may execute.
+
+Import reflection is **disabled by default** and requires `--allow-reflection` or
+`discovery.allow_import_reflection: true`. It may execute target code.
+`discovery.max_depth` limits the recursive walk; `discovery.max_commands` limits both published
+tools and uncached help invocations, including root queries, failures and fallback flags.
+The help budget is checked before spawning processes; cache hits do not consume it.
+
+| Strategy | How it works | Frameworks |
+| --- | --- | --- |
+| **Native reflection** | Inspects the real command objects in the target process | Python: argparse, click, typer · Node.js: commander.js |
+| **Framework help grammars** | Parses framework-specific help output with type/default/required semantics | Go: cobra · Rust: clap · .NET: System.CommandLine · Node.js: yargs · click · argparse |
+| **Generic help parsing** | Recursive `tool --help` / `tool <command> --help` parser | anything with `--help` |
+| **Manifest file** | User-provided YAML metadata, authoritative for matching tool names | supported executables and scripts |
+
+Every discovered command becomes an MCP tool:
+
+```json
+{
+  "name": "reduce",
+  "description": "Reduce an OPC UA nodeset",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "input": { "type": "string", "description": "Input nodeset file" },
+      "output": { "type": "string", "description": "Reduced nodeset file" }
+    },
+    "required": ["input", "output"]
+  }
+}
+```
+
+Calling the tool executes the original CLI:
+
+```bash
+linker reduce --input model.xml --output reduced.xml
+```
+
+and returns:
+
+```json
+{
+  "stdout": "...",
+  "stderr": "",
+  "exitCode": 0,
+  "executionTimeMs": 125,
+  "argv": ["linker", "reduce", "--input", "model.xml", "--output", "reduced.xml"],
+  "sandboxed": false,
+  "truncated": false
+}
+```
+
+The actual `argv` contains the resolved launch command, including interpreter prefixes where
+needed. A connected client or completed MCP call does not prove CLI success: inspect `exitCode`
+and `stderr`. Exitcode 0 does not establish side-effect freedom; `sandboxed: false` means the
+target ran on the host.
+
+---
+
+## Security
+
+Security is a first-class concern, not an afterthought.
+
+```yaml
+binary: opcua-nodeset-linker
+
+security:
+  allowlist: [git, kubectl, docker, opcua-nodeset-linker]
+  readonly: true          # deny unless the complete argv is explicitly listed
+  readonly_argv: []       # configure verified exact invocations before use
+  approval: true          # human confirmation required
+  timeout_seconds: 30
+  max_output_bytes: 200000
+  sandbox:
+    backend: docker
+    image: my-cli-image:latest
+    network: false
+```
+
+- **Allow list** — a non-empty list restricts configured binaries by basename;
+  an empty list permits the configured binary. This is not an OS permission boundary.
+- **Read-only mode** — only explicitly listed complete argv vectors may execute;
+  known risky commands and flags are additionally blocked. An empty `readonly_argv` blocks
+  every execution and triggers a startup warning; publishing tools does not authorize them.
+- **Approval mode** — `auto`/`prompt` require a local human at a terminal; without a TTY
+  approval-required execution is refused. Clients cannot approve their own calls. Legacy
+  `explicit` refuses approval-required calls. Normal stdio clients do not provide a local TTY.
+- **Sandboxing** — run the CLI inside Docker or Podman; the default working-directory
+  mount is writable. Discovery still runs on the host. Firecracker support planned.
+- **Argument validation** — arguments are validated against the generated JSON schema
+  before the requested tool process is spawned. Arguments are not interpolated into
+  a shell string.
+
+Read-only, approval and sandboxing are opt-in. Exact argv permissions do not prove that a
+program, its environment or its input files are harmless. Discovery is outside tool execution
+guards. Output limits bound retained stdout/stderr, not the target's own CPU or memory use.
+HTTP/SSE defaults to loopback and does not configure authentication or TLS; do not expose it
+publicly without appropriate protection.
+
+Windows batch targets (`.bat`/`.cmd`) are rejected. Output is retained within a byte budget,
+including timeouts. See [security.md](docs/security.md) for limitations, configuration migration,
+and non-invasive Windows/Linux tests using a single loopback ping.
+
+---
+
+## Architecture
+
+Clean architecture, one responsibility per package:
+
+```text
+src/cli_mcp/
+├── cli/            # Typer entry point (expose/inspect/serve/export/doctor/init)
+├── discovery/      # provider protocol + strategies
+├── schema/         # JSON Schema, Markdown docs, OpenAPI
+├── executor/       # argv building, subprocess execution, approval, sandbox
+├── mcp/            # MCPServer assembly, tool adapters
+├── security/       # allow list, read-only rules, access policy
+├── config/         # pydantic settings + YAML loading
+├── transport/      # stdio, HTTP, Streamable HTTP, SSE
+└── plugins/        # entry-point based provider discovery
+```
+
+Dependencies point inward: the CLI depends on discovery/schema/executor/security; the MCP
+layer depends on nothing framework-specific. See
+[docs/architecture.md](docs/architecture.md).
+
+---
+
+## Plugin system
+
+Third parties add discovery providers without touching core code:
+
+```python
+from cli_mcp.discovery.base import DiscoveryContext, DiscoveryResult, TargetInfo
+
+
+class MyProvider:
+    name = "my-framework"
+    strategy = "help"
+    frameworks = ("my-framework",)
+
+    def supports(self, target: TargetInfo) -> bool:
+        return target.framework == "my-framework"
+
+    def discover(self, target: TargetInfo, ctx: DiscoveryContext) -> DiscoveryResult | None:
+        ...  # return CommandSpecs
+```
+
+Register it:
+
+```toml
+[project.entry-points."cli_mcp.discovery"]
+my-framework = "my_pkg.provider:MyProvider"
+```
+
+`cli-mcp providers` lists every registered provider.
+
+---
+
+## Development
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest            # unit + integration + e2e, coverage gate at 90%
+pre-commit run --all-files
+```
+
+The full test suite creates temporary files and runs Git integration commands.
+For non-invasive validation without test caches, coverage files or generated target scripts,
+use the focused Windows/Linux commands in [security.md](docs/security.md).
+
+GitHub Actions run lint, type checking, Windows/Linux tests (Python 3.13/3.14), and
+distribution builds on pushes to `master`/`main` and pull requests. CI can also be started
+manually from the Actions tab. Dependencies are installed from the checked-in lockfile.
+
+Published GitHub releases (or a manual Release workflow run) validate and build distributions,
+then upload wheels and source distributions as workflow artifacts. **PyPI publishing is
+disabled** until a publishing account and trusted publisher are explicitly configured.
+
+---
+
+## Examples
+
+- [`examples/cli-mcp.yaml`](examples/cli-mcp.yaml) — full configuration
+- [`examples/sample-clis/`](examples/sample-clis) — small argparse/click/typer/commander apps used by the tests
+
+## Documentation
+
+- [configuration.md](docs/configuration.md) — every config key and CLI flag
+- [discovery.md](docs/discovery.md) — reflection, help parsing and manifests
+- [security.md](docs/security.md) — allow list, read-only, approval, sandboxing
+- [transports.md](docs/transports.md) — stdio, HTTP, Streamable HTTP, SSE
+- [clients.md](docs/clients.md) — configuration recipes for Claude, VS Code, Cursor, Cline, Open WebUI
+- [plugins.md](docs/plugins.md) — adding a discovery provider for a new framework
+- [architecture.md](docs/architecture.md) — how the pipeline fits together
+
+---
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).