quick-mcp-shell 0.3.0__py3-none-any.whl

quick_mcp_shell/__init__.py

@@ -0,0 +1,3 @@
+"""Quick MCP Shell package."""
+
+__version__ = "0.3.0"

quick_mcp_shell/__main__.py

@@ -0,0 +1,5 @@
+from .server import main
+
+
+if __name__ == "__main__":
+    main()

quick_mcp_shell/config.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+class ConfigurationError(ValueError):
+    """Raised when local shell execution has not been explicitly configured."""
+
+
+def _positive_int(value: str, variable: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise ConfigurationError(f"{variable} 必须是正整数。") from exc
+    if parsed <= 0:
+        raise ConfigurationError(f"{variable} 必须是正整数。")
+    return parsed
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime settings derived from environment variables."""
+
+    allowed_root: Path
+    max_timeout_seconds: int
+    max_output_chars: int
+
+    @classmethod
+    def from_environment(cls, env: Mapping[str, str] | None = None) -> "Settings":
+        environment = os.environ if env is None else env
+        raw_root = environment.get("MCP_SHELL_ALLOWED_ROOT", "").strip()
+        if not raw_root:
+            raise ConfigurationError(
+                "未设置 MCP_SHELL_ALLOWED_ROOT。请在 MCP 配置中显式指定允许执行命令的本地目录。"
+            )
+
+        allowed_root = Path(raw_root).expanduser().resolve()
+        if not allowed_root.is_dir():
+            raise ConfigurationError(
+                f"MCP_SHELL_ALLOWED_ROOT 不是有效目录：{allowed_root}"
+            )
+
+        return cls(
+            allowed_root=allowed_root,
+            max_timeout_seconds=_positive_int(
+                environment.get("MCP_SHELL_MAX_TIMEOUT_SECONDS", "60"),
+                "MCP_SHELL_MAX_TIMEOUT_SECONDS",
+            ),
+            max_output_chars=_positive_int(
+                environment.get("MCP_SHELL_MAX_OUTPUT_CHARS", "100000"),
+                "MCP_SHELL_MAX_OUTPUT_CHARS",
+            ),
+        )

quick_mcp_shell/runtime.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .config import Settings
+
+
+def resolve_cwd(cwd: str | None, settings: Settings) -> Path:
+    candidate = settings.allowed_root if cwd is None else Path(cwd).expanduser().resolve()
+    try:
+        candidate.relative_to(settings.allowed_root)
+    except ValueError as exc:
+        raise ValueError(
+            f"拒绝执行：工作目录 '{candidate}' 不在允许根目录 '{settings.allowed_root}' 下。"
+        ) from exc
+    if not candidate.is_dir():
+        raise ValueError(f"工作目录不存在或不是目录：'{candidate}'")
+    return candidate
+
+
+def effective_timeout(timeout: int, settings: Settings) -> int:
+    if timeout <= 0:
+        raise ValueError("timeout 必须是正整数。")
+    return min(timeout, settings.max_timeout_seconds)
+
+
+def format_result(
+    stdout: str,
+    stderr: str,
+    returncode: int,
+    max_output_chars: int,
+) -> str:
+    parts = [f"returncode: {returncode}"]
+    if stdout:
+        parts.append(f"stdout:\n{stdout}")
+    if stderr:
+        parts.append(f"stderr:\n{stderr}")
+    result = "\n\n".join(parts)
+    if len(result) > max_output_chars:
+        omitted = len(result) - max_output_chars
+        result = f"{result[:max_output_chars]}\n\n[输出已截断，省略 {omitted} 个字符]"
+    return result
+
+
+def run_process(
+    args: str | list[str],
+    *,
+    shell: bool,
+    work_dir: Path,
+    timeout: int,
+    settings: Settings,
+) -> str:
+    try:
+        result = subprocess.run(
+            args,
+            shell=shell,
+            cwd=work_dir,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            encoding="utf-8",
+            errors="replace",
+            close_fds=True,
+        )
+        return format_result(
+            result.stdout,
+            result.stderr,
+            result.returncode,
+            settings.max_output_chars,
+        )
+    except subprocess.TimeoutExpired:
+        return f"错误：命令执行超时（{timeout} 秒）。"
+    except OSError as exc:
+        return f"错误：无法启动进程：{exc}"

quick_mcp_shell/server.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from . import __version__
+from .config import ConfigurationError, Settings
+from .runtime import effective_timeout, resolve_cwd, run_process
+
+
+mcp = FastMCP(
+    name="quick-mcp-shell",
+    instructions=(
+        "Execute trusted local shell commands and Python scripts. "
+        "This server is intentionally powerful and must only be connected to trusted local MCP clients."
+    ),
+)
+
+
+def _settings_or_error() -> tuple[Settings | None, str | None]:
+    try:
+        return Settings.from_environment(), None
+    except ConfigurationError as exc:
+        return None, str(exc)
+
+
+@mcp.tool()
+def run_command(command: str, cwd: str | None = None, timeout: int = 30) -> str:
+    """在允许根目录内执行受信任的本地 shell 命令。"""
+    settings, error = _settings_or_error()
+    if error:
+        return f"配置错误：{error}"
+    assert settings is not None
+    try:
+        work_dir = resolve_cwd(cwd, settings)
+        timeout_seconds = effective_timeout(timeout, settings)
+    except ValueError as exc:
+        return f"错误：{exc}"
+    return run_process(
+        command,
+        shell=True,
+        work_dir=work_dir,
+        timeout=timeout_seconds,
+        settings=settings,
+    )
+
+
+@mcp.tool()
+def run_python_script(script: str, cwd: str | None = None, timeout: int = 30) -> str:
+    """在允许根目录内执行受信任的 Python 脚本。"""
+    settings, error = _settings_or_error()
+    if error:
+        return f"配置错误：{error}"
+    assert settings is not None
+    try:
+        work_dir = resolve_cwd(cwd, settings)
+        timeout_seconds = effective_timeout(timeout, settings)
+    except ValueError as exc:
+        return f"错误：{exc}"
+
+    script_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=".py",
+            prefix=".quick-mcp-shell-",
+            dir=work_dir,
+            delete=False,
+            encoding="utf-8",
+        ) as handle:
+            handle.write(script)
+            script_path = Path(handle.name)
+        return run_process(
+            [sys.executable, str(script_path)],
+            shell=False,
+            work_dir=work_dir,
+            timeout=timeout_seconds,
+            settings=settings,
+        )
+    except OSError as exc:
+        return f"错误：无法创建临时 Python 脚本：{exc}"
+    finally:
+        if script_path is not None:
+            try:
+                script_path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+
+def _doctor() -> int:
+    settings, error = _settings_or_error()
+    if error:
+        print(f"配置错误：{error}", file=sys.stderr)
+        return 1
+    assert settings is not None
+    print("quick-mcp-shell 配置正常")
+    print(f"允许根目录: {settings.allowed_root}")
+    print(f"最大超时: {settings.max_timeout_seconds} 秒")
+    print(f"最大输出: {settings.max_output_chars} 字符")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Trusted local MCP shell server")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument(
+        "--allow-root",
+        help="仅用于本次命令的 MCP_SHELL_ALLOWED_ROOT 覆盖值。",
+    )
+    parser.add_argument("command", nargs="?", choices=["doctor"])
+    arguments = parser.parse_args(argv)
+
+    if arguments.allow_root:
+        os.environ["MCP_SHELL_ALLOWED_ROOT"] = arguments.allow_root
+    if arguments.command == "doctor":
+        raise SystemExit(_doctor())
+    mcp.run(transport="stdio")

quick_mcp_shell-0.3.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: quick-mcp-shell
+Version: 0.3.0
+Summary: A local stdio MCP server for trusted shell and Python execution
+Project-URL: Homepage, https://pypi.org/project/quick-mcp-shell/
+Author: Quick MCP Shell maintainers
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.11
+Requires-Dist: mcp<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# Quick MCP Shell
+
+`quick-mcp-shell` 是一个本地 stdio MCP Server，供 Amazon Quick 调用本机 shell 命令和 Python 脚本。
+
+> 警告：这是一个高权限工具。它执行的命令拥有启动它的用户权限。`MCP_SHELL_ALLOWED_ROOT` 仅限制工作目录（`cwd`），**不是文件系统或网络沙箱**。只应连接到受信任的本地 MCP 客户端，绝不能暴露到公网，也不要向不受信任的提示词或用户开放。
+
+## 安装 uv
+
+Amazon Quick 通过 `uvx` 自动下载并运行本工具，无需手动安装 Python 包。
+
+**Windows（PowerShell）**
+
+```powershell
+winget install --id=astral-sh.uv -e
+```
+
+**macOS（需已安装 Homebrew）**
+
+```bash
+brew install uv
+```
+
+**Linux**
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+安装后执行 `uvx --version` 确认命令可用。
+
+## 配置 Amazon Quick
+
+在 Amazon Quick 中打开 **Settings → Capabilities → MCP Servers**，编辑配置文件：
+
+- Windows：`C:\Users\你的用户名\.aws\amazonq\mcp.json`
+- macOS / Linux：`~/.aws/amazonq/mcp.json`
+
+将下列内容合并到 `mcpServers`。必须把 `MCP_SHELL_ALLOWED_ROOT` 改为你希望允许作为工作目录的实际路径。
+
+**Windows 示例**
+
+```json
+{
+  "mcpServers": {
+    "shell": {
+      "command": "uvx",
+      "args": ["--from", "quick-mcp-shell==0.3.0", "quick-mcp-shell"],
+      "description": "在指定工作目录内执行受信任的本地 shell 命令和 Python 脚本。",
+      "env": {
+        "MCP_SHELL_ALLOWED_ROOT": "D:\\workspace\\my-project",
+        "MCP_SHELL_MAX_TIMEOUT_SECONDS": "60",
+        "MCP_SHELL_MAX_OUTPUT_CHARS": "100000"
+      }
+    }
+  }
+}
+```
+
+**macOS / Linux 示例**
+
+```json
+{
+  "mcpServers": {
+    "shell": {
+      "command": "uvx",
+      "args": ["--from", "quick-mcp-shell==0.3.0", "quick-mcp-shell"],
+      "description": "在指定工作目录内执行受信任的本地 shell 命令和 Python 脚本。",
+      "env": {
+        "MCP_SHELL_ALLOWED_ROOT": "/Users/your-name/workspace/my-project",
+        "MCP_SHELL_MAX_TIMEOUT_SECONDS": "60",
+        "MCP_SHELL_MAX_OUTPUT_CHARS": "100000"
+      }
+    }
+  }
+}
+```
+
+Linux 用户可将示例路径替换为 `/home/your-name/workspace/my-project`。保存配置并重启 Amazon Quick。
+
+## 可用工具
+
+### `run_command`
+
+执行本机 shell 命令。
+
+| 参数 | 说明 |
+|---|---|
+| `command` | 要执行的命令，必填 |
+| `cwd` | 工作目录；省略时使用 `MCP_SHELL_ALLOWED_ROOT` |
+| `timeout` | 超时秒数，默认 30；不会超过 `MCP_SHELL_MAX_TIMEOUT_SECONDS` |
+
+示例：让 Amazon Quick 在项目目录中执行 `git status`，或运行项目已有的测试命令。
+
+### `run_python_script`
+
+在所选工作目录中使用本工具自身的 Python 解释器执行一段 Python 脚本。参数与 `run_command` 相同，只是把 `command` 替换为 `script`。
+
+## 配置项
+
+| 环境变量 | 是否必填 | 默认值 | 说明 |
+|---|---:|---|---|
+| `MCP_SHELL_ALLOWED_ROOT` | 是 | 无 | 允许作为 `cwd` 的根目录；未设置时所有工具调用都会被拒绝。 |
+| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | 否 | `60` | 单次调用允许的最大超时。 |
+| `MCP_SHELL_MAX_OUTPUT_CHARS` | 否 | `100000` | 返回给 MCP 客户端的最大输出字符数；超出部分会被截断。 |
+
+## 本地检查
+
+在终端中运行以下命令可检查当前配置：
+
+```bash
+uvx --from quick-mcp-shell==0.3.0 quick-mcp-shell --allow-root /你的工作目录 doctor
+```
+
+Windows 示例：
+
+```powershell
+uvx --from quick-mcp-shell==0.3.0 quick-mcp-shell --allow-root "D:\workspace\my-project" doctor
+```
+
+## 安全边界
+
+- 不要将本工具部署为远程 HTTP 服务或暴露到公网。
+- 不要把允许根目录设为系统盘根目录、用户主目录或包含密钥的目录。
+- 不要把本工具交给不受信任的模型、插件、用户输入或自动化流程。
+- 命令和脚本可访问当前用户能访问的资源；允许根目录不是安全沙箱。
+- 固定版本号。升级前先阅读发布说明，并在隔离的项目目录中验证。

quick_mcp_shell-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+quick_mcp_shell/__init__.py,sha256=Mt_7sRItHgoMiPb31lvJl7LjDouK-Q5BOJySttdf108,54
+quick_mcp_shell/__main__.py,sha256=kXwGR0h4I_1BdqTv1YV6f86NLM1OwukbORECfPc9OPg,65
+quick_mcp_shell/config.py,sha256=rpCnp7yzyC2LonkHrCm90TfxNboIWM3vn5ZWGEsKRYE,1836
+quick_mcp_shell/runtime.py,sha256=smOLQLp_95K1Ni495AIVlidAAQJbNHNwg4EmTS5v6lg,2178
+quick_mcp_shell/server.py,sha256=4ejYmgcJ-QYhaI8TlfrNPuDl7qx7zmlBfzSkU6D3150,3746
+quick_mcp_shell-0.3.0.dist-info/METADATA,sha256=d2y3LrDo5uCQ95yBWgkUFKhZo0az4pf7ScyvGjJ8SmY,4783
+quick_mcp_shell-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+quick_mcp_shell-0.3.0.dist-info/entry_points.txt,sha256=nbAo9plh9AiUVMxjnmu2Bh7Fz72PUWXvI4gEauUO9tA,64
+quick_mcp_shell-0.3.0.dist-info/licenses/LICENSE,sha256=hbUa7wlsXAoAwP-OWYtG0wvIMJThjC5PQhZUVrPhsrI,1062
+quick_mcp_shell-0.3.0.dist-info/RECORD,,

quick_mcp_shell-0.3.0.dist-info/WHEEL

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

quick_mcp_shell-0.3.0.dist-info/entry_points.txt

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

quick_mcp_shell-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 libao
+
+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.