quick-mcp-shell 0.4.0__tar.gz → 0.4.2__tar.gz

{quick_mcp_shell-0.4.0 → quick_mcp_shell-0.4.2}/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-10-09
+
+### Fixed
+
+- 修正 README 的 Amazon Quick 配置示例：补全 `mcpServers` → 服务名 → `{command, args}` 的嵌套结构，之前的裸对象会导致用户配置错误。仅文档变更。
+
+## [0.4.1] - 2026-10-09
+
+### Changed
+
+- README 重写定位说明：说明 Amazon Quick 是隔离 sandbox，需借助本 MCP 执行本地命令，并补充 lark-cli 示例。仅文档变更，运行时行为与 0.4.0 一致。
+
 ## [0.4.0] - 2026-10-09
 
 ### Changed

quick_mcp_shell-0.4.2/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: quick-mcp-shell
+Version: 0.4.2
+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 的执行环境是一个隔离的sandbox，无法调用本地命令，需要借助MCP才能够在本机执行 shell 命令和 运行Python 脚本。
+例如：本地安装了 lark-cli 操作飞书，但是Quick无法直接使用 lark-cli 命令，可以通过该MCP执行 lark-cli 命令。
+
+## 安装 uv
+
+Amazon Quick 使用 `uvx` 启动本工具。
+
+- Windows(PowerShell)：`winget install --id=astral-sh.uv -e`
+- macOS：`brew install uv`
+- Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+执行 `uvx --version` 确认 uvx 已成功安装。
+
+## 配置 Amazon Quick
+
+打开 **Settings → Capabilities → MCP Servers**，编辑配置文件（通常是 `~/.aws/amazonq/mcp.json`），在 `mcpServers` 下添加一个服务条目（下例命名为 `shell`）：
+
+```json
+{
+  "mcpServers": {
+    "execute-cmd": {
+      "command": "uvx",
+      "args": ["--from", "quick-mcp-shell==0.4.2", "quick-mcp-shell"]
+    }
+  }
+}
+```
+
+若已有其他 MCP 服务，把 `"shell": { ... }` 这一条目并入现有的 `mcpServers` 对象即可。
+
+## 工具
+
+配置完成后，Amazon Quick 会自动获得下面两个工具，并在需要时自行调用；你只需用自然语言向 Quick 描述需求，无需手动调用。
+
+- `run_command`：执行 shell 命令。Windows 上通过 `cmd.exe` 执行（不是 PowerShell），macOS/Linux 上通过 `/bin/sh` 执行。
+- `run_python_script`：执行 Python 脚本。使用本工具自带的隔离解释器，项目里安装的第三方包（如 pandas）不可用；需要项目依赖时让 Quick 改用 `run_command`。
+
+两个工具都支持可选的 `cwd` 和 `timeout` 参数，由 Quick 在调用时传入：不传 `cwd` 时使用当前用户的主目录，相对路径也相对主目录解析，传入绝对路径时可指定任意存在的目录；`timeout` 默认 30 秒、最大 60 秒，超时会终止整个进程树。
+
+可选环境变量：
+
+| 变量 | 默认值 | 作用 |
+|---|---:|---|
+| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | `60` | 单次调用允许的最大超时秒数。 |
+| `MCP_SHELL_MAX_OUTPUT_CHARS` | `100000` | 返回结果的最大字符数，超出时保留首尾两段。 |
+
+检查启动环境：
+
+```bash
+uvx --from quick-mcp-shell==0.4.2 quick-mcp-shell doctor
+```
+
+## 安全边界
+
+本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。

{quick_mcp_shell-0.4.0 → quick_mcp_shell-0.4.2}/PUBLISHING.md

