@wumx-labs/noxaeapi-mcp 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,2129 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_PATH = join(homedir(), ".noxaeapi-cli", "config.json");
+function loadCliConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    return { current: null, profiles: {} };
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return { current: null, profiles: {} };
+  }
+}
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--hub") {
+      parsed.hub = true;
+    } else if (arg.startsWith("--") && i + 1 < args.length && !args[i + 1].startsWith("--")) {
+      parsed[arg.slice(2)] = args[++i];
+    } else if (arg.startsWith("--")) {
+      parsed[arg.slice(2)] = true;
+    }
+  }
+  return parsed;
+}
+function resolveConfig() {
+  const args = parseArgs();
+  const env = process.env;
+  if (args.url && typeof args.url === "string") {
+    return {
+      baseUrl: args.url,
+      apiKey: typeof args.key === "string" ? args.key : void 0,
+      hub: args.hub === true,
+      profileName: "custom (via flags)"
+    };
+  }
+  const cliConfig = loadCliConfig();
+  const requestedProfileName = (typeof args.profile === "string" ? args.profile : null) ?? env.NOXAEAPI_PROFILE ?? cliConfig.current;
+  if (requestedProfileName && cliConfig.profiles[requestedProfileName]) {
+    const prof = cliConfig.profiles[requestedProfileName];
+    return {
+      baseUrl: prof.baseUrl,
+      apiKey: prof.apiKey,
+      hub: Boolean(prof.hub),
+      profileName: requestedProfileName
+    };
+  }
+  const envUrl = env.NOXAEAPI_HUB_BASE_URL ?? env.NOXAEAPI_BASE_URL;
+  if (envUrl) {
+    return {
+      baseUrl: envUrl,
+      apiKey: env.NOXAEAPI_HUB_KEY ?? env.NOXAEAPI_KEY,
+      hub: env.NOXAEAPI_HUB === "true" || Boolean(env.NOXAEAPI_HUB_BASE_URL),
+      profileName: "environment variables"
+    };
+  }
+  throw new Error(
+    "No NoxAeApi configuration found. Please run `noxae connect` in noxaeapi-cli, or provide --url <url>, or set NOXAEAPI_BASE_URL env variable."
+  );
+}
+
+// src/tools/network.ts
+import { z } from "zod";
+
+// src/client.ts
+import {
+  NoxAeApiClient,
+  NoxAeApiNetworkHubClient
+} from "@wumx-labs/noxaeapi-sdk";
+var activeSession = null;
+var cachedDefaultNode = null;
+function getSession() {
+  if (activeSession) return activeSession;
+  const config = resolveConfig();
+  if (config.hub) {
+    const hubClient = new NoxAeApiNetworkHubClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey
+    });
+    const singleClient = new NoxAeApiClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey
+    });
+    activeSession = {
+      config,
+      hubClient,
+      singleClient,
+      isHub: true,
+      getClient(nodeId) {
+        if (nodeId && hubClient) {
+          return hubClient.node(nodeId);
+        }
+        return singleClient;
+      },
+      async getDefaultNodeId() {
+        if (cachedDefaultNode && cachedDefaultNode.expires > Date.now()) {
+          return cachedDefaultNode.id;
+        }
+        try {
+          const nodes = await hubClient.network.statusAll();
+          if (Array.isArray(nodes) && nodes.length > 0) {
+            const online = nodes.find((n) => n.online || n.status === "online") || nodes[0];
+            const id = online.name || online.id || online.nodeId;
+            if (id) {
+              cachedDefaultNode = { id: String(id), expires: Date.now() + 2e4 };
+              return String(id);
+            }
+          }
+        } catch {
+        }
+        return void 0;
+      },
+      async resolveTargetClient(nodeId) {
+        if (nodeId) {
+          return { client: hubClient.node(nodeId), effectiveNodeId: nodeId };
+        }
+        const defaultNode = await this.getDefaultNodeId();
+        if (defaultNode) {
+          return { client: hubClient.node(defaultNode), effectiveNodeId: defaultNode };
+        }
+        return { client: singleClient };
+      }
+    };
+  } else {
+    const singleClient = new NoxAeApiClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey
+    });
+    activeSession = {
+      config,
+      hubClient: null,
+      singleClient,
+      isHub: false,
+      getClient() {
+        return singleClient;
+      },
+      async getDefaultNodeId() {
+        return void 0;
+      },
+      async resolveTargetClient() {
+        return { client: singleClient };
+      }
+    };
+  }
+  return activeSession;
+}
+
+// src/tools/network.ts
+function registerNetworkTools(server) {
+  server.tool(
+    "network_status_all",
+    "Get live status, player count, and health/TPS of all Minecraft server nodes registered in the network hub or aggregator.",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        let result;
+        if (session.isHub && session.hubClient) {
+          result = await session.hubClient.network.statusAll();
+        } else if (session.singleClient) {
+          result = await session.singleClient.network.statusAll();
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to fetch network status: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "network_node_status",
+    "Get detailed status and health of a specific server node in the network by its nodeId.",
+    {
+      nodeId: z.string().describe("The ID of the server node, e.g. 'lobby', 'survival-1'")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        let result;
+        if (session.isHub && session.hubClient) {
+          result = await session.hubClient.network.status(nodeId);
+        } else if (session.singleClient) {
+          result = await session.singleClient.network.status(nodeId);
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get status for node '${nodeId}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "network_broadcast",
+    "Broadcast a chat announcement across all servers in the network.",
+    {
+      message: z.string().describe("The message text to broadcast to all players in the network")
+    },
+    async ({ message }) => {
+      const session = getSession();
+      try {
+        let result;
+        if (session.isHub && session.hubClient) {
+          result = await session.hubClient.network.broadcast(message);
+        } else if (session.singleClient) {
+          result = await session.singleClient.network.broadcast(message);
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Network broadcast sent successfully: ${JSON.stringify(result ?? "OK")}`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to broadcast message: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "network_find_player",
+    "Find which server node a player is currently playing on in the proxy/network.",
+    {
+      player: z.string().describe("Username or UUID of the player")
+    },
+    async ({ player }) => {
+      const session = getSession();
+      try {
+        let result;
+        if (session.isHub && session.hubClient) {
+          result = await session.hubClient.network.find(player);
+        } else {
+          throw new Error("network_find_player requires a Velocity Network Hub connection.");
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to find player '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "network_send_player",
+    "Send/transfer a player from their current server to a target server node.",
+    {
+      player: z.string().describe("Username or UUID of the player"),
+      destinationServer: z.string().describe("Destination server name, e.g. 'survival', 'lobby'")
+    },
+    async ({ player, destinationServer }) => {
+      const session = getSession();
+      try {
+        if (!session.isHub || !session.hubClient) {
+          throw new Error("network_send_player requires a Velocity Network Hub connection.");
+        }
+        const result = await session.hubClient.network.sendPlayer(player, destinationServer);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Player ${player} sent to ${destinationServer}: ${JSON.stringify(result ?? "OK")}`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to send player: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/server.ts
+import { z as z2 } from "zod";
+async function resolveUuid(client, playerOrUuid) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(playerOrUuid)) {
+    return { uuid: playerOrUuid, name: playerOrUuid };
+  }
+  try {
+    const res = await client.players.resolve(playerOrUuid);
+    return { uuid: res.uuid, name: playerOrUuid };
+  } catch {
+    return { uuid: playerOrUuid, name: playerOrUuid };
+  }
+}
+function registerServerTools(server) {
+  server.tool(
+    "server_get_status",
+    "Get TPS (1m, 5m, 15m), CPU load, memory/RAM usage, uptime, and version of the Minecraft server.",
+    {
+      nodeId: z2.string().optional().describe("Target server node ID (if connected via Velocity hub, e.g. 'survival', 'lobby')")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const [info2, tps2, health2] = await Promise.allSettled([
+            session.hubClient.network.forward(nodeId, "GET", "server"),
+            session.hubClient.network.forward(nodeId, "GET", "server/tps"),
+            session.hubClient.network.forward(nodeId, "GET", "server/health")
+          ]);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    nodeId,
+                    info: info2.status === "fulfilled" ? info2.value : null,
+                    tps: tps2.status === "fulfilled" ? tps2.value : null,
+                    health: health2.status === "fulfilled" ? health2.value : null
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        const client = session.getClient();
+        const [info, tps, health] = await Promise.allSettled([
+          client.server.info(),
+          client.server.tps(),
+          client.server.health()
+        ]);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  info: info.status === "fulfilled" ? info.value : null,
+                  tps: tps.status === "fulfilled" ? tps.value : null,
+                  health: health.status === "fulfilled" ? health.value : null
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get server status: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_dispatch_command",
+    "Execute a Minecraft console command on the server (e.g. 'say Hello', 'whitelist on', 'gamemode creative Steve').",
+    {
+      command: z2.string().describe("The console command to execute, without leading slash"),
+      nodeId: z2.string().optional().describe("Target server node ID (if on Velocity hub, e.g. 'survival', 'lobby')")
+    },
+    async ({ command, nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const result2 = await session.hubClient.network.forward(nodeId, "POST", "server/exec", {
+            body: { command },
+            form: true
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Command executed on [${nodeId}]: ${JSON.stringify(result2 ?? "Command dispatched successfully")}`
+              }
+            ]
+          };
+        }
+        const client = session.getClient();
+        const result = await client.server.dispatchCommand(command);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Command executed: ${JSON.stringify(result ?? "Command dispatched successfully")}`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to dispatch command: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_broadcast",
+    "Broadcast a chat message to all players on the Minecraft server.",
+    {
+      message: z2.string().describe("The message text to broadcast"),
+      nodeId: z2.string().optional().describe("Target server node ID (if on Velocity hub)")
+    },
+    async ({ message, nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const result2 = await session.hubClient.network.forward(nodeId, "POST", "chat/broadcast", {
+            body: { message },
+            form: true
+          });
+          return {
+            content: [{ type: "text", text: `Broadcast sent to [${nodeId}]: ${JSON.stringify(result2 ?? "OK")}` }]
+          };
+        }
+        const client = session.getClient();
+        const result = await client.server.broadcast(message);
+        return {
+          content: [{ type: "text", text: `Broadcast sent: ${JSON.stringify(result ?? "OK")}` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to broadcast message: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_get_whitelist",
+    "Get the current list of whitelisted players.",
+    {
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const result2 = await session.hubClient.network.forward(nodeId, "GET", "server/whitelist");
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
+        const client = session.getClient();
+        const result = await client.server.getWhitelist();
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get whitelist: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_whitelist_add",
+    "Add a player to the server whitelist by username or UUID.",
+    {
+      player: z2.string().describe("Player username or UUID to whitelist"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ player, nodeId }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const { uuid, name } = await resolveUuid(client, player);
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "POST", "server/whitelist", {
+            body: { uuid, name },
+            form: true
+          });
+          return {
+            content: [{ type: "text", text: `Successfully whitelisted player '${player}' on [${nodeId}].` }]
+          };
+        }
+        await client.server.addToWhitelist(uuid, name);
+        return {
+          content: [{ type: "text", text: `Successfully whitelisted player '${player}'.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to add player to whitelist: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_whitelist_remove",
+    "Remove a player from the server whitelist by username or UUID.",
+    {
+      player: z2.string().describe("Player username or UUID to remove from whitelist"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ player, nodeId }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const { uuid } = await resolveUuid(client, player);
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "DELETE", "server/whitelist", {
+            query: { uuid }
+          });
+          return {
+            content: [{ type: "text", text: `Successfully removed player '${player}' from whitelist on [${nodeId}].` }]
+          };
+        }
+        await client.server.removeFromWhitelist(uuid);
+        return {
+          content: [{ type: "text", text: `Successfully removed player '${player}' from whitelist.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to remove player from whitelist: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_get_ops",
+    "List all server operators (OPs).",
+    {
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const result2 = await session.hubClient.network.forward(nodeId, "GET", "server/ops");
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
+        const client = session.getClient();
+        const result = await client.server.getOps();
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get operators: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_op_player",
+    "Grant operator (OP) status to a player.",
+    {
+      player: z2.string().describe("Player username or UUID to promote to operator"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ player, nodeId }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const { uuid } = await resolveUuid(client, player);
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "POST", "server/ops", {
+            body: { playerUuid: uuid },
+            form: true
+          });
+          return {
+            content: [{ type: "text", text: `Successfully granted OP status to '${player}' on [${nodeId}].` }]
+          };
+        }
+        await client.server.opPlayer(uuid);
+        return {
+          content: [{ type: "text", text: `Successfully granted OP status to '${player}'.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to OP player: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_deop_player",
+    "Revoke operator (OP) status from a player.",
+    {
+      player: z2.string().describe("Player username or UUID to demote from operator"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ player, nodeId }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const { uuid } = await resolveUuid(client, player);
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "DELETE", "server/ops", {
+            query: { playerUuid: uuid }
+          });
+          return {
+            content: [{ type: "text", text: `Successfully revoked OP status from '${player}' on [${nodeId}].` }]
+          };
+        }
+        await client.server.deopPlayer(uuid);
+        return {
+          content: [{ type: "text", text: `Successfully revoked OP status from '${player}'.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to de-OP player: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_get_logs",
+    "Tail recent console log lines from the server.",
+    {
+      lines: z2.number().optional().describe("Number of log lines to retrieve (default 50)"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ lines, nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          const result2 = await session.hubClient.network.forward(nodeId, "GET", "server/logs", {
+            query: { lines: lines ?? 50 }
+          });
+          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+        }
+        const client = session.getClient();
+        const result = await client.server.getLogs(lines ?? 50);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get server logs: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_restart",
+    "Restart the Minecraft server process (requires privileged write key).",
+    {
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "POST", "server/restart");
+          return { content: [{ type: "text", text: `Server [${nodeId}] restart initiated.` }] };
+        }
+        const client = session.getClient();
+        await client.server.restart();
+        return { content: [{ type: "text", text: "Server restart initiated." }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to restart server: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_ban_ip",
+    "Ban an IP address from connecting to the server.",
+    {
+      ip: z2.string().describe("The IP address to ban"),
+      reason: z2.string().optional().describe("Reason for banning this IP"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ ip, reason, nodeId }) => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "POST", "server/ban-ip", {
+            body: { ip, reason },
+            form: true
+          });
+          return { content: [{ type: "text", text: `Successfully banned IP '${ip}' on [${nodeId}].` }] };
+        }
+        const client = session.getClient();
+        await client.server.banIp(ip, reason);
+        return { content: [{ type: "text", text: `Successfully banned IP '${ip}'.` }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to ban IP: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "server_tell_player",
+    "Send a private whisper/message to a specific player.",
+    {
+      player: z2.string().describe("Player username or UUID to message"),
+      message: z2.string().describe("The private message content"),
+      nodeId: z2.string().optional().describe("Target server node ID")
+    },
+    async ({ player, message, nodeId }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const { uuid } = await resolveUuid(client, player);
+        if (session.isHub && session.hubClient && nodeId) {
+          await session.hubClient.network.forward(nodeId, "POST", "chat/tell", {
+            body: { playerUuid: uuid, message },
+            form: true
+          });
+          return { content: [{ type: "text", text: `Message sent to '${player}' on [${nodeId}].` }] };
+        }
+        await client.server.tell(uuid, message);
+        return { content: [{ type: "text", text: `Message sent to '${player}'.` }] };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to send message: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/players.ts
+import { z as z3 } from "zod";
+async function resolveUuid2(client, playerOrUuid) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(playerOrUuid)) {
+    return playerOrUuid;
+  }
+  try {
+    const res = await client.players.resolve(playerOrUuid);
+    return res.uuid;
+  } catch {
+    return playerOrUuid;
+  }
+}
+function registerPlayerTools(server) {
+  server.tool(
+    "players_list_online",
+    "List all players currently online on the Minecraft server (or proxy network), including usernames, UUIDs, ping, and health.",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        if (session.isHub && session.hubClient) {
+          const result = await session.hubClient.network.players();
+          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        const client = session.getClient();
+        const players = await client.players.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(players, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list online players: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "players_get_info",
+    "Get detailed stats, health, and info for a player (online or offline) by username or UUID.",
+    {
+      player: z3.string().describe("Player username or UUID")
+    },
+    async ({ player }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid2(client, player);
+        const [info, stats] = await Promise.allSettled([
+          client.players.get(uuid),
+          client.players.getStats(uuid)
+        ]);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  playerInfo: info.status === "fulfilled" ? info.value : null,
+                  stats: stats.status === "fulfilled" ? stats.value : null
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get player info for '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "players_kick",
+    "Kick an online player from the Minecraft server.",
+    {
+      player: z3.string().describe("Player username or UUID to kick"),
+      reason: z3.string().optional().describe("Kick reason displayed to the player")
+    },
+    async ({ player, reason }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid2(client, player);
+        await client.players.kick(uuid, reason);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully kicked player '${player}'${reason ? ` for reason: ${reason}` : ""}.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to kick player '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "players_ban",
+    "Ban a player from the Minecraft server.",
+    {
+      player: z3.string().describe("Player username or UUID to ban"),
+      reason: z3.string().optional().describe("Ban reason"),
+      expiry: z3.string().optional().describe("ISO-8601 expiry date for temp bans (e.g. '2026-12-31T23:59:59Z'). Omit for permanent ban.")
+    },
+    async ({ player, reason, expiry }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid2(client, player);
+        await client.players.ban(uuid, reason, expiry);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully banned player '${player}'${expiry ? ` until ${expiry}` : " permanently"}.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to ban player '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "players_unban",
+    "Unban a previously banned player.",
+    {
+      player: z3.string().describe("Player username or UUID to unban")
+    },
+    async ({ player }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid2(client, player);
+        await client.players.unban(uuid);
+        return {
+          content: [{ type: "text", text: `Successfully unbanned player '${player}'.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to unban player '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "players_set_gamemode",
+    "Change the gamemode of an online player (survival, creative, adventure, spectator).",
+    {
+      player: z3.string().describe("Player username or UUID"),
+      gamemode: z3.enum(["survival", "creative", "adventure", "spectator"]).describe("Gamemode to set")
+    },
+    async ({ player, gamemode }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid2(client, player);
+        await client.players.setGamemode(uuid, gamemode);
+        return {
+          content: [{ type: "text", text: `Successfully set gamemode of '${player}' to ${gamemode}.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to set gamemode: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/luckperms.ts
+import { z as z4 } from "zod";
+async function resolveUuid3(client, playerOrUuid) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(playerOrUuid)) {
+    return playerOrUuid;
+  }
+  try {
+    const res = await client.players.resolve(playerOrUuid);
+    return res.uuid;
+  } catch {
+    return playerOrUuid;
+  }
+}
+function registerLuckPermsTools(server) {
+  server.tool(
+    "luckperms_get_player_info",
+    "Get all groups and permission nodes assigned to a player in LuckPerms.",
+    {
+      player: z4.string().describe("Player username or UUID")
+    },
+    async ({ player }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid3(client, player);
+        const [primaryGroup, groups, permissions] = await Promise.allSettled([
+          client.luckperms.getPlayerPrimaryGroup(uuid),
+          client.luckperms.getPlayerGroups(uuid),
+          client.luckperms.getPlayerPermissions(uuid)
+        ]);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  player,
+                  uuid,
+                  primaryGroup: primaryGroup.status === "fulfilled" ? primaryGroup.value : null,
+                  groups: groups.status === "fulfilled" ? groups.value : null,
+                  permissions: permissions.status === "fulfilled" ? permissions.value : null
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get LuckPerms info for '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "luckperms_add_player_permission",
+    "Grant a permission node to a player in LuckPerms (permanent or temporary).",
+    {
+      player: z4.string().describe("Player username or UUID"),
+      permission: z4.string().describe("Permission node (e.g. 'essentials.fly', 'worldedit.*')"),
+      value: z4.boolean().optional().describe("Permission value: true to grant, false to negate (default: true)"),
+      expiry: z4.string().optional().describe("Expiry in ISO-8601 format (e.g. '2026-12-31T00:00:00Z'). Omit for permanent.")
+    },
+    async ({ player, permission, value, expiry }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid3(client, player);
+        await client.luckperms.addPlayerPermission(uuid, permission, { value, expiry });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully granted permission '${permission}' to player '${player}' (value=${value ?? true}${expiry ? `, expires=${expiry}` : ""}).`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to add permission: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "luckperms_remove_player_permission",
+    "Remove a permission node from a player in LuckPerms.",
+    {
+      player: z4.string().describe("Player username or UUID"),
+      permission: z4.string().describe("Permission node to remove")
+    },
+    async ({ player, permission }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid3(client, player);
+        await client.luckperms.removePlayerPermission(uuid, permission);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully removed permission '${permission}' from player '${player}'.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to remove permission: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "luckperms_set_player_primary_group",
+    "Set the primary LuckPerms group for a player (e.g. 'default', 'vip', 'moderator', 'admin').",
+    {
+      player: z4.string().describe("Player username or UUID"),
+      group: z4.string().describe("The name of the LuckPerms group")
+    },
+    async ({ player, group }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const uuid = await resolveUuid3(client, player);
+        await client.luckperms.setPlayerPrimaryGroup(uuid, group);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Successfully set primary group of '${player}' to '${group}'.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to set primary group: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "luckperms_list_groups",
+    "List all available permission groups configured in LuckPerms.",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const groups = await client.luckperms.getGroups();
+        return {
+          content: [{ type: "text", text: JSON.stringify(groups, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list groups: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/economy.ts
+import { z as z5 } from "zod";
+async function resolveUuid4(client, playerOrUuid) {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(playerOrUuid)) {
+    return playerOrUuid;
+  }
+  try {
+    if (client.players?.resolve) {
+      const res = await client.players.resolve(playerOrUuid);
+      return res.uuid;
+    }
+  } catch {
+  }
+  return playerOrUuid;
+}
+function registerEconomyTools(server) {
+  server.tool(
+    "economy_info",
+    "Get information about the economy provider/plugin installed on the server.",
+    {
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const result = await client.economy.info();
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [{ type: "text", text: prefix + JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get economy info: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_get_balance",
+    "Get the economy balance for a player (supports Vault default money and custom currencies).",
+    {
+      player: z5.string().describe("Player username or UUID"),
+      currency: z5.string().optional().describe("Currency ID (e.g. 'coins', 'candy'). Leave empty for primary Vault balance."),
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ player, currency, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const uuid = await resolveUuid4(client, player);
+        let result;
+        if (currency && client.economy.getCurrencyBalance) {
+          result = await client.economy.getCurrencyBalance(currency, uuid);
+        } else {
+          result = await client.economy.getBalance(uuid);
+        }
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [{ type: "text", text: prefix + JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get balance for '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_get_top",
+    "Get the leaderboard of richest players by Vault/server default balance. Runs in < 0.1ms with zero lag.",
+    {
+      limit: z5.number().optional().describe("Maximum number of players to return (default 10, max 100)"),
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ limit = 10, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const result = await client.economy.getTopBalance(limit);
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [{ type: "text", text: prefix + JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get top balances: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_list_currencies",
+    "List all custom currencies configured on the server (e.g. coins, candy, gems).",
+    {
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        if (!client.economy?.listCurrencies) {
+          return { content: [{ type: "text", text: "Multi-currency module not available." }] };
+        }
+        const currencies = await client.economy.listCurrencies();
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [{ type: "text", text: prefix + JSON.stringify(currencies, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list currencies: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_get_currency_top",
+    "Get the leaderboard of richest players for a specific custom currency (e.g. coins, candy).",
+    {
+      currency: z5.string().describe("The currency ID (e.g. 'coins', 'candy')"),
+      limit: z5.number().optional().describe("Maximum number of players to return (default 10, max 100)"),
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ currency, limit = 10, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        if (!client.economy?.getCurrencyTop) {
+          throw new Error("Currency top balances not supported on this economy provider.");
+        }
+        const result = await client.economy.getCurrencyTop(currency, limit);
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [{ type: "text", text: prefix + JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get currency top for '${currency}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_pay",
+    "Deposit / add money to a player's balance.",
+    {
+      player: z5.string().describe("Player username or UUID"),
+      amount: z5.number().positive().describe("Amount to deposit"),
+      currency: z5.string().optional().describe("Optional currency ID for multi-currency plugins (leave blank for Vault default)"),
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ player, amount, currency, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const uuid = await resolveUuid4(client, player);
+        if (currency && client.economy.payCurrency) {
+          await client.economy.payCurrency(currency, uuid, amount);
+        } else {
+          await client.economy.pay(uuid, amount);
+        }
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}] ` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${prefix}Successfully added ${amount} ${currency || "money"} to '${player}' balance.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to pay '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "economy_debit",
+    "Withdraw / deduct money from a player's balance.",
+    {
+      player: z5.string().describe("Player username or UUID"),
+      amount: z5.number().positive().describe("Amount to deduct"),
+      currency: z5.string().optional().describe("Optional currency ID for multi-currency plugins (leave blank for Vault default)"),
+      nodeId: z5.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ player, amount, currency, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const uuid = await resolveUuid4(client, player);
+        if (currency && client.economy.debitCurrency) {
+          await client.economy.debitCurrency(currency, uuid, amount);
+        } else {
+          await client.economy.debit(uuid, amount);
+        }
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}] ` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${prefix}Successfully deducted ${amount} ${currency || "money"} from '${player}' balance.`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to debit '${player}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/worlds.ts
+import { z as z6 } from "zod";
+function registerWorldTools(server) {
+  server.tool(
+    "worlds_list",
+    "List all worlds loaded on the Minecraft server (including name, environment, difficulty, time, and weather).",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const worlds = await client.worlds.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(worlds, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list worlds: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "worlds_set_time",
+    "Set the in-game time of a world (0 = day, 6000 = noon, 13000 = night, 18000 = midnight).",
+    {
+      worldUuid: z6.string().describe("World UUID or name"),
+      time: z6.number().min(0).max(24e3).describe("Time in ticks (0-24000)")
+    },
+    async ({ worldUuid, time }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        await client.worlds.setTime(worldUuid, time);
+        return {
+          content: [{ type: "text", text: `Successfully set world '${worldUuid}' time to ${time} ticks.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to set world time: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "worlds_set_weather",
+    "Set the weather condition in a world (clear, rain, thunder).",
+    {
+      worldUuid: z6.string().describe("World UUID or name"),
+      weather: z6.enum(["clear", "rain", "thunder"]).describe("Weather state")
+    },
+    async ({ worldUuid, weather }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        await client.worlds.setWeather(worldUuid, weather);
+        return {
+          content: [{ type: "text", text: `Successfully set world '${worldUuid}' weather to ${weather}.` }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to set weather: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "worlds_get_entities",
+    "Get count and breakdown of entities (mobs, items, players) currently loaded in a world.",
+    {
+      worldUuid: z6.string().describe("World UUID or name")
+    },
+    async ({ worldUuid }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const result = await client.worlds.getEntities(worldUuid);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get world entities: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/plugins.ts
+import { z as z7 } from "zod";
+function registerPluginTools(server) {
+  server.tool(
+    "plugins_list",
+    "List all plugins installed on the Minecraft server and their status (enabled/disabled, version).",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const plugins = await client.plugins.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(plugins, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list plugins: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "plugins_get_info",
+    "Get detailed metadata and description for a specific plugin installed on the server.",
+    {
+      pluginName: z7.string().describe("Name of the plugin, e.g. 'LuckPerms', 'Essentials'")
+    },
+    async ({ pluginName }) => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const plugin = await client.plugins.get(pluginName);
+        return {
+          content: [{ type: "text", text: JSON.stringify(plugin, null, 2) }]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get info for plugin '${pluginName}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/dispatch.ts
+import { z as z8 } from "zod";
+var SKIP_KEYS = /* @__PURE__ */ new Set(["connect"]);
+function buildResourceMap(client) {
+  const map = {};
+  for (const [key, value] of Object.entries(client)) {
+    if (SKIP_KEYS.has(key)) continue;
+    if (!value || typeof value !== "object") continue;
+    const proto = Object.getPrototypeOf(value);
+    if (!proto || proto === Object.prototype) continue;
+    const actions = Object.getOwnPropertyNames(proto).filter(
+      (name) => name !== "constructor" && typeof value[name] === "function"
+    );
+    if (actions.length === 0) continue;
+    map[key] = actions;
+  }
+  return map;
+}
+function registerDispatchTools(server) {
+  server.tool(
+    "noxae_list_modules",
+    "List all available SDK resource modules and their executable actions (e.g. essentials, worldguard, coreprotect, discordsrv, authme, shopgui, etc.).",
+    {},
+    async () => {
+      const session = getSession();
+      try {
+        const client = session.getClient();
+        const map = buildResourceMap(client);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(map, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list modules: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "noxae_call_action",
+    "Universal executor for any NoxAeApi module action. Allows calling all integration modules shown in CLI (e.g. worldguard, coreprotect, essentials, betterteams, discordsrv, authme, playerpoints, mythicmobs, shopgui, etc.).",
+    {
+      module: z8.string().describe("The module name (e.g. 'worldguard', 'essentials', 'coreprotect', 'betterteams', 'discordsrv', 'authme', 'shopgui')"),
+      action: z8.string().describe("The method name to execute on the module (use noxae_list_modules to see available actions)"),
+      args: z8.array(z8.unknown()).optional().describe("Arguments to pass to the method"),
+      nodeId: z8.string().optional().describe("Target server node ID (if connected via Velocity hub, e.g. 'survival', 'lobby')")
+    },
+    async ({ module: modName, action, args = [], nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const mod = client[modName];
+        if (!mod) {
+          throw new Error(`Module '${modName}' not found on client.`);
+        }
+        const fn = mod[action];
+        if (typeof fn !== "function") {
+          throw new Error(`Action '${action}' not found on module '${modName}'.`);
+        }
+        const result = await fn.apply(mod, args);
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: prefix + JSON.stringify(result ?? "Success (void)", null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to execute ${modName}.${action}(): ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/leaderboard.ts
+import { z as z9 } from "zod";
+var NOISY_BOARD_PATTERNS = [
+  /^ajlb:.*prevent-type.*/i,
+  /^ajlb:citizens\..*/i,
+  /^ajlb:commands\..*/i,
+  /^ajlb:loading\..*/i,
+  /^ajlb:updater\..*/i,
+  /^ajlb:formatted\..*/i,
+  /^ajlb:no-data\..*/i,
+  /^ajlb:signs\..*/i,
+  /^ajlb:no-player-skin.*/i,
+  /^ajlb:time\..*/i,
+  /^ajlb:[0-9a-z]$/i,
+  /^ajlb:java\..*/i,
+  /^ajlb:essentials\..*/i
+];
+function registerLeaderboardTools(server) {
+  server.tool(
+    "leaderboards_list",
+    "List all available gameplay leaderboard rankings on the server (e.g. player:kills, player:deaths, player:playtime, mcmmo:power, auraskills:power). Automatically filters out internal plugin noise. Note: For economy and balances, prefer the dedicated economy_* tools.",
+    {
+      includeNoisy: z9.boolean().optional().describe("If true, includes internal plugin placeholder keys (default false)"),
+      nodeId: z9.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ includeNoisy = false, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        if (!client?.leaderboards?.list) {
+          throw new Error("Leaderboards module is not available on this connection.");
+        }
+        const rawList = await client.leaderboards.list();
+        let filtered = rawList;
+        if (!includeNoisy && Array.isArray(rawList)) {
+          filtered = rawList.filter((entry) => {
+            const id = entry?.id || "";
+            return !NOISY_BOARD_PATTERNS.some((pattern) => pattern.test(id));
+          });
+        }
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        return {
+          content: [
+            {
+              type: "text",
+              text: prefix + JSON.stringify(filtered, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to list leaderboards: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server.tool(
+    "leaderboards_get_top",
+    "Get top ranking players for a specific gameplay leaderboard (e.g. 'player:kills', 'player:deaths', 'player:playtime', 'mcmmo:power', 'auraskills:power'). Note: For money/balances, always use economy_get_top or economy_get_currency_top.",
+    {
+      board: z9.string().describe("The leaderboard source ID (e.g. 'player:kills', 'player:deaths', 'player:playtime', 'mcmmo:power')"),
+      limit: z9.number().optional().describe("Number of top players to return (default 10, max 100)"),
+      nodeId: z9.string().optional().describe("Target server node ID (e.g. 'CSMP', 'LOBBY') when connected via Velocity hub")
+    },
+    async ({ board, limit = 10, nodeId }) => {
+      const session = getSession();
+      try {
+        const { client, effectiveNodeId } = await session.resolveTargetClient(nodeId);
+        const prefix = effectiveNodeId ? `[Target Node: @${effectiveNodeId}]
+` : "";
+        const cleanBoard = board.trim();
+        if (cleanBoard === "economy:vault" || cleanBoard === "economy:money" || cleanBoard === "money" || cleanBoard === "vault" || cleanBoard === "balance" || cleanBoard === "ajlb:vault_eco_balance") {
+          if (client.economy?.getTopBalance) {
+            const entries2 = await client.economy.getTopBalance(limit);
+            const formatted = (entries2 || []).map((e, idx) => ({
+              rank: idx + 1,
+              name: e.name || e.uuid,
+              value: typeof e.balance === "number" ? e.balance : e.value,
+              uuid: e.uuid
+            }));
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `${prefix}[Intercepted -> Native Vault Economy Top]
+` + JSON.stringify(formatted, null, 2)
+                }
+              ]
+            };
+          }
+        }
+        const customCurMatch = cleanBoard.startsWith("economy:") ? cleanBoard.replace("economy:", "") : ["coins", "candy", "tokens", "point", "points"].includes(cleanBoard.toLowerCase()) ? cleanBoard.toLowerCase() : null;
+        if (customCurMatch && customCurMatch !== "vault" && client.economy?.getCurrencyTop) {
+          try {
+            const res = await client.economy.getCurrencyTop(customCurMatch, limit);
+            if (Array.isArray(res) && res.length > 0) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `${prefix}[Native Currency Top: ${customCurMatch}]
+` + JSON.stringify(res, null, 2)
+                  }
+                ]
+              };
+            }
+          } catch {
+          }
+        }
+        if (!client.leaderboards?.getTop) {
+          throw new Error("Leaderboard client module is not available on this connection.");
+        }
+        const entries = await client.leaderboards.getTop(cleanBoard, limit);
+        return {
+          content: [
+            {
+              type: "text",
+              text: prefix + JSON.stringify(entries, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Failed to get leaderboard '${board}': ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+}
+
+// src/tools/auto-register.ts
+import { z as z10 } from "zod";
+var SKIP_MODULES = /* @__PURE__ */ new Set(["http", "connect"]);
+function registerAllSdkModules(server, registeredNames) {
+  const session = getSession();
+  const client = session.getClient();
+  let totalModules = 0;
+  let totalMethods = 0;
+  let newRegistered = 0;
+  for (const [modName, modInstance] of Object.entries(client)) {
+    if (SKIP_MODULES.has(modName)) continue;
+    if (!modInstance || typeof modInstance !== "object") continue;
+    const proto = Object.getPrototypeOf(modInstance);
+    if (!proto || proto === Object.prototype) continue;
+    const actionNames = Object.getOwnPropertyNames(proto).filter(
+      (name) => name !== "constructor" && typeof modInstance[name] === "function"
+    );
+    if (actionNames.length === 0) continue;
+    totalModules++;
+    for (const action of actionNames) {
+      totalMethods++;
+      const toolName = `${modName}_${action}`;
+      if (registeredNames.has(toolName)) continue;
+      registeredNames.add(toolName);
+      newRegistered++;
+      server.tool(
+        toolName,
+        `NoxAeApi ${modName}.${action}() action. Supports standalone server or Velocity node targeting via nodeId.`,
+        {
+          args: z10.array(z10.unknown()).optional().describe(`Arguments array for ${modName}.${action}()`),
+          nodeId: z10.string().optional().describe("Target server node ID (e.g. 'survival', 'lobby') when connected via Velocity hub")
+        },
+        async ({ args = [], nodeId }) => {
+          const currentSession = getSession();
+          try {
+            if (currentSession.isHub && currentSession.hubClient && nodeId) {
+              const forwardPath = `${modName}/${action}`;
+              try {
+                const res = await currentSession.hubClient.network.forward(nodeId, "POST", forwardPath, {
+                  body: args.length === 1 && typeof args[0] === "object" ? args[0] : { args }
+                });
+                return {
+                  content: [{ type: "text", text: JSON.stringify(res ?? "OK", null, 2) }]
+                };
+              } catch {
+                const res = await currentSession.hubClient.network.forward(nodeId, "GET", forwardPath);
+                return {
+                  content: [{ type: "text", text: JSON.stringify(res ?? "OK", null, 2) }]
+                };
+              }
+            }
+            const activeClient = currentSession.getClient();
+            const targetMod = activeClient[modName];
+            if (!targetMod || typeof targetMod[action] !== "function") {
+              throw new Error(`Method ${modName}.${action} not found on client.`);
+            }
+            const result = await targetMod[action].apply(targetMod, args);
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(result ?? "Success (void)", null, 2)
+                }
+              ]
+            };
+          } catch (err) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `Error in ${modName}.${action}(): ${err instanceof Error ? err.message : String(err)}`
+                }
+              ]
+            };
+          }
+        }
+      );
+    }
+  }
+  return { totalModules, totalMethods, newRegistered };
+}
+
+// src/index.ts
+async function main() {
+  try {
+    const config = resolveConfig();
+    console.error(
+      `[noxaeapi-mcp] Loaded profile: "${config.profileName}" (hub=${config.hub}, url=${config.baseUrl})`
+    );
+  } catch (err) {
+    console.error(
+      `[noxaeapi-mcp] Notice: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const server = new McpServer({
+    name: "noxaeapi-mcp",
+    version: "1.0.0"
+  });
+  const registeredNames = /* @__PURE__ */ new Set();
+  const track = (names) => names.forEach((n) => registeredNames.add(n));
+  registerNetworkTools(server);
+  track([
+    "network_status_all",
+    "network_node_status",
+    "network_broadcast",
+    "network_find_player",
+    "network_send_player"
+  ]);
+  registerServerTools(server);
+  track([
+    "server_get_status",
+    "server_dispatch_command",
+    "server_broadcast",
+    "server_get_whitelist",
+    "server_whitelist_add",
+    "server_whitelist_remove",
+    "server_get_ops",
+    "server_op_player",
+    "server_deop_player",
+    "server_get_logs",
+    "server_restart",
+    "server_ban_ip",
+    "server_tell_player"
+  ]);
+  registerPlayerTools(server);
+  track([
+    "players_list_online",
+    "players_get_info",
+    "players_kick",
+    "players_ban",
+    "players_unban",
+    "players_set_gamemode"
+  ]);
+  registerLuckPermsTools(server);
+  track([
+    "luckperms_get_player_info",
+    "luckperms_add_player_permission",
+    "luckperms_remove_player_permission",
+    "luckperms_set_player_primary_group",
+    "luckperms_list_groups"
+  ]);
+  registerEconomyTools(server);
+  track([
+    "economy_info",
+    "economy_get_balance",
+    "economy_pay",
+    "economy_debit",
+    "economy_get_top",
+    "economy_list_currencies",
+    "economy_get_currency_top"
+  ]);
+  registerLeaderboardTools(server);
+  track([
+    "leaderboards_list",
+    "leaderboards_get_top"
+  ]);
+  registerWorldTools(server);
+  track([
+    "worlds_list",
+    "worlds_set_time",
+    "worlds_set_weather",
+    "worlds_get_entities"
+  ]);
+  registerPluginTools(server);
+  track([
+    "plugins_list",
+    "plugins_get_info"
+  ]);
+  registerDispatchTools(server);
+  track(["noxae_list_modules", "noxae_call_action"]);
+  const stats = registerAllSdkModules(server, registeredNames);
+  console.error(
+    `[noxaeapi-mcp] Registered 100% of SDK: ${stats.totalModules} modules, ${registeredNames.size} total tools active.`
+  );
+  server.prompt(
+    "minecraft_sysadmin",
+    "Expert guidelines and decision trees for AI agents operating Minecraft servers and Velocity networks via NoxAeApi.",
+    {},
+    () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You are an expert Minecraft DevOps and Server Administrator assistant operating with NoxAeApi.
+Follow these operational guidelines to make accurate, reliable decisions:
+
+1. ENVIRONMENT & TOPOLOGY:
+   - When connected to a Velocity Network Hub proxy, multiple backend server nodes exist (e.g. CSMP, LOBBY).
+   - Use 'network_status_all' to discover active nodes, player counts, and node health.
+   - For node-specific actions (players, economy, leaderboards, commands, worlds), always supply the 'nodeId' parameter (e.g. 'CSMP').
+
+2. ECONOMY & BALANCE DECISION TREE:
+   - For primary money/Vault balance: use 'economy_get_top' (richest players) and 'economy_get_balance' (individual balance).
+   - For custom currencies (CoinsEngine, ExcellentEconomy): use 'economy_list_currencies' to find IDs, and 'economy_get_currency_top' for rankings.
+   - DO NOT use generic placeholder boards for money. Always prefer the dedicated 'economy_*' tools.
+
+3. LEADERBOARD DECISION TREE:
+   - For gameplay rankings (kills, deaths, playtime, mcmmo, auraskills): use 'leaderboards_get_top' with IDs like 'player:kills', 'player:deaths', 'player:playtime'.
+   - Use 'leaderboards_list' to discover valid game stats (it automatically filters internal noise).
+
+4. PERFORMANCE & DIAGNOSTICS:
+   - For lag or TPS inquiries: call 'server_get_status'. TPS: 20.0 is perfect, <18.0 is lagging.
+   - For errors or console activity: call 'server_get_logs'.
+
+5. COMMANDS & SAFETY:
+   - For executing commands: call 'server_dispatch_command' without the leading slash.
+   - For player permissions: call 'luckperms_add_player_permission' or 'luckperms_remove_player_permission'.`
+          }
+        }
+      ]
+    })
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[noxaeapi-mcp] Server running on stdio ready for AI agents");
+}
+main().catch((err) => {
+  console.error("[noxaeapi-mcp] Fatal error:", err);
+  process.exit(1);
+});