# mcsm-mcp —— MCSManager Minecraft 服务器管理 MCP Server

由 AstrBot 插件 `siwu-mcs-manager-1_0`（源插件 [AstrBot_siwu-mcs-manager](https://github.com/siwuli/AstrBot_siwu-mcs-manager)）转换的独立 MCP Server：
通过 **MCSManager 面板 API** 管理 Minecraft 服务器实例（列表 / 状态 / 启动 / 停止 / 重启 / 强停 / 控制台指令），
供任意支持 MCP 的客户端（Claude Desktop、IDE、agent 框架等）即插即用。

## 工具一览（10 个）

| 工具 | 说明 |
| --- | --- |
| `mcs_list_instances` | 列出所有服务器实例（名称/状态/在线玩家/端口） |
| `mcs_instance_status` | 查询指定实例状态详情（状态/在线玩家/端口/启动命令） |
| `mcs_start_instance` | 启动指定实例（后台异步执行） |
| `mcs_stop_instance` | 正常停止指定实例（安全存档） |
| `mcs_restart_instance` | 重启指定实例 |
| `mcs_kill_instance` | 强制停止指定实例（杀进程，可能丢数据） |
| `mcs_exec_command` | 向实例发送控制台指令（say/op/whitelist/give/tp/list 等） |
| `mcs_wait_for_status` | 轮询等待实例达到目标状态（替代插件的后台推送通知） |
| `mcs_get_config` | 查看当前生效配置（API Key/密码已脱敏） |
| `mcs_reload_config` | 热重载配置（改完 .env 无需重启），也可切换配置文件 |

## 与原插件的差异

| 原插件（AstrBot） | 本 MCP Server |
| --- | --- |
| 工具返回中文文本，由 LLM 组织回复 | 返回**结构化 JSON**，调用方自行组织 |
| QQ 群权限（admin_ids / admin_role） | **读写开关 `MCSM_ALLOW_WRITE`**（默认只读），调用方客户端负责访问控制 |
| 启动/停止后后台轮询 + 主动推送通知 | `mcs_wait_for_status` 由 LLM 按需轮询确认 |
| `mc列表` 等唤醒词命令 | 交给客户端/LLM 直接用工具（无聊天上下文） |
| 强制 Agent 工具钩子/系统提示注入 | MCP 工具天然由客户端按需暴露，无需注入 |

## 快速开始

```bash
cd servers/mcs-manager
python -m venv .venv                 # 或 uv venv .venv
.venv/Scripts/pip install -e .        # 或 uv pip install -p .venv -e .
```

配置（复制 `.env.example` 为 `.env` 填写，或直接用环境变量）：

```bash
MCSM_BASE_URL=http://127.0.0.1:23333   # 面板地址
MCSM_API_KEY=xxxx                      # v10 API Key（推荐）；或 MCSM_USERNAME + MCSM_PASSWORD
MCSM_ALLOW_WRITE=1                     # 写操作开关：0=只读（默认），1=允许启动/停止等
```

## 如何修改配置（插件配置 → MCP 配置）

原 AstrBot 插件在管理面板里改配置；MCP 化后配置变成 **`servers/mcs-manager/.env` 文件（或环境变量）**，
与原插件配置项的对应关系见下表，**默认值完全一致**：

| 原插件配置项 | MCP 环境变量 | 说明 |
| --- | --- | --- |
| `mcs_base_url` | `MCSM_BASE_URL` | 面板地址 |
| `mcs_api_key` | `MCSM_API_KEY` | v10 API Key（推荐） |
| `mcs_username` / `mcs_password` | `MCSM_USERNAME` / `MCSM_PASSWORD` | 账号密码登录（v9） |
| `mcs_api_timeout` | `MCSM_TIMEOUT` | 请求超时（秒） |
| `mcs_permission_enabled` + `mcs_admin_ids`/`mcs_admin_role` | `MCSM_ALLOW_WRITE` | QQ 群权限 → 读写总开关（默认只读） |
| `mcs_command_whitelist` | `MCSM_COMMAND_WHITELIST` | 指令白名单（逗号分隔） |
| `mcs_blocked_commands` | `MCSM_BLOCKED_COMMANDS` | 指令黑名单 |
| `mcs_operation_wait` | `MCSM_OPERATION_WAIT` | wait 工具默认等待秒数 |
| `mcs_enabled` | —（进程启动即启用） | 不再需要总开关，不启动进程即关闭 |
| `mcs_force_agent_tool` | —（无意义） | MCP 工具由客户端按需暴露，无需强制注入 |

**修改步骤：**

1. 编辑 `servers/mcs-manager/.env`（没有就先 `cp .env.example .env`）；
2. 调用工具 `mcs_reload_config` 热生效，或直接重启 Server 进程；
3. 用 `mcs_get_config` 核对生效值（凭据会脱敏显示为 `***`）。

> 若通过客户端配置传环境变量（如 Claude Desktop 配置里的 `env` 块），改完同样调用 `mcs_reload_config` 或重启即可生效。

## 运行

**stdio（本地进程，推荐）：**

```bash
.venv/Scripts/python -m mcsm_mcp
# 或已安装的入口命令：mcsm-mcp
```

**HTTP（远程/多客户端）：**

```bash
.venv/Scripts/python -m mcsm_mcp --transport http --host 127.0.0.1 --port 8000
# 端点：http://127.0.0.1:8000/mcp （streamable-http）
```

## 客户端接入示例（stdio）

Claude Desktop 的 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "mcs-manager": {
      "command": "<安装路径>/.venv/Scripts/python.exe",  // Windows；Linux/macOS 用 <安装路径>/.venv/bin/python
      "args": ["-m", "mcsm_mcp"],
      "env": {
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "你的面板 API Key",
        "MCSM_ALLOW_WRITE": "1"
      }
    }
  }
}
```

调试：`npx @modelcontextprotocol/inspector` 中选择 stdio 并填上述 command/args。

## 完整环境变量

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `MCSM_BASE_URL` | 面板地址（不带末尾斜杠） | `http://127.0.0.1:23333` |
| `MCSM_API_KEY` | 面板 API Key（v10 推荐） | 空 |
| `MCSM_USERNAME` / `MCSM_PASSWORD` | 账号密码登录（v9 或未配 Key） | 空 |
| `MCSM_TIMEOUT` | 面板请求超时（秒） | `15` |
| `MCSM_ALLOW_WRITE` | 写操作开关 | `0`（只读） |
| `MCSM_COMMAND_WHITELIST` | 控制台指令白名单（逗号分隔前缀；空=全部允许） | 空 |
| `MCSM_BLOCKED_COMMANDS` | 危险指令黑名单（按首词匹配） | `stop,restart` |
| `MCSM_OPERATION_WAIT` | `mcs_wait_for_status` 默认等待上限（秒） | `600` |
| `MCSM_TRANSPORT` | `stdio` 或 `http` | `stdio` |
| `MCSM_HOST` / `MCSM_PORT` | http 监听地址/端口 | `127.0.0.1` / `8000` |
| `MCSM_ENV_FILE` | 指定 .env 文件路径（可选） | `.env` |

## 测试

```bash
.venv/Scripts/python tests/test_smoke.py   # stdio：tools/list + 无凭据/只读拦截/连接错误
.venv/Scripts/python tests/test_http.py    # streamable-http 握手与调用
```

## 安全提示

- **默认只读**：启动/停止/重启/强停/发指令均需 `MCSM_ALLOW_WRITE=1`，请仅在可信客户端接入时开启。
- 指令黑名单默认拦截 `stop`/`restart`，防止通过控制台指令绕过面板操作；可再配白名单收紧。
- 面板凭据存放于 `.env`（已被 .gitignore 忽略）或环境变量，勿提交进仓库。
- 写工具返回 `submitted=true` 仅代表指令已下发（后台异步），完成确认请用 `mcs_wait_for_status`。

## 源码结构

```
src/mcsm_mcp/
├── __main__.py   # python -m mcsm_mcp 入口
├── server.py     # MCPServer + 8 个工具（mcp SDK 2.x）
├── api.py        # MCSManagerAPI 客户端（无 AstrBot 依赖，含 v9/v10 兼容）
└── config.py     # 环境变量配置 + 读写开关 + 指令白/黑名单策略
```