appium-mcp 1.8.11 → 1.8.12

package/docs/CONTRIBUTING.md

@@ -1,424 +0,0 @@
-# Contributing to MCP Appium
-
-Welcome! This guide will help you extend MCP Appium by adding new tools and resources.
-
-## Table of Contents
-
-- [Adding New Tools](#adding-new-tools)
-- [Adding New Resources](#adding-new-resources)
-- [Code Style Guidelines](#code-style-guidelines)
-- [Formatting Best Practices](#formatting-best-practices)
-- [Tool Metadata with YAML](#tool-metadata-with-yaml)
-- [Code Style Guidelines](#code-style-guidelines)
-- [Formatting Best Practices](#formatting-best-practices)
-
----
-
-## Adding New Tools
-
-Tools are the core capabilities of MCP Appium. They define actions that can be performed on mobile devices.
-
-### Quick Start: Simple Tool
-
-Here's a minimal example of adding a new tool:
-
-```typescript
-// src/tools/my-new-tool.ts
-import { FastMCP } from 'fastmcp/dist/FastMCP.js';
-import { z } from 'zod';
-import { getDriver } from './session-store.js';
-
-export default function myNewTool(server: FastMCP): void {
-  server.addTool({
-    name: 'appium_my_new_tool',
-    description: 'Description of what this tool does',
-    parameters: z.object({
-      param1: z.string().describe('Description of param1'),
-      param2: z.number().optional().describe('Description of param2'),
-    }),
-    annotations: {
-      readOnlyHint: false, // Set to true if tool only reads data
-      openWorldHint: false, // Set to true if tool requires real-world knowledge
-    },
-    execute: async (args: any, context: any): Promise<any> => {
-      const driver = getDriver();
-      if (!driver) {
-        throw new Error(
-          'No active driver session. Please create a session first.'
-        );
-      }
-
-      // Your tool logic here
-      const result = await driver.someMethod(args.param1);
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Success message: ${result}`,
-          },
-        ],
-      };
-    },
-  });
-}
-```
-
-### Registering the Tool
-
-Add your tool to `src/tools/index.ts`:
-
-```typescript
-import myNewTool from './my-new-tool.js';
-
-export default function registerTools(server: FastMCP): void {
-  // ... existing code ...
-
-  myNewTool(server); // Add this line
-
-  // ... rest of the tools ...
-}
-```
-
-### Tool Parameters
-
-Use Zod schemas to define parameters:
-
-```typescript
-import { z } from 'zod';
-
-parameters: z.object({
-  // Required string parameter
-  requiredString: z.string().describe('A required string parameter'),
-
-  // Optional number parameter
-  optionalNumber: z.number().optional().describe('An optional number'),
-
-  // Enum parameter
-  platform: z.enum(['ios', 'android']).describe('Target platform'),
-
-  // Object parameter
-  config: z
-    .object({
-      key: z.string(),
-      value: z.string(),
-    })
-    .optional()
-    .describe('Configuration object'),
-
-  // Array parameter
-  items: z.array(z.string()).describe('List of items'),
-});
-```
-
-### Tool Annotations
-
-Annotations help the AI understand when to use your tool:
-
-- `readOnlyHint: true` - Use when the tool only retrieves/reads data without modifying state
-- `readOnlyHint: false` - Use when the tool performs actions or modifications
-- `openWorldHint: true` - Use when the tool requires knowledge beyond the codebase
-- `openWorldHint: false` - Use for codebase-specific operations
-
-### Common Patterns
-
-#### 1. Session Management Tools
-
-```typescript
-import {
-  getDriver,
-  hasActiveSession,
-  safeDeleteSession,
-} from './session-store.js';
-
-// Check for active session
-if (!hasActiveSession()) {
-  throw new Error('No active session. Please create a session first.');
-}
-
-const driver = getDriver();
-// Use driver...
-```
-
-#### 2. Platform-Specific Tools
-
-```typescript
-import { getPlatformName } from './session-store.js';
-
-const platform = getPlatformName(driver);
-if (platform === 'Android') {
-  // Android-specific implementation
-} else if (platform === 'iOS') {
-  // iOS-specific implementation
-}
-```
-
----
-
-## Adding New Resources
-
-Resources provide contextual information to help the AI assist users better.
-
-### Creating a Resource
-
-```typescript
-// src/resources/my-resource.ts
-export default function myResource(server: any): void {
-  server.addResource({
-    uri: 'my://resource-uri',
-    name: 'My Resource Name',
-    description: 'Description of what this resource provides',
-    mimeType: 'text/plain', // or 'application/json', 'text/markdown', etc.
-    async load() {
-      // Return the resource content
-      return {
-        text: 'Resource content here',
-        // or
-        // data: someJSONData,
-      };
-    },
-  });
-}
-```
-
-### Registering a Resource
-
-Add your resource to `src/resources/index.ts`:
-
-```typescript
-import myResource from './my-resource.js';
-
-export default function registerResources(server: any) {
-  myResource(server); // Add this line
-  console.log('All resources registered');
-}
-```
-
-### Resource Types
-
-#### Text Resource
-
-```typescript
-{
-  uri: 'doc://example',
-  name: 'Example Resource',
-  mimeType: 'text/plain',
-  async load() {
-    return { text: 'Simple text content' };
-  }
-}
-```
-
-#### JSON Resource
-
-```typescript
-{
-  uri: 'data://example',
-  name: 'Example Data',
-  mimeType: 'application/json',
-  async load() {
-    return { data: { key: 'value' } };
-  }
-}
-```
-
-#### Markdown Resource
-
-```typescript
-{
-  uri: 'doc://guide',
-  name: 'Guide',
-  mimeType: 'text/markdown',
-  async load() {
-    return { text: '# Markdown Content' };
-  }
-}
-```
-
----
-
-## Code Style Guidelines
-
-### 1. File Naming
-
-- Tools: `kebab-case.ts` (e.g., `boot-simulator.ts`)
-- Resources: `kebab-case.ts` (e.g., `java-template.ts`)
-
-### 2. Function Exports
-
-Always export as default function:
-
-```typescript
-export default function myTool(server: FastMCP): void {
-  // implementation
-}
-```
-
-### 3. Error Handling
-
-Always provide helpful error messages:
-
-```typescript
-if (!driver) {
-  throw new Error('No active driver session. Please create a session first.');
-}
-```
-
-### 4. Return Values
-
-Always return content in the expected format:
-
-```typescript
-return {
-  content: [
-    {
-      type: 'text',
-      text: 'Success message or data',
-    },
-  ],
-};
-```
-
-### 5. Async/Await
-
-Always use async/await for async operations:
-
-```typescript
-// Good
-const result = await driver.someMethod();
-
-// Bad
-driver.someMethod().then(result => ...)
-```
-
-### 6. Type Safety
-
-Use proper TypeScript types:
-
-```typescript
-execute: async (args: any, context: any): Promise<any> => {
-  // Type your variables
-  const driver = getDriver();
-  if (!driver) {
-    throw new Error('No driver');
-  }
-  // ...
-};
-```
-
----
-
-## Examples
-
-See these existing tools for reference:
-
-- **Simple tool**: `src/tools/scroll.ts` - Basic scrolling functionality
-- **Complex tool**: `src/tools/create-session.ts` - Session management with multiple capabilities
-- **Interaction tool**: `src/tools/interactions/click.ts` - Element interaction
-- **Prompt-based tool**: `src/tools/generate-tests.ts` - AI instructions
-
----
-
-## Testing
-
-After adding a new tool:
-
-1. Build the project: `npm run build`
-2. Run linter: `npm run lint`
-3. Test the tool with an MCP client
-4. Verify the tool appears in the tools list
-
----
-
-## Pre-Release Checklist
-
-Before releasing a new version, ensure documentation submodules are up to date:
-
-### Updating Documentation Submodules
-
-This project uses Git submodules to automatically sync documentation from the official Appium repositories. Before each release, you must update the submodules to ensure you have the latest documentation files (.md and image files).
-
-**Required steps before each release:**
-
-1. **Update all submodules to latest commits:**
-
-   ```bash
-   ./scripts/update-submodules.sh
-   ```
-
-   This script will:
-
-   - Update all Git submodules to their latest commits
-   - Reapply sparse-checkout to only fetch `.md` and image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`)
-   - Ensure you have the latest documentation without downloading entire repositories
-
-2. **Re-index the documentation (if needed):**
-
-   ```bash
-   npm run build
-   npm run index-docs
-   ```
-
-3. **Commit the updated submodule references:**
-   ```bash
-   git add .gitmodules src/resources/submodules
-   git commit -m "chore: update documentation submodules"
-   ```
-
-### Why This Is Important
-
-- **Fresh Documentation**: Ensures RAG indexing uses the latest Appium documentation
-- **Smaller Repository**: Sparse-checkout keeps repository size manageable by only fetching documentation files
-- **Automatic Sync**: Submodules automatically track upstream repository commits
-- **Reproducibility**: Submodule commits are tracked, ensuring consistent documentation across environments
-
-See [SUBMODULES.md](../docs/SUBMODULES.md) for detailed information about submodule setup and usage.
-
----
-
----
-
-## Formatting Best Practices
-
-### Long Descriptions
-
-For better readability when descriptions are long, use template literals with proper indentation:
-
-**Bad (hard to read):**
-
-```typescript
-description: 'REQUIRED: First ASK THE USER which mobile platform they want to use (Android or iOS) before creating a session. DO NOT assume or default to any platform. You MUST explicitly prompt the user to choose between Android or iOS. This is mandatory before proceeding to use the create_session tool.',
-```
-
-**Good (readable):**
-
-```typescript
-description: `REQUIRED: First ASK THE USER which mobile platform they want to use (Android or iOS) before creating a session.
-  DO NOT assume or default to any platform.
-  You MUST explicitly prompt the user to choose between Android or iOS.
-  This is mandatory before proceeding to use the create_session tool.
-  `,
-```
-
-### Parameter Descriptions
-
-For long parameter descriptions, also use template literals:
-
-```typescript
-parameters: z.object({
-  platform: z.enum(['ios', 'android']).describe(
-    `REQUIRED: Must match the platform the user explicitly selected via the select_platform tool.
-      DO NOT default to Android or iOS without asking the user first.`
-  ),
-});
-```
-
----
-
-## Need Help?
-
-- Check existing tools in `src/tools/`
-- See examples in `examples/`
-- Open an issue for questions
-
-Happy contributing! 🎉

