appium-mcp 0.0.1 → 1.1.4

package/src/tests/__mocks__/@appium/support.ts

@@ -0,0 +1,31 @@
+// Mock @appium/support for Jest tests
+// This avoids the ESM/CommonJS mismatch with uuid dependency
+
+export const logger = {
+  getLogger: (name: string) => {
+    // Simple logger implementation for tests
+    // No-op functions that match the logger interface
+    return {
+      debug: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      info: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      warn: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      error: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+      trace: (message: string, ...args: any[]) => {
+        // Silent in tests by default
+      },
+    };
+  },
+};
+
+// Export other commonly used utilities from @appium/support if needed
+export default {
+  logger,
+};

package/src/tests/generate-all-locators.test.ts

@@ -0,0 +1,179 @@
+import { describe, test, expect } from '@jest/globals';
+import {
+  generateAllElementLocators,
+  ElementWithLocators,
+} from '../locators/generate-all-locators.js';
+
+describe('generateAllElementLocators', () => {
+  // Sample XML for testing
+  const sampleXML = `
+    <hierarchy>
+      <android.widget.FrameLayout resource-id="android:id/content">
+        <android.widget.LinearLayout>
+          <android.widget.TextView text="Hello World" resource-id="com.example:id/text_view" clickable="true" enabled="true" displayed="true" />
+          <android.widget.Button text="Click Me" resource-id="com.example:id/button" clickable="true" enabled="true" displayed="true" />
+          <android.widget.EditText text="" resource-id="com.example:id/edit_text" clickable="true" enabled="true" displayed="true" />
+        </android.widget.LinearLayout>
+      </android.widget.FrameLayout>
+    </hierarchy>
+  `;
+
+  // Sample iOS XML for testing
+  const sampleIOSXML = `
+    <hierarchy>
+      <XCUIElementTypeApplication>
+        <XCUIElementTypeWindow>
+          <XCUIElementTypeButton name="Click Me" enabled="true" visible="true" />
+          <XCUIElementTypeTextField name="Enter text" enabled="true" visible="true" />
+          <XCUIElementTypeStaticText name="Hello World" enabled="true" visible="true" />
+        </XCUIElementTypeWindow>
+      </XCUIElementTypeApplication>
+    </hierarchy>
+  `;
+
+  test('should return an array when given valid XML', () => {
+    // Call the function with the sample XML
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2');
+
+    // Basic validation of the result
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBeGreaterThan(0);
+
+    // Verify the structure of the returned elements
+    if (result.length > 0) {
+      const element = result[0];
+      expect(element).toHaveProperty('tagName');
+      expect(element).toHaveProperty('locators');
+      expect(element).toHaveProperty('text');
+      expect(element).toHaveProperty('contentDesc');
+      expect(element).toHaveProperty('resourceId');
+      expect(element).toHaveProperty('clickable');
+      expect(element).toHaveProperty('enabled');
+      expect(element).toHaveProperty('displayed');
+    }
+  });
+
+  test('should return an empty array when given invalid XML', () => {
+    // Call the function with invalid XML (just a root element with no content)
+    const result = generateAllElementLocators(
+      '<hierarchy></hierarchy>',
+      true,
+      'uiautomator2'
+    );
+
+    // Verify the result is an empty array or at least doesn't throw an error
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBe(0);
+  });
+
+  test('should apply includeTagNames filter correctly', () => {
+    // Call the function with filters
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      includeTagNames: ['android.widget.Button'],
+    });
+
+    // If the filter works, either the result will be empty (if no buttons found)
+    // or all elements will be buttons
+    if (result.length > 0) {
+      expect(result.every(element => element.tagName.includes('Button'))).toBe(
+        true
+      );
+    }
+  });
+
+  test('should apply excludeTagNames filter correctly', () => {
+    // Call the function with excludeTagNames filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      excludeTagNames: ['android.widget.Button'],
+    });
+
+    // Verify no Button elements are included
+    expect(result.every(element => !element.tagName.includes('Button'))).toBe(
+      true
+    );
+  });
+
+  test('should apply minAttributeCount filter correctly', () => {
+    // Call the function with minAttributeCount filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      minAttributeCount: 3,
+    });
+
+    // All elements should have at least 3 attributes
+    if (result.length > 0) {
+      // We can't directly check the attributes count since we only have the processed elements
+      // But we can verify that elements with fewer attributes are filtered out
+      expect(result.length).toBeLessThanOrEqual(
+        generateAllElementLocators(sampleXML, true, 'uiautomator2').length
+      );
+    }
+  });
+
+  test('should handle fetchableOnly filter for Android', () => {
+    // Call the function with fetchableOnly filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      fetchableOnly: true,
+    });
+
+    // Verify the result contains only interactable elements
+    if (result.length > 0) {
+      const interactableTags = [
+        'EditText',
+        'Button',
+        'ImageButton',
+        'CheckBox',
+        'RadioButton',
+        'Switch',
+        'ToggleButton',
+        'TextView',
+      ];
+
+      expect(
+        result.every(element => {
+          return (
+            interactableTags.some(tag => element.tagName.includes(tag)) ||
+            element.clickable === true
+          );
+        })
+      ).toBe(true);
+    }
+  });
+
+  test('should handle fetchableOnly filter for iOS', () => {
+    // Call the function with fetchableOnly filter for iOS
+    const result = generateAllElementLocators(sampleIOSXML, true, 'xcuitest', {
+      fetchableOnly: true,
+    });
+
+    // Verify the result contains only interactable iOS elements
+    if (result.length > 0) {
+      const interactableTags = [
+        'XCUIElementTypeTextField',
+        'XCUIElementTypeSecureTextField',
+        'XCUIElementTypeButton',
+        'XCUIElementTypeImage',
+        'XCUIElementTypeSwitch',
+        'XCUIElementTypeStaticText',
+        'XCUIElementTypeTextView',
+        'XCUIElementTypeCell',
+        'XCUIElementTypeLink',
+      ];
+
+      expect(
+        result.every(element => {
+          return interactableTags.some(tag => element.tagName.includes(tag));
+        })
+      ).toBe(true);
+    }
+  });
+
+  test('should handle clickableOnly filter correctly', () => {
+    // Call the function with clickableOnly filter
+    const result = generateAllElementLocators(sampleXML, true, 'uiautomator2', {
+      clickableOnly: true,
+    });
+
+    // Verify all elements are clickable
+    expect(result.every(element => element.clickable === true)).toBe(true);
+  });
+});

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

