quick-mcp-shell 0.4.0__tar.gz

quick_mcp_shell-0.4.0/.gitignore

@@ -0,0 +1,31 @@
+# Build artefacts
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.so
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local state that must never be published
+*.jsonl
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

quick_mcp_shell-0.4.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [0.4.0] - 2026-10-09
+
+### Changed
+
+- 移除必填的 `MCP_SHELL_ALLOWED_ROOT` 与 `--allow-root`；不再限制命令的工作目录。
+- 不指定 `cwd` 时默认使用当前用户的主目录；相对路径也相对主目录解析，不再依赖服务进程的当前目录。
+- `run_python_script` 的临时脚本改写入系统临时目录，不再写入工作目录。
+- 运行时依赖提升为 `mcp>=1.2.0`，即 `mcp.server.fastmcp` 首次可用的版本。
+- 输出超限时保留首尾两段，并确保结果不超过 `MCP_SHELL_MAX_OUTPUT_CHARS`。
+- 删除过时的 `config.example.toml`，以及根目录的兼容入口 `server.py`、`config.py` 和 `legacy/` 目录。原先用 `python server.py` 从源码启动的用户，请改用 `python -m quick_mcp_shell`。
+
+### Fixed
+
+- 超时现在会终止整个进程树，后代进程不再残留；Windows 上也不会因子进程占用输出管道而卡住调用。
+- Windows 上按系统代码页解码命令输出，`dir`、`ipconfig` 等命令的中文不再乱码。`run_python_script` 仍固定使用 UTF-8。
+
+### Security
+
+- 这是一次有意的行为变更：0.3.0 强制的工作目录限制已移除。工作目录从来不是沙箱，命令仍以启动进程的用户权限执行。若需访问隔离，请依赖受限系统账户、容器或操作系统权限。
+
+## [0.3.0] - 2026-08-07
+
+### Changed
+
+- 统一发布名、console script 与 Amazon Quick 配置名为 `quick-mcp-shell`，避免与已存在的 `mcp-shell` PyPI 项目冲突。
+- 改为标准 Python 包布局，并提供可用的 `quick-mcp-shell` 命令入口、`--version` 与 `doctor`。
+- 运行时依赖限制为 MCP SDK 1.x，以匹配当前 FastMCP 实现。
+- README 改为面向 Amazon Quick 使用者的 Windows、macOS、Linux 配置指南。
+
+### Security
+
+- 不再使用硬编码工作目录。必须显式设置 `MCP_SHELL_ALLOWED_ROOT`，未设置时拒绝执行。
+- 最大超时与最大输出量可以配置，且每次调用会受上限约束。
+- 明确说明允许根目录只限制工作目录，不构成文件系统或网络沙箱。

quick_mcp_shell-0.4.0/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.

quick_mcp_shell-0.4.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: quick-mcp-shell
+Version: 0.4.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: 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.2.0
+Description-Content-Type: text/markdown
+
+# Quick MCP Shell
+
+一个供 Amazon Quick 使用的本地 stdio MCP Server，可执行本机 shell 命令和 Python 脚本。
+
+> **安全提示：** 命令以运行本工具的用户权限执行，可访问该用户有权限访问的文件和网络。只连接可信的本地 MCP 客户端；不要暴露到公网或交给不可信输入。
+
+## 安装 uv
+
+Amazon Quick 使用 `uvx` 启动本工具。安装 uv 并确认 `uvx --version` 可用：
+
+- Windows：`winget install --id=astral-sh.uv -e`
+- macOS：`brew install uv`
+- Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+## 配置 Amazon Quick
+
+打开 **Settings → Capabilities → MCP Servers**，在配置文件的 `mcpServers` 中加入以下配置：
+
+```json
+{
+  "shell": {
+    "command": "uvx",
+    "args": ["--from", "quick-mcp-shell==0.4.0", "quick-mcp-shell"]
+  }
+}
+```
+
+配置文件位置：Windows `C:\Users\<用户名>\.aws\amazonq\mcp.json`；macOS/Linux `~/.aws/amazonq/mcp.json`。保存后重启 Amazon Quick。
+
+## 使用
+
+- `run_command(command, cwd?, timeout?)`：执行 shell 命令。Windows 上通过 `cmd.exe` 执行，不是 PowerShell；macOS/Linux 上通过 `/bin/sh` 执行。
+- `run_python_script(script, cwd?, timeout?)`：执行 Python 脚本。使用本工具自带的隔离解释器，你项目里安装的第三方包（如 pandas）不可用；需要项目依赖时请改用 `run_command`。
+
+不传 `cwd` 时使用当前用户的主目录，相对路径也相对主目录解析；传入绝对路径时可指定任意存在的目录。`timeout` 默认 30 秒，最大值默认 60 秒；超时会终止整个进程树。
+
+可选环境变量：
+
+| 变量 | 默认值 | 作用 |
+|---|---:|---|
+| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | `60` | 单次调用允许的最大超时秒数。 |
+| `MCP_SHELL_MAX_OUTPUT_CHARS` | `100000` | 返回结果的最大字符数，超出时保留首尾两段。 |
+
+检查启动环境：
+
+```bash
+uvx --from quick-mcp-shell==0.4.0 quick-mcp-shell doctor
+```
+
+## 安全边界
+
+本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。

