mcp-shell-server 0.1.0__py3-none-any.whl

mcp_shell_server/__init__.py

@@ -0,0 +1,15 @@
+"""MCP Shell Server Package."""
+
+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"]
+__version__ = "0.1.0"

mcp_shell_server/server.py

@@ -0,0 +1,123 @@
+import logging
+import traceback
+from collections.abc import Sequence
+from typing import Any
+
+from mcp.server import Server
+from mcp.types import TextContent, Tool
+
+from .shell_executor import ShellExecutor
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("mcp-shell-server")
+
+app = Server("mcp-shell-server")
+
+
+class ExecuteToolHandler:
+    """Handler for shell command execution"""
+
+    name = "shell_execute"
+    description = "Execute a shell command"
+
+    def __init__(self):
+        self.executor = ShellExecutor()
+
+    def get_allowed_commands(self) -> list[str]:
+        """Get the allowed commands"""
+        return self.executor.get_allowed_commands()
+
+    def get_tool_description(self) -> Tool:
+        """Get the tool description for the execute command"""
+        return Tool(
+            name=self.name,
+            description=f"{self.description}\nAllowed commands: {', '.join(self.get_allowed_commands())}",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Command and its arguments as array",
+                    },
+                    "stdin": {
+                        "type": "string",
+                        "description": "Input to be passed to the command via stdin",
+                    },
+                    "directory": {
+                        "type": "string",
+                        "description": "Working directory where the command will be executed",
+                    },
+                },
+                "required": ["command"],
+            },
+        )
+
+    async def run_tool(self, arguments: dict) -> Sequence[TextContent]:
+        """Execute the shell command with the given arguments"""
+        command = arguments.get("command", [])
+        stdin = arguments.get("stdin")
+        directory = arguments.get("directory")
+
+        if not command:
+            raise ValueError("No command provided")
+
+        result = await self.executor.execute(command, stdin, directory)
+
+        # Raise error if command execution failed
+        if result.get("error"):
+            raise RuntimeError(result["error"])
+
+        # Convert executor result to TextContent sequence
+        content: list[TextContent] = []
+
+        if result.get("stdout"):
+            content.append(TextContent(type="text", text=result["stdout"]))
+        if result.get("stderr"):
+            content.append(TextContent(type="text", text=result["stderr"]))
+
+        return content
+
+
+# Initialize tool handlers
+tool_handler = ExecuteToolHandler()
+
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    """List available tools."""
+    return [tool_handler.get_tool_description()]
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: Any) -> Sequence[TextContent]:
+    """Handle tool calls"""
+    try:
+        if name != tool_handler.name:
+            raise ValueError(f"Unknown tool: {name}")
+
+        if not isinstance(arguments, dict):
+            raise ValueError("Arguments must be a dictionary")
+
+        return await tool_handler.run_tool(arguments)
+
+    except Exception as e:
+        logger.error(traceback.format_exc())
+        logger.error(f"Error during call_tool: {str(e)}")
+        raise RuntimeError(f"Error executing command: {str(e)}") from e
+
+
+async def main() -> None:
+    """Main entry point for the MCP shell server"""
+    logger.info("Starting MCP shell server")
+    try:
+        from mcp.server.stdio import stdio_server
+
+        async with stdio_server() as (read_stream, write_stream):
+            await app.run(
+                read_stream, write_stream, app.create_initialization_options()
+            )
+    except Exception as e:
+        logger.error(f"Server error: {str(e)}")
+        raise

mcp_shell_server/shell_executor.py