@@ -0,0 +1,247 @@
+/**
+ * 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, response => {
+        // Handle redirects
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          file.close();
+          fs.unlinkSync(destPath);
+          return downloadFile(response.headers.location!, destPath)
+            .then(resolve)
+            .catch(reject);
+        }
+
+        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
+main().catch(error => {
+  console.error('\n💥 Unexpected error:', error);
+  process.exit(1);
+});

package/src/tools/README.md

@@ -0,0 +1,170 @@
+# Tools Directory
+
+This directory contains all MCP tools available in MCP Appium.
+
+## Tool Categories
+
+### Session Management
+
+- `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
+
+- `boot-simulator.ts` - Boot iOS simulators
+- `setup-wda.ts` - Setup WebDriverAgent
+- `install-wda.ts` - Install WebDriverAgent
+
+### Element Interaction
+
+- `interactions/` - Direct appium interactions
+  - `find.ts` - Find elements
+  - `click.ts` - Click elements
+  - `double-tap.ts` - Double tap elements
+  - `set-value.ts` - Enter text
+  - `get-text.ts` - Get element text
+  - `screenshot.ts` - Capture screenshots
+  - `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
+
+### Navigation
+
+- `scroll.ts` - Scroll screens
+- `scroll-to-element.ts` - Scroll until element found
+
+### AI & Test Generation
+
+- `generate_locators.ts` - Generate page locators
+- `generate-tests.ts` - Generate test code from scenarios
+- `answer-appium.ts` - Answer Appium questions
+
+## Adding a New Tool
+
+See [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md) for detailed instructions.
+
+Quick steps:
+
+1. Create a new file in this directory (e.g., `my-tool.ts`)
+2. Define the tool following the template
+3. 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 './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 `console.log` for debugging
+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/answer-appium.ts

@@ -0,0 +1,75 @@
+/**
+ * Tool to select mobile platform before creating a session
+ */
+import { z } from 'zod';
+import {
+  answerAppiumQuery,
+  initializeAppiumDocumentation,
+} from './documentation/index.js';
+
+export default function answerAppium(server: any): void {
+  server.addTool({
+    name: 'appium_documentation_query',
+    description: `Query Appium documentation using RAG (Retrieval-Augmented Generation).
+      This tool searches through indexed Appium documentation to answer questions about Appium features, setup, configuration, drivers, and usage.
+      `,
+    parameters: z.object({
+      query: z
+        .string()
+        .describe('The question or query about Appium documentation'),
+    }),
+    execute: async (args: any, context: any): Promise<any> => {
+      const query = args.query;
+      if (!query) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Query parameter is required',
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        const result = await answerAppiumQuery({ query });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: result.answer,
+            },
+          ],
+        };
+      } catch (docError) {
+        // If documentation query fails, try to initialize and retry once
+        try {
+          console.log('Documentation not initialized, initializing now...');
+          await initializeAppiumDocumentation();
+          const result = await answerAppiumQuery({ query });
+          return {
+            content: [
+              {
+                type: 'text',
+                text: result.answer,
+              },
+            ],
+          };
+        } catch (retryError) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error querying Appium documentation: ${
+                  (retryError as Error).message
+                }. Please ensure the documentation is indexed first.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+    },
+  });
+}