mcsm-sdk-python 1.0.6
An unoffical SDK for the MCSManager
Requires Python: >=3.9

# MCSM SDK Python

一个用于 MCSManager 的非官方 Python SDK，提供简单易用的 API 接口来管理 Minecraft 服务器实例。

## 特性

- 🚀 异步支持，基于 `httpx` 构建
- 📊 完整的仪表板信息获取
- 👥 用户管理功能（创建、查询、更新、删除）
- 🎮 实例管理功能（创建、启动、停止、重启等）
- 📝 类型提示支持
- 🔧 简单易用的 API 设计

## 安装

### 使用 pip 安装

```bash
pip install mcsm-sdk-python
```

### 从源码安装

```bash
git clone https://github.com/laobinghu/mcsm-sdk-python.git
cd mcsm-sdk-python
pip install -e .
```

## 快速开始

```python
import asyncio
from httpx import AsyncClient
from mcsm_sdk_python import McsmSdk

async def main():
    # 创建 HTTP 客户端
    http_client = AsyncClient()
    
    # 初始化 MCSM SDK
    mcsm = McsmSdk(
        client=http_client,
        endpoint="http://127.0.0.1:2333",  # 你的 MCSManager 地址
        apikey="your_api_key_here"         # 你的 API 密钥
    )
    
    try:
        # 获取系统概览信息
        overview = await mcsm.get_overview()
        print("系统概览:", overview)
        
        # 获取用户列表
        users = await mcsm.get_user_list(page=1, page_size=10)
        print("用户列表:", users)
        
    finally:
        # 关闭 HTTP 客户端
        await http_client.aclose()

# 运行示例
asyncio.run(main())
```

## API 文档

### 初始化

```python
from httpx import AsyncClient
from mcsm_sdk_python import McsmSdk

client = AsyncClient()
mcsm = McsmSdk(
    client=client,
    endpoint="http://your-mcsm-server:2333",
    apikey="your_api_key"
)
```

### 仪表板 API

#### 获取系统概览

```python
overview = await mcsm.get_overview()
```

返回系统的基本信息，包括服务器状态、实例数量等。

### 用户管理 API

#### 获取用户列表

```python
users = await mcsm.get_user_list(
    page=1,           # 页码
    page_size=10,     # 每页数量
    userName="",      # 可选：用户名筛选
    role=1           # 可选：角色筛选
)
```

#### 创建用户

```python
result = await mcsm.create_user(
    username="new_user",
    password="password123",
    permission=1  # 权限级别
)
```

#### 更新用户信息

```python
result = await mcsm.update_user({
    "uuid": "user_uuid",
    "username": "updated_name",
    "permission": 2
})
```

#### 删除用户

```python
result = await mcsm.delete_user(["user_uuid_1", "user_uuid_2"])
```

### 实例管理 API

#### 获取实例列表

```python
instances = await mcsm.get_instances_list(
    daemonId="daemon_id",
    page=1,
    page_size=10,
    status="running",        # 状态筛选
    instance_name=""         # 可选：实例名称筛选
)
```

#### 获取实例详细信息

```python
instance_info = await mcsm.get_instances_info(
    daemonId="daemon_id",
    page=1,
    page_size=10,
    status="running",
    instance_id="instance_uuid"
)
```

#### 创建实例

```python
result = await mcsm.create_instance(
    daemonId="daemon_id",
    data={
        "nickname": "我的服务器",
        "startCommand": "java -jar server.jar",
        "stopCommand": "stop",
        "cwd": "/path/to/server",
        "ie": "utf-8",
        "oe": "utf-8"
    }
)
```

#### 实例操作

支持单个实例和批量实例操作：

```python
# 单个实例操作
result = await mcsm.instances_operate(
    method="start",           # 操作类型：start, stop, restart, kill
    daemonId="daemon_id",
    instance_id="instance_uuid"
)

# 批量实例操作
result = await mcsm.instances_operate(
    method="start",
    isBatch=True,
    instance_list=[
        {
            "daemonId": "daemon-123",
            "instanceUuids": ["uuid-1", "uuid-2", "uuid-3"]
        },
        {
            "daemonId": "daemon-456", 
            "instanceUuids": ["uuid-4", "uuid-5"]
        }
    ]
)
```

支持的操作类型：
- `start` - 启动实例
- `stop` - 停止实例
- `restart` - 重启实例
- `kill` - 强制终止实例

#### 更新实例

```python
result = await mcsm.update_instance(
    daemonId="daemon_id",
    uuid="instance_uuid"
)
```

## 错误处理

SDK 使用 `httpx` 的异常处理机制：

```python
import httpx

try:
    result = await mcsm.get_overview()
except httpx.HTTPStatusError as e:
    print(f"HTTP 错误: {e.response.status_code}")
    print(f"响应内容: {e.response.text}")
except httpx.RequestError as e:
    print(f"请求错误: {e}")
```

## 配置要求

- Python 3.9+
- httpx >= 0.28.1

## 项目结构

```
mcsm_sdk_python/
├── __init__.py          # 主入口，导出 McsmSdk 类
├── base.py             # 基础类，提供通用功能
├── dashboard.py        # 仪表板相关 API
├── users.py           # 用户管理 API
├── instance.py        # 实例管理 API
├── daemon.py          # 守护进程 API（待实现）
├── fileManager.py     # 文件管理 API（待实现）
└── imageManager.py    # 镜像管理 API（待实现）
```

## 开发计划

- [ ] 守护进程管理 API
- [ ] 文件管理 API
- [ ] 镜像管理 API
- [ ] 单元测试
- [ ] 文档完善

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 相关链接

- [MCSManager 官方网站](https://mcsmanager.com/)
- [MCSManager GitHub](https://github.com/MCSManager/MCSManager)

---

**注意**: 这是一个非官方的 SDK，与 MCSManager 官方团队无关。使用前请确保你的 MCSManager 版本支持相应的 API。