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 服务或暴露到公网。
- 不要把允许根目录设为系统盘根目录、用户主目录或包含密钥的目录。
- 不要把本工具交给不受信任的模型、插件、用户输入或自动化流程。
- 命令和脚本可访问当前用户能访问的资源；允许根目录不是安全沙箱。
- 固定版本号。升级前先阅读发布说明，并在隔离的项目目录中验证。
