@sveltium/mcp 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# nwjs-mcp
+
+MCP (Model Context Protocol) server for NW.js application testing and automation.
+
+This package enables AI assistants (like Claude Code) to interact with and test NW.js applications, addressing the limitation that browser automation tools like Playwright don't work with NW.js.
+
+## Installation
+
+```bash
+npm install nwjs-mcp
+```
+
+## Quick Start
+
+Add to your NW.js app's `node-main` script:
+
+```javascript
+// main.js (node-main in package.json)
+if (process.argv.includes('--mcp')) {
+  require('nwjs-mcp').startServer({
+    mode: 'stdio',
+    native: true
+  })
+}
+```
+
+Or in your `package.json`:
+
+```json
+{
+  "main": "index.html",
+  "node-main": "mcp-bootstrap.js"
+}
+```
+
+## Claude Code Integration
+
+Add to your `.claude.json` or Claude Code settings:
+
+```json
+{
+  "mcpServers": {
+    "nwjs": {
+      "command": "path/to/nw.exe",
+      "args": ["path/to/your-app", "--mcp"],
+      "env": {
+        "NWJS_MCP_MODE": "stdio"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `browser_snapshot` | Get accessibility tree of the page with element refs |
+| `browser_take_screenshot` | Capture page screenshot |
+| `browser_click` | Click an element by ref |
+| `browser_type` | Type text into an element |
+| `browser_press_key` | Press a keyboard key |
+| `browser_evaluate` | Execute JavaScript on the page |
+| `browser_navigate` | Navigate to a URL |
+| `browser_console_messages` | Get console log history |
+| `browser_resize` | Resize the window |
+| `browser_wait_for` | Wait for text or time |
+| `browser_fill_form` | Fill multiple form fields |
+
+## API
+
+### startServer(options)
+
+Start the MCP server.
+
+```javascript
+var server = require('nwjs-mcp').startServer({
+  mode: 'stdio',     // 'stdio' or 'http'
+  port: 3000,        // HTTP port (only for http mode)
+  native: true       // Try to load native addon
+})
+```
+
+### createServer(options)
+
+Create server instance without starting.
+
+```javascript
+var server = require('nwjs-mcp').createServer({ mode: 'http' })
+// Start later
+server.start()
+// Stop when done
+server.stop()
+```
+
+## Server Modes
+
+### stdio Mode (Recommended)
+
+Uses stdin/stdout for communication. Best for integration with Claude Code.
+
+```javascript
+startServer({ mode: 'stdio' })
+```
+
+### HTTP Mode
+
+Runs an HTTP server for network access.
+
+```javascript
+startServer({ mode: 'http', port: 3000 })
+```
+
+## Native Addon (Optional)
+
+For enhanced features like system-level input (useful for testing native dialogs), install the native addon:
+
+```bash
+npm install @aspect/nwjs-addons
+```
+
+Native features:
+- System-level mouse clicks (for native dialogs)
+- System-level keyboard input
+- Window management (focus, minimize)
+- Screen capture
+
+The server gracefully falls back to JS-only mode if native addon is unavailable.
+
+## Example Usage with Claude Code
+
+Once configured, you can ask Claude Code to:
+
+```
+"Test my NW.js app - click the login button and verify the form appears"
+```
+
+Claude Code will:
+1. Use `browser_snapshot` to see the page structure
+2. Use `browser_click` to click the login button
+3. Use `browser_snapshot` again to verify the form
+4. Report the results
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sveltium/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for NW.js application testing and automation",
+  "main": "src/client/index.js",
+  "type": "commonjs",
+  "bin": {
+    "nwjs-mcp": "./src/server/index.js"
+  },
+  "exports": {
+    ".": "./src/client/index.js",
+    "./client": "./src/client/index.js",
+    "./server": "./src/server/index.js"
+  },
+  "files": [
+    "src/**/*.js",
+    "scripts/**/*.js",
+    "types/**/*.d.ts"
+  ],
+  "scripts": {
+    "start": "node src/server/index.js",
+    "postinstall": "node scripts/postinstall.js",
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "nwjs",
+    "mcp",
+    "model-context-protocol",
+    "testing",
+    "automation",
+    "claude"
+  ],
+  "author": {
+    "name": "Oosuke Ren",
+    "email": "oosukeren@gmail.com",
+    "url": "https://github.com/OosukeRen"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.0.0"
+  },
+  "peerDependencies": {
+    "nw": "*"
+  },
+  "peerDependenciesMeta": {
+    "nw": {
+      "optional": true
+    }
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Postinstall script that configures .mcp.json for Claude Code integration
+ */
+
+var fs = require('fs')
+var path = require('path')
+
+// Find the project root - use npm's INIT_CWD which is where npm was run from
+function findProjectRoot() {
+  // INIT_CWD is set by npm to the directory where `npm install` was run
+  if (process.env.INIT_CWD) {
+    return process.env.INIT_CWD
+  }
+
+  // Fallback: use current working directory
+  return process.cwd()
+}
+
+// Get the path to the main server index.js in node_modules
+function getServerPath(projectRoot) {
+  // Check if we're installed in node_modules of the project (with scope)
+  var nodeModulesPath = path.join(projectRoot, 'node_modules', '@sveltium', 'nwjs-mcp', 'src', 'server', 'index.js')
+
+  // Also check without scope
+  var nodeModulesPathNoScope = path.join(projectRoot, 'node_modules', 'nwjs-mcp', 'src', 'server', 'index.js')
+
+  if (fs.existsSync(nodeModulesPath)) {
+    return nodeModulesPath
+  }
+
+  if (fs.existsSync(nodeModulesPathNoScope)) {
+    return nodeModulesPathNoScope
+  }
+
+  // Fallback: use relative to this script (for dev mode)
+  var localPath = path.join(__dirname, '..', 'src', 'server', 'index.js')
+  return path.resolve(localPath)
+}
+
+function main() {
+  // Skip for global installs
+  if (process.env.npm_config_global === 'true') {
+    console.log('[nwjs-mcp] Global install detected. Run "nwjs-mcp init" in your project to configure .mcp.json')
+    return
+  }
+
+  var projectRoot = findProjectRoot()
+  if (!projectRoot) {
+    console.log('[nwjs-mcp] Could not find project root, skipping .mcp.json configuration')
+    return
+  }
+
+  var mcpJsonPath = path.join(projectRoot, '.mcp.json')
+  var serverPath = getServerPath(projectRoot)
+
+  var mcpConfig = {}
+
+  // Read existing .mcp.json if it exists
+  if (fs.existsSync(mcpJsonPath)) {
+    try {
+      mcpConfig = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'))
+    } catch (e) {
+      console.log('[nwjs-mcp] Could not parse existing .mcp.json, creating new one')
+      mcpConfig = {}
+    }
+  }
+
+  // Ensure mcpServers object exists
+  if (!mcpConfig.mcpServers) {
+    mcpConfig.mcpServers = {}
+  }
+
+  // Add or update nwjs entry
+  mcpConfig.mcpServers.nwjs = {
+    command: 'node',
+    args: [serverPath]
+  }
+
+  // Write .mcp.json
+  try {
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + '\n')
+    console.log('[nwjs-mcp] Configured .mcp.json at:', mcpJsonPath)
+    console.log('[nwjs-mcp] Server path:', serverPath)
+    console.log('[nwjs-mcp] To use nwjs_start_app, either:')
+    console.log('  - Install "nw" package: npm install nw')
+    console.log('  - Or set NWJS_PATH in .env file')
+    console.log('  - Or add NWJS_PATH env to .mcp.json')
+  } catch (e) {
+    console.log('[nwjs-mcp] Could not write .mcp.json:', e.message)
+  }
+}
+
+main()

package/src/client/dom/console-capture.js

@@ -0,0 +1,143 @@
+'use strict'
+
+/**
+ * Console Capture
+ *
+ * Captures console messages for retrieval
+ */
+
+function ConsoleCapture(win) {
+  this.win = win
+  this.messages = []
+  this.maxMessages = 1000
+  this.originalConsole = {}
+  this.started = false
+}
+
+/**
+ * Start capturing console messages
+ */
+ConsoleCapture.prototype.start = function() {
+  if (this.started) {
+    return
+  }
+
+  var self = this
+  var console = this.win.console
+
+  // Store original methods
+  this.originalConsole.log = console.log
+  this.originalConsole.info = console.info
+  this.originalConsole.warn = console.warn
+  this.originalConsole.error = console.error
+  this.originalConsole.debug = console.debug
+
+  // Override console methods
+  console.log = function() {
+    self._capture('info', arguments)
+    self.originalConsole.log.apply(console, arguments)
+  }
+
+  console.info = function() {
+    self._capture('info', arguments)
+    self.originalConsole.info.apply(console, arguments)
+  }
+
+  console.warn = function() {
+    self._capture('warning', arguments)
+    self.originalConsole.warn.apply(console, arguments)
+  }
+
+  console.error = function() {
+    self._capture('error', arguments)
+    self.originalConsole.error.apply(console, arguments)
+  }
+
+  console.debug = function() {
+    self._capture('debug', arguments)
+    self.originalConsole.debug.apply(console, arguments)
+  }
+
+  this.started = true
+}
+
+/**
+ * Stop capturing console messages
+ */
+ConsoleCapture.prototype.stop = function() {
+  if (!this.started) {
+    return
+  }
+
+  var console = this.win.console
+
+  // Restore original methods
+  console.log = this.originalConsole.log
+  console.info = this.originalConsole.info
+  console.warn = this.originalConsole.warn
+  console.error = this.originalConsole.error
+  console.debug = this.originalConsole.debug
+
+  this.started = false
+}
+
+/**
+ * Capture a console message
+ */
+ConsoleCapture.prototype._capture = function(level, args) {
+  var message = ''
+
+  for (var i = 0; i < args.length; i++) {
+    if (i > 0) message += ' '
+
+    var arg = args[i]
+    if (typeof arg === 'object') {
+      try {
+        message += JSON.stringify(arg)
+      } catch (e) {
+        message += String(arg)
+      }
+    } else {
+      message += String(arg)
+    }
+  }
+
+  this.messages.push({
+    level: level,
+    message: message,
+    timestamp: Date.now()
+  })
+
+  // Trim old messages
+  if (this.messages.length > this.maxMessages) {
+    this.messages = this.messages.slice(-this.maxMessages)
+  }
+}
+
+/**
+ * Get messages at or above a given level
+ */
+ConsoleCapture.prototype.getMessages = function(minLevel) {
+  var levels = ['debug', 'info', 'warning', 'error']
+  var minIndex = levels.indexOf(minLevel || 'info')
+
+  var result = []
+  for (var i = 0; i < this.messages.length; i++) {
+    var msg = this.messages[i]
+    var msgIndex = levels.indexOf(msg.level)
+    if (msgIndex >= minIndex) {
+      result.push('[' + msg.level.toUpperCase() + '] ' + msg.message)
+    }
+  }
+
+  return result
+}
+
+/**
+ * Clear all captured messages
+ */
+ConsoleCapture.prototype.clear = function() {
+  this.messages = []
+}
+
+module.exports = ConsoleCapture

package/src/client/dom/element-finder.js

@@ -0,0 +1,59 @@
+'use strict'
+
+/**
+ * Element Finder
+ *
+ * Finds elements by ref (populated by SnapshotBuilder)
+ */
+
+// Global ref map (shared with SnapshotBuilder instances)
+var _globalRefMap = {}
+
+function ElementFinder(win) {
+  this.win = win
+  this.doc = win.document
+}
+
+/**
+ * Set the global ref map (called by SnapshotBuilder after building)
+ */
+ElementFinder.setRefMap = function(refMap) {
+  _globalRefMap = refMap
+}
+
+/**
+ * Find element by ref
+ */
+ElementFinder.prototype.findByRef = function(ref) {
+  if (ref === 'page') {
+    return this.doc.body
+  }
+  return _globalRefMap[ref] || null
+}
+
+/**
+ * Get bounding box of element
+ */
+ElementFinder.prototype.getBounds = function(element) {
+  var rect = element.getBoundingClientRect()
+  return {
+    x: rect.left,
+    y: rect.top,
+    width: rect.width,
+    height: rect.height
+  }
+}
+
+/**
+ * Check if element is visible
+ */
+ElementFinder.prototype.isVisible = function(element) {
+  var style = this.win.getComputedStyle(element)
+  if (style.display === 'none' || style.visibility === 'hidden') {
+    return false
+  }
+  var rect = element.getBoundingClientRect()
+  return rect.width > 0 && rect.height > 0
+}
+
+module.exports = ElementFinder

package/src/client/dom/event-dispatcher.js

@@ -0,0 +1,180 @@
+'use strict'
+
+/**
+ * Event Dispatcher
+ *
+ * Dispatches DOM events to elements
+ */
+
+function EventDispatcher(win) {
+  this.win = win
+  this.doc = win.document
+}
+
+/**
+ * Click an element
+ */
+EventDispatcher.prototype.click = function(element, button, doubleClick) {
+  var buttonCode = 0
+  if (button === 'right') buttonCode = 2
+  if (button === 'middle') buttonCode = 1
+
+  // Focus the element if focusable
+  if (element.focus) {
+    element.focus()
+  }
+
+  // Get element center
+  var rect = element.getBoundingClientRect()
+  var x = rect.left + rect.width / 2
+  var y = rect.top + rect.height / 2
+
+  // Dispatch mouse events
+  this._dispatchMouse(element, 'mousedown', x, y, buttonCode)
+  this._dispatchMouse(element, 'mouseup', x, y, buttonCode)
+  this._dispatchMouse(element, 'click', x, y, buttonCode)
+
+  if (doubleClick) {
+    this._dispatchMouse(element, 'mousedown', x, y, buttonCode)
+    this._dispatchMouse(element, 'mouseup', x, y, buttonCode)
+    this._dispatchMouse(element, 'click', x, y, buttonCode)
+    this._dispatchMouse(element, 'dblclick', x, y, buttonCode)
+  }
+}
+
+/**
+ * Type text into an element
+ */
+EventDispatcher.prototype.type = function(element, text, slowly, submit) {
+  // Focus the element
+  if (element.focus) {
+    element.focus()
+  }
+
+  if (slowly) {
+    // Type character by character
+    for (var i = 0; i < text.length; i++) {
+      var char = text[i]
+      this._dispatchKey(element, 'keydown', char)
+      this._dispatchKey(element, 'keypress', char)
+
+      // Update value
+      if (element.value !== undefined) {
+        element.value += char
+      }
+
+      this._dispatchKey(element, 'keyup', char)
+      this.dispatchInput(element)
+    }
+  } else {
+    // Set value directly
+    if (element.value !== undefined) {
+      element.value = text
+    } else if (element.contentEditable === 'true') {
+      element.textContent = text
+    }
+    this.dispatchInput(element)
+  }
+
+  if (submit) {
+    this.pressKey('Enter', element)
+  }
+}
+
+/**
+ * Press a key
+ */
+EventDispatcher.prototype.pressKey = function(key, target) {
+  target = target || this.doc.activeElement || this.doc.body
+
+  this._dispatchKey(target, 'keydown', key)
+  this._dispatchKey(target, 'keypress', key)
+  this._dispatchKey(target, 'keyup', key)
+
+  // Handle Enter key submitting forms
+  if (key === 'Enter') {
+    var form = target.form || target.closest('form')
+    if (form) {
+      var submitEvent = new this.win.Event('submit', {
+        bubbles: true,
+        cancelable: true
+      })
+      form.dispatchEvent(submitEvent)
+    }
+  }
+}
+
+/**
+ * Dispatch input event
+ */
+EventDispatcher.prototype.dispatchInput = function(element) {
+  var inputEvent = new this.win.Event('input', {
+    bubbles: true,
+    cancelable: true
+  })
+  element.dispatchEvent(inputEvent)
+
+  var changeEvent = new this.win.Event('change', {
+    bubbles: true,
+    cancelable: true
+  })
+  element.dispatchEvent(changeEvent)
+}
+
+/**
+ * Dispatch mouse event
+ */
+EventDispatcher.prototype._dispatchMouse = function(element, type, x, y, button) {
+  var event = new this.win.MouseEvent(type, {
+    view: this.win,
+    bubbles: true,
+    cancelable: true,
+    clientX: x,
+    clientY: y,
+    button: button
+  })
+  element.dispatchEvent(event)
+}
+
+/**
+ * Dispatch keyboard event
+ */
+EventDispatcher.prototype._dispatchKey = function(element, type, key) {
+  var keyCode = key.length === 1 ? key.charCodeAt(0) : this._getKeyCode(key)
+
+  var event = new this.win.KeyboardEvent(type, {
+    view: this.win,
+    bubbles: true,
+    cancelable: true,
+    key: key,
+    code: key.length === 1 ? 'Key' + key.toUpperCase() : key,
+    keyCode: keyCode,
+    which: keyCode
+  })
+  element.dispatchEvent(event)
+}
+
+/**
+ * Get key code for special keys
+ */
+EventDispatcher.prototype._getKeyCode = function(key) {
+  var codes = {
+    'Enter': 13,
+    'Tab': 9,
+    'Escape': 27,
+    'Backspace': 8,
+    'Delete': 46,
+    'ArrowUp': 38,
+    'ArrowDown': 40,
+    'ArrowLeft': 37,
+    'ArrowRight': 39,
+    'Home': 36,
+    'End': 35,
+    'PageUp': 33,
+    'PageDown': 34,
+    'Space': 32
+  }
+  return codes[key] || 0
+}
+
+module.exports = EventDispatcher