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
```

## 安全边界

本工具不限制命令访问的目录。命令可以切换目录或使用绝对路径；若需要真正的访问隔离，请使用受限系统账户、容器或操作系统权限控制。
