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

cli_mcp/models.py

@@ -0,0 +1,213 @@
+"""Canonical discovery model shared by every provider and every inner layer.
+
+The model is deliberately framework-agnostic: providers translate their own
+metadata into :class:`CommandSpec` / :class:`Parameter`, and the schema,
+executor and MCP layers only ever see these objects.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+JSON_TYPES = frozenset({"string", "integer", "number", "boolean", "array", "object"})
+
+_TYPE_ALIASES: dict[str, str] = {
+    "str": "string",
+    "string": "string",
+    "text": "string",
+    "file": "string",
+    "path": "string",
+    "filename": "string",
+    "dir": "string",
+    "int": "integer",
+    "integer": "integer",
+    "count": "integer",
+    "number": "number",
+    "float": "number",
+    "double": "number",
+    "bool": "boolean",
+    "boolean": "boolean",
+    "flag": "boolean",
+    "list": "array",
+    "array": "array",
+    "json": "object",
+    "object": "object",
+}
+
+_TOOL_NAME_RE = re.compile(r"[^A-Za-z0-9._-]+")
+_IDENTIFIER_RE = re.compile(r"[^A-Za-z0-9_]+")
+MAX_TOOL_NAME_LENGTH = 128
+
+
+class ParamKind(StrEnum):
+    """How a parameter is passed to the underlying CLI."""
+
+    OPTION = "option"
+    FLAG = "flag"
+    POSITIONAL = "positional"
+
+
+def normalize_identifier(value: str) -> str:
+    """Return an MCP/client-safe argument name derived from a CLI flag."""
+    cleaned = value.strip().strip("-").replace("-", "_")
+    cleaned = _IDENTIFIER_RE.sub("_", cleaned).strip("_")
+    if not cleaned:
+        return "arg"
+    if cleaned[0].isdigit():
+        cleaned = f"arg_{cleaned}"
+    return cleaned
+
+
+def sanitize_tool_name(value: str) -> str:
+    """Return a tool name conforming to the MCP tool-name rules."""
+    cleaned = _TOOL_NAME_RE.sub("_", value.strip()).strip("._-")
+    if not cleaned:
+        return "tool"
+    if cleaned[0].isdigit():
+        cleaned = f"tool_{cleaned}"
+    return cleaned[:MAX_TOOL_NAME_LENGTH]
+
+
+def normalize_type(value: str | None) -> str:
+    """Map framework type spellings onto JSON Schema types."""
+    if not value:
+        return "string"
+    return _TYPE_ALIASES.get(value.strip().lower().strip("[]()"), "string")
+
+
+class Parameter(BaseModel):
+    """One argument, flag or positional of a discovered CLI command."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="Argument name published in the MCP tool schema")
+    kind: ParamKind = ParamKind.OPTION
+    cli_name: str | None = Field(None, description="Original CLI flag name (dashed)")
+    short: str | None = Field(None, description="Short flag alias, e.g. 'i' for -i")
+    short_only: bool = Field(False, description="The CLI advertises only a short option")
+    type: str = Field("string", description="JSON Schema type")
+    description: str | None = None
+    required: bool = False
+    default: Any = None
+    choices: list[str] | None = Field(None, description="Allowed values, published as enum")
+    repeatable: bool = Field(False, description="Flag may be given more than once")
+    metavar: str | None = Field(None, description="Placeholder shown in help output")
+
+    @field_validator("name")
+    @classmethod
+    def _names(cls, value: str) -> str:
+        return normalize_identifier(value)
+
+    @field_validator("cli_name")
+    @classmethod
+    def _cli_names(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        stripped = value.strip().lstrip("-")
+        return stripped or None
+
+    @field_validator("short")
+    @classmethod
+    def _shorts(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        stripped = value.strip().lstrip("-")
+        return stripped or None
+
+    @field_validator("type")
+    @classmethod
+    def _types(cls, value: str) -> str:
+        normalized = normalize_type(value)
+        return normalized if normalized in JSON_TYPES else "string"
+
+    @field_validator("choices")
+    @classmethod
+    def _choices(cls, value: list[str] | None) -> list[str] | None:
+        if not value:
+            return None
+        cleaned = [str(item) for item in value if str(item)]
+        return cleaned or None
+
+    @model_validator(mode="after")
+    def _flag_type(self) -> Parameter:
+        """Force the boolean schema type for a CLI toggle flag."""
+        if self.kind is ParamKind.FLAG:
+            self.type = "boolean"
+        if self.short_only and not self.short:
+            raise ValueError("short_only requires a short option spelling")
+        return self
+
+    @property
+    def cli_flag(self) -> str:
+        """Option spelling as it must appear on the command line."""
+        if self.short_only or (self.cli_name is None and self.short):
+            return f"-{self.short}"
+        return f"--{self.cli_name or self.name}"
+
+
+class CommandSpec(BaseModel):
+    """A discovered CLI command expressed as a candidate MCP tool."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(description="MCP tool name")
+    path: list[str] = Field(default_factory=list, description="Subcommand path after the binary")
+    description: str = ""
+    parameters: list[Parameter] = Field(default_factory=list)
+    provider: str = "unknown"
+    examples: list[str] = Field(default_factory=list)
+    destructive: bool = False
+    has_subcommands: bool = False
+
+    @field_validator("name")
+    @classmethod
+    def _names(cls, value: str) -> str:
+        return sanitize_tool_name(value)
+
+    @property
+    def argv_path(self) -> list[str]:
+        """Argument vector that selects this command (without the binary)."""
+        return list(self.path)
+
+    def invocation(self, binary: str) -> str:
+        """Shell-style invocation string for this command."""
+        return " ".join([binary, *self.path])
+
+    def parameter(self, name: str) -> Parameter | None:
+        """Look up a parameter by its published argument name."""
+        target = normalize_identifier(name)
+        return next((param for param in self.parameters if param.name == target), None)
+
+    def ordered_positionals(self) -> list[Parameter]:
+        """Positional parameters in declaration order."""
+        return [param for param in self.parameters if param.kind is ParamKind.POSITIONAL]
+
+
+class DiscoveryResult(BaseModel):
+    """Outcome of a discovery run for one binary."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    binary: str
+    resolved_path: str | None = None
+    framework: str | None = None
+    commands: list[CommandSpec] = Field(default_factory=list)
+    strategies: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+
+    def tool_names(self) -> list[str]:
+        """Names of the published tools."""
+        return [command.name for command in self.commands]
+
+    def get(self, name: str) -> CommandSpec | None:
+        """Find a command by tool name."""
+        return next((command for command in self.commands if command.name == name), None)
+
+    def add_warning(self, message: str) -> None:
+        """Record a non-fatal discovery problem."""
+        if message not in self.warnings:
+            self.warnings.append(message)

cli_mcp/plugins/__init__.py

@@ -0,0 +1,41 @@
+"""Plugin system: third-party discovery providers.
+
+A provider implements the :class:`cli_mcp.discovery.base.DiscoveryProvider`
+protocol and is registered through the ``cli_mcp.discovery`` entry-point group:
+
+.. code-block:: toml
+
+    [project.entry-points."cli_mcp.discovery"]
+    my-framework = "my_pkg.provider:MyProvider"
+
+Provider classes are instantiated with the current ``Settings`` when they accept
+a ``settings`` parameter, otherwise with no arguments.
+"""
+
+from __future__ import annotations
+
+from cli_mcp.config.settings import Settings
+from cli_mcp.discovery.base import DiscoveryProvider
+from cli_mcp.discovery.registry import ENTRY_POINT_GROUP, ProviderRegistry, plugin_providers
+
+PROTOCOL_DOC = """DiscoveryProvider protocol:
+
+    name: str             display name, e.g. "my-framework"
+    strategy: str         "reflection", "help" or "manifest"
+    frameworks: tuple     framework fingerprints this provider understands
+    supports(target)      whether the provider can handle this binary
+    discover(target, ctx) return a DiscoveryResult, or None to abstain
+"""
+
+
+def load_plugins(settings: Settings) -> list[DiscoveryProvider]:
+    """Load third-party providers from the installed distributions."""
+    return plugin_providers(settings)
+
+
+def registry_with_plugins(settings: Settings, load_plugins: bool = True) -> ProviderRegistry:
+    """Return a registry containing built-ins and any installed plugins."""
+    return ProviderRegistry(settings, load_plugins=load_plugins)
+
+
+__all__ = ["ENTRY_POINT_GROUP", "PROTOCOL_DOC", "load_plugins", "registry_with_plugins"]

cli_mcp/schema/__init__.py

@@ -0,0 +1,31 @@
+"""Schema layer: JSON Schema generation, argument validation, docs and OpenAPI."""
+
+from __future__ import annotations
+
+from cli_mcp.schema.docgen import command_section, parameter_summary, render_docs
+from cli_mcp.schema.jsonschema import (
+    argument_name,
+    cli_hint,
+    coerce_choices,
+    execution_result_schema,
+    input_schema,
+    parameter_schema,
+)
+from cli_mcp.schema.openapi import OPENAPI_VERSION, build_openapi, tool_endpoint
+from cli_mcp.schema.validate import validate_arguments
+
+__all__ = [
+    "OPENAPI_VERSION",
+    "argument_name",
+    "build_openapi",
+    "cli_hint",
+    "coerce_choices",
+    "command_section",
+    "execution_result_schema",
+    "input_schema",
+    "parameter_schema",
+    "parameter_summary",
+    "render_docs",
+    "tool_endpoint",
+    "validate_arguments",
+]

cli_mcp/schema/docgen.py

@@ -0,0 +1,104 @@
+"""Markdown documentation generated from discovered command metadata."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cli_mcp.config.settings import ServerSettings
+from cli_mcp.models import CommandSpec, DiscoveryResult, Parameter
+from cli_mcp.schema.jsonschema import argument_name, cli_hint
+
+
+def _display_binary(binary: str) -> str:
+    """Return the name a user types, not the absolute path that resolved it."""
+    return Path(binary).name if "\\" in binary or "/" in binary else binary
+
+
+def _escape(text: str) -> str:
+    """Make text safe inside a Markdown table cell."""
+    return text.replace("|", "\\|").replace("\n", " ")
+
+
+def _arguments_table(command: CommandSpec) -> list[str]:
+    """Markdown table rows for a command's parameters."""
+    lines = ["| Argument | CLI | Type | Required | Default | Description |", "| --- | --- | --- | --- | --- | --- |"]
+    for param in command.parameters:
+        default = "" if param.default is None else str(param.default)
+        choices = f" one of: {', '.join(param.choices)}" if param.choices else ""
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    argument_name(param),
+                    _escape(cli_hint(param)),
+                    param.type,
+                    "yes" if param.required else "no",
+                    _escape(default),
+                    _escape((param.description or "") + choices),
+                ]
+            )
+            + " |"
+        )
+    return lines
+
+
+def command_section(command: CommandSpec, binary: str) -> list[str]:
+    """Markdown block for one tool."""
+    lines = [f"### `{command.name}`", "", command.description or "No description available.", ""]
+    lines.append(f"CLI invocation: `{command.invocation(_display_binary(binary))}`")
+    lines.append("")
+    if command.parameters:
+        lines.extend(_arguments_table(command))
+        lines.append("")
+    else:
+        lines.append("This tool takes no arguments.")
+        lines.append("")
+    if command.examples:
+        lines.append("Examples:")
+        lines.append("")
+        lines.append("```bash")
+        display = _display_binary(binary)
+        lines.extend(example.replace(f"{binary} ", f"{display} ") for example in command.examples)
+        lines.append("```")
+        lines.append("")
+    if command.destructive:
+        lines.append("> **Security:** this command is treated as destructive and needs approval.")
+        lines.append("")
+    if command.has_subcommands:
+        lines.append("> This command also exposes nested subcommands as separate tools.")
+        lines.append("")
+    return lines
+
+
+def render_docs(result: DiscoveryResult, server: ServerSettings | None = None) -> str:
+    """Render the full documentation document for a discovery result."""
+    name = server.name if server else result.binary
+    display = _display_binary(result.binary)
+    lines = [f"# `{display}` as an MCP server", ""]
+    lines.append(f"Server name: `{name}`")
+    if result.framework:
+        lines.append(f"Discovery framework: `{result.framework}`")
+    if result.strategies:
+        lines.append(f"Strategies used: {', '.join(result.strategies)}")
+    lines.append(f"Published tools: {len(result.commands)}")
+    lines.append("")
+    lines.append("Every tool below maps to one CLI command. Arguments are validated against the")
+    lines.append("schema below before the command runs, and unknown arguments are rejected.")
+    lines.append("")
+    lines.append("## Tools")
+    lines.append("")
+    for command in result.commands:
+        lines.extend(command_section(command, display))
+    if result.warnings:
+        lines.append("## Discovery notes")
+        lines.append("")
+        for warning in result.warnings:
+            lines.append(f"- {warning}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def parameter_summary(param: Parameter) -> str:
+    """One-line summary of a parameter, used by ``cli-mcp inspect``."""
+    required = "required" if param.required else "optional"
+    return f"{argument_name(param)} ({param.type}, {required}) — {cli_hint(param)}"

cli_mcp/schema/jsonschema.py

@@ -0,0 +1,104 @@
+"""JSON Schema generation from discovered command metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_mcp.models import CommandSpec, Parameter, ParamKind, normalize_identifier
+
+
+def argument_name(param: Parameter) -> str:
+    """Return the MCP-facing argument name for a parameter."""
+    return normalize_identifier(param.cli_name or param.name)
+
+
+def cli_hint(param: Parameter) -> str:
+    """Describe how the parameter appears on the command line."""
+    if param.kind is ParamKind.POSITIONAL:
+        metavar = param.metavar or param.cli_name or param.name
+        return f"Positional argument: {metavar}"
+    flag = param.cli_flag
+    if param.kind is ParamKind.FLAG:
+        return f"CLI flag: {flag}"
+    metavar = param.metavar or param.cli_name or param.name
+    return f"CLI option: {flag} {metavar}"
+
+
+def coerce_choices(param: Parameter) -> list[Any]:
+    """Choices narrowed to the parameter's declared numeric type.
+
+    Help text spells enum values as text (``[choices: 1, 2, 3]``), so numeric
+    parameters need numeric values to stay schema-valid.
+    """
+    choices = list(param.choices or [])
+    if param.type not in {"integer", "number"}:
+        return choices
+    coerced: list[Any] = []
+    for choice in choices:
+        try:
+            value = float(choice)
+        except ValueError:
+            return choices
+        coerced.append(int(value) if value.is_integer() else value)
+    return coerced
+
+
+def parameter_schema(param: Parameter) -> dict[str, Any]:
+    """Build the JSON Schema for one parameter, keeping description, enum and default."""
+    schema: dict[str, Any] = {"type": param.type}
+    choices = coerce_choices(param)
+    if param.type == "array":
+        items: dict[str, Any] = {"type": "string"}
+        if choices:
+            items["enum"] = choices
+        schema["items"] = items
+    elif choices:
+        schema["enum"] = choices
+    if param.default is not None:
+        schema["default"] = param.default
+    description = param.description or ("Toggle flag" if param.kind is ParamKind.FLAG else "Required value")
+    schema["description"] = f"{description} ({cli_hint(param)})"
+    if param.repeatable:
+        schema["description"] += " May be passed multiple times as an array."
+    return schema
+
+
+def input_schema(spec: CommandSpec) -> dict[str, Any]:
+    """Build the MCP ``inputSchema`` for a discovered command."""
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for param in spec.parameters:
+        name = argument_name(param)
+        properties[name] = parameter_schema(param)
+        if param.required:
+            required.append(name)
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def execution_result_schema() -> dict[str, Any]:
+    """JSON Schema for the tool result cli-mcp returns after running a command."""
+    return {
+        "type": "object",
+        "properties": {
+            "stdout": {"type": "string", "description": "Standard output of the CLI process"},
+            "stderr": {"type": "string", "description": "Standard error of the CLI process"},
+            "exitCode": {"type": "integer", "description": "Process exit code"},
+            "executionTimeMs": {"type": "integer", "description": "Wall-clock execution time in milliseconds"},
+            "argv": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Exact argv the CLI process was started with",
+            },
+            "truncated": {"type": "boolean", "description": "Whether output was truncated"},
+            "sandboxed": {"type": "boolean", "description": "Whether execution used a container sandbox"},
+        },
+        "required": ["stdout", "stderr", "exitCode", "executionTimeMs"],
+        "additionalProperties": False,
+    }

cli_mcp/schema/openapi.py

@@ -0,0 +1,57 @@
+"""OpenAPI export: each MCP tool becomes an endpoint, plus the result schema."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_mcp.config.settings import ServerSettings
+from cli_mcp.models import DiscoveryResult
+from cli_mcp.schema.jsonschema import execution_result_schema, input_schema
+
+OPENAPI_VERSION = "3.1.0"
+
+
+def tool_endpoint(command: Any, binary: str) -> dict[str, Any]:
+    """Build the OpenAPI operation for one MCP tool."""
+    description = command.description or f"Run {command.invocation(binary)}"
+    return {
+        "description": description,
+        "requestBody": {
+            "required": True,
+            "content": {"application/json": {"schema": input_schema(command)}},
+        },
+        "responses": {
+            "200": {
+                "description": "CLI execution result",
+                "content": {"application/json": {"schema": execution_result_schema()}},
+            },
+            "400": {"description": "Arguments rejected by schema validation"},
+            "403": {"description": "Rejected by the security policy (allow list, read-only mode or approval)"},
+        },
+    }
+
+
+def build_openapi(result: DiscoveryResult, server: ServerSettings | None = None) -> dict[str, Any]:
+    """Build an OpenAPI 3.1 document describing the published tools."""
+    settings = server or ServerSettings(name=result.binary)
+    paths: dict[str, Any] = {}
+    for command in result.commands:
+        paths[f"/tools/{command.name}"] = {"post": tool_endpoint(command, result.binary)}
+    document: dict[str, Any] = {
+        "openapi": OPENAPI_VERSION,
+        "info": {
+            "title": settings.title or settings.name or result.binary,
+            "description": settings.description or f"{result.binary} exposed as an MCP server by cli-mcp",
+            "version": settings.version or "0.1.0",
+        },
+        "paths": paths,
+        "components": {"schemas": {"ExecutionResult": execution_result_schema()}},
+        "x-cli-mcp": {
+            "binary": result.binary,
+            "framework": result.framework,
+            "strategies": result.strategies,
+            "transport": settings.transport,
+            "tool_count": len(result.commands),
+        },
+    }
+    return document

cli_mcp/schema/validate.py

@@ -0,0 +1,84 @@
+"""Strict argument validation against a discovered command's schema."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cli_mcp.errors import SchemaError
+from cli_mcp.models import CommandSpec, Parameter, normalize_identifier
+from cli_mcp.schema.jsonschema import argument_name, coerce_choices
+
+_TYPE_CHECKERS: dict[str, type | tuple[type, ...]] = {
+    "string": str,
+    "integer": int,
+    "number": (int, float),
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+}
+
+
+def _type_matches(param: Parameter, value: Any) -> bool:
+    """Whether *value* satisfies the parameter's declared type."""
+    expected = _TYPE_CHECKERS.get(param.type)
+    if expected is None:
+        return True
+    if param.type == "integer" and isinstance(value, bool):
+        return False
+    if param.type == "number" and isinstance(value, bool):
+        return False
+    return isinstance(value, expected)
+
+
+def _check(param: Parameter, name: str, value: Any) -> list[str]:
+    """Problems for one supplied argument."""
+    problems: list[str] = []
+    if not _type_matches(param, value):
+        problems.append(f"argument {name!r} must be of type {param.type}, got {type(value).__name__}")
+        return problems
+    choices = coerce_choices(param)
+    if choices:
+        if param.type == "array" and isinstance(value, list):
+            invalid = [item for item in value if item not in choices]
+            if invalid:
+                problems.append(f"argument {name!r} has invalid items {invalid}; allowed: {choices}")
+        elif value not in choices:
+            problems.append(f"argument {name!r} must be one of {choices}, got {value!r}")
+    return problems
+
+
+def validate_arguments(spec: CommandSpec, arguments: dict[str, Any] | None) -> dict[str, Any]:
+    """Validate tool arguments and return them keyed by canonical argument names.
+
+    Unknown keys are rejected: an MCP client must not silently pass options the
+    CLI does not understand.
+    """
+    lookup: dict[str, Parameter] = {}
+    for param in spec.parameters:
+        lookup[argument_name(param)] = param
+    supplied = arguments or {}
+    problems: list[str] = []
+    missing: set[str] = set()
+    normalized: dict[str, Any] = {}
+    for key, value in supplied.items():
+        name = normalize_identifier(str(key))
+        matched = lookup.get(name)
+        if matched is None:
+            hint = ", ".join(sorted(lookup)) or "none"
+            problems.append(f"unknown argument {key!r} for tool {spec.name!r}; supported arguments: {hint}")
+            continue
+        if value is None:
+            if not matched.required:
+                continue  # the SDK passes None for omitted optional arguments
+            missing.add(name)
+            problems.append(f"missing required argument {name!r} for tool {spec.name!r}")
+            continue
+        problems.extend(_check(matched, name, value))
+        normalized[argument_name(matched)] = value
+    for param in spec.parameters:
+        name = argument_name(param)
+        if param.required and name not in normalized and name not in missing:
+            problems.append(f"missing required argument {name!r} for tool {spec.name!r}")
+    if problems:
+        raise SchemaError(f"invalid arguments for tool {spec.name}: " + "; ".join(problems))
+    return normalized

cli_mcp/security/__init__.py

@@ -0,0 +1,26 @@
+"""Security package."""
+
+from cli_mcp.security.policy import AccessPolicy, Decision
+from cli_mcp.security.readonly import (
+    BLOCKED_BINARIES,
+    DESTRUCTIVE_FLAGS,
+    DESTRUCTIVE_VERBS,
+    RiskAssessment,
+    assess,
+    binary_basename,
+    is_blocked_binary,
+    is_destructive_verb,
+)
+
+__all__ = [
+    "BLOCKED_BINARIES",
+    "DESTRUCTIVE_FLAGS",
+    "DESTRUCTIVE_VERBS",
+    "AccessPolicy",
+    "Decision",
+    "RiskAssessment",
+    "assess",
+    "binary_basename",
+    "is_blocked_binary",
+    "is_destructive_verb",
+]