feat(mcp): add MCP server with 39 tools and unit test suite

Introduce a standalone MCP server binary (novawindows-mcp) that exposes the NovaWindows driver capabilities over the Model Context Protocol.

Author: y-schwab

lib/mcp/appium-manager.ts

@@ -0,0 +1,141 @@
+import * as http from 'node:http';
+import * as path from 'node:path';
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { McpConfig } from './config.js';
+
+const POLL_INTERVAL_MS = 500;
+const STARTUP_TIMEOUT_MS = 30_000;
+const SHUTDOWN_TIMEOUT_MS = 5_000;
+
+function isAppiumReady(host: string, port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+        const req = http.get(
+            { hostname: host, port, path: '/status', timeout: 2000 },
+            (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk; });
+                res.on('end', () => {
+                    try {
+                        const json = JSON.parse(body);
+                        resolve(json?.value?.ready === true);
+                    } catch {
+                        resolve(false);
+                    }
+                });
+            }
+        );
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
+
+function waitForAppium(host: string, port: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+        const poll = async () => {
+            if (await isAppiumReady(host, port)) {
+                resolve();
+                return;
+            }
+            if (Date.now() >= deadline) {
+                reject(new Error(`Appium did not become ready within ${STARTUP_TIMEOUT_MS / 1000}s on ${host}:${port}`));
+                return;
+            }
+            setTimeout(poll, POLL_INTERVAL_MS);
+        };
+        poll();
+    });
+}
+
+function resolveAppiumBinary(configBinary?: string): string {
+    if (configBinary) {return configBinary;}
+
+    // Prefer a local node_modules/.bin/appium (3 levels up from build/lib/mcp/)
+    const localBin = path.resolve(__dirname, '..', '..', '..', 'node_modules', '.bin', 'appium');
+    if (require('node:fs').existsSync(localBin)) {return localBin;}
+
+    // Fall back to appium on the system PATH (global install: npm install -g appium)
+    return 'appium';
+}
+
+export class AppiumManager {
+    private process: ChildProcess | null = null;
+    private managed = false;
+
+    async ensureRunning(config: McpConfig): Promise<void> {
+        const { appiumHost: host, appiumPort: port } = config;
+
+        if (await isAppiumReady(host, port)) {
+            process.stderr.write(`[MCP] Appium already running on ${host}:${port}\n`);
+            return;
+        }
+
+        if (!config.appiumAutoStart) {
+            throw new Error(
+                `Appium is not running on ${host}:${port}.\n` +
+                `Start it with: appium --port ${port}\n` +
+                `Or set APPIUM_AUTO_START=true to start it automatically.`
+            );
+        }
+
+        const binary = resolveAppiumBinary(config.appiumBinary);
+        process.stderr.write(`[MCP] Starting Appium: ${binary} --port ${port} --address ${host}\n`);
+
+        const child = spawn(binary, ['--port', String(port), '--address', host], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: process.platform === 'win32',
+        });
+
+        // Attach error handler immediately to prevent unhandled error crash
+        await new Promise<void>((resolve, reject) => {
+            child.once('error', (err) => {
+                reject(new Error(
+                    `Failed to spawn Appium binary at "${binary}": ${err.message}\n` +
+                    `Install Appium globally with: npm install -g appium\n` +
+                    `Or set APPIUM_BINARY to the full path of the appium executable.`
+                ));
+            });
+            // If no error fires synchronously, we're past the spawn phase
+            setImmediate(resolve);
+        });
+
+        this.process = child;
+        this.managed = true;
+
+        this.process.stdout?.on('data', (data: Buffer) => {
+            process.stderr.write(`[Appium] ${data}`);
+        });
+        this.process.stderr?.on('data', (data: Buffer) => {
+            process.stderr.write(`[Appium] ${data}`);
+        });
+        this.process.on('exit', (code) => {
+            process.stderr.write(`[MCP] Appium process exited with code ${code}\n`);
+        });
+
+        await waitForAppium(host, port);
+        process.stderr.write(`[MCP] Appium ready on ${host}:${port}\n`);
+    }
+
+    async shutdown(): Promise<void> {
+        if (!this.managed || !this.process) {return;}
+
+        process.stderr.write('[MCP] Stopping Appium...\n');
+        this.process.kill('SIGTERM');
+
+        const child = this.process;
+        await new Promise<void>((resolve) => {
+            const timeout = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, SHUTDOWN_TIMEOUT_MS);
+
+            child.on('exit', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+        });
+
+        this.process = null;
+        this.managed = false;
+    }
+}

lib/mcp/config.ts

@@ -0,0 +1,21 @@
+/** Infrastructure config — read from env vars at startup. */
+export interface McpConfig {
+    appiumHost: string;
+    appiumPort: number;
+    appiumAutoStart: boolean;
+    appiumBinary?: string;
+}
+
+export function loadConfig(): McpConfig {
+    const appiumPort = parseInt(process.env.APPIUM_PORT ?? '4723', 10);
+    if (isNaN(appiumPort) || appiumPort < 1 || appiumPort > 65535) {
+        throw new Error(`APPIUM_PORT must be a valid port number (1-65535), got: '${process.env.APPIUM_PORT}'`);
+    }
+
+    return {
+        appiumHost: process.env.APPIUM_HOST ?? '127.0.0.1',
+        appiumPort,
+        appiumAutoStart: process.env.APPIUM_AUTO_START !== 'false',
+        appiumBinary: process.env.APPIUM_BINARY,
+    };
+}

