mseep-cmd-line-mcp 0.5.0__py3-none-any.whl

cmd_line_mcp/session.py

@@ -0,0 +1,144 @@
+"""Session management for the command-line MCP server."""
+
+import time
+import os
+from typing import Dict, Any, Set
+
+
+class SessionManager:
+    """Manage user sessions for command permissions."""
+
+    def __init__(self):
+        """Initialize the session manager."""
+        self.sessions: Dict[str, Dict[str, Any]] = {}
+
+    def get_session(self, session_id: str) -> Dict[str, Any]:
+        """Get a session by ID, creating it if it doesn't exist.
+
+        Args:
+            session_id: The session ID
+
+        Returns:
+            The session data
+        """
+        if session_id not in self.sessions:
+            self.sessions[session_id] = {
+                "created_at": time.time(),
+                "last_active": time.time(),
+                "approved_commands": set(),
+                "approved_command_types": set(),
+                "approved_directories": set(),  # New: track approved directories
+            }
+
+        # Update last active time
+        self.sessions[session_id]["last_active"] = time.time()
+        return self.sessions[session_id]
+
+    def has_command_approval(self, session_id: str, command: str) -> bool:
+        """Check if a command has been approved for a session.
+
+        Args:
+            session_id: The session ID
+            command: The command to check
+
+        Returns:
+            True if the command has been approved, False otherwise
+        """
+        session = self.get_session(session_id)
+        return command in session["approved_commands"]
+
+    def has_command_type_approval(self, session_id: str, command_type: str) -> bool:
+        """Check if a command type has been approved for a session.
+
+        Args:
+            session_id: The session ID
+            command_type: The command type to check
+
+        Returns:
+            True if the command type has been approved, False otherwise
+        """
+        session = self.get_session(session_id)
+        return command_type in session["approved_command_types"]
+
+    def approve_command(self, session_id: str, command: str) -> None:
+        """Approve a command for a session.
+
+        Args:
+            session_id: The session ID
+            command: The command to approve
+        """
+        session = self.get_session(session_id)
+        session["approved_commands"].add(command)
+
+    def approve_command_type(self, session_id: str, command_type: str) -> None:
+        """Approve a command type for a session.
+
+        Args:
+            session_id: The session ID
+            command_type: The command type to approve
+        """
+        session = self.get_session(session_id)
+        session["approved_command_types"].add(command_type)
+
+    def has_directory_approval(self, session_id: str, directory: str) -> bool:
+        """Check if a directory has been approved for a session.
+
+        Args:
+            session_id: The session ID
+            directory: The directory to check
+
+        Returns:
+            True if the directory has been approved, False otherwise
+        """
+        session = self.get_session(session_id)
+        approved_dirs = session["approved_directories"]
+
+        # Check if the directory or any of its parents have been approved
+        for approved_dir in approved_dirs:
+            # Exact match
+            if directory == approved_dir:
+                return True
+
+            # Check if directory is a subdirectory of an approved directory
+            if directory.startswith(approved_dir + os.sep):
+                return True
+
+        return False
+
+    def approve_directory(self, session_id: str, directory: str) -> None:
+        """Approve a directory for a session.
+
+        Args:
+            session_id: The session ID
+            directory: The directory to approve
+        """
+        session = self.get_session(session_id)
+        session["approved_directories"].add(directory)
+
+    def get_approved_directories(self, session_id: str) -> Set[str]:
+        """Get all approved directories for a session.
+
+        Args:
+            session_id: The session ID
+
+        Returns:
+            Set of approved directories
+        """
+        session = self.get_session(session_id)
+        return session["approved_directories"]
+
+    def clean_old_sessions(self, max_age: int = 3600) -> None:
+        """Clean up old sessions.
+
+        Args:
+            max_age: Maximum age of sessions in seconds (default: 1 hour)
+        """
+        now = time.time()
+        to_remove = []
+
+        for session_id, session in self.sessions.items():
+            if now - session["last_active"] > max_age:
+                to_remove.append(session_id)
+
+        for session_id in to_remove:
+            del self.sessions[session_id]