quick_mcp_shell-0.4.0/PUBLISHING.md

@@ -0,0 +1,35 @@
+# 发布 quick-mcp-shell 到 PyPI
+
+## 发布前检查
+
+在项目根目录执行：
+
+```powershell
+python -m unittest discover -s tests -v
+uv build
+uvx twine check --strict dist/*
+```
+
+检查 wheel 中只包含预期的包文件，且 README 没有包含本机路径、凭据或真实用户数据。
+
+```powershell
+python -m zipfile -l dist\quick_mcp_shell-0.4.0-py3-none-any.whl
+```
+
+## 发布
+
+使用 PyPI 中新建、未泄露且尽可能限制到单个项目的 API Token。不要把 token 写入仓库、文档或聊天。
+
+```powershell
+$env:UV_PUBLISH_TOKEN = "pypi-新令牌"
+uv publish --token $env:UV_PUBLISH_TOKEN
+Remove-Item Env:\UV_PUBLISH_TOKEN
+```
+
+上传后，在干净环境中验证命令入口：
+
+```powershell
+uvx --from quick-mcp-shell==0.4.0 quick-mcp-shell --version
+```
+
+每次发布都必须递增 `pyproject.toml` 和 `quick_mcp_shell/__init__.py` 中的版本号；PyPI 不允许覆盖已上传的版本。

quick_mcp_shell-0.4.0/README.md

@@ -0,0 +1,52 @@
+# Quick MCP Shell
+
+一个供 Amazon Quick 使用的本地 stdio MCP Server，可执行本机 shell 命令和 Python 脚本。
+
+> **安全提示：** 命令以运行本工具的用户权限执行，可访问该用户有权限访问的文件和网络。只连接可信的本地 MCP 客户端；不要暴露到公网或交给不可信输入。
+
+## 安装 uv
+
+Amazon Quick 使用 `uvx` 启动本工具。安装 uv 并确认 `uvx --version` 可用：
+
+- Windows：`winget install --id=astral-sh.uv -e`
+- macOS：`brew install uv`
+- Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+## 配置 Amazon Quick
+
+打开 **Settings → Capabilities → MCP Servers**，在配置文件的 `mcpServers` 中加入以下配置：
+
+```json
+{
+  "shell": {
+    "command": "uvx",
+    "args": ["--from", "quick-mcp-shell==0.4.0", "quick-mcp-shell"]
+  }
+}
+```
+
+配置文件位置：Windows `C:\Users\<用户名>\.aws\amazonq\mcp.json`；macOS/Linux `~/.aws/amazonq/mcp.json`。保存后重启 Amazon Quick。
+
+## 使用
+
+- `run_command(command, cwd?, timeout?)`：执行 shell 命令。Windows 上通过 `cmd.exe` 执行，不是 PowerShell；macOS/Linux 上通过 `/bin/sh` 执行。
+- `run_python_script(script, cwd?, timeout?)`：执行 Python 脚本。使用本工具自带的隔离解释器，你项目里安装的第三方包（如 pandas）不可用；需要项目依赖时请改用 `run_command`。
+
+不传 `cwd` 时使用当前用户的主目录，相对路径也相对主目录解析；传入绝对路径时可指定任意存在的目录。`timeout` 默认 30 秒，最大值默认 60 秒；超时会终止整个进程树。
+
+可选环境变量：
+
+| 变量 | 默认值 | 作用 |
+|---|---:|---|
+| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | `60` | 单次调用允许的最大超时秒数。 |
+| `MCP_SHELL_MAX_OUTPUT_CHARS` | `100000` | 返回结果的最大字符数，超出时保留首尾两段。 |
+
+检查启动环境：
+
+```bash
+uvx --from quick-mcp-shell==0.4.0 quick-mcp-shell doctor
+```
+
+## 安全边界
+
+本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。

quick_mcp_shell-0.4.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "quick-mcp-shell"
+version = "0.4.0"
+description = "A local stdio MCP server for trusted shell and Python execution"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Quick MCP Shell maintainers" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: System :: Shells",
+]
+dependencies = ["mcp>=1.2.0,<2.0.0"]
+
+[project.urls]
+Homepage = "https://pypi.org/project/quick-mcp-shell/"
+
+[project.scripts]
+quick-mcp-shell = "quick_mcp_shell.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["quick_mcp_shell"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/quick_mcp_shell",
+  "/README.md",
+  "/LICENSE",
+  "/CHANGELOG.md",
+  "/PUBLISHING.md",
+  "/pyproject.toml",
+]

