appium-mcp 1.8.10 → 1.8.12

package/src/tests/test-setup-wda.ts

@@ -1,255 +0,0 @@
-/**
- * Test file for setup-wda tool
- * Run with: npx tsx src/tests/test-setup-wda.ts
- */
-import path from 'path';
-import fs from 'fs';
-import os from 'os';
-import { createRequire } from 'module';
-import https from 'https';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-// Mock server object to test the tool
-class MockServer {
-  private tools: Map<string, any> = new Map();
-
-  addTool(tool: any) {
-    this.tools.set(tool.name, tool);
-    console.log(`✅ Tool registered: ${tool.name}`);
-  }
-
-  getTool(name: string) {
-    return this.tools.get(name);
-  }
-}
-
-async function downloadFile(url: string, destPath: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(destPath);
-
-    https
-      .get(url, async (response) => {
-        // Handle redirects
-        if (response.statusCode === 302 || response.statusCode === 301) {
-          file.close();
-          fs.unlinkSync(destPath);
-          try {
-            await downloadFile(response.headers.location!, destPath);
-            resolve();
-          } catch (err) {
-            reject(err);
-          }
-          return;
-        }
-
-        if (response.statusCode !== 200) {
-          file.close();
-          fs.unlinkSync(destPath);
-          return reject(
-            new Error(`Failed to download: ${response.statusCode}`)
-          );
-        }
-
-        const totalSize = parseInt(
-          response.headers['content-length'] || '0',
-          10
-        );
-        let downloadedSize = 0;
-
-        response.on('data', (chunk) => {
-          downloadedSize += chunk.length;
-          const percent = ((downloadedSize / totalSize) * 100).toFixed(1);
-          process.stdout.write(
-            `\r   Downloading... ${percent}% (${Math.round(downloadedSize / 1024 / 1024)}MB / ${Math.round(totalSize / 1024 / 1024)}MB)`
-          );
-        });
-
-        response.pipe(file);
-
-        file.on('finish', () => {
-          file.close();
-          process.stdout.write('\n');
-          resolve();
-        });
-      })
-      .on('error', (err) => {
-        file.close();
-        fs.unlinkSync(destPath);
-        reject(err);
-      });
-  });
-}
-
-async function unzipFile(zipPath: string, destDir: string): Promise<void> {
-  console.log(`   Extracting to: ${destDir}`);
-  await execAsync(`unzip -q "${zipPath}" -d "${destDir}"`);
-  console.log('   ✅ Extraction complete');
-}
-
-function cachePath(folder: string): string {
-  return path.join(os.homedir(), '.cache', 'appium-mcp', folder);
-}
-
-async function getLatestWDAVersion(): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const options = {
-      hostname: 'api.github.com',
-      path: '/repos/appium/WebDriverAgent/releases/latest',
-      method: 'GET',
-      headers: {
-        'User-Agent': 'mcp-appium-test',
-        Accept: 'application/vnd.github.v3+json',
-      },
-    };
-
-    https
-      .get(options, (response) => {
-        let data = '';
-
-        response.on('data', (chunk) => {
-          data += chunk;
-        });
-
-        response.on('end', () => {
-          try {
-            const release = JSON.parse(data);
-            if (release.tag_name) {
-              // Remove 'v' prefix if present
-              const version = release.tag_name.replace(/^v/, '');
-              resolve(version);
-            } else {
-              reject(new Error('No tag_name found in release data'));
-            }
-          } catch (error) {
-            reject(error);
-          }
-        });
-      })
-      .on('error', (err) => {
-        reject(err);
-      });
-  });
-}
-
-async function main() {
-  console.log('🧪 Testing WDA Download and Setup\n');
-  console.log('='.repeat(60));
-
-  try {
-    // Fetch latest WDA version from GitHub releases API
-    console.log('\n🔍 Fetching latest WDA version from GitHub...');
-    const wdaVersion = await getLatestWDAVersion();
-    console.log(`✅ Latest WDA Version: v${wdaVersion}`);
-    console.log(
-      '   Source: https://github.com/appium/WebDriverAgent/releases/latest'
-    );
-
-    // Create cache directory structure using home directory
-    const versionCacheDir = cachePath(`wda/${wdaVersion}`);
-    const extractDir = path.join(versionCacheDir, 'extracted');
-    const zipPath = path.join(
-      versionCacheDir,
-      'WebDriverAgentRunner-Runner.zip'
-    );
-    const appPath = path.join(extractDir, 'WebDriverAgentRunner-Runner.app');
-
-    console.log('\n📁 Cache Directory:', versionCacheDir);
-    console.log(`   (~/.cache/appium-device-farm/wda/${wdaVersion})`);
-
-    // Check if this version is already cached
-    if (fs.existsSync(appPath)) {
-      console.log('\n✅ WDA version already cached! Skipping download.');
-      console.log(`   Location: ${appPath}`);
-
-      // Show app contents
-      const appContents = fs.readdirSync(appPath);
-      console.log('\n📋 Cached App bundle contents:');
-      appContents.forEach((item) => {
-        console.log(`      - ${item}`);
-      });
-
-      console.log('\n' + '='.repeat(60));
-      console.log('🎉 Using cached WDA!');
-      console.log(`💡 Cache location: ${versionCacheDir}`);
-      return;
-    }
-
-    // Version not cached, proceed with download
-    console.log('\n⚠️  Version not found in cache. Downloading...');
-
-    // Create cache directories
-    fs.mkdirSync(versionCacheDir, { recursive: true });
-    fs.mkdirSync(extractDir, { recursive: true });
-
-    // Download URL
-    const downloadUrl = `https://github.com/appium/WebDriverAgent/releases/download/v${wdaVersion}/WebDriverAgentRunner-Runner.zip`;
-
-    console.log('\n⬇️  Downloading WDA from GitHub releases...');
-    console.log(`   URL: ${downloadUrl}`);
-
-    const startTime = Date.now();
-    await downloadFile(downloadUrl, zipPath);
-    const downloadTime = ((Date.now() - startTime) / 1000).toFixed(1);
-
-    console.log(`   ✅ Download complete (${downloadTime}s)`);
-
-    // Check file size
-    const stats = fs.statSync(zipPath);
-    const fileSizeMB = (stats.size / 1024 / 1024).toFixed(2);
-    console.log(`   📦 File size: ${fileSizeMB} MB`);
-
-    // Unzip the file
-    console.log('\n📂 Extracting WDA bundle...');
-    await unzipFile(zipPath, extractDir);
-
-    // List contents
-    console.log('\n📋 Extracted contents:');
-    const contents = fs.readdirSync(extractDir);
-    contents.forEach((item) => {
-      const itemPath = path.join(extractDir, item);
-      const isDir = fs.statSync(itemPath).isDirectory();
-      console.log(`   ${isDir ? '📁' : '📄'} ${item}`);
-    });
-
-    // Check if WebDriverAgentRunner-Runner.app exists
-    if (fs.existsSync(appPath)) {
-      console.log('\n✅ WebDriverAgentRunner-Runner.app found!');
-      console.log(`   Location: ${appPath}`);
-
-      // Show app contents
-      const appContents = fs.readdirSync(appPath);
-      console.log('\n   App bundle contents:');
-      appContents.forEach((item) => {
-        console.log(`      - ${item}`);
-      });
-    } else {
-      console.log('\n⚠️  WebDriverAgentRunner-Runner.app not found');
-    }
-
-    console.log('\n' + '='.repeat(60));
-    console.log('🎉 Download and setup completed successfully!');
-    console.log(`\n💡 Cached location: ${versionCacheDir}`);
-    console.log(
-      '   This version will be reused on subsequent runs (no re-download needed)'
-    );
-  } catch (error: any) {
-    console.error('\n❌ Test failed:', error.message);
-    if (error.stack) {
-      console.error('\nStack trace:', error.stack);
-    }
-    process.exit(1);
-  }
-}
-
-// Run main function
-(async () => {
-  try {
-    await main();
-  } catch (error: any) {
-    console.error('\n💥 Unexpected error:', error);
-    process.exit(1);
-  }
-})();