mseep_cmd_line_mcp-0.5.0.data/data/default_config.json

@@ -0,0 +1,65 @@
+{
+  "server": {
+    "name": "cmd-line-mcp",
+    "version": "0.4.0",
+    "description": "MCP server for safely executing command-line tools",
+    "log_level": "INFO"
+  },
+  "security": {
+    "session_timeout": 3600,
+    "max_output_size": 102400,
+    "allow_user_confirmation": true,
+    "require_session_id": false,
+    "allow_command_separators": true,
+    "whitelisted_directories": [
+      "~/Downloads",
+      "/tmp",
+      "/usr/local/share"
+    ],
+    "auto_approve_directories_in_desktop_mode": false
+  },
+  "commands": {
+    "read": [
+      "ls", "pwd", "cat", "less", "head", "tail", "grep",
+      "find", "which", "du", "df", "file", "uname", "hostname", 
+      "uptime", "date", "whoami", "id", "env", "history", "man",
+      "info", "help", "sort", "wc"
+    ],
+    "write": [
+      "cp", "mv", "rm", "mkdir", "rmdir", "touch", "chmod", "chown",
+      "ln", "echo", "printf", "export", "tar", "gzip", "zip", "unzip",
+      "awk", "sed"
+    ],
+    "system": [
+      "ps", "top", "htop", "who", "netstat", "ifconfig", "ping",
+      "ssh", "scp", "curl", "wget", "xargs"
+    ],
+    "blocked": [
+      "sudo", "su", "bash", "sh", "zsh", "ksh", "csh", "fish",
+      "screen", "tmux", "nc", "telnet", "nmap",
+      "dd", "mkfs", "mount", "umount", "shutdown", "reboot",
+      "passwd", "chpasswd", "useradd", "userdel", "groupadd", "groupdel",
+      "eval", "exec", "source", "."
+    ],
+    "dangerous_patterns": [
+      "rm\\s+-rf\\s+/",
+      ">\\s+/dev/(sd|hd|nvme|xvd)",
+      ">\\s+/dev/null",
+      ">\\s+/etc/",
+      ">\\s+/boot/",
+      ">\\s+/bin/",
+      ">\\s+/sbin/",
+      ">\\s+/usr/bin/",
+      ">\\s+/usr/sbin/",
+      ">\\s+/usr/local/bin/",
+      "2>&1",
+      "\\$\\(",
+      "\\$\\{\\w+\\}",
+      "`"
+    ]
+  },
+  "output": {
+    "max_size": 102400,
+    "format": "text"
+  }
+}

mseep_cmd_line_mcp-0.5.0.dist-info/METADATA

