mcsm-sdk-python 1.0.6

An unoffical SDK for the MCSManager

MCSM SDK Python

一个用于 MCSManager 的非官方 Python SDK，提供简单易用的 API 接口来管理 Minecraft 服务器实例。

特性

• 🚀 异步支持，基于 httpx 构建
• 📊 完整的仪表板信息获取
• 👥 用户管理功能（创建、查询、更新、删除）
• 🎮 实例管理功能（创建、启动、停止、重启等）
• 📝 类型提示支持
• 🔧 简单易用的 API 设计

安装

使用 pip 安装

pip install mcsm-sdk-python

从源码安装

git clone https://github.com/laobinghu/mcsm-sdk-python.git
cd mcsm-sdk-python
pip install -e .

快速开始

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 文档

初始化

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

获取系统概览

overview = await mcsm.get_overview()

返回系统的基本信息，包括服务器状态、实例数量等。

用户管理 API

获取用户列表

users = await mcsm.get_user_list(
    page=1,           # 页码
    page_size=10,     # 每页数量
    userName="",      # 可选：用户名筛选
    role=1           # 可选：角色筛选
)

创建用户

result = await mcsm.create_user(
    username="new_user",
    password="password123",
    permission=1  # 权限级别
)

更新用户信息

result = await mcsm.update_user({
    "uuid": "user_uuid",
    "username": "updated_name",
    "permission": 2
})

删除用户

result = await mcsm.delete_user(["user_uuid_1", "user_uuid_2"])

实例管理 API

获取实例列表

instances = await mcsm.get_instances_list(
    daemonId="daemon_id",
    page=1,
    page_size=10,
    status="running",        # 状态筛选
    instance_name=""         # 可选：实例名称筛选
)

获取实例详细信息

instance_info = await mcsm.get_instances_info(
    daemonId="daemon_id",
    page=1,
    page_size=10,
    status="running",
    instance_id="instance_uuid"
)

创建实例

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"
    }
)

实例操作

支持单个实例和批量实例操作：

# 单个实例操作
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 - 强制终止实例

更新实例

result = await mcsm.update_instance(
    daemonId="daemon_id",
    uuid="instance_uuid"
)

错误处理

SDK 使用 httpx 的异常处理机制：

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 官方网站
• MCSManager GitHub

---

注意: 这是一个非官方的 SDK，与 MCSManager 官方团队无关。使用前请确保你的 MCSManager 版本支持相应的 API。