mcp-shell-tools 4.0.0__tar.gz

mcp_shell_tools-4.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+*.egg
+.pytest_cache/
+.claude/

mcp_shell_tools-4.0.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mcp-shell-tools
+Version: 4.0.0
+Summary: 26 workstation tools for MCP — filesystem, editor, search, shell, system diagnostics
+Project-URL: Homepage, https://github.com/cuber-it/mcp_tools
+Project-URL: Repository, https://github.com/cuber-it/mcp_tools
+Author-email: Ulrich Berkmueller <ulrich@cuber-it.de>
+License-Expression: MIT
+Keywords: filesystem,mcp,shell,tools,workstation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: mcp-server-framework>=1.4.0
+Description-Content-Type: text/markdown
+
+# mcp-shell-tools
+
+26 workstation tools as a standalone MCP server or proxy plugin — filesystem, editor, search, shell, system diagnostics.
+
+Built on [mcp-server-framework](https://pypi.org/project/mcp-server-framework/).
+
+> **v4.0 Breaking Change:** Git, HTTP, pip, and systemd tools have been split into dedicated packages
+> (`mcp-git-tools`, `mcp-http-tools`, `mcp-python-tools`, `mcp-systemd-tools`).
+> If you depend on those tools, install the corresponding package or use `mcp-devtools` (planned metapackage).
+
+## Installation
+
+```bash
+pip install mcp-shell-tools
+```
+
+## Usage
+
+### Standalone
+
+```bash
+mcp-shell-tools                                  # stdio (default)
+mcp-shell-tools --transport http --port 12200    # HTTP with health endpoint
+```
+
+### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "shell": { "command": "mcp-shell-tools" }
+  }
+}
+```
+
+### As proxy plugin
+
+```yaml
+# proxy.yaml
+autoload:
+  - mcp_shell_tools.shell
+```
+
+## Tools
+
+### Filesystem (11 tools)
+
+| Tool | Description |
+|------|-------------|
+| `file_read` | Read a file with optional line range (1-based, with line numbers) |
+| `file_write` | Write content to a file, creates directories if needed |
+| `file_append` | Append content to a file |
+| `file_list` | List directory contents (recursive, hidden files) |
+| `file_delete` | Delete a file or directory (with recursive flag) |
+| `file_move` | Move or rename a file/directory |
+| `file_copy` | Copy a file or directory |
+| `file_info` | File metadata: size, permissions, owner, timestamps |
+| `head` | First N lines of a file |
+| `tail` | Last N lines of a file |
+| `tree` | Directory tree as ASCII art (configurable depth) |
+
+### Editor (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `str_replace` | Replace an exact, unique string in a file |
+| `diff_preview` | Preview a unified diff before applying changes |
+| `find_replace` | Find and replace across multiple files (dry-run by default) |
+
+### Search (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `grep` | Search file contents with regex (recursive, case-insensitive, glob filter) |
+| `glob_search` | Find files by glob pattern (e.g. `**/*.py`) |
+
+### Shell (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `exec` | Execute a shell command (bash) with configurable timeout |
+| `cd` | Change working directory (persists across calls) |
+| `cwd` | Show current working directory |
+| `which` | Find the full path of a command |
+| `env` | Show environment variables (all or specific) |
+| `set_env` | Set or unset environment variables for shell_exec |
+
+### System (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `ps` | List running processes (filterable by name) |
+| `sysinfo` | System overview: OS, CPU, memory, disk, uptime, load |
+| `port_check` | Check what's listening on a port, or list all open ports |
+| `disk_usage` | Disk usage of a directory and subdirectories |
+
+## Security
+
+The shell tools include a configurable security sandbox:
+
+```yaml
+# Restrict filesystem access to specific paths
+allowed_paths:
+  - /home/user/projects
+  - /tmp
+
+# Block dangerous commands
+blocked_commands:
+  - "sudo"
+  - "rm -rf /"
+  - "mkfs"
+```
+
+- **Path restriction**: When `allowed_paths` is set, all filesystem operations are confined to those directories. Symlinks pointing outside are rejected.
+- **Command blocking**: `shell_exec` checks commands against the blocklist before execution. Partial matches work — blocking `sudo` also blocks `sudo rm`.
+- **No restriction by default**: Without config, all paths and commands are allowed. This is intentional for development workstations. Lock it down for shared or production environments.
+
+## Configuration
+
+```yaml
+server_name: "Shell Tools"
+transport: stdio              # stdio | http
+working_dir: /home/user       # initial cwd (optional)
+timeout: 120                  # default shell_exec timeout in seconds
+
+# Security (optional)
+allowed_paths: ["/home/user/projects"]
+blocked_commands: ["sudo", "rm -rf /"]
+
+# HTTP mode
+port: 12200
+health_port: 12201
+```
+
+Environment variables override YAML config with `MCP_` prefix:
+
+```bash
+export MCP_TRANSPORT=http
+export MCP_PORT=12200
+```
+
+## What moved where (v3 → v4)
+
+| v3 tool | v4 package | PyPI |
+|---------|------------|------|
+| `git`, `git_status`, `git_log`, `git_diff` | mcp-git-tools | `pip install mcp-git-tools` |
+| `http_request`, `json_query` | mcp-http-tools | `pip install mcp-http-tools` |
+| `pip_list`, `pip_install` | mcp-python-tools | `pip install mcp-python-tools` |
+| `systemctl` | mcp-systemd-tools | `pip install mcp-systemd-tools` |
+
+This split follows the principle: when package creation costs nothing, optimal package size gets smaller. Each package does one thing well, and you only install what you need.
+
+## Part of mcp_tools
+
+This package is part of the [mcp_tools](https://github.com/cuber-it/mcp_tools) ecosystem — modular MCP tool packages that work standalone and as plugins.
+
+## License
+
+MIT

mcp_shell_tools-4.0.0/README.md

@@ -0,0 +1,159 @@
+# mcp-shell-tools
+
+26 workstation tools as a standalone MCP server or proxy plugin — filesystem, editor, search, shell, system diagnostics.
+
+Built on [mcp-server-framework](https://pypi.org/project/mcp-server-framework/).
+
+> **v4.0 Breaking Change:** Git, HTTP, pip, and systemd tools have been split into dedicated packages
+> (`mcp-git-tools`, `mcp-http-tools`, `mcp-python-tools`, `mcp-systemd-tools`).
+> If you depend on those tools, install the corresponding package or use `mcp-devtools` (planned metapackage).
+
+## Installation
+
+```bash
+pip install mcp-shell-tools
+```
+
+## Usage
+
+### Standalone
+
+```bash
+mcp-shell-tools                                  # stdio (default)
+mcp-shell-tools --transport http --port 12200    # HTTP with health endpoint
+```
+
+### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "shell": { "command": "mcp-shell-tools" }
+  }
+}
+```
+
+### As proxy plugin
+
+```yaml
+# proxy.yaml
+autoload:
+  - mcp_shell_tools.shell
+```
+
+## Tools
+
+### Filesystem (11 tools)
+
+| Tool | Description |
+|------|-------------|
+| `file_read` | Read a file with optional line range (1-based, with line numbers) |
+| `file_write` | Write content to a file, creates directories if needed |
+| `file_append` | Append content to a file |
+| `file_list` | List directory contents (recursive, hidden files) |
+| `file_delete` | Delete a file or directory (with recursive flag) |
+| `file_move` | Move or rename a file/directory |
+| `file_copy` | Copy a file or directory |
+| `file_info` | File metadata: size, permissions, owner, timestamps |
+| `head` | First N lines of a file |
+| `tail` | Last N lines of a file |
+| `tree` | Directory tree as ASCII art (configurable depth) |
+
+### Editor (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `str_replace` | Replace an exact, unique string in a file |
+| `diff_preview` | Preview a unified diff before applying changes |
+| `find_replace` | Find and replace across multiple files (dry-run by default) |
+
+### Search (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `grep` | Search file contents with regex (recursive, case-insensitive, glob filter) |
+| `glob_search` | Find files by glob pattern (e.g. `**/*.py`) |
+
+### Shell (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `exec` | Execute a shell command (bash) with configurable timeout |
+| `cd` | Change working directory (persists across calls) |
+| `cwd` | Show current working directory |
+| `which` | Find the full path of a command |
+| `env` | Show environment variables (all or specific) |
+| `set_env` | Set or unset environment variables for shell_exec |
+
+### System (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `ps` | List running processes (filterable by name) |
+| `sysinfo` | System overview: OS, CPU, memory, disk, uptime, load |
+| `port_check` | Check what's listening on a port, or list all open ports |
+| `disk_usage` | Disk usage of a directory and subdirectories |
+
+## Security
+
+The shell tools include a configurable security sandbox:
+
+```yaml
+# Restrict filesystem access to specific paths
+allowed_paths:
+  - /home/user/projects
+  - /tmp
+
+# Block dangerous commands
+blocked_commands:
+  - "sudo"
+  - "rm -rf /"
+  - "mkfs"
+```
+
+- **Path restriction**: When `allowed_paths` is set, all filesystem operations are confined to those directories. Symlinks pointing outside are rejected.
+- **Command blocking**: `shell_exec` checks commands against the blocklist before execution. Partial matches work — blocking `sudo` also blocks `sudo rm`.
+- **No restriction by default**: Without config, all paths and commands are allowed. This is intentional for development workstations. Lock it down for shared or production environments.
+
+## Configuration
+
+```yaml
+server_name: "Shell Tools"
+transport: stdio              # stdio | http
+working_dir: /home/user       # initial cwd (optional)
+timeout: 120                  # default shell_exec timeout in seconds
+
+# Security (optional)
+allowed_paths: ["/home/user/projects"]
+blocked_commands: ["sudo", "rm -rf /"]
+
+# HTTP mode
+port: 12200
+health_port: 12201
+```
+
+Environment variables override YAML config with `MCP_` prefix:
+
+```bash
+export MCP_TRANSPORT=http
+export MCP_PORT=12200
+```
+
+## What moved where (v3 → v4)
+
+| v3 tool | v4 package | PyPI |
+|---------|------------|------|
+| `git`, `git_status`, `git_log`, `git_diff` | mcp-git-tools | `pip install mcp-git-tools` |
+| `http_request`, `json_query` | mcp-http-tools | `pip install mcp-http-tools` |
+| `pip_list`, `pip_install` | mcp-python-tools | `pip install mcp-python-tools` |
+| `systemctl` | mcp-systemd-tools | `pip install mcp-systemd-tools` |
+
+This split follows the principle: when package creation costs nothing, optimal package size gets smaller. Each package does one thing well, and you only install what you need.
+
+## Part of mcp_tools
+
+This package is part of the [mcp_tools](https://github.com/cuber-it/mcp_tools) ecosystem — modular MCP tool packages that work standalone and as plugins.
+
+## License
+
+MIT

mcp_shell_tools-4.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "mcp-shell-tools"
+version = "4.0.0"
+description = "26 workstation tools for MCP — filesystem, editor, search, shell, system diagnostics"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Ulrich Berkmueller", email = "ulrich@cuber-it.de" },
+]
+keywords = ["mcp", "shell", "tools", "filesystem", "workstation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "mcp-server-framework>=1.4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cuber-it/mcp_tools"
+Repository = "https://github.com/cuber-it/mcp_tools"
+
+[project.scripts]
+mcp-shell-tools = "mcp_shell_tools:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_shell_tools"]

mcp_shell_tools-4.0.0/src/mcp_shell_tools/__init__.py

@@ -0,0 +1,16 @@
+"""mcp-shell-tools — 33 workstation tools as a standalone MCP server.
+
+Built on mcp-server-framework. Can also be used as a plugin via register().
+"""
+
+__version__ = "3.0.0"
+
+
+def main():
+    from mcp_server_framework import load_config, create_server, run_server
+    from mcp_shell_tools.shell import register
+
+    config = load_config()
+    mcp = create_server(config)
+    register(mcp, config)
+    run_server(mcp, config)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/__init__.py

@@ -0,0 +1,203 @@
+"""Shell tools — MCP plugin for workstation access.
+
+Provides filesystem, editor, search, shell execution, and system diagnostics.
+Git, HTTP, pip, and systemd have been split into separate packages (v4.0).
+
+Config keys:
+    working_dir: Initial working directory (optional, defaults to cwd)
+    timeout: Default shell timeout in seconds (optional, default 120)
+    allowed_paths: Restrict filesystem access (optional)
+    blocked_commands: Block dangerous commands (optional)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+
+from . import tools
+
+
+def register(mcp, config: dict) -> None:
+    """Register shell tools as MCP tools."""
+    if config.get("working_dir"):
+        from pathlib import Path
+        tools.set_working_dir(Path(config["working_dir"]))
+
+    tools.set_security_boundaries(
+        allowed_paths=config.get("allowed_paths"),
+        blocked_commands=config.get("blocked_commands"),
+    )
+
+    default_timeout = config.get("timeout", 120)
+
+    # Auto-record all tool calls in history
+    _original_tool = mcp.tool
+
+    def _recording_tool(**kwargs):
+        def decorator(fn):
+            name = fn.__name__.replace("shell_", "")
+
+            @functools.wraps(fn)
+            def wrapper(*args, **kw):
+                result = fn(*args, **kw)
+                args_str = ", ".join(
+                    [repr(a) for a in args] + [f"{k}={v!r}" for k, v in kw.items()]
+                )
+                tools._record(name, args_str, str(result))
+                return result
+
+            return _original_tool(**kwargs)(wrapper)
+        return decorator
+
+    tool = _recording_tool
+
+    # --- Filesystem ---
+
+    @tool()
+    def shell_file_read(path: str, start_line: int = 0, end_line: int = 0) -> str:
+        """Read a file with optional line range (1-based). Returns content with line numbers."""
+        return tools.file_read(path, start_line or None, end_line or None)
+
+    @tool()
+    def shell_file_write(path: str, content: str) -> str:
+        """Write content to a file. Creates directories if needed."""
+        return tools.file_write(path, content)
+
+    @tool()
+    def shell_file_append(path: str, content: str) -> str:
+        """Append content to a file. Creates file and directories if needed."""
+        return tools.file_append(path, content)
+
+    @tool()
+    def shell_file_list(path: str = ".", recursive: bool = False, show_hidden: bool = False) -> str:
+        """List files and directories."""
+        return tools.file_list(path, recursive, show_hidden)
+
+    @tool()
+    def shell_file_delete(path: str, recursive: bool = False) -> str:
+        """Delete a file or directory. Use recursive=True for directories."""
+        return tools.file_delete(path, recursive)
+
+    @tool()
+    def shell_file_move(source: str, destination: str) -> str:
+        """Move or rename a file/directory."""
+        return tools.file_move(source, destination)
+
+    @tool()
+    def shell_file_copy(source: str, destination: str) -> str:
+        """Copy a file or directory."""
+        return tools.file_copy(source, destination)
+
+    @tool()
+    def shell_file_info(path: str) -> str:
+        """Show file metadata: size, permissions, owner, timestamps."""
+        return tools.file_info(path)
+
+    @tool()
+    def shell_head(path: str, lines: int = 20) -> str:
+        """Show first N lines of a file (default 20)."""
+        return tools.head(path, lines)
+
+    @tool()
+    def shell_tail(path: str, lines: int = 20) -> str:
+        """Show last N lines of a file (default 20)."""
+        return tools.tail(path, lines)
+
+    @tool()
+    def shell_tree(path: str = ".", max_depth: int = 3, show_hidden: bool = False) -> str:
+        """Show directory tree as ASCII art."""
+        return tools.tree(path, max_depth, show_hidden)
+
+    # --- Editor ---
+
+    @tool()
+    def shell_str_replace(path: str, old_string: str, new_string: str) -> str:
+        """Replace an exact, unique string in a file."""
+        return tools.str_replace(path, old_string, new_string)
+
+    @tool()
+    def shell_diff_preview(path: str, old_string: str, new_string: str = "", context_lines: int = 3) -> str:
+        """Show unified diff preview before applying str_replace."""
+        return tools.diff_preview(path, old_string, new_string, context_lines)
+
+    @tool()
+    def shell_find_replace(pattern: str, replacement: str, path: str = ".", file_pattern: str = "*", dry_run: bool = True) -> str:
+        """Find and replace text across files. Default: dry_run preview. Set dry_run=False to apply."""
+        return tools.find_replace(pattern, replacement, path, file_pattern, dry_run)
+
+    # --- Search ---
+
+    @tool()
+    def shell_grep(
+        pattern: str, path: str = ".", recursive: bool = True,
+        ignore_case: bool = False, file_pattern: str = "*", max_results: int = 50,
+    ) -> str:
+        """Search for a pattern (text or regex) in files."""
+        return tools.grep(pattern, path, recursive, ignore_case, file_pattern, max_results)
+
+    @tool()
+    def shell_glob(pattern: str, path: str = ".") -> str:
+        """Search files by glob pattern (e.g. '**/*.py')."""
+        return tools.glob_search(pattern, path)
+
+    # --- Shell ---
+
+    @tool()
+    def shell_exec(command: str, timeout: int = default_timeout, working_dir: str = "") -> str:
+        """Execute a shell command (bash). Returns stdout, stderr, exit code."""
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                future = pool.submit(asyncio.run, tools.shell_exec(command, timeout, working_dir or None))
+                return future.result()
+        return asyncio.run(tools.shell_exec(command, timeout, working_dir or None))
+
+    @tool()
+    def shell_cd(path: str) -> str:
+        """Change working directory."""
+        return tools.cd(path)
+
+    @tool()
+    def shell_cwd() -> str:
+        """Show current working directory."""
+        return tools.cwd()
+
+    @tool()
+    def shell_which(command: str) -> str:
+        """Find the full path of a command (like 'which' in shell)."""
+        return tools.which(command)
+
+    @tool()
+    def shell_env(name: str = "") -> str:
+        """Show environment variables. Without name: show custom vars only."""
+        return tools.env(name)
+
+    @tool()
+    def shell_set_env(name: str, value: str = "") -> str:
+        """Set or delete an environment variable for shell_exec calls."""
+        return tools.set_env(name, value)
+
+    # --- System Diagnostics ---
+
+    @tool()
+    def shell_ps(filter: str = "") -> str:
+        """Show running processes. Optional filter by name or PID."""
+        return tools.ps(filter)
+
+    @tool()
+    def shell_sysinfo() -> str:
+        """System overview: OS, CPU, memory, disk, uptime, load."""
+        return tools.sysinfo()
+
+    @tool()
+    def shell_port_check(port: int = 0, host: str = "127.0.0.1") -> str:
+        """Check what's listening on a port, or list all listening ports."""
+        return tools.port_check(port, host)
+
+    @tool()
+    def shell_disk_usage(path: str = ".") -> str:
+        """Show disk usage of directory and its subdirectories."""
+        return tools.disk_usage(path)
+

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/_history.py

@@ -0,0 +1,53 @@
+"""Tool call history tracking."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+
+# ── History ──────────────────────────────────────────────────────────
+
+@dataclass
+class HistoryEntry:
+    seq: int
+    timestamp: str
+    tool: str
+    args: str
+    result: str
+
+
+_history: list[HistoryEntry] = []
+_session_id: str = uuid.uuid4().hex[:8]
+_seq: int = 0
+
+
+def record(tool: str, args: str, result: str) -> None:
+    global _seq
+    _seq += 1
+    _history.append(HistoryEntry(
+        seq=_seq,
+        timestamp=datetime.now().strftime("%H:%M:%S"),
+        tool=tool,
+        args=args[:500],
+        result=result[:5000],
+    ))
+    if len(_history) > 1000:
+        _history.pop(0)
+
+
+def history(count: int = 20, filter: str = "", full: bool = False) -> str:
+    """Show tool call history."""
+    if not _history:
+        return "No history yet."
+    entries = _history
+    if filter:
+        f = filter.lower()
+        entries = [e for e in entries if f in e.tool or f in e.args.lower()]
+    selected = entries[-count:]
+    lines = [f"Session {_session_id} ({_seq} calls)\n"]
+    for e in selected:
+        lines.append(f"#{e.seq} [{e.timestamp}] {e.tool}({e.args})")
+        preview = e.result if full else e.result[:200].replace("\n", " ")
+        lines.append(f"  -> {preview}")
+    return "\n".join(lines)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/_state.py

@@ -0,0 +1,96 @@
+"""Shared state, security checks, and helpers."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+# ── Mutable state ────────────────────────────────────────────────────
+
+_working_dir: Path = Path.cwd()
+_allowed_paths: list[Path] = []
+_blocked_commands: list[str] = []
+_custom_env: dict[str, str] = {}
+
+
+def set_working_dir(path: Path) -> None:
+    global _working_dir
+    _working_dir = path.resolve()
+
+
+def get_working_dir() -> Path:
+    return _working_dir
+
+
+def get_custom_env() -> dict[str, str]:
+    return _custom_env
+
+
+def set_security_boundaries(
+    allowed_paths: list[str] | None = None,
+    blocked_commands: list[str] | None = None,
+) -> None:
+    """Set path and command restrictions."""
+    global _allowed_paths, _blocked_commands
+    _allowed_paths = [Path(p).resolve() for p in (allowed_paths or [])]
+    _blocked_commands = [c.strip() for c in (blocked_commands or [])]
+
+
+# ── Checks ───────────────────────────────────────────────────────────
+
+def resolve_path(path: str) -> Path:
+    p = Path(path)
+    return p.resolve() if p.is_absolute() else (_working_dir / p).resolve()
+
+
+def check_path(resolved: Path) -> str | None:
+    if not _allowed_paths:
+        return None
+    for allowed in _allowed_paths:
+        try:
+            resolved.relative_to(allowed)
+            return None
+        except ValueError:
+            continue
+    return f"Error: path outside allowed directories: {resolved}"
+
+
+def check_command(command: str) -> str | None:
+    if not _blocked_commands:
+        return None
+    cmd = command.strip()
+    for blocked in _blocked_commands:
+        if cmd.startswith(blocked) or f"| {blocked}" in cmd or f"; {blocked}" in cmd:
+            return f"Error: '{blocked}' is blocked"
+    return None
+
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+def read_text(resolved: Path) -> str | None:
+    """Read file as UTF-8, return None on binary."""
+    try:
+        return resolved.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
+def run(cmd: list[str], timeout: int = 10) -> str:
+    """Run a subprocess, return stdout+stderr."""
+    out = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    result = out.stdout.strip()
+    if out.stderr.strip():
+        result += ("\n[STDERR] " if out.returncode else "\n") + out.stderr.strip()
+    if out.returncode and not result:
+        result = f"[Exit {out.returncode}]"
+    return result or "(no output)"
+
+
+def format_size(size: int) -> str:
+    if size < 1024:
+        return f"{size} bytes"
+    if size < 1048576:
+        return f"{size / 1024:.1f} KB"
+    return f"{size / 1048576:.1f} MB"

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/editor.py

@@ -0,0 +1,86 @@
+"""Text editing: str_replace, diff preview, find & replace."""
+
+from __future__ import annotations
+
+import difflib
+from pathlib import Path
+
+from ._state import check_path, read_text, resolve_path
+
+
+def str_replace(path: str, old_string: str, new_string: str) -> str:
+    """Replace exact, unique string in a file."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_file():
+        return f"Error: not a file: {resolved}"
+    content = resolved.read_text(encoding="utf-8")
+    count = content.count(old_string)
+    if count == 0:
+        return f"Error: string not found in {resolved}"
+    if count > 1:
+        return f"Error: string appears {count} times, must be unique"
+    resolved.write_text(content.replace(old_string, new_string, 1), encoding="utf-8")
+    return f"Replaced in {resolved}"
+
+
+def diff_preview(path: str, old_string: str, new_string: str = "", context_lines: int = 3) -> str:
+    """Unified diff preview before applying str_replace."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_file():
+        return f"Error: not a file: {resolved}"
+    content = resolved.read_text(encoding="utf-8")
+    count = content.count(old_string)
+    if count == 0:
+        return f"Error: string not found in {resolved}"
+    if count > 1:
+        return f"Warning: appears {count} times, str_replace would fail"
+    new_content = content.replace(old_string, new_string, 1)
+    diff = difflib.unified_diff(
+        content.splitlines(keepends=True),
+        new_content.splitlines(keepends=True),
+        fromfile=f"a/{resolved.name}",
+        tofile=f"b/{resolved.name}",
+        n=context_lines,
+    )
+    return "".join(diff) or "No changes"
+
+
+def find_replace(
+    pattern: str, replacement: str, path: str = ".",
+    file_pattern: str = "*", dry_run: bool = True,
+) -> str:
+    """Find and replace across files. dry_run=True for preview."""
+    resolved = resolve_path(path)
+    if not resolved.exists():
+        return f"Error: not found: {resolved}"
+    if resolved.is_file():
+        files = [resolved]
+    else:
+        files = sorted(
+            f for f in resolved.rglob(file_pattern)
+            if f.is_file() and not any(p.startswith(".") for p in f.parts)
+        )
+    results = []
+    total = 0
+    for f in files:
+        if check_path(f):
+            continue
+        content = read_text(f)
+        if not content:
+            continue
+        count = content.count(pattern)
+        if count == 0:
+            continue
+        rel = f.relative_to(resolved) if resolved.is_dir() else f.name
+        if not dry_run:
+            f.write_text(content.replace(pattern, replacement), encoding="utf-8")
+        results.append(f"  {rel}: {count}x")
+        total += count
+    if not results:
+        return f"No matches for '{pattern}'"
+    mode = "PREVIEW" if dry_run else "APPLIED"
+    return f"[{mode}] {total} in {len(results)} file(s)\n" + "\n".join(results)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/filesystem.py

@@ -0,0 +1,229 @@
+"""Filesystem operations: read, write, copy, move, delete, list, tree."""
+
+from __future__ import annotations
+
+import shutil
+import time
+from pathlib import Path
+
+from ._state import check_path, format_size, read_text, resolve_path
+
+
+def file_read(path: str, start_line: int | None = None, end_line: int | None = None) -> str:
+    """Read file with optional line range (1-based). Returns numbered lines."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.exists():
+        return f"Error: not found: {resolved}"
+    if not resolved.is_file():
+        return f"Error: not a file: {resolved}"
+    content = read_text(resolved)
+    if content is None:
+        return f"Binary file: {resolved} ({resolved.stat().st_size:,} bytes)"
+    lines = content.splitlines()
+    total = len(lines)
+    start = (start_line or 1) - 1
+    end = end_line or min(total, 500)
+    numbered = [f"{i + start + 1:>5} | {ln}" for i, ln in enumerate(lines[start:end])]
+    result = "\n".join(numbered)
+    if not start_line and not end_line and total > 500:
+        result += f"\n[{total} lines total, showing first 500]"
+    return result
+
+
+def file_write(path: str, content: str) -> str:
+    """Write content to file. Creates directories if needed."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    resolved.write_text(content, encoding="utf-8")
+    return f"Written: {resolved} ({len(content.splitlines())} lines)"
+
+
+def file_append(path: str, content: str) -> str:
+    """Append content to file. Creates file if needed."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    with open(resolved, "a", encoding="utf-8") as f:
+        f.write(content)
+    return f"Appended {len(content.splitlines())} lines to: {resolved}"
+
+
+def file_list(path: str = ".", recursive: bool = False, show_hidden: bool = False) -> str:
+    """List files and directories."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_dir():
+        return f"Error: not a directory: {resolved}"
+    lines = [str(resolved)]
+    items = sorted(resolved.rglob("*") if recursive else resolved.iterdir())
+    for item in items[:200]:
+        if not show_hidden and item.name.startswith("."):
+            continue
+        rel = item.relative_to(resolved)
+        suffix = "/" if item.is_dir() else f"  ({item.stat().st_size:,} bytes)"
+        lines.append(f"  {rel}{suffix}")
+    if len(items) > 200:
+        lines.append(f"[... {len(items) - 200} more]")
+    return "\n".join(lines)
+
+
+def file_delete(path: str, recursive: bool = False) -> str:
+    """Delete file or directory."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.exists():
+        return f"Error: not found: {resolved}"
+    if resolved.is_dir():
+        if not recursive:
+            return "Error: is a directory, use recursive=True"
+        shutil.rmtree(resolved)
+    else:
+        resolved.unlink()
+    return f"Deleted: {resolved}"
+
+
+def file_move(source: str, destination: str) -> str:
+    """Move or rename file/directory."""
+    src, dst = resolve_path(source), resolve_path(destination)
+    if err := check_path(src):
+        return err
+    if err := check_path(dst):
+        return err
+    if not src.exists():
+        return f"Error: not found: {src}"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(src), str(dst))
+    return f"Moved: {src} -> {dst}"
+
+
+def file_copy(source: str, destination: str) -> str:
+    """Copy file or directory."""
+    src, dst = resolve_path(source), resolve_path(destination)
+    if err := check_path(src):
+        return err
+    if err := check_path(dst):
+        return err
+    if not src.exists():
+        return f"Error: not found: {src}"
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if src.is_dir():
+        shutil.copytree(str(src), str(dst))
+    else:
+        shutil.copy2(str(src), str(dst))
+    return f"Copied: {src} -> {dst}"
+
+
+def file_info(path: str) -> str:
+    """File metadata: size, permissions, owner, timestamps."""
+    import grp
+    import pwd
+    import stat as stat_mod
+
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.exists():
+        return f"Error: not found: {resolved}"
+    st = resolved.stat()
+    try:
+        owner = pwd.getpwuid(st.st_uid).pw_name
+    except KeyError:
+        owner = str(st.st_uid)
+    try:
+        group = grp.getgrgid(st.st_gid).gr_name
+    except KeyError:
+        group = str(st.st_gid)
+    ftype = "directory" if resolved.is_dir() else "symlink" if resolved.is_symlink() else "file"
+    lines = [
+        f"Path: {resolved}",
+        f"Type: {ftype}",
+        f"Size: {format_size(st.st_size)}",
+        f"Permissions: {stat_mod.filemode(st.st_mode)}",
+        f"Owner: {owner}:{group}",
+        f"Modified: {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(st.st_mtime))}",
+    ]
+    if resolved.is_symlink():
+        lines.append(f"Target: {resolved.resolve()}")
+    return "\n".join(lines)
+
+
+def head(path: str, lines: int = 20) -> str:
+    """First N lines of a file."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_file():
+        return f"Error: not a file: {resolved}"
+    content = read_text(resolved)
+    if content is None:
+        return f"Binary file: {resolved}"
+    all_lines = content.splitlines()
+    numbered = [f"{i + 1:>5} | {ln}" for i, ln in enumerate(all_lines[:lines])]
+    result = "\n".join(numbered)
+    if len(all_lines) > lines:
+        result += f"\n[{len(all_lines)} lines total]"
+    return result
+
+
+def tail(path: str, lines: int = 20) -> str:
+    """Last N lines of a file."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_file():
+        return f"Error: not a file: {resolved}"
+    content = read_text(resolved)
+    if content is None:
+        return f"Binary file: {resolved}"
+    all_lines = content.splitlines()
+    total = len(all_lines)
+    start = max(0, total - lines)
+    numbered = [f"{start + i + 1:>5} | {ln}" for i, ln in enumerate(all_lines[start:])]
+    result = "\n".join(numbered)
+    if total > lines:
+        result = f"[{total} lines total]\n" + result
+    return result
+
+
+def tree(path: str = ".", max_depth: int = 3, show_hidden: bool = False) -> str:
+    """Directory tree as ASCII art."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_dir():
+        return f"Error: not a directory: {resolved}"
+
+    lines = [str(resolved)]
+
+    def walk(dir_path: Path, prefix: str, depth: int) -> None:
+        if depth > max_depth:
+            return
+        try:
+            entries = sorted(dir_path.iterdir(), key=lambda x: (not x.is_dir(), x.name.lower()))
+        except PermissionError:
+            lines.append(f"{prefix}[permission denied]")
+            return
+        if not show_hidden:
+            entries = [e for e in entries if not e.name.startswith(".")]
+        for i, entry in enumerate(entries):
+            last = i == len(entries) - 1
+            connector = "└── " if last else "├── "
+            if entry.is_dir():
+                lines.append(f"{prefix}{connector}{entry.name}/")
+                walk(entry, prefix + ("    " if last else "│   "), depth + 1)
+            else:
+                sz = entry.stat().st_size
+                s = f"{sz}B" if sz < 1024 else f"{sz // 1024}K" if sz < 1048576 else f"{sz // 1048576}M"
+                lines.append(f"{prefix}{connector}{entry.name} ({s})")
+
+    walk(resolved, "", 1)
+    if len(lines) > 200:
+        lines = lines[:200] + ["[... truncated]"]
+    return "\n".join(lines)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/search.py

@@ -0,0 +1,55 @@
+"""Search: grep and glob."""
+
+from __future__ import annotations
+
+import re
+
+from ._state import check_path, read_text, resolve_path
+
+
+def grep(
+    pattern: str, path: str = ".", recursive: bool = True,
+    ignore_case: bool = False, file_pattern: str = "*", max_results: int = 50,
+) -> str:
+    """Search for pattern in files."""
+    resolved = resolve_path(path)
+    if not resolved.exists():
+        return f"Error: not found: {resolved}"
+    flags = re.IGNORECASE if ignore_case else 0
+    try:
+        regex = re.compile(pattern, flags)
+    except re.error as e:
+        return f"Error: invalid regex: {e}"
+    if resolved.is_file():
+        files = [resolved]
+    else:
+        files = sorted(resolved.rglob(file_pattern) if recursive else resolved.glob(file_pattern))
+        files = [f for f in files if f.is_file() and not any(p.startswith(".") for p in f.parts)]
+    results = []
+    for f in files:
+        content = read_text(f)
+        if not content:
+            continue
+        for i, line in enumerate(content.splitlines(), 1):
+            if regex.search(line):
+                rel = f.relative_to(resolved) if resolved.is_dir() else f.name
+                results.append(f"{rel}:{i}: {line}")
+                if len(results) >= max_results:
+                    break
+        if len(results) >= max_results:
+            break
+    if not results:
+        return f"No matches for '{pattern}'"
+    return f"{len(results)} matches for '{pattern}':\n" + "\n".join(results)
+
+
+def glob_search(pattern: str, path: str = ".") -> str:
+    """Find files by glob pattern."""
+    resolved = resolve_path(path)
+    if not resolved.is_dir():
+        return f"Error: not a directory: {resolved}"
+    matches = sorted(resolved.glob(pattern))[:100]
+    if not matches:
+        return f"No matches for '{pattern}'"
+    lines = [str(m.relative_to(resolved)) for m in matches]
+    return f"{len(matches)} matches:\n" + "\n".join(lines)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/shell.py

@@ -0,0 +1,92 @@
+"""Shell execution: exec, cd, cwd, which, env."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import signal
+
+from ._state import check_command, check_path, get_custom_env, get_working_dir, resolve_path, set_working_dir
+
+
+async def shell_exec(command: str, timeout: int = 120, working_dir: str | None = None) -> str:
+    """Execute a shell command. Returns stdout, stderr, exit code."""
+    if err := check_command(command):
+        return err
+    cwd = resolve_path(working_dir) if working_dir else get_working_dir()
+    if err := check_path(cwd):
+        return err
+    if not cwd.is_dir():
+        return f"Error: directory not found: {cwd}"
+    try:
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=cwd,
+            start_new_session=True,
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+        except asyncio.TimeoutError:
+            os.killpg(proc.pid, signal.SIGTERM)
+            await proc.wait()
+            return f"$ {command}\n\nTimeout after {timeout}s"
+        parts = [f"$ {command}"]
+        if stdout:
+            parts.append(stdout.decode("utf-8", errors="replace"))
+        if stderr:
+            parts.append(f"[STDERR]\n{stderr.decode('utf-8', errors='replace')}")
+        if proc.returncode:
+            parts.append(f"[Exit {proc.returncode}]")
+        if not stdout and not stderr:
+            parts.append("(no output)")
+        return "\n".join(parts)
+    except Exception as e:
+        return f"$ {command}\n\nError: {e}"
+
+
+def cd(path: str) -> str:
+    """Change working directory."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_dir():
+        return f"Error: not a directory: {resolved}"
+    set_working_dir(resolved)
+    return str(resolved)
+
+
+def cwd() -> str:
+    """Current working directory."""
+    return str(get_working_dir())
+
+
+def which(command: str) -> str:
+    """Full path of a command."""
+    return shutil.which(command) or f"'{command}' not found in PATH"
+
+
+def env(name: str = "") -> str:
+    """Show environment variables. Without name: custom vars only."""
+    custom = get_custom_env()
+    if name:
+        if name in custom:
+            return f"{name}={custom[name]} (custom)"
+        val = os.environ.get(name)
+        return f"{name}={val}" if val else f"'{name}' not set"
+    if not custom:
+        return "No custom variables set."
+    return "\n".join(f"  {k}={v}" for k, v in sorted(custom.items()))
+
+
+def set_env(name: str, value: str = "") -> str:
+    """Set or delete (value='') an environment variable."""
+    custom = get_custom_env()
+    if not value:
+        removed = custom.pop(name, None)
+        return f"Deleted '{name}'" if removed else f"'{name}' was not set"
+    custom[name] = value
+    os.environ[name] = value
+    return f"{name}={value}"

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/system.py

@@ -0,0 +1,82 @@
+"""System diagnostics: ps, sysinfo, ports, disk usage."""
+
+from __future__ import annotations
+
+import os
+import platform
+
+from ._state import check_path, resolve_path, run
+
+
+def ps(filter: str = "") -> str:
+    """Running processes. Optional filter by name."""
+    lines = run(["ps", "aux", "--sort=-pcpu"], timeout=5).splitlines()
+    if filter:
+        header = lines[0] if lines else ""
+        matched = [ln for ln in lines[1:] if filter.lower() in ln.lower()][:50]
+        return (header + "\n" + "\n".join(matched)) if matched else f"No processes matching '{filter}'"
+    return "\n".join(lines[:31])
+
+
+def sysinfo() -> str:
+    """System overview: OS, CPU, memory, disk, uptime, load."""
+    parts = [
+        f"Host: {platform.node()}",
+        f"OS: {platform.system()} {platform.release()}",
+    ]
+    try:
+        with open("/proc/cpuinfo") as f:
+            cpus = [ln for ln in f if ln.startswith("model name")]
+        if cpus:
+            parts.append(f"CPU: {cpus[0].split(':')[1].strip()} ({len(cpus)} cores)")
+    except OSError:
+        pass
+    try:
+        with open("/proc/meminfo") as f:
+            mem = {}
+            for ln in f:
+                k, v = ln.split(":")
+                mem[k.strip()] = int(v.strip().split()[0])
+        parts.append(f"Memory: {mem.get('MemAvailable', 0) // 1024}M free / {mem.get('MemTotal', 0) // 1024}M")
+    except OSError:
+        pass
+    try:
+        st = os.statvfs("/")
+        parts.append(f"Disk: {st.f_bavail * st.f_frsize / 1024**3:.1f}G free / {st.f_blocks * st.f_frsize / 1024**3:.1f}G")
+    except OSError:
+        pass
+    try:
+        with open("/proc/uptime") as f:
+            secs = int(float(f.read().split()[0]))
+        d, r = divmod(secs, 86400)
+        h, r = divmod(r, 3600)
+        parts.append(f"Uptime: {d}d {h}h {r // 60}m")
+    except OSError:
+        pass
+    try:
+        l1, l5, l15 = os.getloadavg()
+        parts.append(f"Load: {l1:.2f} {l5:.2f} {l15:.2f}")
+    except OSError:
+        pass
+    return "\n".join(parts)
+
+
+def port_check(port: int = 0) -> str:
+    """What's listening on a port (or all ports if port=0)."""
+    cmd = ["ss", "-tlnp"]
+    if port:
+        cmd.append(f"sport = :{port}")
+    result = run(cmd, timeout=5)
+    if port and len(result.splitlines()) <= 1:
+        return f"Nothing on port {port}"
+    return result
+
+
+def disk_usage(path: str = ".") -> str:
+    """Disk usage of directory."""
+    resolved = resolve_path(path)
+    if err := check_path(resolved):
+        return err
+    if not resolved.is_dir():
+        return f"Error: not a directory: {resolved}"
+    return run(["du", "-sh", "--max-depth=1", str(resolved)], timeout=30)

mcp_shell_tools-4.0.0/src/mcp_shell_tools/shell/tools.py

@@ -0,0 +1,55 @@
+"""Shell tools — re-export facade.
+
+Imports all tool functions from submodules so that
+``from . import tools`` in __init__.py keeps working.
+
+v4.0: Git, HTTP, systemd, pip removed — see mcp-git-tools, mcp-http-tools,
+mcp-python-tools, mcp-systemd-tools.
+"""
+
+from ._history import record as _record
+from ._state import (
+    check_command as _check_command,
+    check_command as _check_command_allowed,
+    check_path as _check_path,
+    format_size as _format_size,
+    read_text as _read_text,
+    resolve_path,
+    run as _run,
+    set_security_boundaries,
+    set_working_dir,
+)
+from .editor import diff_preview, find_replace, str_replace
+from .filesystem import (
+    file_append,
+    file_copy,
+    file_delete,
+    file_info,
+    file_list,
+    file_move,
+    file_read,
+    file_write,
+    head,
+    tail,
+    tree,
+)
+from .search import glob_search, grep
+from .shell import cd, cwd, env, set_env, shell_exec, which
+from .system import disk_usage, port_check, ps, sysinfo
+
+__all__ = [
+    # state
+    "set_working_dir", "set_security_boundaries", "resolve_path",
+    # filesystem
+    "file_read", "file_write", "file_append", "file_list",
+    "file_delete", "file_move", "file_copy", "file_info",
+    "head", "tail", "tree",
+    # editor
+    "str_replace", "diff_preview", "find_replace",
+    # search
+    "grep", "glob_search",
+    # shell
+    "shell_exec", "cd", "cwd", "which", "env", "set_env",
+    # system
+    "ps", "sysinfo", "port_check", "disk_usage",
+]