package/eslint.config.js

@@ -1,23 +0,0 @@
-import appiumConfig from '@appium/eslint-config-appium-ts';
-
-export default [
-  ...appiumConfig,
-  {
-    files: ['src/**/*.ts'],
-    rules: {
-      'no-console': 'off',
-      'import/no-named-as-default': 'off',
-      'import/no-named-as-default-member': 'off',
-      '@typescript-eslint/no-unused-vars': 'off',
-      '@typescript-eslint/no-non-null-assertion': 'off',
-      '@typescript-eslint/explicit-function-return-type': 'off',
-      '@typescript-eslint/explicit-module-boundary-types': 'off',
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/ban-ts-comment': 'off',
-      'no-case-declarations': 'off',
-    },
-  },
-  {
-    ignores: ['dist/', 'node_modules/', '*.js'],
-  },
-];

package/examples/android-gmail.md

@@ -1,7 +0,0 @@
-Using appium  generate test tool create automation test for below step
-
-Steps:
-1. Open Gmail app
-2. Compose a email to sudharshrocks@gmail.com with subject "Test email from appium"
-3. Add body as "Hello World!"
-4. and send

package/examples/android-todo-app.md

@@ -1,9 +0,0 @@
-Using appium  generate test tool create automation test for below step
-
-STEPS:
-1. Open TODO app 
-2. Add a todo list with Title "Complete appium mcp server" 
-3. Use June 25 2025 as date 
-4. Add it to personal list
-
-Use JAVA + Testng for test generation