quick_mcp_shell-0.4.0/quick_mcp_shell/__init__.py

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

quick_mcp_shell-0.4.0/quick_mcp_shell/__main__.py

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

quick_mcp_shell-0.4.0/quick_mcp_shell/config.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+
+
+class ConfigurationError(ValueError):
+    """Raised when a shell runtime setting is invalid."""
+
+
+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."""
+
+    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
+        return cls(
+            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-0.4.0/quick_mcp_shell/runtime.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import locale
+import os
+import signal
+import subprocess
+from pathlib import Path
+from typing import Mapping
+
+from .config import Settings
+
+# Seconds to wait for output pipes to drain after the process tree is killed.
+_DRAIN_SECONDS = 5
+
+_TRUNCATION_MARKER = "\n\n[输出已截断，省略 {} 个字符]\n\n"
+
+
+def resolve_cwd(cwd: str | None) -> Path:
+    """Default to the user's home; relative paths are resolved against it too."""
+    home = Path.home()
+    candidate = home if cwd is None else (home / Path(cwd).expanduser()).resolve()
+    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 shell_output_encoding() -> str:
+    """cmd.exe and most Windows tools write in the system code page, not UTF-8."""
+    if os.name == "nt":
+        return locale.getpreferredencoding(False)
+    return "utf-8"
+
+
+def truncate_output(text: str, limit: int) -> str:
+    """Keep the head and tail of long output; the result never exceeds ``limit``."""
+    if len(text) <= limit:
+        return text
+    # Size the marker for the widest possible omitted count so the total stays in bounds.
+    keep = limit - len(_TRUNCATION_MARKER.format(len(text)))
+    if keep <= 0:
+        return text[:limit]
+    head = keep // 2
+    tail = keep - head
+    omitted = len(text) - keep
+    return f"{text[:head]}{_TRUNCATION_MARKER.format(omitted)}{text[-tail:]}"
+
+
+def _render(status: str, stdout: str, stderr: str, limit: int) -> str:
+    parts = [status]
+    if stdout:
+        parts.append(f"stdout:\n{stdout}")
+    if stderr:
+        parts.append(f"stderr:\n{stderr}")
+    return truncate_output("\n\n".join(parts), limit)
+
+
+def format_result(
+    stdout: str,
+    stderr: str,
+    returncode: int,
+    max_output_chars: int,
+) -> str:
+    return _render(f"returncode: {returncode}", stdout, stderr, max_output_chars)
+
+
+def _kill_process_tree(process: subprocess.Popen[str]) -> None:
+    """Kill the process and everything it started, so nothing keeps the pipes open."""
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                ["taskkill", "/T", "/F", "/PID", str(process.pid)],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+                timeout=10,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError):
+            pass
+    else:
+        # The child was started in its own session, so its pid is also its process group id.
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except OSError:
+            pass
+    if process.poll() is None:
+        try:
+            process.kill()
+        except OSError:
+            pass
+
+
+def run_process(
+    args: str | list[str],
+    *,
+    shell: bool,
+    work_dir: Path,
+    timeout: int,
+    settings: Settings,
+    encoding: str = "utf-8",
+    env: Mapping[str, str] | None = None,
+) -> str:
+    try:
+        process = subprocess.Popen(
+            args,
+            shell=shell,
+            cwd=work_dir,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding=encoding,
+            errors="replace",
+            close_fds=True,
+            env=env,
+            start_new_session=os.name != "nt",
+        )
+    except OSError as exc:
+        return f"错误：无法启动进程：{exc}"
+
+    try:
+        stdout, stderr = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        _kill_process_tree(process)
+        try:
+            stdout, stderr = process.communicate(timeout=_DRAIN_SECONDS)
+        except subprocess.TimeoutExpired:
+            stdout, stderr = "", ""
+        return _render(
+            f"错误：命令执行超时（{timeout} 秒），已终止其进程树。",
+            stdout,
+            stderr,
+            settings.max_output_chars,
+        )
+
+    return format_result(stdout, stderr, process.returncode, settings.max_output_chars)

quick_mcp_shell-0.4.0/quick_mcp_shell/server.py

@@ -0,0 +1,119 @@
+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, shell_output_encoding
+
+
+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)
+        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,
+        encoding=shell_output_encoding(),
+    )
+
+
+@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)
+        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-",
+            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,
+            # Force UTF-8 so printing any character works and decodes correctly on every OS.
+            encoding="utf-8",
+            env={**os.environ, "PYTHONIOENCODING": "utf-8"},
+        )
+    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"默认工作目录: {Path.home()}")
+    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("command", nargs="?", choices=["doctor"])
+    arguments = parser.parse_args(argv)
+
+    if arguments.command == "doctor":
+        raise SystemExit(_doctor())
+    mcp.run(transport="stdio")