add initila files

Author: tumf

.gitignore

@@ -0,0 +1,78 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.env
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST

README.md

@@ -0,0 +1,114 @@
+# 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
+* **Stdin 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 (; , &&, ||, |)
+
+## Installation
+
+```bash
+pip install mcp-shell-server
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/mcp-shell-server.git
+cd mcp-shell-server
+pip install -e .
+```
+
+## 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.
+
+### Making Requests
+
+Example requests to the server:
+
+```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
+
+## Environment Variables
+
+* `ALLOW_COMMANDS`: Comma-separated list of allowed commands (e.g., "ls, cat, echo")
+
+## API Reference
+
+### Request Format
+
+| Field    | Type       | Description                                   |
+|----------|------------|-----------------------------------------------|
+| command  | string[]   | Command and its arguments as array elements   |
+| stdin    | string     | (Optional) Input to be passed to the command |
+
+### Response Format
+
+| 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  | (Optional) Error message if failed         |
+
+## Requirements
+
+* Python 3.11 or higher
+* uvicorn
+* fastapi
+* mcp-core

mcp_shell_server/__init__.py

@@ -0,0 +1,5 @@
+from .server import ShellServer, main
+from .shell_executor import ShellExecutor
+
+__version__ = "0.1.0"
+__all__ = ["ShellServer", "ShellExecutor", "main"]

mcp_shell_server/server.py

@@ -0,0 +1,27 @@
+import os
+import asyncio
+from typing import Dict, List, Optional, Any
+from mcp_core import MCPServer, MCPRequest
+from .shell_executor import ShellExecutor
+
+class ShellServer(MCPServer):
+    def __init__(self):
+        super().__init__()
+        self.executor = ShellExecutor()
+
+    async def handle_request(self, request: MCPRequest) -> Dict[str, Any]:
+        command: List[str] = request.args.get("command", [])
+        stdin: Optional[str] = request.args.get("stdin")
+        
+        if not command:
+            return {
+                "error": "No command provided",
+                "status": 1
+            }
+        
+        result = await self.executor.execute(command, stdin)
+        return result
+
+def main():
+    server = ShellServer()
+    server.run()

mcp_shell_server/shell_executor.py

@@ -0,0 +1,62 @@
+import os
+import time
+import asyncio
+from typing import Dict, List, Optional, Any
+
+class ShellExecutor:
+    def __init__(self):
+        # Allow whitespace in ALLOW_COMMANDS and trim each command
+        allow_commands = os.environ.get("ALLOW_COMMANDS", "")
+        self.allowed_commands = set(cmd.strip() for cmd in allow_commands.split(",") if cmd.strip())
+
+    def _validate_command(self, command: List[str]) -> None:
+        if not command:
+            raise ValueError("Empty command")
+
+        # Check first command
+        if command[0] not in self.allowed_commands:
+            raise ValueError(f"Command not allowed: {command[0]}")
+
+        # Check for shell operators and subsequent commands
+        for arg in command[1:]:
+            if arg in [";", "&&", "||", "|"]:
+                next_cmd_idx = command.index(arg) + 1
+                if next_cmd_idx < len(command):
+                    next_cmd = command[next_cmd_idx]
+                    if next_cmd not in self.allowed_commands:
+                        raise ValueError(f"Command not allowed: {next_cmd}")
+
+    async def execute(self, command: List[str], stdin: Optional[str] = None) -> Dict[str, Any]:
+        try:
+            self._validate_command(command)
+        except ValueError as e:
+            return {
+                "error": str(e),
+                "status": 1,
+                "stdout": "",
+                "stderr": str(e),
+                "execution_time": 0
+            }
+
+        start_time = time.time()
+        
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdin=asyncio.subprocess.PIPE if stdin else None,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE
+        )
+
+        if stdin:
+            stdout, stderr = await process.communicate(stdin.encode())
+        else:
+            stdout, stderr = await process.communicate()
+
+        execution_time = time.time() - start_time
+
+        return {
+            "stdout": stdout.decode() if stdout else "",
+            "stderr": stderr.decode() if stderr else "",
+            "status": process.returncode,
+            "execution_time": execution_time
+        }

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "mcp-shell-server"
+version = "0.1.0"
+description = "MCP Shell Server - Execute shell commands via MCP protocol"
+authors = [
+    { name = "tumf" }
+]
+dependencies = [
+    "uvicorn>=0.27.0",
+    "fastapi>=0.109.0",
+    "mcp-core>=0.2.0",
+]
+requires-python = ">=3.11"
+readme = "README.md"
+license = { text = "MIT" }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[project.scripts]
+mcp-shell-server = "mcp_shell_server.server:main"