package/jest.config.js

@@ -1,23 +0,0 @@
-export default {
-  preset: 'ts-jest/presets/js-with-ts-esm',
-  testEnvironment: 'node',
-  extensionsToTreatAsEsm: ['.ts'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1',
-    // Mock @appium/support to avoid ESM/CommonJS issues with uuid
-    '^@appium/support$': '<rootDir>/src/tests/__mocks__/@appium/support.ts',
-  },
-  transform: {
-    '^.+\\.tsx?$': [
-      'ts-jest',
-      {
-        useESM: true,
-      },
-    ],
-  },
-  // Add this to ensure Jest can handle ESM
-  // Exclude ES modules from transformation
-  transformIgnorePatterns: [
-    'node_modules/(?!(@xmldom|fast-xml-parser|xpath|uuid)/)',
-  ],
-};

package/src/devicemanager/adb-manager.ts

@@ -1,164 +0,0 @@
-import { ADB } from 'appium-adb';
-import log from '../logger.js';
-/**
- * Singleton ADB Manager to prevent multiple ADB instances
- * This ensures only one ADB instance per host machine
- */
-export class ADBManager {
-  private static instance: ADBManager;
-  private adbInstance: ADB | null = null;
-  private isInitialized = false;
-  private initializationPromise: Promise<ADB> | null = null;
-
-  private constructor() {}
-
-  /**
-   * Get the singleton instance of ADBManager
-   */
-  public static getInstance(): ADBManager {
-    if (!ADBManager.instance) {
-      ADBManager.instance = new ADBManager();
-    }
-    return ADBManager.instance;
-  }
-
-  /**
-   * Initialize ADB instance with configuration
-   * @param options ADB configuration options
-   * @returns Promise<ADB> The initialized ADB instance
-   */
-  public async initialize(
-    options: { adbExecTimeout?: number; udid?: string } = {}
-  ): Promise<ADB> {
-    // If already initialized, return existing instance
-    if (this.isInitialized && this.adbInstance) {
-      log.debug(
-        'ADB instance already initialized, returning existing instance'
-      );
-      return this.adbInstance;
-    }
-
-    // If initialization is in progress, wait for it
-    if (this.initializationPromise) {
-      log.debug('ADB initialization in progress, waiting for completion');
-      return await this.initializationPromise;
-    }
-
-    // Start initialization
-    this.initializationPromise = this._createADBInstance(options);
-
-    try {
-      this.adbInstance = await this.initializationPromise;
-      this.isInitialized = true;
-      log.info('ADB instance initialized successfully');
-      return this.adbInstance;
-    } catch (error) {
-      log.error(`Failed to initialize ADB instance: ${error}`);
-      this.initializationPromise = null;
-      throw error;
-    }
-  }
-
-  /**
-   * Get the current ADB instance
-   * @returns ADB instance or null if not initialized
-   */
-  public getADBInstance(): ADB | null {
-    return this.adbInstance;
-  }
-
-  /**
-   * Check if ADB is initialized
-   * @returns boolean indicating initialization status
-   */
-  public isADBInitialized(): boolean {
-    return this.isInitialized && this.adbInstance !== null;
-  }
-
-  /**
-   * Reset the ADB instance (for testing or cleanup)
-   */
-  public async reset(): Promise<void> {
-    if (this.adbInstance) {
-      try {
-        // Cleanup any existing ADB instance
-        log.info('Resetting ADB instance');
-        this.adbInstance = null;
-        this.isInitialized = false;
-        this.initializationPromise = null;
-      } catch (error) {
-        log.error(`Error resetting ADB instance: ${error}`);
-      }
-    }
-  }
-
-  /**
-   * Create ADB instance with proper error handling
-   * @param options ADB configuration options
-   * @returns Promise<ADB> The created ADB instance
-   */
-  private async _createADBInstance(
-    options: { adbExecTimeout?: number; udid?: string } = {}
-  ): Promise<ADB> {
-    const defaultOptions = {
-      adbExecTimeout: 60000,
-      ...options,
-    };
-
-    log.info(
-      `Creating ADB instance with options: ${JSON.stringify(defaultOptions)}`
-    );
-
-    try {
-      const adb = await ADB.createADB(defaultOptions);
-      log.info('ADB instance created successfully');
-      return adb;
-    } catch (error) {
-      log.error(`Failed to create ADB instance: ${error}`);
-      throw new Error(`ADB initialization failed: ${error}`);
-    }
-  }
-
-  /**
-   * Get ADB instance for specific device operations
-   * This method ensures we reuse the singleton instance
-   * @param udid Optional device UDID for device-specific operations
-   * @returns Promise<ADB> The ADB instance
-   */
-  public async getADBForDevice(udid?: string): Promise<ADB> {
-    if (!this.isADBInitialized()) {
-      await this.initialize({ udid });
-    }
-
-    if (!this.adbInstance) {
-      throw new Error('ADB instance not available');
-    }
-
-    return this.adbInstance;
-  }
-}
-
-/**
- * Global ADB Manager instance
- * Use this throughout the application to access ADB functionality
- */
-export const adbManager = ADBManager.getInstance();
-
-/**
- * Convenience function to get ADB instance
- * @param options ADB configuration options
- * @returns Promise<ADB> The ADB instance
- */
-export async function getADBInstance(
-  options: { adbExecTimeout?: number; udid?: string } = {}
-): Promise<ADB> {
-  return await adbManager.getADBForDevice(options.udid);
-}
-
-/**
- * Convenience function to get existing ADB instance (without initialization)
- * @returns ADB instance or null if not initialized
- */
-export function getExistingADBInstance(): ADB | null {
-  return adbManager.getADBInstance();
-}