@@ -13,7 +13,7 @@ uvx twine check --strict dist/*
 检查 wheel 中只包含预期的包文件，且 README 没有包含本机路径、凭据或真实用户数据。
 
 ```powershell
-python -m zipfile -l dist\quick_mcp_shell-0.4.0-py3-none-any.whl
+python -m zipfile -l dist\quick_mcp_shell-0.4.2-py3-none-any.whl
 ```
 
 ## 发布
@@ -29,7 +29,7 @@ Remove-Item Env:\UV_PUBLISH_TOKEN
 上传后，在干净环境中验证命令入口：
 
 ```powershell
-uvx --from quick-mcp-shell==0.4.0 quick-mcp-shell --version
+uvx --from quick-mcp-shell==0.4.2 quick-mcp-shell --version
 ```
 
 每次发布都必须递增 `pyproject.toml` 和 `quick_mcp_shell/__init__.py` 中的版本号；PyPI 不允许覆盖已上传的版本。

quick_mcp_shell-0.4.2/README.md

@@ -0,0 +1,57 @@
+# Quick MCP Shell
+
+Amazon Quick 的执行环境是一个隔离的sandbox，无法调用本地命令，需要借助MCP才能够在本机执行 shell 命令和 运行Python 脚本。
+例如：本地安装了 lark-cli 操作飞书，但是Quick无法直接使用 lark-cli 命令，可以通过该MCP执行 lark-cli 命令。
+
+## 安装 uv
+
+Amazon Quick 使用 `uvx` 启动本工具。
+
+- Windows(PowerShell)：`winget install --id=astral-sh.uv -e`
+- macOS：`brew install uv`
+- Linux：`curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+执行 `uvx --version` 确认 uvx 已成功安装。
+
+## 配置 Amazon Quick
+
+打开 **Settings → Capabilities → MCP Servers**，编辑配置文件（通常是 `~/.aws/amazonq/mcp.json`），在 `mcpServers` 下添加一个服务条目（下例命名为 `shell`）：
+
+```json
+{
+  "mcpServers": {
+    "execute-cmd": {
+      "command": "uvx",
+      "args": ["--from", "quick-mcp-shell==0.4.2", "quick-mcp-shell"]
+    }
+  }
+}
+```
+
+若已有其他 MCP 服务，把 `"shell": { ... }` 这一条目并入现有的 `mcpServers` 对象即可。
+
+## 工具
+
+配置完成后，Amazon Quick 会自动获得下面两个工具，并在需要时自行调用；你只需用自然语言向 Quick 描述需求，无需手动调用。
+
+- `run_command`：执行 shell 命令。Windows 上通过 `cmd.exe` 执行（不是 PowerShell），macOS/Linux 上通过 `/bin/sh` 执行。
+- `run_python_script`：执行 Python 脚本。使用本工具自带的隔离解释器，项目里安装的第三方包（如 pandas）不可用；需要项目依赖时让 Quick 改用 `run_command`。
+
+两个工具都支持可选的 `cwd` 和 `timeout` 参数，由 Quick 在调用时传入：不传 `cwd` 时使用当前用户的主目录，相对路径也相对主目录解析，传入绝对路径时可指定任意存在的目录；`timeout` 默认 30 秒、最大 60 秒，超时会终止整个进程树。
+
+可选环境变量：
+
+| 变量 | 默认值 | 作用 |
+|---|---:|---|
+| `MCP_SHELL_MAX_TIMEOUT_SECONDS` | `60` | 单次调用允许的最大超时秒数。 |
+| `MCP_SHELL_MAX_OUTPUT_CHARS` | `100000` | 返回结果的最大字符数，超出时保留首尾两段。 |
+
+检查启动环境：
+
+```bash
+uvx --from quick-mcp-shell==0.4.2 quick-mcp-shell doctor
+```
+
+## 安全边界
+
+本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。

{quick_mcp_shell-0.4.0 → quick_mcp_shell-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quick-mcp-shell"
-version = "0.4.0"
+version = "0.4.2"
 description = "A local stdio MCP server for trusted shell and Python execution"
 readme = "README.md"
 requires-python = ">=3.11"

{quick_mcp_shell-0.4.0 → quick_mcp_shell-0.4.2}/quick_mcp_shell/__init__.py

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

quick_mcp_shell-0.4.0/PKG-INFO

@@ -1,70 +0,0 @@
-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/README.md

@@ -1,52 +0,0 @@
-# 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
-```
-
-## 安全边界
-
-本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。