appium-mcp 1.67.1 → 1.68.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.68.0](https://github.com/appium/appium-mcp/compare/v1.67.1...v1.68.0) (2026-04-29)
+
+### Features
+
+* **tools:** single appium_mobile_clipboard tool ([#292](https://github.com/appium/appium-mcp/issues/292)) ([ce7c7dc](https://github.com/appium/appium-mcp/commit/ce7c7dc6e20f0dd43b0ebf3f56651065af55fa8c))
+
+### Bug Fixes
+
+* loading mcp server to start ([#298](https://github.com/appium/appium-mcp/issues/298)) ([82414d6](https://github.com/appium/appium-mcp/commit/82414d6dbec351887758aae9414ac9adfc4de22d))
+
 ## [1.67.1](https://github.com/appium/appium-mcp/compare/v1.67.0...v1.67.1) (2026-04-27)
 
 ### Bug Fixes

package/README.md

@@ -343,8 +343,7 @@ The default regex pattern allows any URL that starts with `http://` or `https://
 | `appium_mobile_hide_keyboard` | Dismiss the on-screen keyboard (`mobile: hideKeyboard`) |
 | `appium_mobile_is_keyboard_shown` | Whether the on-screen keyboard is visible (`mobile: isKeyboardShown`) |
 | `appium_get_text`     | Get text content from an element                                                             |
-| `appium_get_clipboard` | Get the current clipboard content as plain text from the device            |
-| `appium_set_clipboard` | Set the device clipboard to the provided plain text                        |
+| `appium_mobile_clipboard` | Read or set device clipboard plain text. `action=get` \| `set` (`content` required for set). |
 | `appium_alert` | Handle alerts with `action` = `accept`, `dismiss`, or `get_text` (optional `buttonLabel`) |
 
 ### Screen & Navigation

package/dist/index.js

@@ -9,7 +9,7 @@ async function startServer() {
     log.info('Starting MCP Appium MCP Server...');
     try {
         if (useHttpStream) {
-            server.start({
+            await server.start({
                 transportType: 'httpStream',
                 httpStream: {
                     endpoint: '/sse',
@@ -21,7 +21,7 @@ async function startServer() {
         }
         else {
             // Start with stdio transport
-            server.start({
+            await server.start({
                 transportType: 'stdio',
             });
             log.info('Server started with stdio transport');

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,GAAG,MAAM,aAAa,CAAC;AAE9B,+BAA+B;AAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AACpD,MAAM,IAAI,GACR,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;AAEzE,KAAK,UAAU,WAAW;IACxB,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,CAAC,KAAK,CAAC;gBACX,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE;oBACV,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;iBACzB;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CACN,gEAAgE,IAAI,MAAM,CAC3E,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,6BAA6B;YAC7B,MAAM,CAAC,KAAK,CAAC;gBACX,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,mBAAmB;AACnB,WAAW,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,GAAG,MAAM,aAAa,CAAC;AAE9B,+BAA+B;AAC/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACnC,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;AACpD,MAAM,IAAI,GACR,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;AAEzE,KAAK,UAAU,WAAW;IACxB,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE;oBACV,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;iBACzB;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CACN,gEAAgE,IAAI,MAAM,CAC3E,CAAC;YACF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,6BAA6B;YAC7B,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,mBAAmB;AACnB,WAAW,EAAE,CAAC"}

package/dist/tools/interactions/clipboard.d.ts

@@ -1,13 +1,3 @@
 import type { FastMCP } from 'fastmcp';
-/**
- * Register clipboard read/write tools.
- *
- * - appium_get_clipboard: reads the current clipboard content as plain text
- * - appium_set_clipboard: writes plain text to the clipboard
- *
- * Both tools rely on the `mobile: getClipboard` / `mobile: setClipboard`
- * Appium execute commands and work on Android, iOS, and remote WebDriver
- * sessions.
- */
 export default function clipboard(server: FastMCP): void;
 //# sourceMappingURL=clipboard.d.ts.map

package/dist/tools/interactions/clipboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/clipboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AAUtD;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAyFvD"}
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/clipboard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AA0DtD,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAiCvD"}

package/dist/tools/interactions/clipboard.js

@@ -1,84 +1,65 @@
 import { z } from 'zod';
 import { getClipboard, setClipboard } from '../../command.js';
 import { resolveDriver, textResult, errorResult, toolErrorMessage, } from '../tool-response.js';
-/**
- * Register clipboard read/write tools.
- *
- * - appium_get_clipboard: reads the current clipboard content as plain text
- * - appium_set_clipboard: writes plain text to the clipboard
- *
- * Both tools rely on the `mobile: getClipboard` / `mobile: setClipboard`
- * Appium execute commands and work on Android, iOS, and remote WebDriver
- * sessions.
- */
+const schema = z.object({
+    action: z
+        .enum(['get', 'set'])
+        .describe('get: read device clipboard as plain text. set: write plain text to the clipboard.'),
+    content: z
+        .string()
+        .optional()
+        .describe('Required when action is set. Plain text to put on the clipboard.'),
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Session ID to target. If omitted, uses the active session.'),
+});
+async function handleGet(sessionId) {
+    const resolved = resolveDriver(sessionId);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const { driver } = resolved;
+    const text = await getClipboard(driver);
+    if (!text) {
+        return textResult('Clipboard is empty.');
+    }
+    return textResult(`Clipboard content: ${text}`);
+}
+async function handleSet(sessionId, content) {
+    const resolved = resolveDriver(sessionId);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const { driver } = resolved;
+    await setClipboard(driver, content);
+    return textResult(`Successfully set clipboard content to: ${content}`);
+}
 export default function clipboard(server) {
-    // ─── Get Clipboard ────────────────────────────────────────────────────────
-    server.addTool({
-        name: 'appium_mobile_get_clipboard',
-        description: 'Get the current clipboard content as plain text from the device. ' +
-            'Works on Android (UiAutomator2) and iOS (XCUITest). ' +
-            'Returns an empty string if the clipboard is empty.',
-        parameters: z.object({
-            sessionId: z
-                .string()
-                .optional()
-                .describe('Session ID to target. If omitted, uses the active session.'),
-        }),
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: false,
-        },
-        execute: async (args, _context) => {
-            const resolved = resolveDriver(args.sessionId);
-            if (!resolved.ok) {
-                return resolved.result;
-            }
-            const { driver } = resolved;
-            try {
-                const content = await getClipboard(driver);
-                if (!content) {
-                    return textResult('Clipboard is empty.');
-                }
-                return textResult(`Clipboard content: ${content}`);
-            }
-            catch (err) {
-                return errorResult(`Failed to get clipboard content. err: ${toolErrorMessage(err)}`);
-            }
-        },
-    });
-    // ─── Set Clipboard ────────────────────────────────────────────────────────
-    const setClipboardSchema = z.object({
-        content: z
-            .string()
-            .describe('The plain text content to write to the device clipboard'),
-        sessionId: z
-            .string()
-            .optional()
-            .describe('Session ID to target. If omitted, uses the active session.'),
-    });
     server.addTool({
-        name: 'appium_mobile_set_clipboard',
-        description: 'Set the device clipboard to the provided plain text. ' +
-            'Works on Android (UiAutomator2) and iOS (XCUITest). ' +
-            'Useful for pre-filling clipboard content before testing paste operations, ' +
-            'or for injecting long strings without typing them character by character.',
-        parameters: setClipboardSchema,
+        name: 'appium_mobile_clipboard',
+        description: 'Read or set the device clipboard as plain text (Android UiAutomator2 / iOS XCUITest). ' +
+            'action=get returns current text; action=set requires content.',
+        parameters: schema,
         annotations: {
             readOnlyHint: false,
             openWorldHint: false,
         },
         execute: async (args, _context) => {
-            const resolved = resolveDriver(args.sessionId);
-            if (!resolved.ok) {
-                return resolved.result;
-            }
-            const { driver } = resolved;
             try {
-                await setClipboard(driver, args.content);
-                return textResult(`Successfully set clipboard content to: ${args.content}`);
+                switch (args.action) {
+                    case 'get':
+                        return await handleGet(args.sessionId);
+                    case 'set': {
+                        if (args.content === undefined) {
+                            return errorResult('content is required for set action');
+                        }
+                        return await handleSet(args.sessionId, args.content);
+                    }
+                }
             }
             catch (err) {
-                return errorResult(`Failed to set clipboard content. err: ${toolErrorMessage(err)}`);
+                return errorResult(`Failed to ${args.action} clipboard. err: ${toolErrorMessage(err)}`);
             }
         },
     });

package/dist/tools/interactions/clipboard.js.map

@@ -1 +1 @@
-{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../../../src/tools/interactions/clipboard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clipboard.js","sourceRoot":"","sources":["../../../src/tools/interactions/clipboard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC;IACtB,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;SACpB,QAAQ,CACP,mFAAmF,CACpF;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,kEAAkE,CACnE;IACH,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4DAA4D,CAAC;CAC1E,CAAC,CAAC;AAIH,KAAK,UAAU,SAAS,CAAC,SAAkB;IACzC,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IAE5B,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,UAAU,CAAC,qBAAqB,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,UAAU,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,SAAS,CACtB,SAA6B,EAC7B,OAAe;IAEf,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IAE5B,MAAM,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,UAAU,CAAC,0CAA0C,OAAO,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,OAAO,UAAU,SAAS,CAAC,MAAe;IAC/C,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EACT,wFAAwF;YACxF,+DAA+D;QACjE,UAAU,EAAE,MAAM;QAClB,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,IAAmB,EACnB,QAA6C,EACrB,EAAE;YAC1B,IAAI,CAAC;gBACH,QAAQ,IAAI,CAAC,MAAM,EAAE,CAAC;oBACpB,KAAK,KAAK;wBACR,OAAO,MAAM,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACzC,KAAK,KAAK,CAAC,CAAC,CAAC;wBACX,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;4BAC/B,OAAO,WAAW,CAAC,oCAAoC,CAAC,CAAC;wBAC3D,CAAC;wBACD,OAAO,MAAM,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;oBACvD,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,OAAO,WAAW,CAChB,aAAa,IAAI,CAAC,MAAM,oBAAoB,gBAAgB,CAAC,GAAG,CAAC,EAAE,CACpE,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.67.1",
+  "version": "1.68.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.67.1",
+  "version": "1.68.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.67.1",
+      "version": "1.68.0",
       "transport": {
         "type": "stdio"
       }

package/src/index.ts

@@ -14,7 +14,7 @@ async function startServer(): Promise<void> {
 
   try {
     if (useHttpStream) {
-      server.start({
+      await server.start({
         transportType: 'httpStream',
         httpStream: {
           endpoint: '/sse',
@@ -28,7 +28,7 @@ async function startServer(): Promise<void> {
       log.info('Waiting for client connections...');
     } else {
       // Start with stdio transport
-      server.start({
+      await server.start({
         transportType: 'stdio',
       });
 

package/src/tools/interactions/clipboard.ts

@@ -8,101 +8,83 @@ import {
   toolErrorMessage,
 } from '../tool-response.js';
 
-/**
- * Register clipboard read/write tools.
- *
- * - appium_get_clipboard: reads the current clipboard content as plain text
- * - appium_set_clipboard: writes plain text to the clipboard
- *
- * Both tools rely on the `mobile: getClipboard` / `mobile: setClipboard`
- * Appium execute commands and work on Android, iOS, and remote WebDriver
- * sessions.
- */
-export default function clipboard(server: FastMCP): void {
-  // ─── Get Clipboard ────────────────────────────────────────────────────────
+const schema = z.object({
+  action: z
+    .enum(['get', 'set'])
+    .describe(
+      'get: read device clipboard as plain text. set: write plain text to the clipboard.'
+    ),
+  content: z
+    .string()
+    .optional()
+    .describe(
+      'Required when action is set. Plain text to put on the clipboard.'
+    ),
+  sessionId: z
+    .string()
+    .optional()
+    .describe('Session ID to target. If omitted, uses the active session.'),
+});
 
-  server.addTool({
-    name: 'appium_mobile_get_clipboard',
-    description:
-      'Get the current clipboard content as plain text from the device. ' +
-      'Works on Android (UiAutomator2) and iOS (XCUITest). ' +
-      'Returns an empty string if the clipboard is empty.',
-    parameters: z.object({
-      sessionId: z
-        .string()
-        .optional()
-        .describe('Session ID to target. If omitted, uses the active session.'),
-    }),
-    annotations: {
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
-    execute: async (
-      args: { sessionId?: string },
-      _context: Record<string, unknown> | undefined
-    ): Promise<ContentResult> => {
-      const resolved = resolveDriver(args.sessionId);
-      if (!resolved.ok) {
-        return resolved.result;
-      }
-      const { driver } = resolved;
+type ClipboardArgs = z.infer<typeof schema>;
 
-      try {
-        const content = await getClipboard(driver);
-        if (!content) {
-          return textResult('Clipboard is empty.');
-        }
-        return textResult(`Clipboard content: ${content}`);
-      } catch (err: unknown) {
-        return errorResult(
-          `Failed to get clipboard content. err: ${toolErrorMessage(err)}`
-        );
-      }
-    },
-  });
+async function handleGet(sessionId?: string): Promise<ContentResult> {
+  const resolved = resolveDriver(sessionId);
+  if (!resolved.ok) {
+    return resolved.result;
+  }
+  const { driver } = resolved;
 
-  // ─── Set Clipboard ────────────────────────────────────────────────────────
+  const text = await getClipboard(driver);
+  if (!text) {
+    return textResult('Clipboard is empty.');
+  }
+  return textResult(`Clipboard content: ${text}`);
+}
 
-  const setClipboardSchema = z.object({
-    content: z
-      .string()
-      .describe('The plain text content to write to the device clipboard'),
-    sessionId: z
-      .string()
-      .optional()
-      .describe('Session ID to target. If omitted, uses the active session.'),
-  });
+async function handleSet(
+  sessionId: string | undefined,
+  content: string
+): Promise<ContentResult> {
+  const resolved = resolveDriver(sessionId);
+  if (!resolved.ok) {
+    return resolved.result;
+  }
+  const { driver } = resolved;
 
+  await setClipboard(driver, content);
+  return textResult(`Successfully set clipboard content to: ${content}`);
+}
+
+export default function clipboard(server: FastMCP): void {
   server.addTool({
-    name: 'appium_mobile_set_clipboard',
+    name: 'appium_mobile_clipboard',
     description:
-      'Set the device clipboard to the provided plain text. ' +
-      'Works on Android (UiAutomator2) and iOS (XCUITest). ' +
-      'Useful for pre-filling clipboard content before testing paste operations, ' +
-      'or for injecting long strings without typing them character by character.',
-    parameters: setClipboardSchema,
+      'Read or set the device clipboard as plain text (Android UiAutomator2 / iOS XCUITest). ' +
+      'action=get returns current text; action=set requires content.',
+    parameters: schema,
     annotations: {
       readOnlyHint: false,
       openWorldHint: false,
     },
     execute: async (
-      args: z.infer<typeof setClipboardSchema>,
+      args: ClipboardArgs,
       _context: Record<string, unknown> | undefined
     ): Promise<ContentResult> => {
-      const resolved = resolveDriver(args.sessionId);
-      if (!resolved.ok) {
-        return resolved.result;
-      }
-      const { driver } = resolved;
-
       try {
-        await setClipboard(driver, args.content);
-        return textResult(
-          `Successfully set clipboard content to: ${args.content}`
-        );
+        switch (args.action) {
+          case 'get':
+            return await handleGet(args.sessionId);
+          case 'set': {
+            if (args.content === undefined) {
+              return errorResult('content is required for set action');
+            }
+            return await handleSet(args.sessionId, args.content);
+          }
+        }
       } catch (err: unknown) {
         return errorResult(
-          `Failed to set clipboard content. err: ${toolErrorMessage(err)}`
+          `Failed to ${args.action} clipboard. err: ${toolErrorMessage(err)}`
         );
       }
     },