mcp-shell-server 0.1.0__tar.gz

mcp_shell_server-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10

mcp_shell_server-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,52 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Install dev/test dependencies
+        run: |
+          pip install -e ".[dev]"
+          pip install -e ".[test]"
+
+      - name: Run tests
+        run: |
+          uv run pytest
+
+      - name: Run ruff
+        run: |
+          uv run ruff check .
+
+      - name: Run black
+        run: |
+          uv run black . --check
+
+      - name: Run isort
+        run: |
+          uv run isort . --check-only
+
+      - name: Run mypy
+        run: |
+          uv run mypy mcp_shell_server tests

mcp_shell_server-0.1.0/.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

mcp_shell_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

mcp_shell_server-0.1.0/Makefile

@@ -0,0 +1,23 @@
+.PHONY: test format lint typecheck check
+
+test:
+	pytest
+
+format:
+	black .
+	isort .
+	ruff check --fix .
+
+
+lint:
+	black --check .
+	isort --check .
+	ruff check .
+
+typecheck:
+	mypy mcp_shell_server tests
+
+# Run all checks required before pushing
+check:  lint typecheck test
+fix: check format
+all: check

mcp_shell_server-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,158 @@
+# 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/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-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