Merge pull request #11 from verisoft-ai/feat/mcp-server

Add MCP server (novawindows-mcp)

Exposes the NovaWindows driver as an MCP server, allowing AI agents to automate Windows desktop apps directly via the Model Context Protocol 39 tools across 8 domains: session lifecycle, app launch/close, element finding, interaction (click, type, scroll, drag), inspection, window management, clipboard, and advanced UIA patterns.

Includes a full unit test suite and .mcp.json for zero-config local setup.

Author: y-schwab

.gitignore

@@ -1,3 +1,6 @@
+# Claude Code local settings
+.claude/
+
 # Logs
 logs
 *.log

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "novawindows-mcp": {
+      "command": "node",
+      "args": ["./build/lib/mcp/index.js"],
+      "env": {}
+    }
+  }
+}

lib/mcp/config.ts

@@ -0,0 +1,17 @@
+/** Infrastructure config — read from env vars at startup. */
+export interface McpConfig {
+    appiumHost: string;
+    appiumPort: number;
+}
+
+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,
+    };
+}

lib/mcp/constants.ts

@@ -0,0 +1,2 @@
+/** W3C WebDriver element reference key */
+export const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';

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,87 @@
+#!/usr/bin/env node
+import * as http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { AppiumSession } from './session.js';
+import { registerAllTools } from './tools/index.js';
+
+function checkAppiumReachable(host: string, port: number): Promise<boolean> {
+    return new Promise((resolve) => {
+        const req = http.get(
+            { hostname: host, port, path: '/status', timeout: 3000 },
+            (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk; });
+                res.on('end', () => {
+                    try { resolve(JSON.parse(body)?.value?.ready === true); }
+                    catch { resolve(false); }
+                });
+            }
+        );
+        req.on('error', () => resolve(false));
+        req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+}
+
+async function main() {
+    // Step 1: Load infrastructure config (host, port — 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: Verify Appium is reachable
+    const { appiumHost: host, appiumPort: port } = config;
+    if (!await checkAppiumReachable(host, port)) {
+        process.stderr.write(
+            `[MCP] Appium is not running on ${host}:${port}.\n` +
+            `Start it first with: appium --port ${port}\n`
+        );
+        process.exit(1);
+    }
+    process.stderr.write(`[MCP] Appium detected on ${host}:${port}\n`);
+
+    // 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)),
+            ]);
+        }
+
+        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': 'DesktopDriver',
+            '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: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 });
+        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;
+    }
+}

lib/mcp/tools/advanced.ts