package/src/tools/README.md

@@ -1,179 +0,0 @@
-# Tools Directory
-
-This directory contains all MCP tools available in MCP Appium.
-
-## Tool Categories
-
-### Session Management (`session/`)
-
-- `create-session.ts` - Create mobile automation sessions
-- `delete-session.ts` - Clean up sessions
-- `select-platform.ts` - Choose Android or iOS
-- `select-device.ts` - Choose specific device
-
-### iOS Setup (`ios/`)
-
-- `boot-simulator.ts` - Boot iOS simulators
-- `setup-wda.ts` - Setup WebDriverAgent
-- `install-wda.ts` - Install WebDriverAgent
-
-### Navigation (`navigations/`)
-
-- `scroll.ts` - Scroll screens
-- `scroll-to-element.ts` - Scroll until element found
-- `swipe.ts` - Swipe screens in any direction or between custom coordinates
-
-### Element Interactions (`interactions/`)
-
-- `find.ts` - Find elements
-- `click.ts` - Click elements
-- `double-tap.ts` - Double tap elements
-- `long-press.ts` - Long press (press and hold) elements
-- `drag-and-drop.ts` - Drag and drop elements or coordinates
-- `set-value.ts` - Enter text
-- `get-text.ts` - Get element text
-- `get-page-source.ts` - Get page source (XML) from current screen
-- `screenshot.ts` - Capture screenshots
-
-### App Management (`app-management/`)
-
-- `activate-app.ts` - Activate apps
-- `terminate-app.ts` - Terminate apps
-- `install-app.ts` - Install apps
-- `uninstall-app.ts` - Uninstall apps
-- `list-apps.ts` - List installed apps
-
-### Test Generation (`test-generation/`)
-
-- `locators.ts` - Generate page locators
-- `generate-tests.ts` - Generate test code from scenarios
-
-### Documentation (`documentation/`)
-
-- `answer-appium.ts` - Answer Appium questions using RAG
-
-## Adding a New Tool
-
-See [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md) for detailed instructions.
-
-Quick steps:
-
-1. Create a new file in the appropriate subdirectory (e.g., `interactions/my-tool.ts`)
-2. Define the tool following the template
-3. Import and register it in `index.ts`
-4. Test with `npm run build && npm start`
-
-### Tool Template
-
-```typescript
-import { FastMCP } from 'fastmcp/dist/FastMCP.js';
-import { z } from 'zod';
-import { getDriver } from '../../session-store.js';
-
-export default function myTool(server: FastMCP): void {
-  server.addTool({
-    name: 'appium_my_tool',
-    description: 'What this tool does',
-    parameters: z.object({
-      param: z.string().describe('Parameter description'),
-    }),
-    annotations: {
-      readOnlyHint: false,
-      openWorldHint: false,
-    },
-    execute: async (args: any, context: any): Promise<any> => {
-      const driver = getDriver();
-      if (!driver) {
-        throw new Error('No active session');
-      }
-
-      // Implementation
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'Success',
-          },
-        ],
-      };
-    },
-  });
-}
-```
-
-### Registering a Tool
-
-Add to `src/tools/index.ts`:
-
-```typescript
-import myTool from './interactions/my-tool.js';
-
-export default function registerTools(server: FastMCP): void {
-  // ... existing tools ...
-  myTool(server);
-  // ...
-}
-```
-
-## Best Practices
-
-1. **Always check for active session**: Use `getDriver()` and check for null
-2. **Provide helpful errors**: Give clear error messages
-3. **Use proper types**: Leverage TypeScript and Zod for type safety
-4. **Add logging**: Use the logger from `logger.js` for debugging. Import with: `import log from 'logger.js'`. Use `log.info()`, `log.error()`, `log.warn()` instead of `console.log/error/warn` to maintain JSON-RPC compatibility
-5. **Handle errors**: Always wrap risky operations in try-catch
-6. **Return proper format**: Always return content in expected MCP format
-
-## Session Store
-
-Tools interact with the session through `session-store.ts`:
-
-```typescript
-import {
-  getDriver,
-  hasActiveSession,
-  safeDeleteSession,
-} from '../../session-store.js';
-
-// Check if session exists
-if (!hasActiveSession()) {
-  throw new Error('No active session');
-}
-
-// Get the driver
-const driver = getDriver();
-
-// Use the driver
-await driver.someMethod();
-```
-
-## Common Patterns
-
-### Platform-Specific Logic
-
-```typescript
-import { getPlatformName } from '../../session-store.js';
-
-if (getPlatformName(driver) === 'Android') {
-  // Android implementation
-} else if (getPlatformName(driver) === 'iOS') {
-  // iOS implementation
-}
-```
-
-## Testing
-
-After adding a new tool:
-
-1. Build: `npm run build`
-2. Run linter: `npm run lint`
-3. Test with an MCP client
-4. Verify tool appears in tools list
-
-## Need Help?
-
-- Check existing tools for examples
-- Read [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md)
-- Look at examples in `examples/` directory
-- Open an issue for questions

