appium-mcp 0.0.1 → 1.1.5

package/docs/CONTRIBUTING.md

@@ -0,0 +1,424 @@
+# 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

@@ -0,0 +1,49 @@
+import js from '@eslint/js';
+import typescript from '@typescript-eslint/eslint-plugin';
+import typescriptParser from '@typescript-eslint/parser';
+import prettier from 'eslint-plugin-prettier';
+import prettierConfig from 'eslint-config-prettier';
+
+export default [
+  js.configs.recommended,
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+      globals: {
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        global: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        exports: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': typescript,
+      prettier: prettier,
+    },
+    rules: {
+      ...typescript.configs.recommended.rules,
+      ...prettierConfig.rules,
+      'prettier/prettier': 'error',
+      '@typescript-eslint/no-unused-vars': '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-undef': 'off', // TypeScript handles this
+      'no-case-declarations': 'off',
+    },
+  },
+  {
+    ignores: ['dist/', 'node_modules/', '*.js'],
+  },
+];

package/examples/android-gmail.md

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,23 @@
+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/package.json

@@ -1,12 +1,77 @@
 {
   "name": "appium-mcp",
-  "version": "0.0.1",
-  "main": "index.js",
+  "version": "1.1.5",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "mcp-appium": "dist/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "rimraf dist && tsc && chmod +x dist/index.js && npm run copy-docs",
+    "copy-docs": "mkdir -p dist/tools/documentation/uploads && cp -f src/tools/documentation/uploads/documents.json dist/tools/documentation/uploads/documents.json 2>/dev/null || true",
+    "start": "node src/index.js",
+    "start:stdio": "node src/index.js",
+    "start:sse": "node src/index.js --sse",
+    "start:sse:port": "node src/index.js --sse --port=",
+    "dev": "npx fastmcp dev src/index.js",
+    "inspect": "npx fastmcp inspect src/index.js",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:locators": "NODE_OPTIONS=--experimental-vm-modules jest src/tests/generate-all-locators.test.ts",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.{ts,js,json}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json}\"",
+    "check": "npm run lint && npm run format:check",
+    "index-docs": "node dist/scripts/simple-index-documentation.js",
+    "query-docs": "node dist/scripts/simple-query-documentation.js",
+    "prepublish": "npm run build"
   },
-  "keywords": [],
   "author": "",
-  "license": "ISC",
-  "description": ""
+  "license": "MIT",
+  "description": "Intelligent MCP server providing AI assistants with powerful tools and resources for Appium mobile automation",
+  "dependencies": {
+    "@appium/support": "^7.0.2",
+    "@langfuse/otel": "^4.2.0",
+    "@langfuse/tracing": "^4.2.0",
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@opentelemetry/sdk-node": "^0.206.0",
+    "@xenova/transformers": "^2.17.2",
+    "@xmldom/xmldom": "^0.9.8",
+    "appium-adb": "^12.12.1",
+    "appium-ios-device": "^3.1.0",
+    "appium-uiautomator2-driver": "^5.0.5",
+    "appium-xcuitest-driver": "^10.2.1",
+    "axios": "^1.7.9",
+    "fast-xml-parser": "^5.2.3",
+    "fastmcp": "^1.23.2",
+    "langchain": "^0.3.27",
+    "lodash": "^4.17.21",
+    "node-simctl": "^8.0.4",
+    "rimraf": "^6.0.1",
+    "xpath": "^0.0.34",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.0.2",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "@types/jest": "^29.5.12",
+    "@types/lodash": "^4.17.17",
+    "@types/node": "^22.15.18",
+    "@typescript-eslint/eslint-plugin": "^8.34.0",
+    "@typescript-eslint/parser": "^8.34.0",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "eslint": "^9.28.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.4.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
 }

package/scripts/setup-submodules-sparse.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Setup sparse-checkout for Git submodules to only checkout .md and image files
+
+set -e
+
+SUBMODULES=(
+  "src/resources/submodules/appium"
+  "src/resources/submodules/appium-uiautomator2-driver"
+  "src/resources/submodules/appium-xcuitest-driver"
+)
+
+configure_sparse_checkout() {
+  local submodule_path=$1
+  echo "Configuring sparse-checkout for $submodule_path..."
+  
+  cd "$submodule_path"
+  
+  # Initialize sparse-checkout in non-cone mode
+  git sparse-checkout init --no-cone
+  
+  # Get the actual git directory path (handles submodules correctly)
+  GIT_DIR=$(git rev-parse --git-dir)
+  
+  # Add patterns for markdown and image files
+  echo -e "/*.md\n/**/*.md\n/*.png\n/**/*.png\n/*.jpg\n/**/*.jpg\n/*.jpeg\n/**/*.jpeg\n/*.gif\n/**/*.gif\n/*.svg\n/**/*.svg" > "$GIT_DIR/info/sparse-checkout"
+  
+  # Reapply sparse-checkout
+  git sparse-checkout reapply
+  
+  # Update the working directory
+  git checkout
+  
+  cd - > /dev/null
+  echo "✓ Configured sparse-checkout for $submodule_path"
+}
+
+# Configure each submodule
+for submodule in "${SUBMODULES[@]}"; do
+  if [ -d "$submodule" ]; then
+    configure_sparse_checkout "$submodule"
+  else
+    echo "⚠ Warning: $submodule not found, skipping..."
+  fi
+done
+
+echo ""
+echo "✓ Sparse-checkout configuration complete!"
+echo ""
+echo "To update submodules in the future, run:"
+echo "  git submodule update --remote"
+echo ""
+echo "To reapply sparse-checkout after updates:"
+echo "  ./scripts/setup-submodules-sparse.sh"

package/scripts/update-submodules.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Update Git submodules to latest commits and reapply sparse-checkout
+
+set -e
+
+echo "Updating Git submodules..."
+git submodule update --remote --recursive
+
+echo ""
+echo "Reapplying sparse-checkout to submodules..."
+./scripts/setup-submodules-sparse.sh
+
+echo ""
+echo "✓ Submodules updated successfully!"