@@ -0,0 +1,347 @@
+Metadata-Version: 2.4
+Name: mseep-cmd-line-mcp
+Version: 0.5.0
+Summary: Command-line MCP server for safe command execution
+Home-page: 
+Author: mseep
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# Command-Line MCP Server
+
+[![PyPI version](https://badge.fury.io/py/cmd-line-mcp.svg)](https://badge.fury.io/py/cmd-line-mcp)
+[![Python Versions](https://img.shields.io/pypi/pyversions/cmd-line-mcp.svg)](https://pypi.org/project/cmd-line-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A secure Model Control Protocol (MCP) server that allows AI assistants to execute terminal commands with controlled directory access and command permissions.
+
+## Overview
+
+Command-Line MCP provides a security layer between AI assistants and your terminal. It implements a dual security model:
+
+1. **Command Permissions**: Commands are categorized as read (safe), write (changes data), or system (affects system state), with different approval requirements
+2. **Directory Permissions**: Commands can only access explicitly whitelisted directories or directories approved during a session
+
+AI assistants interact with this server using standardized MCP tools, enabling safe terminal command execution while preventing access to sensitive files or dangerous operations. You can configure the security level from highly restrictive to more permissive based on your needs.
+
+## Key Features
+
+| Security | Usability | Integration |
+|----------|-----------|-------------|
+| Directory whitelisting | Command categorization (read/write/system) | Claude Desktop compatibility |
+| Command filtering | Persistent session permissions | Standard MCP protocol |
+| Pattern matching | Command chaining (pipes, etc.) | Auto-approval options |
+| Dangerous command blocking | Intuitive approval workflow | Multiple config methods |
+
+## Supported Commands (out of the box)
+
+### Read Commands
+- `ls`, `pwd`, `cat`, `less`, `head`, `tail`, `grep`, `find`, `which`, `du`, `df`, `file`, `sort`, etc.
+
+### Write Commands  
+- `cp`, `mv`, `rm`, `mkdir`, `rmdir`, `touch`, `chmod`, `chown`, etc.
+
+### System Commands
+- `ps`, `top`, `htop`, `who`, `netstat`, `ifconfig`, `ping`, etc.
+
+## Security Architecture
+
+The system implements a multi-layered security approach:
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                   COMMAND-LINE MCP SERVER                     │
+├──────────────────┬────────────────────────┬───────────────────┤
+│ COMMAND SECURITY │   DIRECTORY SECURITY   │ SESSION SECURITY  │
+├──────────────────┼────────────────────────┼───────────────────┤
+│ ✓ Read commands  │ ✓ Directory whitelist  │ ✓ Session IDs     │
+│ ✓ Write commands │ ✓ Runtime approvals    │ ✓ Persistent      │
+│ ✓ System commands│ ✓ Path validation      │   permissions     │
+│ ✓ Blocked list   │ ✓ Home dir expansion   │ ✓ Auto timeouts   │
+│ ✓ Pattern filters│ ✓ Subdirectory check   │ ✓ Desktop mode    │
+└──────────────────┴────────────────────────┴───────────────────┘
+```
+
+All security features can be configured from restrictive to permissive based on your threat model and convenience requirements.
+
+## Quick Start
+
+```bash
+# Install
+git clone https://github.com/yourusername/cmd-line-mcp.git
+cd cmd-line-mcp
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+cp config.json.example config.json
+
+# Run
+cmd-line-mcp                        # With default config
+cmd-line-mcp --config config.json   # With specific config
+```
+
+### Configuration Options
+
+The server supports four configuration methods in order of precedence:
+
+1. **Built-in default configuration** (default_config.json)
+2. **JSON configuration file** (recommended for customization)
+   ```bash
+   cmd-line-mcp --config config.json
+   ```
+3. **Environment variables** (for specific overrides)
+   ```bash
+   export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="~,/tmp"
+   ```
+4. **.env file** (for environment-specific settings)
+   ```bash
+   cmd-line-mcp --config config.json --env .env
+   ```
+
+The default configuration is stored in `default_config.json` and is included with the package. You can copy this file to create your own custom configuration.
+
+#### Core Configuration Settings
+
+```json
+{
+  "security": {
+    "whitelisted_directories": ["/home", "/tmp", "~"],
+    "auto_approve_directories_in_desktop_mode": false, 
+    "require_session_id": false,
+    "allow_command_separators": true
+  },
+  "commands": {
+    "read": ["ls", "cat", "grep"], 
+    "write": ["touch", "mkdir", "rm"],
+    "system": ["ps", "ping"]
+  }
+}
+```
+
+#### Environment Variable Format
+
+Environment variables use a predictable naming pattern:
+```
+CMD_LINE_MCP_<SECTION>_<SETTING>
+```
+
+Examples:
+```bash
+# Security settings
+export CMD_LINE_MCP_SECURITY_WHITELISTED_DIRECTORIES="/projects,/var/data"
+export CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE=true
+
+# Command additions (these merge with defaults)
+export CMD_LINE_MCP_COMMANDS_READ="awk,jq,wc"
+```
+
+### Claude Desktop Integration
+
+#### Setup
+
+1. Install [Claude for Desktop](https://claude.ai/download)
+2. Configure in `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cmd-line": {
+      "command": "/path/to/venv/bin/cmd-line-mcp",
+      "args": ["--config", "/path/to/config.json"],
+      "env": {
+        "CMD_LINE_MCP_SECURITY_REQUIRE_SESSION_ID": "false",
+        "CMD_LINE_MCP_SECURITY_AUTO_APPROVE_DIRECTORIES_IN_DESKTOP_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+#### Recommended Claude Desktop Settings
+
+For best experience, configure:
+- `require_session_id: false` - Essential to prevent approval loops
+- `auto_approve_directories_in_desktop_mode: true` - Optional for convenient access
+- Include common directories in your whitelist
+
+After configuration, restart Claude for Desktop.
+
+## AI Assistant Tools
+
+The server provides these MCP tools for AI assistants:
+
+| Tool | Purpose | Needs Approval |
+|------|---------|----------------|
+| `execute_command` | Run any command type | Yes, for write/system commands |
+| `execute_read_command` | Run read-only commands | Directory approval only |
+| `approve_directory` | Grant access to a directory | N/A - it's an approval tool |
+| `approve_command_type` | Grant permission for command category | N/A - it's an approval tool |
+| `list_directories` | Show authorized directories | No |
+| `list_available_commands` | Show command categories | No |
+| `get_command_help` | Get command usage guidance | No |
+| `get_configuration` | View current settings | No |
+
+### Tool Examples
+
+#### Directory Management
+
+```python
+# Check available directories
+dirs = await list_directories(session_id="session123")
+whitelisted = dirs["whitelisted_directories"]
+approved = dirs["session_approved_directories"]
+
+# Request permission for a directory
+if "/projects/my-data" not in whitelisted and "/projects/my-data" not in approved:
+    result = await approve_directory(
+        directory="/projects/my-data", 
+        session_id="session123"
+    )
+```
+
+#### Command Execution
+
+```python
+# Read commands (read permissions enforced)
+result = await execute_read_command("ls -la ~/Documents")
+
+# Any command type (may require command type approval)
+result = await execute_command(
+    command="mkdir -p ~/Projects/new-folder", 
+    session_id="session123"
+)
+```
+
+#### Get Configuration
+
+```python
+# Check current settings
+config = await get_configuration()
+whitelist = config["directory_whitelisting"]["whitelisted_directories"]
+```
+
+
+## Directory Security System
+
+The server restricts command execution to specific directories, preventing access to sensitive files.
+
+### Directory Security Modes
+
+The system supports three security modes:
+
+| Mode | Description | Best For | Configuration |
+|------|-------------|----------|--------------|
+| **Strict** | Only whitelisted directories allowed | Maximum security | `auto_approve_directories_in_desktop_mode: false` |
+| **Approval** | Non-whitelisted directories require explicit approval | Interactive use | Default behavior for standard clients |
+| **Auto-approve** | Auto-approves directories for Claude Desktop | Convenience | `auto_approve_directories_in_desktop_mode: true` |
+
+### Whitelisted Directory Configuration
+
+```json
+"security": {
+  "whitelisted_directories": [
+    "/home",                  // System directories
+    "/tmp",
+    "~",                      // User's home
+    "~/Documents"             // Common user directories
+  ],
+  "auto_approve_directories_in_desktop_mode": false  // Set to true for convenience
+}
+```
+
+### Directory Approval Flow
+
+1. Command is requested in a directory
+2. System checks:
+   - Is the directory in the global whitelist? → **Allow**
+   - Has directory been approved in this session? → **Allow**
+   - Neither? → **Request approval**
+3. After approval, directory remains approved for the entire session
+
+### Path Format Support
+
+- Absolute paths: `/home/user/documents`
+- Home directory: `~` (expands to user's home)
+- User subdirectories: `~/Downloads`
+
+### Claude Desktop Integration
+
+The server maintains a persistent session for Claude Desktop, ensuring directory approvals persist between requests and preventing approval loops.
+
+## Command Customization
+
+The system uses command categorization to control access:
+
+| Category | Description | Example Commands | Requires Approval |
+|----------|-------------|------------------|-------------------|
+| Read | Safe operations | ls, cat, find | No |
+| Write | Data modification | mkdir, rm, touch | Yes |
+| System | System operations | ps, ping, ifconfig | Yes |
+| Blocked | Dangerous commands | sudo, bash, eval | Always denied |
+
+### Customization Methods
+
+```json
+// In config.json
+{
+  "commands": {
+    "read": ["ls", "cat", "grep", "awk", "jq"],
+    "write": ["mkdir", "touch", "rm"],
+    "system": ["ping", "ifconfig", "kubectl"],
+    "blocked": ["sudo", "bash", "eval"]
+  }
+}
+```
+
+**Environment Variable Method:**
+```bash
+# Add to existing lists, not replace (comma-separated)
+export CMD_LINE_MCP_COMMANDS_READ="awk,jq"
+export CMD_LINE_MCP_COMMANDS_BLOCKED="npm,pip"
+```
+
+The MCP server merges these additions with existing commands, letting you extend functionality without recreating complete command lists.
+
+### Command Chaining
+
+The server supports three command chaining methods:
+
+| Method | Symbol | Example | Config Setting |
+|--------|--------|---------|---------------|
+| Pipes | `\|` | `ls \| grep txt` | `allow_command_separators: true` |
+| Sequence | `;` | `mkdir dir; cd dir` | `allow_command_separators: true` |
+| Background | `&` | `find . -name "*.log" &` | `allow_command_separators: true` |
+
+All commands in a chain must be from the supported command list. Security checks apply to the entire chain.
+
+**Quick Configuration:**
+```json
+"security": {
+  "allow_command_separators": true  // Set to false to disable all chaining
+}
+```
+
+To disable specific separators, add them to the `dangerous_patterns` list.
+
+## License
+
+MIT

mseep_cmd_line_mcp-0.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cmd_line_mcp/__init__.py,sha256=UKEzBWEKLg9mcsuPrnA2q2Uvx02u-3lcg9v4NGKjeiU,81
+cmd_line_mcp/config.py,sha256=2S6peOVFlKLHvwIQ8I-hI17swf4fVWczO8PFxPJ82gA,15569
+cmd_line_mcp/security.py,sha256=DxxL_6SJX2y2FQXlIsxRk8yuPE0N-YrdfV2FxLBxYhk,15690
+cmd_line_mcp/server.py,sha256=G5nvGBHt3myESqF2xqlBKUpgRlI8kuPxUtAPHNG-SQo,41215
+cmd_line_mcp/session.py,sha256=mSb9LOisKymiXXEr7LDl4kEl0jVEDEiH6_0tMEE9_a8,4664
+mseep_cmd_line_mcp-0.5.0.data/data/default_config.json,sha256=AVBNID4Yijq3ZXwHYJL_t70oqnfj8g8TwwqV-5ODgSw,1804
+mseep_cmd_line_mcp-0.5.0.dist-info/licenses/LICENSE,sha256=aOVb-txipM-E8cp9jtNoqJE4l6yz3T05ZsZmQeYHaPI,1067
+mseep_cmd_line_mcp-0.5.0.dist-info/METADATA,sha256=kA1SfW1Lo0ChmxC6EM5RaAaEy_HQv2kctsD3NPtU-wQ,12306
+mseep_cmd_line_mcp-0.5.0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+mseep_cmd_line_mcp-0.5.0.dist-info/entry_points.txt,sha256=7ufnALgZOundGRNHoaR2OxIo7v_OVsHLV9qVjUyGVdI,58
+mseep_cmd_line_mcp-0.5.0.dist-info/top_level.txt,sha256=TNbegkhclSa2OO_Era8636j0ZvCn2DS0XaYutU5UM7s,13
+mseep_cmd_line_mcp-0.5.0.dist-info/RECORD,,

mseep_cmd_line_mcp-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mseep_cmd_line_mcp-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cmd-line-mcp = cmd_line_mcp.server:main

mseep_cmd_line_mcp-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Your Name]
+
+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.

mseep_cmd_line_mcp-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmd_line_mcp