@pyworkload/3x-ui-mcp 0.4.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @pyworkload/3x-ui-mcp
+
+MCP (Model Context Protocol) server for [3x-ui](https://github.com/MHSanaei/3x-ui) —
+an Xray/V2Ray proxy management panel. It exposes the panel's HTTP API as 166 MCP
+tools, so an LLM agent can manage inbounds, clients, routing rules, balancers,
+nodes and the Xray service itself.
+
+This package ships prebuilt binaries: nothing is compiled and nothing is
+downloaded at install time. The Go toolchain is not required.
+
+## Use it
+
+```json
+{
+  "mcpServers": {
+    "3x-ui": {
+      "command": "npx",
+      "args": ["-y", "@pyworkload/3x-ui-mcp"],
+      "env": {
+        "XUI_HOST": "http://localhost:2053",
+        "XUI_USERNAME": "admin",
+        "XUI_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add 3x-ui \
+  --env XUI_HOST=http://localhost:2053 \
+  --env XUI_USERNAME=admin \
+  --env XUI_PASSWORD=your-password \
+  -- npx -y @pyworkload/3x-ui-mcp
+```
+
+Provide either `XUI_USERNAME` + `XUI_PASSWORD` or `XUI_API_TOKEN`. Optional:
+`XUI_BASE_PATH`, `XUI_LOG_LEVEL`, and `XUI_TOOLSETS` to load only the tool groups
+you need instead of all 166.
+
+Requires 3x-ui **v3.3.0+**. Some tools need newer panels; the
+[main README](https://github.com/pyworkload/3x-ui-mcp#panel-versions) has the table.
+
+## Platforms
+
+Linux, macOS and Windows on x64 and arm64. The binary is statically linked
+(`CGO_ENABLED=0`), so the Linux build runs on glibc and musl alike.
+
+The matching binary arrives as an optional dependency, one package per platform,
+so an install pulls exactly one of them. Installing with `--omit=optional` skips
+it and the CLI will say so rather than failing obscurely.
+
+## Documentation
+
+Full tool reference, agent skills and panel-version notes:
+<https://github.com/pyworkload/3x-ui-mcp>
+
+MIT licensed.

package/bin/xui-mcp.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// Locates the prebuilt xui-mcp binary for this platform and hands the process
+// over to it. The binary ships in a per-platform package pulled in through
+// optionalDependencies, so nothing is downloaded or compiled at install time.
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+// process.platform + process.arch -> the package carrying that build.
+const PACKAGES = {
+  'darwin arm64': '@pyworkload/3x-ui-mcp-darwin-arm64',
+  'darwin x64': '@pyworkload/3x-ui-mcp-darwin-x64',
+  'linux arm64': '@pyworkload/3x-ui-mcp-linux-arm64',
+  'linux x64': '@pyworkload/3x-ui-mcp-linux-x64',
+  'win32 arm64': '@pyworkload/3x-ui-mcp-win32-arm64',
+  'win32 x64': '@pyworkload/3x-ui-mcp-win32-x64',
+};
+
+function fail(message) {
+  // stdout carries the MCP protocol, so diagnostics go to stderr only.
+  process.stderr.write(`3x-ui-mcp: ${message}\n`);
+  process.exit(1);
+}
+
+function resolveBinary() {
+  const target = `${process.platform} ${process.arch}`;
+  const pkg = PACKAGES[target];
+  if (!pkg) {
+    fail(
+      `no prebuilt binary for ${target}. Supported: ${Object.keys(PACKAGES).join(', ')}. ` +
+        'Build from source instead: go install github.com/pyworkload/3x-ui-mcp/cmd/xui-mcp@latest',
+    );
+  }
+
+  const exe = process.platform === 'win32' ? 'xui-mcp.exe' : 'xui-mcp';
+  try {
+    // Resolve through package.json: the binary itself is not a module, and this
+    // works no matter how the installer laid the tree out (nested or hoisted).
+    return path.join(path.dirname(require.resolve(`${pkg}/package.json`)), 'bin', exe);
+  } catch {
+    fail(
+      `the platform package ${pkg} is missing. It installs automatically as an optional ` +
+        'dependency, so this usually means installation ran with --no-optional or ' +
+        '--omit=optional. Reinstall with optional dependencies enabled.',
+    );
+  }
+}
+
+const binary = resolveBinary();
+
+// stdio: 'inherit' gives the Go process the real file descriptors, which the MCP
+// stdio transport needs — anything piped through Node here would add buffering
+// between the client and the server.
+const result = spawnSync(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+if (result.error) {
+  if (result.error.code === 'ENOENT') {
+    fail(`binary not found at ${binary}. Reinstall the package.`);
+  }
+  if (result.error.code === 'EACCES') {
+    fail(`binary at ${binary} is not executable. Reinstall the package.`);
+  }
+  fail(`failed to start ${binary}: ${result.error.message}`);
+}
+
+// Report a signal death the way a shell would, so a supervisor sees the real cause.
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pyworkload/3x-ui-mcp",
+  "version": "0.4.3",
+  "description": "MCP server for the 3x-ui Xray/V2Ray proxy panel: manage inbounds, clients, routing, nodes and Xray itself from an LLM agent.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "3x-ui",
+    "xray",
+    "v2ray",
+    "vless",
+    "reality",
+    "proxy",
+    "vpn"
+  ],
+  "homepage": "https://github.com/pyworkload/3x-ui-mcp#readme",
+  "bugs": "https://github.com/pyworkload/3x-ui-mcp/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pyworkload/3x-ui-mcp.git"
+  },
+  "license": "MIT",
+  "author": "pyworkload",
+  "type": "commonjs",
+  "bin": {
+    "3x-ui-mcp": "bin/xui-mcp.js",
+    "xui-mcp": "bin/xui-mcp.js"
+  },
+  "files": [
+    "bin/xui-mcp.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "optionalDependencies": {
+    "@pyworkload/3x-ui-mcp-darwin-arm64": "0.4.3",
+    "@pyworkload/3x-ui-mcp-darwin-x64": "0.4.3",
+    "@pyworkload/3x-ui-mcp-linux-arm64": "0.4.3",
+    "@pyworkload/3x-ui-mcp-linux-x64": "0.4.3",
+    "@pyworkload/3x-ui-mcp-win32-arm64": "0.4.3",
+    "@pyworkload/3x-ui-mcp-win32-x64": "0.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}