@@ -0,0 +1,138 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { AppiumSession } from '../session.js';
+import { formatError } from '../errors.js';
+
+const modifierKeys = z.array(z.enum(['shift', 'ctrl', 'alt', 'win'])).default([]);
+
+export function registerAdvancedTools(server: McpServer, session: AppiumSession): void {
+    server.registerTool(
+        'advanced_click',
+        {
+            description: 'Perform an advanced click with modifier keys, multiple clicks, or custom duration. Use this for right-click, Ctrl+click, double-click, etc.',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                elementId: z.string().optional().describe('Element to click (its center). Provide either elementId or x+y.'),
+                x: z.number().int().optional().describe('Absolute screen x coordinate'),
+                y: z.number().int().optional().describe('Absolute screen y coordinate'),
+                button: z.enum(['left', 'right', 'middle', 'back', 'forward']).default('left'),
+                modifierKeys,
+                durationMs: z.number().int().min(0).default(0).describe('Hold duration in ms (for long-press)'),
+                times: z.number().int().min(1).default(1).describe('Number of clicks (2 = double-click)'),
+                interClickDelayMs: z.number().int().min(0).default(100),
+            },
+        },
+        async (args) => {
+            try {
+                const driver = session.getDriver();
+                await driver.executeScript('windows: click', [args]);
+                return { content: [{ type: 'text' as const, text: 'clicked' }] };
+            } catch (err) {
+                return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
+            }
+        }
+    );
+
+    server.registerTool(
+        'send_keys',
+        {
+            description: 'Send keyboard input. Each action can be a pause (ms delay), text to type, or a virtual key code press/release.',
+            annotations: { destructiveHint: false },
+            inputSchema: {
+                actions: z.array(z.object({
+                    pause: z.number().int().optional().describe('Pause in milliseconds'),
+                    text: z.string().optional().describe('Text to type (unicode supported)'),
+                    virtualKeyCode: z.number().int().optional().describe('Windows Virtual Key code (e.g. 13 = Enter, 27 = Escape)'),
+                    down: z.boolean().optional().describe('true = key down only, false = key up only, omit = press and release'),
+                })).describe('Sequence of keyboard actions to perform'),
+                forceUnicode: z.boolean().default(false).describe('Use Unicode input method for special characters'),
+            },
+        },
+        async (args) => {
+            try {
+                const driver = session.getDriver();
+                await driver.executeScript('windows: keys', [args]);
+                return { content: [{ type: 'text' as const, text: 'keys sent' }] };
+            } catch (err) {
+                return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
+            }
+        }
+    );
+
+    server.registerTool(
+        'hover',
+        {
+            description: 'Move the mouse pointer from one position to another, optionally with modifier keys held. Useful for hover effects and drag-without-click.',
+            inputSchema: {
+                startElementId: z.string().optional().describe('Element to start hover from (uses element center)'),
+                startX: z.number().int().optional(),
+                startY: z.number().int().optional(),
+                endElementId: z.string().optional().describe('Element to hover to'),
+                endX: z.number().int().optional(),
+                endY: z.number().int().optional(),
+                modifierKeys,
+                durationMs: z.number().int().min(0).default(500).describe('Duration of the hover movement in ms'),
+            },
+        },
+        async (args) => {
+            try {
+                const driver = session.getDriver();
+                await driver.executeScript('windows: hover', [args]);
+                return { content: [{ type: 'text' as const, text: 'hovered' }] };
+            } catch (err) {
+                return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
+            }
+        }
+    );
+
+    server.registerTool(
+        'scroll',
+        {
+            description: 'Scroll the mouse wheel at an element or screen coordinate.',
+            inputSchema: {
+                elementId: z.string().optional().describe('Element to scroll over (uses element center)'),
+                x: z.number().int().optional().describe('Absolute screen x coordinate'),
+                y: z.number().int().optional().describe('Absolute screen y coordinate'),
+                deltaX: z.number().int().default(0).describe('Horizontal scroll amount (positive = right)'),
+                deltaY: z.number().int().default(0).describe('Vertical scroll amount (positive = down)'),
+                modifierKeys,
+            },
+        },
+        async (args) => {
+            try {
+                const driver = session.getDriver();
+                await driver.executeScript('windows: scroll', [args]);
+                return { content: [{ type: 'text' as const, text: 'scrolled' }] };
+            } catch (err) {
+                return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
+            }
+        }
+    );
+
+    server.registerTool(
+        'click_and_drag',
+        {
+            description: 'Click and drag from one position to another. Useful for resizing, reordering, or moving elements.',
+            inputSchema: {
+                startElementId: z.string().optional().describe('Element to start drag from'),
+                startX: z.number().int().optional(),
+                startY: z.number().int().optional(),
+                endElementId: z.string().optional().describe('Element to drag to'),
+                endX: z.number().int().optional(),
+                endY: z.number().int().optional(),
+                modifierKeys,
+                durationMs: z.number().int().min(0).default(500),
+                button: z.enum(['left', 'right', 'middle']).default('left'),
+            },
+        },
+        async (args) => {
+            try {
+                const driver = session.getDriver();
+                await driver.executeScript('windows: clickAndDrag', [args]);
+                return { content: [{ type: 'text' as const, text: 'drag completed' }] };
+            } catch (err) {
+                return { isError: true, content: [{ type: 'text' as const, text: formatError(err) }] };
+            }
+        }
+    );
+}