cli-mcp-server 0.1.2__py3-none-any.whl

cli_mcp_server/__init__.py

@@ -0,0 +1,12 @@
+import asyncio
+
+from . import server
+
+
+def main():
+    """Main entry point for the package."""
+    asyncio.run(server.main())
+
+
+# Optionally expose other important items at package level
+__all__ = ['main', 'server']

cli_mcp_server/server.py

@@ -0,0 +1,337 @@
+import os
+import re
+import shlex
+import subprocess
+from dataclasses import dataclass
+from typing import List, Dict, Any, Optional
+
+import mcp.server.stdio
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+
+server = Server("cli-mcp-server")
+
+
+class CommandSecurityError(Exception):
+    """
+    Custom exception for command security violations
+    """
+
+    pass
+
+
+@dataclass
+class SecurityConfig:
+    """
+    Security configuration for command execution
+    """
+
+    allowed_commands: set[str]
+    allowed_flags: set[str]
+    allowed_patterns: List[str]
+    max_command_length: int
+    command_timeout: int
+
+
+class CommandExecutor:
+    def __init__(self, allowed_dir: str, security_config: SecurityConfig):
+        if not allowed_dir or not os.path.exists(allowed_dir):
+            raise ValueError("Valid ALLOWED_DIR is required")
+        self.allowed_dir = os.path.abspath(os.path.realpath(allowed_dir))
+        self.security_config = security_config
+
+    def validate_command(self, command_string: str) -> tuple[str, List[str]]:
+        """
+        Validates and parses a command string for security and formatting.
+
+        Checks the command string for unsupported shell operators and splits it into
+        command and arguments. Only single commands without shell operators are allowed.
+
+        Args:
+            command_string (str): The command string to validate and parse.
+
+        Returns:
+            tuple[str, List[str]]: A tuple containing:
+                - The command name (str)
+                - List of command arguments (List[str])
+
+        Raises:
+            CommandSecurityError: If the command contains unsupported shell operators.
+        """
+
+        # Check for shell operators that we don't support
+        shell_operators = ["&&", "||", "|", ">", ">>", "<", "<<", ";"]
+        for operator in shell_operators:
+            if operator in command_string:
+                raise CommandSecurityError(
+                    f"Shell operator '{operator}' is not supported. "
+                    "Only single commands are allowed."
+                )
+
+        try:
+            parts = shlex.split(command_string)
+            if not parts:
+                raise CommandSecurityError("Empty command")
+
+            command, args = parts[0], parts[1:]
+
+            # Validate command
+            if command not in self.security_config.allowed_commands:
+                raise CommandSecurityError(f"Command '{command}' is not allowed")
+
+            # Validate arguments
+            for arg in args:
+                if arg.startswith("-"):
+                    if arg not in self.security_config.allowed_flags:
+                        raise CommandSecurityError(f"Flag '{arg}' is not allowed")
+                    continue
+
+                # Validate path if argument looks like a path
+                if "/" in arg or "\\" in arg or os.path.isabs(arg):
+                    full_path = os.path.abspath(os.path.join(self.allowed_dir, arg))
+                    if not self._is_path_safe(full_path):
+                        raise CommandSecurityError(f"Path '{arg}' is not allowed")
+
+                # Check patterns
+                if not any(
+                        re.match(pattern, arg)
+                        for pattern in self.security_config.allowed_patterns
+                ):
+                    raise CommandSecurityError(
+                        f"Argument '{arg}' doesn't match allowed patterns"
+                    )
+
+            return command, args
+        except ValueError as e:
+            raise CommandSecurityError(f"Invalid command format: {str(e)}")
+
+    def _is_path_safe(self, path: str) -> bool:
+        """
+        Checks if a given path is safe to access within allowed directory boundaries.
+
+        Validates that the absolute resolved path is within the allowed directory
+        to prevent directory traversal attacks.
+
+        Args:
+            path (str): The path to validate.
+
+        Returns:
+            bool: True if path is within allowed directory, False otherwise.
+                Returns False if path resolution fails for any reason.
+
+        Private method intended for internal use only.
+        """
+        try:
+            abs_path = os.path.abspath(os.path.realpath(path))
+            return abs_path.startswith(self.allowed_dir)
+        except Exception:
+            return False
+
+    def execute(self, command_string: str) -> subprocess.CompletedProcess:
+        """
+        Executes a command string in a secure, controlled environment.
+
+        Runs the command after validating it against security constraints including length limits
+        and shell operator restrictions. Executes with controlled parameters for safety.
+
+        Args:
+            command_string (str): The command string to execute.
+
+        Returns:
+            subprocess.CompletedProcess: The result of the command execution containing
+                stdout, stderr, and return code.
+
+        Raises:
+            CommandSecurityError: If the command:
+                - Exceeds maximum length
+                - Contains invalid shell operators
+                - Fails security validation
+                - Fails during execution
+
+        Notes:
+            - Executes with shell=False for security
+            - Uses timeout and working directory constraints
+            - Captures both stdout and stderr
+        """
+        if len(command_string) > self.security_config.max_command_length:
+            raise CommandSecurityError("Command string too long")
+
+        try:
+
+            command, args = self.validate_command(command_string)
+            return subprocess.run(
+                [command] + args,
+                shell=False,
+                text=True,
+                capture_output=True,
+                timeout=self.security_config.command_timeout,
+                cwd=self.allowed_dir,
+            )
+        except Exception as e:
+            if isinstance(e, CommandSecurityError):
+                raise
+            raise CommandSecurityError(f"Command execution failed: {str(e)}")
+
+
+# Load security configuration from environment
+def load_security_config() -> SecurityConfig:
+    """
+    Loads security configuration from environment variables with default fallbacks.
+
+    Creates a SecurityConfig instance using environment variables to configure allowed
+    commands, flags, patterns, and execution constraints. Uses predefined defaults if
+    environment variables are not set.
+
+    Returns:
+        SecurityConfig: Configuration object containing:
+            - allowed_commands: Set of permitted command names
+            - allowed_flags: Set of permitted command flags/options
+            - allowed_patterns: List of regex patterns for valid inputs
+            - max_command_length: Maximum length of command string
+            - command_timeout: Maximum execution time in seconds
+
+    Environment Variables:
+        ALLOWED_COMMANDS: Comma-separated list of allowed commands (default: "ls,cat,pwd")
+        ALLOWED_FLAGS: Comma-separated list of allowed flags (default: "-l,-a,--help")
+        ALLOWED_PATTERNS: Comma-separated list of patterns (default: "*.txt,*.log,*.md")
+        MAX_COMMAND_LENGTH: Maximum command string length (default: 1024)
+        COMMAND_TIMEOUT: Command timeout in seconds (default: 30)
+    """
+    return SecurityConfig(
+        allowed_commands=set(os.getenv("ALLOWED_COMMANDS", "ls,cat,pwd").split(",")),
+        allowed_flags=set(os.getenv("ALLOWED_FLAGS", "-l,-a,--help").split(",")),
+        allowed_patterns=[
+            r"^[\w\-. ]+$",  # Basic filename pattern
+            *os.getenv("ALLOWED_PATTERNS", "*.txt,*.log,*.md").split(","),
+        ],
+        max_command_length=int(os.getenv("MAX_COMMAND_LENGTH", "1024")),
+        command_timeout=int(os.getenv("COMMAND_TIMEOUT", "30")),
+    )
+
+
+executor = CommandExecutor(
+    allowed_dir=os.getenv("ALLOWED_DIR", ""), security_config=load_security_config()
+)
+
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="run_command",
+            description=(
+                f"Allows command (CLI) execution in the directory: {executor.allowed_dir}\n\n"
+                f"Available commands: {', '.join(executor.security_config.allowed_commands)}\n"
+                f"Available flags: {', '.join(executor.security_config.allowed_flags)}\n\n"
+                "Note: Shell operators (&&, |, >, >>) are not supported."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Single command to execute (example: 'ls -l' or 'cat file.txt')"
+                    }
+                },
+                "required": ["command"],
+            },
+        ),
+        types.Tool(
+            name="show_security_rules",
+            description=(
+                "Show what commands and operations are allowed in this environment.\n"
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        )
+    ]
+
+
+@server.call_tool()
+async def handle_call_tool(
+        name: str, arguments: Optional[Dict[str, Any]]
+) -> List[types.TextContent]:
+    if name == "run_command":
+        if not arguments or "command" not in arguments:
+            return [
+                types.TextContent(type="text", text="No command provided", error=True)
+            ]
+
+        try:
+            result = executor.execute(arguments["command"])
+
+            response = []
+            if result.stdout:
+                response.append(types.TextContent(type="text", text=result.stdout))
+            if result.stderr:
+                response.append(
+                    types.TextContent(type="text", text=result.stderr, error=True)
+                )
+
+            response.append(
+                types.TextContent(
+                    type="text",
+                    text=f"\nCommand completed with return code: {result.returncode}",
+                )
+            )
+
+            return response
+
+        except CommandSecurityError as e:
+            return [
+                types.TextContent(
+                    type="text", text=f"Security violation: {str(e)}", error=True
+                )
+            ]
+        except subprocess.TimeoutExpired:
+            return [
+                types.TextContent(
+                    type="text",
+                    text=f"Command timed out after {executor.security_config.command_timeout} seconds",
+                    error=True,
+                )
+            ]
+        except Exception as e:
+            return [types.TextContent(type="text", text=f"Error: {str(e)}", error=True)]
+
+    elif name == "show_security_rules":
+        security_info = (
+            "Security Configuration:\n"
+            f"==================\n"
+            f"Working Directory: {executor.allowed_dir}\n"
+            f"\nAllowed Commands:\n"
+            f"----------------\n"
+            f"{', '.join(sorted(executor.security_config.allowed_commands))}\n"
+            f"\nAllowed Flags:\n"
+            f"-------------\n"
+            f"{', '.join(sorted(executor.security_config.allowed_flags))}\n"
+            f"\nAllowed Patterns:\n"
+            f"----------------\n"
+            f"{', '.join(executor.security_config.allowed_patterns)}\n"
+            f"\nSecurity Limits:\n"
+            f"---------------\n"
+            f"Max Command Length: {executor.security_config.max_command_length} characters\n"
+            f"Command Timeout: {executor.security_config.command_timeout} seconds\n"
+        )
+        return [types.TextContent(type="text", text=security_info)]
+
+    raise ValueError(f"Unknown tool: {name}")
+
+
+async def main():
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="cli-mcp-server",
+                server_version="0.1.1",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )

cli_mcp_server-0.1.2.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.3
+Name: cli-mcp-server
+Version: 0.1.2
+Summary: Command line interface for MCP clients with secure execution and customizable security policies
+Project-URL: Homepage, https://github.com/MladenSU/cli-mcp-server
+Project-URL: Documentation, https://github.com/MladenSU/cli-mcp-server#readme
+Project-URL: Repository, https://github.com/MladenSU/cli-mcp-server.git
+Project-URL: Bug Tracker, https://github.com/MladenSU/cli-mcp-server/issues
+Author-email: Mladen <fangs-lever6n@icloud.com>
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# CLI MCP Server
+
+---
+
+A secure Model Context Protocol (MCP) server implementation for executing controlled command-line operations with
+comprehensive security
+features.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)
+![MCP Protocol](https://img.shields.io/badge/MCP-Compatible-green)
+
+---
+
+# Table of Contents
+
+1. [Overview](#overview)
+2. [Features](#features)
+3. [Configuration](#configuration)
+4. [Available Tools](#available-tools)
+    - [run_command](#run_command)
+    - [show_security_rules](#show_security_rules)
+5. [Usage with Claude Desktop](#usage-with-claude-desktop)
+    - [Development/Unpublished Servers Configuration](#developmentunpublished-servers-configuration)
+    - [Published Servers Configuration](#published-servers-configuration)
+6. [Security Features](#security-features)
+7. [Error Handling](#error-handling)
+8. [Development](#development)
+    - [Prerequisites](#prerequisites)
+    - [Building and Publishing](#building-and-publishing)
+    - [Debugging](#debugging)
+9. [License](#license)
+
+---
+
+## Overview
+
+This MCP server enables secure command-line execution with robust security measures including command whitelisting, path
+validation, and
+execution controls. Perfect for providing controlled CLI access to LLM applications while maintaining security.
+
+## Features
+
+- 🔒 Secure command execution with strict validation
+- ⚙️ Configurable command and flag whitelisting
+- 🛡️ Path traversal prevention
+- 🚫 Shell operator injection protection
+- ⏱️ Execution timeouts and length limits
+- 📝 Detailed error reporting
+- 🔄 Async operation support
+
+## Configuration
+
+Configure the server using environment variables:
+
+| Variable             | Description                              | Default            |
+ |----------------------|------------------------------------------|--------------------|
+| `ALLOWED_DIR`        | Base directory for command execution     | Required           |
+| `ALLOWED_COMMANDS`   | Comma-separated list of allowed commands | `ls,cat,pwd`       |
+| `ALLOWED_FLAGS`      | Comma-separated list of allowed flags    | `-l,-a,--help`     |
+| `ALLOWED_PATTERNS`   | Comma-separated file patterns            | `*.txt,*.log,*.md` |
+| `MAX_COMMAND_LENGTH` | Maximum command string length            | `1024`             |
+| `COMMAND_TIMEOUT`    | Command execution timeout (seconds)      | `30`               |
+
+## Available Tools
+
+### run_command
+
+Executes whitelisted CLI commands within allowed directories.
+
+**Input Schema:**
+
+ ```json
+ {
+  "command": {
+    "type": "string",
+    "description": "Command to execute (e.g., 'ls -l' or 'cat file.txt')"
+  }
+}
+ ```
+
+### show_security_rules
+
+Displays current security configuration and restrictions.
+
+## Usage with Claude Desktop
+
+Add to your `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
+
+> Development/Unpublished Servers Configuration
+
+ ```json
+{
+  "mcpServers": {
+    "cli-mcp-server": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "<path/to/the/repo>/cli-mcp-server",
+        "run",
+        "cli-mcp-server"
+      ],
+      "env": {
+        "ALLOWED_DIR": "</your/desired/dir>",
+        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
+        "ALLOWED_FLAGS": "-l,-a,--help,--version",
+        "ALLOWED_PATTERNS": "*.txt,*.log,*.md",
+        "MAX_COMMAND_LENGTH": "1024",
+        "COMMAND_TIMEOUT": "30"
+      }
+    }
+  }
+}
+ ```
+
+> Published Servers Configuration
+
+```json
+{
+  "mcpServers": {
+    "cli-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "cli-mcp-server"
+      ],
+      "env": {
+        "ALLOWED_DIR": "</your/desired/dir>",
+        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
+        "ALLOWED_FLAGS": "-l,-a,--help,--version",
+        "ALLOWED_PATTERNS": "*.txt,*.log,*.md",
+        "MAX_COMMAND_LENGTH": "1024",
+        "COMMAND_TIMEOUT": "30"
+      }
+    }
+  }
+}
+```
+
+## Security Features
+
+- ✅ Command whitelist enforcement
+- ✅ Flag validation
+- ✅ Path traversal prevention
+- ✅ Shell operator blocking
+- ✅ Command length limits
+- ✅ Execution timeouts
+- ✅ Working directory restrictions
+
+## Error Handling
+
+The server provides detailed error messages for:
+
+- Security violations
+- Command timeouts
+- Invalid command formats
+- Path security violations
+- Execution failures
+
+## Development
+
+### Prerequisites
+
+- Python 3.10+
+- MCP protocol library
+
+## Development
+
+### Building and Publishing
+
+To prepare the package for distribution:
+
+1. Sync dependencies and update lockfile:
+    ```bash
+    uv sync
+    ```
+
+2. Build package distributions:
+    ```bash
+    uv build
+    ```
+
+   > This will create source and wheel distributions in the `dist/` directory.
+
+3. Publish to PyPI:
+   ```bash
+   uv publish --token {{YOUR_PYPI_API_TOKEN}}
+   ```
+
+### Debugging
+
+Since MCP servers run over stdio, debugging can be challenging. For the best debugging
+experience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).
+
+You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with
+this command:
+
+```bash
+npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/unichat-mcp-server run unichat-mcp-server
+```
+
+Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+ ---
+
+For more information or support, please open an issue on the project repository.

cli_mcp_server-0.1.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+cli_mcp_server/__init__.py,sha256=F95EXGXtBnIVQqu-bXcasy5OfORA-gzLnvXyqWFtjcY,216
+cli_mcp_server/server.py,sha256=vXfPFCIbPjZ8J6cyRinCMZgFYBev5muwmPkq4ZFAh3s,12336
+cli_mcp_server-0.1.2.dist-info/METADATA,sha256=daSaUn_7-fGogH5fHN9VOPWETW1x2hO7pauuZ59x5eI,6199
+cli_mcp_server-0.1.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+cli_mcp_server-0.1.2.dist-info/entry_points.txt,sha256=07bDmJJSXg-6VCFEFTOlsGoxI-0faJafT1yEEjUdN-U,55
+cli_mcp_server-0.1.2.dist-info/licenses/LICENSE,sha256=85rOR_IMpb2VzXBA4VCRZh_KWlaO1Rly8HDYDwGgMWk,1062
+cli_mcp_server-0.1.2.dist-info/RECORD,,

cli_mcp_server-0.1.2.dist-info/WHEEL

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

cli_mcp_server-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cli-mcp-server = cli_mcp_server:main

cli_mcp_server-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mladen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.