package/src/tools/app-management/activate-app.ts

@@ -1,46 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { getDriver } from '../../session-store.js';
-import { z } from 'zod';
-
-export default function activateApp(server: FastMCP): void {
-  const activateAppSchema = z.object({
-    id: z.string().describe('The app id'),
-  });
-
-  server.addTool({
-    name: 'appium_activate_app',
-    description: 'Activate app by id',
-    parameters: activateAppSchema,
-    annotations: {
-      readOnlyHint: false,
-      openWorldHint: false,
-    },
-    execute: async (args: { id: string }, context: any): Promise<any> => {
-      const driver = getDriver();
-      if (!driver) {
-        throw new Error('No driver found');
-      }
-
-      try {
-        await (driver as any).activateApp(args.id);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `App ${args.id} activated correctly.`,
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Error activating the app ${args.id}: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/app-management/install-app.ts

@@ -1,54 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import type { Client } from 'webdriver';
-
-export default function installApp(server: FastMCP): void {
-  const schema = z.object({
-    path: z.string().describe('Path to the app file to install'),
-  });
-
-  server.addTool({
-    name: 'appium_install_app',
-    description: 'Install an app on the device from a file path.',
-    parameters: schema,
-    execute: async (args: z.infer<typeof schema>) => {
-      const { path } = args;
-      const driver = await getDriver();
-      if (!driver) {
-        throw new Error('No driver found');
-      }
-      try {
-        const platform = getPlatformName(driver);
-        const params =
-          platform === 'Android' ? { appPath: path } : { app: path };
-        const _ok = isRemoteDriverSession(driver)
-          ? await (driver as Client).executeScript('mobile: installApp', [
-              params,
-            ])
-          : await (driver as any).execute('mobile: installApp', params);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'App installed successfully',
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to install app. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/app-management/list-apps.ts

@@ -1,87 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import {
-  createUIResource,
-  createAppListUI,
-  addUIResourceToResponse,
-} from '../../ui/mcp-ui-utils.js';
-import type { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
-
-async function listAppsFromDevice(): Promise<any[]> {
-  const driver = await getDriver();
-  if (!driver) {
-    throw new Error('No driver found');
-  }
-
-  if (isRemoteDriverSession(driver)) {
-    throw new Error('listApps is not yet implemented for the remote driver');
-  }
-
-  const platform = getPlatformName(driver);
-  if (platform === 'iOS') {
-    throw new Error('listApps is not yet implemented for iOS');
-  }
-
-  const appPackages = await (driver as AndroidUiautomator2Driver).adb.adbExec([
-    'shell',
-    'cmd',
-    'package',
-    'list',
-    'packages',
-  ]);
-
-  const apps: any[] = appPackages
-    .split('package:')
-    .filter((s: any) => s.trim())
-    .map((s: any) => ({
-      packageName: s.trim(),
-      appName: '',
-    }));
-
-  return apps;
-}
-
-export default function listApps(server: FastMCP): void {
-  const schema = z.object({});
-
-  server.addTool({
-    name: 'appium_list_apps',
-    description: 'List all installed apps on the device.',
-    parameters: schema,
-    execute: async () => {
-      try {
-        const apps = await listAppsFromDevice();
-        const textResponse = {
-          content: [
-            {
-              type: 'text',
-              text: `Installed apps: ${JSON.stringify(apps, null, 2)}`,
-            },
-          ],
-        };
-
-        // Add interactive app list UI
-        const uiResource = createUIResource(
-          `ui://appium-mcp/app-list/${Date.now()}`,
-          createAppListUI(apps)
-        );
-
-        return addUIResourceToResponse(textResponse, uiResource);
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to list apps. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/app-management/terminate-app.ts

@@ -1,56 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import type { Client } from 'webdriver';
-
-export default function terminateApp(server: FastMCP): void {
-  const schema = z.object({
-    id: z
-      .string()
-      .describe('App identifier (package name for Android, bundle ID for iOS)'),
-  });
-
-  server.addTool({
-    name: 'appium_terminate_app',
-    description: 'Terminate an app on the device.',
-    parameters: schema,
-    execute: async (args: z.infer<typeof schema>) => {
-      const { id } = args;
-      const driver = await getDriver();
-      if (!driver) {
-        throw new Error('No driver found');
-      }
-      try {
-        const platform = getPlatformName(driver);
-        const params =
-          platform === 'Android' ? { appId: id } : { bundleId: id };
-        const _ok = isRemoteDriverSession(driver)
-          ? await (driver as Client).executeScript('mobile: terminateApp', [
-              params,
-            ])
-          : await (driver as any).execute('mobile: terminateApp', params);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: 'App terminated successfully',
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to terminate app. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}