@voltajeba/selenium-mcp 0.0.0-stage → 1.0.26

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @voltajeba/selenium-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI coding assistants (Claude Code, Cursor, VS Code, Claude Desktop) drive a real Chrome, Edge, or Firefox through Selenium WebDriver — built for Java/Selenium/REST Assured test automation engineers.
+
+This package bundles its own Java runtime, so **you don't need Java installed**. All you need is Node.js (for `npx`) and a browser.
+
+## Setup
+
+**Claude Code / Cursor / Claude Desktop** (`.mcp.json`, `mcp.json`, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "selenium-mcp": {
+      "command": "npx",
+      "args": ["-y", "@voltajeba/selenium-mcp"]
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "selenium-mcp": {
+      "command": "npx",
+      "args": ["-y", "@voltajeba/selenium-mcp"]
+    }
+  }
+}
+```
+
+On **native Windows**, Claude Code needs `npx` wrapped in `cmd /c`: `"command": "cmd", "args": ["/c", "npx", "-y", "@voltajeba/selenium-mcp"]`.
+
+Or, in Claude Code, from a terminal: `claude mcp add selenium-mcp -- npx -y @voltajeba/selenium-mcp`
+
+The first start downloads about 90 MB (the runtime for your OS, plus the server). If your client times out on that first start, restart the server once — or pre-download it with `npx -y @voltajeba/selenium-mcp --version` in a terminal.
+
+Supported platforms: Windows x64, Linux x64 (glibc), macOS Intel, macOS Apple Silicon.
+
+## Options
+
+Any extra arguments are passed to the server, e.g. to load fewer tools:
+
+```json
+"args": ["-y", "@voltajeba/selenium-mcp", "--selenium.mcp.exclude-tool-groups=api,network,cookies"]
+```
+
+Logs go to `~/.selenium-mcp/mcp-server.log`.
+
+Full tool reference and documentation: [selenium-mcp.xpathy.uk](https://selenium-mcp.xpathy.uk/) · Source: [GitHub](https://github.com/Volta-Jebaprashanth/selenium-mcp)

package/bin/selenium-mcp.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Launches the selenium-mcp jar on the Java runtime bundled in the matching
+// @voltajeba/selenium-mcp-<platform>-<arch> package. stdout carries the MCP protocol,
+// so this script must never write to it - diagnostics go to stderr only.
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { version } = require('../package.json');
+const SUPPORTED = ['win32-x64', 'linux-x64', 'darwin-x64', 'darwin-arm64'];
+const target = `${process.platform}-${process.arch}`;
+const platformPackage = `@voltajeba/selenium-mcp-${target}`;
+
+function resolvePlatformPackage() {
+  try {
+    return path.dirname(require.resolve(`${platformPackage}/package.json`));
+  } catch {
+    return null;
+  }
+}
+
+// npm skips an optionalDependency it can't fetch (e.g. a run that raced a release
+// still being processed by the registry), and npx then reuses that incomplete install
+// from its cache on every later run. When we're running from the npx cache, install
+// the missing platform package into it so the next start doesn't hit this again.
+function repairNpxInstall() {
+  const npxInstallDir = path.resolve(__dirname, '..', '..', '..', '..');
+  const npmCli = process.env.npm_execpath;
+  if (path.basename(path.dirname(npxInstallDir)) !== '_npx' || !npmCli || !/npm-cli\.js$/.test(npmCli)) {
+    return null;
+  }
+  process.stderr.write(`selenium-mcp: ${platformPackage} is missing from the npx cache - installing it...\n`);
+  const result = spawnSync(
+    process.execPath,
+    [npmCli, 'install', '--no-save', '--no-audit', '--no-fund', `${platformPackage}@${version}`],
+    // npm's own output goes to stderr (fd 2): stdout belongs to the MCP client.
+    { cwd: npxInstallDir, stdio: ['ignore', 2, 2] }
+  );
+  return result.status === 0 ? resolvePlatformPackage() : null;
+}
+
+let packageDir = resolvePlatformPackage();
+if (!packageDir && SUPPORTED.includes(target)) {
+  packageDir = repairNpxInstall();
+}
+if (!packageDir) {
+  const npxInstallDir = path.resolve(__dirname, '..', '..', '..', '..');
+  process.stderr.write(
+    SUPPORTED.includes(target)
+      ? `selenium-mcp: ${platformPackage}@${version} is not installed, and installing it failed.\n` +
+          (path.basename(path.dirname(npxInstallDir)) === '_npx'
+            ? `Delete ${npxInstallDir} and restart the server so npx reinstalls it.\n`
+            : `Reinstall @voltajeba/selenium-mcp without --omit=optional / --no-optional.\n`)
+      : `selenium-mcp: no bundled Java runtime for ${target}. Supported: ${SUPPORTED.join(', ')}.\n` +
+          'On other platforms, install Java 21+ and run the jar from ' +
+          'https://github.com/Volta-Jebaprashanth/selenium-mcp/releases/latest\n'
+  );
+  process.exit(1);
+}
+
+const isWindows = process.platform === 'win32';
+const java = path.join(packageDir, 'runtime', 'bin', isWindows ? 'java.exe' : 'java');
+const jar = path.join(packageDir, 'selenium-mcp.jar');
+
+if (!isWindows) {
+  // Package managers don't always preserve the executable bit. jspawnhelper is what
+  // the JVM uses to start child processes such as chromedriver.
+  for (const file of [java, path.join(packageDir, 'runtime', 'lib', 'jspawnhelper')]) {
+    try {
+      fs.chmodSync(file, 0o755);
+    } catch {
+      // Already executable or not present; java will report a real problem itself.
+    }
+  }
+}
+
+const args = process.argv.slice(2);
+
+if (args[0] === '--version') {
+  // Terminal-only convenience (an MCP client never passes it): lets users pre-download
+  // the package with `npx -y @voltajeba/selenium-mcp --version` before the first real start.
+  process.stdout.write(`@voltajeba/selenium-mcp ${version} (${platformPackage})\n`);
+  process.exit(0);
+}
+
+if (!args.some((arg) => arg.startsWith('--logging.file.name'))) {
+  // The jar's default log path is relative to the working directory, which an MCP
+  // client may set to somewhere unexpected or read-only.
+  const logDir = path.join(os.homedir(), '.selenium-mcp');
+  try {
+    fs.mkdirSync(logDir, { recursive: true });
+    args.push(`--logging.file.name=${path.join(logDir, 'mcp-server.log')}`);
+  } catch {
+    // Fall back to the jar's default log location.
+  }
+}
+
+// The server closes its browsers when it shuts down cleanly: on a signal (SIGTERM etc. run the
+// JVM's shutdown hooks) or at the end of stdin. On Windows neither survives a plain spawn: Node
+// puts the child in a job object that is killed outright along with this launcher, and child.kill()
+// is a hard TerminateProcess, so an MCP client killing the launcher would leave chromedriver and
+// browser processes behind. There the server runs detached, outside the job, and reads stdin through
+// this launcher, so it sees end-of-input - and shuts down cleanly - when the launcher goes away.
+const child = isWindows
+  ? spawn(java, ['-jar', jar, ...args], { stdio: ['pipe', 'inherit', 'inherit'], detached: true, windowsHide: true })
+  : spawn(java, ['-jar', jar, ...args], { stdio: 'inherit' });
+
+if (isWindows) {
+  process.stdin.pipe(child.stdin);
+  child.stdin.on('error', () => {
+    // The server already exited; its exit handler below ends this process.
+  });
+}
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    if (!isWindows) {
+      child.kill(signal);
+      return;
+    }
+    child.stdin.end();
+    setTimeout(() => child.kill(), 10000).unref();
+  });
+}
+
+child.on('error', (err) => {
+  process.stderr.write(`selenium-mcp: failed to start ${java}: ${err.message}\n`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  process.exit(signal ? 128 + (os.constants.signals[signal] ?? 0) : code ?? 1);
+});

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@voltajeba/selenium-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.26",
+  "description": "Selenium MCP server for Java/Selenium test automation engineers, with a Java runtime bundled - no JDK install needed.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "selenium",
+    "webdriver",
+    "test-automation"
+  ],
+  "homepage": "https://selenium-mcp.xpathy.uk/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Volta-Jebaprashanth/selenium-mcp.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "selenium-mcp": "bin/selenium-mcp.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@voltajeba/selenium-mcp-win32-x64": "1.0.26",
+    "@voltajeba/selenium-mcp-linux-x64": "1.0.26",
+    "@voltajeba/selenium-mcp-darwin-x64": "1.0.26",
+    "@voltajeba/selenium-mcp-darwin-arm64": "1.0.26"
+  },
+  "mcpName": "io.github.volta-jebaprashanth/selenium-mcp"
+}