lib/mcp/errors.ts

@@ -0,0 +1,4 @@
+export function formatError(err: unknown): string {
+    if (err instanceof Error) {return `${err.constructor.name}: ${err.message}`;}
+    return String(err);
+}

lib/mcp/index.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { AppiumManager } from './appium-manager.js';
+import { AppiumSession } from './session.js';
+import { registerAllTools } from './tools/index.js';
+
+async function main() {
+    // Step 1: Load infrastructure config (host, port, auto-start only — no app required)
+    let config;
+    try {
+        config = loadConfig();
+    } catch (err) {
+        process.stderr.write(`[MCP] Configuration error: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+
+    // Step 2: Ensure Appium is running
+    const appiumManager = new AppiumManager();
+    try {
+        await appiumManager.ensureRunning(config);
+    } catch (err) {
+        process.stderr.write(`[MCP] Failed to start Appium: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+
+    // Step 3: Create session holder (no app launched yet — agent calls create_session)
+    const session = new AppiumSession(config);
+
+    // Step 4: Create and configure MCP server
+    const server = new McpServer({
+        name: 'novawindows-mcp',
+        version: '1.3.0',
+    });
+
+    // Step 5: Register all tools (including create_session / delete_session)
+    registerAllTools(server, session);
+
+    // Step 6: Shutdown handler
+    let shuttingDown = false;
+    async function shutdown(reason: string) {
+        if (shuttingDown) {return;}
+        shuttingDown = true;
+        process.stderr.write(`[MCP] Shutting down (${reason})...\n`);
+
+        if (session.isActive()) {
+            await Promise.race([
+                session.delete(),
+                new Promise<void>((resolve) => setTimeout(resolve, 10_000)),
+            ]);
+        }
+
+        await appiumManager.shutdown();
+        process.exit(0);
+    }
+
+    process.on('SIGINT', () => { shutdown('SIGINT'); });
+    process.on('SIGTERM', () => { shutdown('SIGTERM'); });
+    process.stdin.on('end', () => { shutdown('stdin closed'); });
+
+    // Step 7: Connect transport (stdout is owned by MCP protocol — all logs go to stderr)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[MCP] novawindows-mcp server ready. Call create_session to launch an app.\n');
+}
+
+main();

lib/mcp/session.ts

@@ -0,0 +1,75 @@
+import { remote } from 'webdriverio';
+import type { Browser } from 'webdriverio';
+import type { McpConfig } from './config.js';
+
+/** Session parameters provided by the agent via the create_session tool. */
+export interface SessionParams {
+    app: string;
+    appArguments?: string;
+    appWorkingDir?: string;
+    waitForAppLaunch?: number;
+    shouldCloseApp?: boolean;
+    implicitTimeout?: number;
+    delayAfterClick?: number;
+    delayBeforeClick?: number;
+    smoothPointerMove?: string;
+}
+
+export class AppiumSession {
+    private driver: Browser | null = null;
+
+    constructor(private readonly appiumConfig: McpConfig) {}
+
+    async create(params: SessionParams): Promise<void> {
+        if (this.driver) {
+            throw new Error('A session is already active. Call delete_session first.');
+        }
+
+        process.stderr.write(`[MCP] Creating Appium session for app: ${params.app}\n`);
+
+        const caps: Record<string, unknown> = {
+            platformName: 'Windows',
+            'appium:automationName': 'NovaWindows',
+            'appium:app': params.app,
+        };
+
+        if (params.appArguments !== undefined) {caps['appium:appArguments'] = params.appArguments;}
+        if (params.appWorkingDir !== undefined) {caps['appium:appWorkingDir'] = params.appWorkingDir;}
+        if (params.waitForAppLaunch !== undefined) {caps['appium:ms:waitForAppLaunch'] = params.waitForAppLaunch;}
+        if (params.shouldCloseApp !== undefined) {caps['appium:shouldCloseApp'] = params.shouldCloseApp;}
+        if (params.delayAfterClick !== undefined) {caps['appium:delayAfterClick'] = params.delayAfterClick;}
+        if (params.delayBeforeClick !== undefined) {caps['appium:delayBeforeClick'] = params.delayBeforeClick;}
+        if (params.smoothPointerMove !== undefined) {caps['appium:smoothPointerMove'] = params.smoothPointerMove;}
+
+        this.driver = await remote({
+            hostname: this.appiumConfig.appiumHost,
+            port: this.appiumConfig.appiumPort,
+            path: '/',
+            capabilities: caps as WebdriverIO.Capabilities,
+        });
+
+        await this.driver.setTimeout({ implicit: params.implicitTimeout ?? 1500 });
+        process.stderr.write('[MCP] Session created successfully\n');
+    }
+
+    async delete(): Promise<void> {
+        if (!this.driver) {return;}
+        try {
+            await this.driver.deleteSession();
+            process.stderr.write('[MCP] Session deleted\n');
+        } catch (err) {
+            process.stderr.write(`[MCP] Warning: session delete failed: ${err}\n`);
+        } finally {
+            this.driver = null;
+        }
+    }
+
+    isActive(): boolean {
+        return this.driver !== null;
+    }
+
+    getDriver(): Browser {
+        if (!this.driver) {throw new Error('No active session. Call create_session first.');}
+        return this.driver;
+    }
+}