@@ -0,0 +1,175 @@
+import asyncio
+import os
+import time
+from typing import Any, Dict, List, Optional
+
+
+class ShellExecutor:
+    """
+    Executes shell commands in a secure manner by validating against a whitelist.
+    """
+
+    def __init__(self):
+        """
+        Initialize the executor. The allowed commands are read from ALLOW_COMMANDS
+        environment variable during command validation, not at initialization.
+        """
+        pass
+
+    def _get_allowed_commands(self) -> set:
+        """
+        Get the set of allowed commands from environment variable.
+
+        Returns:
+            set: Set of allowed command names
+        """
+        allow_commands = os.environ.get("ALLOW_COMMANDS", "")
+        return {cmd.strip() for cmd in allow_commands.split(",") if cmd.strip()}
+
+    def _clean_command(self, command: List[str]) -> List[str]:
+        """
+        Clean command by trimming whitespace from each part.
+
+        Args:
+            command (List[str]): Original command and its arguments
+
+        Returns:
+            List[str]: Cleaned command with trimmed whitespace
+        """
+        return [arg.strip() for arg in command if arg.strip()]
+
+    def _validate_command(self, command: List[str]) -> None:
+        """
+        Validate if the command is allowed to be executed.
+
+        Args:
+            command (List[str]): Command and its arguments
+
+        Raises:
+            ValueError: If the command is empty, not allowed, or contains invalid shell operators
+        """
+        if not command:
+            raise ValueError("Empty command")
+
+        allowed_commands = self._get_allowed_commands()
+        if not allowed_commands:
+            raise ValueError(
+                "No commands are allowed. Please set ALLOW_COMMANDS environment variable."
+            )
+
+        # Clean and check the first command
+        cleaned_cmd = command[0].strip()
+        if cleaned_cmd not in allowed_commands:
+            raise ValueError(f"Command not allowed: {cleaned_cmd}")
+
+        # Check for shell operators and validate subsequent commands
+        for i, arg in enumerate(command[1:], start=1):
+            cleaned_arg = arg.strip()
+            if cleaned_arg in [";", "&&", "||", "|"]:
+                if i + 1 >= len(command):
+                    raise ValueError(f"Unexpected shell operator: {cleaned_arg}")
+                next_cmd = command[i + 1].strip()
+                if next_cmd not in allowed_commands:
+                    raise ValueError(
+                        f"Command not allowed after {cleaned_arg}: {next_cmd}"
+                    )
+
+    def _validate_directory(self, directory: Optional[str]) -> None:
+        """
+        Validate if the directory exists and is accessible.
+
+        Args:
+            directory (Optional[str]): Directory path to validate
+
+        Raises:
+            ValueError: If the directory doesn't exist or is not accessible
+        """
+        if directory is None:
+            return
+
+        if not os.path.exists(directory):
+            raise ValueError(f"Directory does not exist: {directory}")
+        if not os.path.isdir(directory):
+            raise ValueError(f"Not a directory: {directory}")
+        if not os.access(directory, os.R_OK | os.X_OK):
+            raise ValueError(f"Directory is not accessible: {directory}")
+
+    def get_allowed_commands(self) -> list[str]:
+        """Get the allowed commands"""
+        return list(self._get_allowed_commands())
+
+    async def execute(
+        self,
+        command: List[str],
+        stdin: Optional[str] = None,
+        directory: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Execute a shell command with optional stdin input and working directory.
+
+        Args:
+            command (List[str]): Command and its arguments
+            stdin (Optional[str]): Input to be passed to the command via stdin
+            directory (Optional[str]): Working directory for command execution
+
+        Returns:
+            Dict[str, Any]: Execution result containing stdout, stderr, status code, and execution time.
+                           If error occurs, result contains additional 'error' field.
+        """
+        start_time = time.time()
+
+        try:
+            # Clean command before validation and execution
+            cleaned_command = self._clean_command(command)
+            if not cleaned_command:
+                raise ValueError("Empty command")
+
+            self._validate_command(cleaned_command)
+            self._validate_directory(directory)
+        except ValueError as e:
+            return {
+                "error": str(e),
+                "status": 1,
+                "stdout": "",
+                "stderr": str(e),
+                "execution_time": time.time() - start_time,
+            }
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                cleaned_command[0],
+                *cleaned_command[1:],
+                stdin=asyncio.subprocess.PIPE if stdin else None,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env={"PATH": os.environ.get("PATH", "")},
+                cwd=directory,  # Set working directory if specified
+            )
+
+            stdin_bytes = stdin.encode() if stdin else None
+            stdout, stderr = await process.communicate(input=stdin_bytes)
+
+            return {
+                "error": None,  # Set error field to None for success case
+                "stdout": stdout.decode() if stdout else "",
+                "stderr": stderr.decode() if stderr else "",
+                "status": process.returncode,
+                "execution_time": time.time() - start_time,
+                "directory": directory,  # Include working directory in response
+            }
+        except FileNotFoundError:
+            return {
+                "error": f"Command not found: {cleaned_command[0]}",
+                "status": 1,
+                "stdout": "",
+                "stderr": f"Command not found: {cleaned_command[0]}",
+                "execution_time": time.time() - start_time,
+            }
+        except Exception as e:
+            return {
+                "error": str(e),
+                "status": 1,
+                "stdout": "",
+                "stderr": str(e),
+                "execution_time": time.time() - start_time,
+            }

mcp_shell_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.3
+Name: mcp-shell-server
+Version: 0.1.0
+Summary: MCP Shell Server - Execute shell commands via MCP protocol
+Author: tumf
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: mcp>=1.1.0
+Provides-Extra: dev
+Requires-Dist: black>=23.3.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.2.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.2.2; extra == 'dev'
+Requires-Dist: ruff>=0.0.262; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
+Requires-Dist: pytest-env>=1.1.0; extra == 'test'
+Requires-Dist: pytest>=7.4.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MCP Shell Server
+
+A secure shell command execution server implementing the Model Context Protocol (MCP). This server allows remote execution of whitelisted shell commands with support for stdin input.
+
+## Features
+
+* **Secure Command Execution**: Only whitelisted commands can be executed
+* **Standard Input Support**: Pass input to commands via stdin
+* **Comprehensive Output**: Returns stdout, stderr, exit status, and execution time
+* **Shell Operator Safety**: Validates commands after shell operators (; , &&, ||, |)
+
+## MCP client setting in your Claude.app
+
+```shell
+code ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
+
+```json
+{
+  "mcpServers": {
+    "shell": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        ".",
+        "run",
+        "mcp-shell-server"
+      ],
+      "env": {
+        "ALLOW_COMMANDS": "ls,cat,pwd,grep,wc,touch,find"
+      }
+    },
+  }
+}
+```
+
+## Installation
+
+```bash
+pip install mcp-shell-server
+```
+
+## Usage
+
+### Starting the Server
+
+```bash
+ALLOW_COMMANDS="ls,cat,echo" uvx mcp-shell-server
+```
+
+The `ALLOW_COMMANDS` environment variable specifies which commands are allowed to be executed. Commands can be separated by commas with optional spaces around them.
+
+Valid formats for ALLOW_COMMANDS:
+
+```bash
+ALLOW_COMMANDS="ls,cat,echo"          # Basic format
+ALLOW_COMMANDS="ls ,echo, cat"        # With spaces
+ALLOW_COMMANDS="ls,  cat  , echo"     # Multiple spaces
+```
+
+### Request Format
+
+```python
+# Basic command execution
+{
+    "command": ["ls", "-l", "/tmp"]
+}
+
+# Command with stdin input
+{
+    "command": ["cat"],
+    "stdin": "Hello, World!"
+}
+```
+
+### Response Format
+
+Successful response:
+
+```json
+{
+    "stdout": "command output",
+    "stderr": "",
+    "status": 0,
+    "execution_time": 0.123
+}
+```
+
+Error response:
+
+```json
+{
+    "error": "Command not allowed: rm",
+    "status": 1,
+    "stdout": "",
+    "stderr": "Command not allowed: rm",
+    "execution_time": 0
+}
+```
+
+## Security
+
+The server implements several security measures:
+
+1. **Command Whitelisting**: Only explicitly allowed commands can be executed
+2. **Shell Operator Validation**: Commands after shell operators (;, &&, ||, |) are also validated against the whitelist
+3. **No Shell Injection**: Commands are executed directly without shell interpretation
+
+## Development
+
+### Setting up Development Environment
+
+1. Clone the repository
+
+```bash
+git clone https://github.com/yourusername/mcp-shell-server.git
+cd mcp-shell-server
+```
+
+2. Install dependencies including test requirements
+
+```bash
+pip install -e ".[test]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+## API Reference
+
+### Request Arguments
+
+| Field    | Type       | Required | Description                                   |
+|----------|------------|----------|-----------------------------------------------|
+| command  | string[]   | Yes      | Command and its arguments as array elements   |
+| stdin    | string     | No       | Input to be passed to the command            |
+
+### Response Fields
+
+| Field           | Type    | Description                                |
+|----------------|---------|---------------------------------------------|
+| stdout         | string  | Standard output from the command           |
+| stderr         | string  | Standard error output from the command     |
+| status         | integer | Exit status code                           |
+| execution_time | float   | Time taken to execute (in seconds)         |
+| error          | string  | Error message (only present if failed)     |
+
+## Requirements
+
+* Python 3.11 or higher
+* mcp>=1.1.0
+
+## License
+
+MIT License - See LICENSE file for details

mcp_shell_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_shell_server/__init__.py,sha256=PXUa6MYNfCK7XRaIeod8TRp4_NXWRhnC2MyZq4iwbjA,271
+mcp_shell_server/server.py,sha256=EPQ3p232eeak4vAfaKJKn5dXa7CWZK4oawRKnng5JUU,3890
+mcp_shell_server/shell_executor.py,sha256=5_wKIQQzobaYXdCUYe17qPDH4GMmOgop4wm3IDmDcG0,6329
+mcp_shell_server-0.1.0.dist-info/METADATA,sha256=A0L0xv1ex-xoaUtebiQ-DWA0bHFwoO_tp-0_yhkj56M,4400
+mcp_shell_server-0.1.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+mcp_shell_server-0.1.0.dist-info/entry_points.txt,sha256=cliA1OUE6oGFNpFqxK39iVUAEYITAYn1JnufKxl5Kn8,59
+mcp_shell_server-0.1.0.dist-info/RECORD,,

mcp_shell_server-0.1.0.dist-info/WHEEL

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

mcp_shell_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-shell-server = mcp_shell_server:main