universal-cli-mcp-server 0.1.0__tar.gz → 0.2.0__tar.gz

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: universal-cli-mcp-server
-Version: 0.1.0
+Version: 0.2.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
@@ -250,10 +250,13 @@ security:
   approval: true          # human confirmation required
   timeout_seconds: 30
   max_output_bytes: 200000
+  max_argv_tokens: 256
+  max_argv_bytes: 32768
   sandbox:
     backend: docker
     image: my-cli-image:latest
     network: false
+    workdir_mount: false
 ```
 
 - **Allow list** — a non-empty list restricts configured binaries by basename;
@@ -264,8 +267,10 @@ security:
 - **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.
+- **Sandboxing** — run the CLI inside Docker or Podman; the working directory is not
+  mounted by default. Discovery still runs on the host. Firecracker support planned.
+- **Execution limits** — each invocation is limited to 256 argv tokens and 32 KiB,
+  including the executable and separators, before approval or process creation.
 - **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.

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/README.md

@@ -214,10 +214,13 @@ security:
   approval: true          # human confirmation required
   timeout_seconds: 30
   max_output_bytes: 200000
+  max_argv_tokens: 256
+  max_argv_bytes: 32768
   sandbox:
     backend: docker
     image: my-cli-image:latest
     network: false
+    workdir_mount: false
 ```
 
 - **Allow list** — a non-empty list restricts configured binaries by basename;
@@ -228,8 +231,10 @@ security:
 - **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.
+- **Sandboxing** — run the CLI inside Docker or Podman; the working directory is not
+  mounted by default. Discovery still runs on the host. Firecracker support planned.
+- **Execution limits** — each invocation is limited to 256 argv tokens and 32 KiB,
+  including the executable and separators, before approval or process creation.
 - **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.

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/docs/configuration.md

@@ -36,10 +36,12 @@ cli-mcp init git --readonly --transport streamable-http --sandbox-image alpine:3
 | `security.allow_patterns` | `[]` | Regex overrides for custom block patterns outside read-only mode only. |
 | `security.timeout_seconds` | `60` | Hard limit per executed command. |
 | `security.max_output_bytes` | `200000` | Maximum retained raw bytes per output stream, including timeouts. |
+| `security.max_argv_tokens` | `256` | Maximum tokens in one complete CLI invocation, including the executable. |
+| `security.max_argv_bytes` | `32768` | Maximum encoded bytes in one complete CLI invocation, including token separators. |
 | `security.sandbox.backend` | `docker` | `docker` or `podman`. |
 | `security.sandbox.image` | `alpine:3.20` | Container image the command runs in. |
 | `security.sandbox.network` | `false` | Attach the container network. |
-| `security.sandbox.workdir_mount` | `true` | Mount the working directory at `/work`. |
+| `security.sandbox.workdir_mount` | `false` | Mount the working directory at `/work`; opt in only when required. |
 | `security.sandbox.container_workdir` | `/work` | Working directory inside the container. |
 | `security.sandbox.extra_args` | `[]` | Extra arguments for the container runtime. |
 | `discovery.strategies` | `[reflection, help, manifest]` | Ordered strategies to try. |

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/docs/security.md

