minecraft-management-client

minecraft-management-client

现代化、强类型的 Minecraft Server Management Protocol 客户端（TypeScript）。 支持 Node.js 与浏览器环境，提供统一的 Promise API、强类型方法与通知常量，适合企业级集成。

快速概览

import { ManagementClient, Message, Notifications } from 'minecraft-management-client';

const client = await ManagementClient.connect({
  url: 'wss://localhost:25566',
  token: 'YOUR_SECRET',
  autoDiscover: true,
  strictMethods: true,
});

await client.server.systemMessage({
  receivingPlayers: [],
  overlay: false,
  message: Message.literal('Hello'),
});

client.onNotification(Notifications.playersJoined, (params) => {
  console.log('player joined:', params?.[0]);
});

特性

• 强类型方法与通知（基于 rpc.md 自动生成）
• 自动 rpc.discover，不兼容方法给出友好错误
• 统一错误类型：RpcError / RpcMethodNotSupportedError / RpcDiscoverError
• 统一入口、统一命名、统一注释风格
• 兼容多版本服务器（依赖服务端 rpc.discover）

安装

# npm
npm i minecraft-management-client
# pnpm
pnpm i minecraft-management-client
# yarn
yarn add minecraft-management-client

教程

1) 配置服务器

在 server.properties 中开启管理协议：

management-server-enabled=true
management-server-host=localhost
management-server-port=25566
management-server-secret=YOUR_SECRET
management-server-tls-enabled=true

2) 建立连接

import { ManagementClient } from 'minecraft-management-client';

const client = await ManagementClient.connect({
  url: 'wss://localhost:25566',
  token: 'YOUR_SECRET',
  autoDiscover: true,
  strictMethods: true,
});

3) 调用强类型 API

const status = await client.server.status();
const players = await client.players.get();

console.log('server version:', status.version.name);
console.log('online players:', players.map((p) => p.name));

4) 发送系统消息

import { Message } from 'minecraft-management-client';

await client.server.systemMessage({
  receivingPlayers: [],
  overlay: false,
  message: Message.literal('Hello from minecraft-management-client'),
});

5) 修改服务器设置

await client.serverSettings.setMotd('My Server');
await client.serverSettings.setViewDistance(10);
await client.serverSettings.setSimulationDistance(10);

6) 操作名单

// allowlist
await client.allowlist.add([{ id: 'uuid', name: 'Steve' }]);

// operators
await client.operators.add([{ permissionLevel: 4, bypassesPlayerLimit: false, player: { id: 'uuid', name: 'Steve' } }]);

7) 监听通知（不手写 key）

import { Notifications } from 'minecraft-management-client';

client.onNotification(Notifications.playersJoined, (params) => {
  console.log('player joined:', params?.[0]);
});

8) 错误处理

import { RpcError, RpcMethodNotSupportedError } from 'minecraft-management-client';

try {
  await client.server.status();
} catch (err) {
  if (err instanceof RpcMethodNotSupportedError) {
    console.error('method not supported:', err.method);
  } else if (err instanceof RpcError) {
    console.error('rpc error:', err.code, err.data);
  } else {
    console.error(err);
  }
}

协议生成

使用 rpc.md 生成强类型方法与通知：

npm run gen:protocol

从正在运行的服务器重新抓取协议：

npm run gen:rpc

测试

运行一次 npm test 即可覆盖所有功能。

• 创建 test.env（不要提交到仓库）：

MC_MGMT_ENABLED=true
MC_MGMT_URL=wss://localhost:25566
MC_MGMT_SECRET=YOUR_SECRET
MC_MGMT_REJECT_UNAUTHORIZED=false
MC_ALLOW_DESTRUCTIVE=false

• 运行测试：

npm test

说明：

• MC_ALLOW_DESTRUCTIVE=false 时，不会执行破坏性命令。
• MC_MGMT_ENABLED=false 时，集成测试会跳过。
• MC_MGMT_REJECT_UNAUTHORIZED=false 仅用于本地自签名证书测试。

构建

npm run build

安全提示

• 管理协议属于高权限接口，务必避免暴露公网。
• 建议启用 TLS 并妥善保管 management-server-secret。

许可证

MIT