@@ -98,19 +98,26 @@ security:
 ```
 
 cli-mcp checks the runtime is available (`docker`/`podman` on `PATH`) and prefixes the command with
-`run --rm`. The default bind mount is writable, so a sandboxed command can still change host
-files in that directory. Use `workdir_mount: false` for no working-directory host access, or
-configure read-only mounts in trusted runtime arguments. Do not expose runtime sockets or
-privileged mounts. Set runtime memory/CPU limits as appropriate; sandboxing is opt-in and
-does not sandbox discovery. Firecracker microVMs are planned for a later release.
+`run --rm`. The working directory is not mounted by default. Set `workdir_mount: true` only when
+the command needs host files; that bind mount is writable, so the command can change files in the
+directory. Do not expose runtime sockets or privileged mounts. Set runtime memory/CPU limits as
+appropriate; sandboxing is opt-in and does not sandbox discovery. Firecracker microVMs are planned
+for a later release.
 
 ## Limits
 
 `timeout_seconds` limits execution and reports `exitCode: -1` with a
 `[cli-mcp] timed out after Ns` note. `max_output_bytes` bounds retained raw bytes separately
 for stdout and stderr, including partial timeout output; excess output is drained and discarded.
-Truncation is reported in the result. These limits do not bound the target program's own RAM
-or CPU usage. Discovery also uses bounded output capture.
+Truncation is reported in the result. `max_argv_tokens` and `max_argv_bytes` bound each complete
+invocation, counting the executable and NUL separators; oversized or NUL-containing invocations
+are rejected before approval or process creation. These limits do not bound the target program's
+own RAM or CPU usage. Discovery also uses bounded output capture.
+
+`execution.cwd` sets the process working directory but does not confine file access. Paths passed
+as CLI arguments are interpreted by the target program and are not generally normalized or
+restricted by cli-mcp; their behavior differs between CLIs. Use a container without host directory
+mounts, or define and enforce CLI-specific path rules when filesystem confinement is required.
 
 `discovery.max_commands` additionally limits uncached help invocations, checked before
 process creation. The root query, failed attempts and alternate help flags consume this

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "universal-cli-mcp-server"
-version = "0.1.0"
+version = "0.2.0"
 description = "Swagger for command line tools — expose any CLI as a fully compliant MCP server"
 readme = "README.md"
 requires-python = ">=3.13"

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/config/loader.py

@@ -96,6 +96,8 @@ def template(
         "    approval_mode: auto  # auto/prompt require a local TTY; explicit always refuses",
         "    timeout_seconds: 60",
         "    max_output_bytes: 200000",
+        "    max_argv_tokens: 256",
+        "    max_argv_bytes: 32768",
         "    allowlist:",
         f"      - {binary}",
     ]
@@ -105,7 +107,7 @@ def template(
             "      backend: docker",
             f"      image: {sandbox_image}",
             "      network: false",
-            "      workdir_mount: true",
+            "      workdir_mount: false",
         ]
     lines = [
         "# cli-mcp configuration",

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/config/settings.py

@@ -23,7 +23,7 @@ class SandboxSettings(BaseModel):
 
     backend: Literal["docker", "podman"] = "docker"
     image: str = "alpine:3.20"
-    workdir_mount: bool = Field(True, description="Mount the current directory into the container")
+    workdir_mount: bool = Field(False, description="Mount the current directory into the container")
     container_workdir: str = "/work"
     network: bool = False
     extra_args: list[str] = Field(default_factory=list)
@@ -53,6 +53,8 @@ class SecuritySettings(BaseModel):
     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)
+    max_argv_tokens: int = Field(256, ge=1)
+    max_argv_bytes: int = Field(32_768, ge=1)
     sandbox: SandboxSettings | None = None
 
     @field_validator("readonly_argv")

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/executor/argv.py

@@ -2,11 +2,31 @@
 
 from __future__ import annotations
 
+import os
 from typing import Any
 
+from cli_mcp.config.settings import SecuritySettings
+from cli_mcp.errors import SecurityViolation
 from cli_mcp.models import CommandSpec, Parameter, ParamKind
 
 
+def enforce_argv_limits(argv: list[str], security: SecuritySettings) -> None:
+    """Reject empty, NUL-containing or oversized CLI invocations."""
+    if not argv:
+        raise SecurityViolation("command argv must not be empty")
+    if any("\0" in token for token in argv):
+        raise SecurityViolation("command argv must not contain NUL bytes")
+    if len(argv) > security.max_argv_tokens:
+        raise SecurityViolation(
+            f"command argv has {len(argv)} tokens; limit is {security.max_argv_tokens}"
+        )
+    size = sum(len(os.fsencode(token)) + 1 for token in argv)
+    if size > security.max_argv_bytes:
+        raise SecurityViolation(
+            f"command argv is {size} bytes; limit is {security.max_argv_bytes}"
+        )
+
+
 def format_value(param: Parameter, value: Any) -> str:
     """Render one argument value as a CLI token."""
     if isinstance(value, bool):

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/executor/runner.py

@@ -19,6 +19,7 @@ from typing import IO, Any
 from cli_mcp.config.settings import SecuritySettings
 from cli_mcp.detect import reject_batch_target
 from cli_mcp.errors import ExecutionError
+from cli_mcp.executor.argv import enforce_argv_limits
 from cli_mcp.executor.sandbox import sandbox_argv, sandbox_available
 
 TRUNCATION_NOTE = "\n[cli-mcp: output truncated]"
@@ -332,6 +333,7 @@ def run(
     job/session members are terminated on timeout. Windows job members are also
     terminated after successful exit; already-reaped POSIX IDs are not signaled.
     """
+    enforce_argv_limits(argv, security)
     reject_batch_target(argv[0])
     sandboxed = security.sandbox is not None
     if sandboxed and security.sandbox is not None:

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/mcp/tool_adapter.py

@@ -16,7 +16,7 @@ from cli_mcp.config.settings import Settings
 from cli_mcp.detect import executable_stem
 from cli_mcp.errors import SecurityViolation
 from cli_mcp.executor.approval import ApprovalGate
-from cli_mcp.executor.argv import build_argv
+from cli_mcp.executor.argv import build_argv, enforce_argv_limits
 from cli_mcp.executor.runner import run
 from cli_mcp.models import CommandSpec
 from cli_mcp.schema.jsonschema import input_schema
@@ -67,6 +67,7 @@ def build_tool(
         """Validate, gate and run the command, returning the execution payload as JSON."""
         validated = validate_arguments(spec, arguments)
         argv = build_argv(launch, spec, validated)
+        enforce_argv_limits(argv, settings.security)
         decision = policy.evaluate(settings.binary, spec, argv)
         if not decision.allowed:
             raise SecurityViolation(decision.reason or "command rejected by security policy")

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/src/cli_mcp/version.py

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

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/tests/test_config.py

@@ -91,6 +91,9 @@ def test_load_settings_defaults_without_file(tmp_path: Path) -> None:
     settings = load_settings(cwd=tmp_path, binary="git")
     assert settings.binary == "git"
     assert settings.mcp.transport == "stdio"
+    assert settings.security.max_argv_tokens == 256
+    assert settings.security.max_argv_bytes == 32768
+    assert settings.security.sandbox is None
 
 
 def test_load_settings_without_anything_raises(tmp_path: Path) -> None:
@@ -114,6 +117,7 @@ def test_template_round_trips_through_the_loader(tmp_path: Path) -> None:
     assert settings.security.approval is True
     assert settings.security.sandbox is not None
     assert settings.security.sandbox.image == "alpine:3.20"
+    assert settings.security.sandbox.workdir_mount is False
     assert "strategies: [reflection, help, manifest]" in text
 
 

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/tests/test_executor.py

@@ -9,7 +9,7 @@ import pytest
 from cli_mcp.config.settings import SandboxSettings, SecuritySettings
 from cli_mcp.errors import ApprovalRequired, ExecutionError, SecurityViolation
 from cli_mcp.executor.approval import EXPLICIT_HINT, ApprovalGate
-from cli_mcp.executor.argv import build_argv, format_value
+from cli_mcp.executor.argv import build_argv, enforce_argv_limits, format_value
 from cli_mcp.executor.runner import TRUNCATION_NOTE, run
 from cli_mcp.executor.sandbox import sandbox_argv, sandbox_available
 from cli_mcp.models import CommandSpec, Parameter, ParamKind
@@ -68,8 +68,22 @@ def test_build_argv_expands_positional_lists() -> None:
     assert build_argv(["tool"], spec, {"left": "a.xml", "right": "b.xml"}) == ["tool", "diff", "a.xml", "b.xml"]
 
 
+def test_enforce_argv_limits_counts_tokens_bytes_and_nul_separators() -> None:
+    security = SecuritySettings(max_argv_tokens=2, max_argv_bytes=5)
+    enforce_argv_limits(["x", "é"], security)
+
+    with pytest.raises(SecurityViolation, match="2 tokens; limit is 1"):
+        enforce_argv_limits(["x", "y"], SecuritySettings(max_argv_tokens=1))
+    with pytest.raises(SecurityViolation, match="5 bytes; limit is 4"):
+        enforce_argv_limits(["x", "é"], SecuritySettings(max_argv_bytes=4))
+    with pytest.raises(SecurityViolation, match="NUL"):
+        enforce_argv_limits(["x", "bad\0arg"], SecuritySettings())
+    with pytest.raises(SecurityViolation, match="must not be empty"):
+        enforce_argv_limits([], SecuritySettings())
+
+
 def test_sandbox_argv_wraps_the_command_in_a_container() -> None:
-    argv = sandbox_argv(["git", "status"], SandboxSettings(), Path("/work"))
+    argv = sandbox_argv(["git", "status"], SandboxSettings(workdir_mount=True), Path("/work"))
     assert argv[:3] == ["docker", "run", "--rm"]
     assert "--network=none" in argv
     assert "--workdir" in argv and "/work" in argv
@@ -77,6 +91,14 @@ def test_sandbox_argv_wraps_the_command_in_a_container() -> None:
     assert argv[-3:] == ["alpine:3.20", "git", "status"]
 
 
+def test_sandbox_does_not_mount_the_working_directory_by_default() -> None:
+    settings = SandboxSettings()
+    assert settings.workdir_mount is False
+    argv = sandbox_argv(["tool"], settings, Path("/work"))
+    assert "-v" not in argv
+    assert "--workdir" not in argv
+
+
 def test_sandbox_argv_keeps_network_and_extra_args() -> None:
     sandbox = SandboxSettings(network=True, extra_args=["--user", "nobody"], image="alpine:3.20")
     argv = sandbox_argv(["tool"], sandbox, None)
@@ -122,6 +144,11 @@ def test_run_raises_when_the_binary_is_missing() -> None:
         run(["definitely-not-a-binary"], SecuritySettings())
 
 
+def test_run_rejects_oversized_argv_before_process_creation() -> None:
+    with pytest.raises(SecurityViolation, match="tokens; limit is 1"):
+        run(["tool", "arg"], SecuritySettings(max_argv_tokens=1))
+
+
 def test_run_requires_an_available_sandbox_backend(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr("cli_mcp.executor.runner.sandbox_available", lambda backend: False)
     security = SecuritySettings(sandbox=SandboxSettings(backend="docker"))

{universal_cli_mcp_server-0.1.0 → universal_cli_mcp_server-0.2.0}/tests/test_mcp.py

@@ -125,6 +125,20 @@ async def test_handler_rejects_missing_required_arguments(tmp_path: Path) -> Non
         await tool.handler(input=None, output="out.xml")
 
 
+async def test_handler_enforces_argv_limits_before_approval() -> None:
+    security = SecuritySettings(approval=True, max_argv_bytes=32)
+    settings = Settings(binary="reducer.py", security=security)
+    tool = build_tool(
+        SPEC,
+        ["reducer.py"],
+        settings,
+        AccessPolicy(security),
+        ApprovalGate(security, stdin=io.StringIO(), stdout=io.StringIO()),
+    )
+    with pytest.raises(SecurityViolation, match="bytes; limit is 32"):
+        await tool.handler(input="x" * 40, output="out.xml")
+
+
 async def test_read_only_mode_blocks_destructive_tools(tmp_path: Path) -> None:
     script = tmp_path / "git.py"
     script.write_text("pass\n", encoding="utf-8")