From 0d07e8978f98c92489900c883d88c52bebf0d8dc Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 11:59:40 +0600 Subject: [PATCH 01/22] docs: Add comprehensive development setup guide - Add DEVELOPMENT.md with complete setup instructions - Include verified environment requirements for macOS - Document iOS simulator and Android emulator setup - Provide troubleshooting tips and common issues - Add development workflow and testing procedures - Include IDE recommendations and configuration This addresses the need for clear developer onboarding documentation that was missing from the project. --- DEVELOPMENT.md | 140 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 DEVELOPMENT.md diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 0000000..edbd972 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,140 @@ +# Mobile MCP Development Setup + +## ✅ Your Environment Status + +**System Information:** +- **OS**: macOS (Darwin 24.5.0) +- **Node.js**: v24.2.0 ✅ +- **npm**: 11.3.0 ✅ +- **Git**: 2.48.1 ✅ +- **TypeScript**: Installed globally ✅ + +**Platform Tools:** +- **iOS Simulators**: Available (iOS 18.2, 18.4) ✅ +- **Android ADB**: v1.0.41 (Version 35.0.2) ✅ +- **go-ios**: Installed ✅ +- **Xcode CLI Tools**: Available ✅ + +**Project Status:** +- **Dependencies**: Installed ✅ +- **Build**: Successful ✅ +- **Linting**: Passing ✅ + +## 🚀 Development Workflow + +### Quick Start Commands +```bash +# Build and watch for changes +npm run watch + +# Build once +npm run build + +# Run linting +npm run lint + +# Test specific components +npx mocha --require ts-node/register test/iphone-simulator.ts +npx mocha --require ts-node/register test/android.ts +``` + +### Testing the MCP Server +```bash +# Test the built server +node lib/index.js --help + +# Start server in stdio mode (default) +node lib/index.js + +# Start server with SSE on port 3000 +node lib/index.js --port 3000 +``` + +## 📱 Device Testing + +### iOS Simulator Testing +```bash +# List available simulators +xcrun simctl list devices + +# Boot a simulator for testing +xcrun simctl boot "iPhone 16" + +# Verify simulator is booted +xcrun simctl list devices | grep Booted +``` + +### Android Emulator Testing +```bash +# Check connected devices +adb devices + +# If you have Android Studio, start an emulator: +# emulator -avd YOUR_AVD_NAME +``` + +## 🛠️ Development Tips + +### Project Structure +- `src/server.ts` - Main MCP server logic +- `src/robot.ts` - Core device abstraction +- `src/android.ts` - Android implementation +- `src/ios.ts` - iOS physical device implementation +- `src/iphone-simulator.ts` - iOS simulator implementation + +### Making Changes +1. Edit source files in `src/` +2. Watch mode will auto-rebuild (`npm run watch`) +3. Test changes with `node lib/index.js` +4. Run specific tests for your changes + +### Testing Your Changes +```bash +# Test with MCP client like Cursor/Cline by updating your config: +{ + "mcpServers": { + "mobile-mcp-dev": { + "command": "node", + "args": ["/Users/rbs_saiful_mac_mini/office_projects/mobile-mcp/lib/index.js"] + } + } +} +``` + +## 🔧 IDE Recommendations + +### VS Code Extensions +- TypeScript Importer +- ESLint +- Prettier +- GitLens + +### Settings +```json +// .vscode/settings.json +{ + "typescript.preferences.importModuleSpecifier": "relative", + "editor.codeActionsOnSave": { + "source.fixAll.eslint": true + } +} +``` + +## 🐛 Troubleshooting + +### Common Issues +1. **Tests failing with 'ios ENOENT'**: Install go-ios globally +2. **WebDriverAgent not found**: Ensure you have Xcode installed +3. **Android ADB issues**: Check ANDROID_HOME environment variable + +### Getting Help +- Check the [wiki](https://github.com/mobile-next/mobile-mcp/wiki) +- Join [Slack community](http://mobilenexthq.com/join-slack) +- Review existing [GitHub issues](https://github.com/mobile-next/mobile-mcp/issues) + +--- + +**Next Steps:** +1. Try making a small change in `src/server.ts` +2. Test with a simulator/emulator +3. Consider adding new MCP tools or improving existing ones \ No newline at end of file From ddc71a953ec08f8a18ef98b264c6fbad20d3033f Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 12:03:46 +0600 Subject: [PATCH 02/22] docs: Improve DEVELOPMENT.md to comprehensive macOS setup guide - Transform from environment-specific to generic macOS guide - Add multiple installation methods (Homebrew, manual, nvm) - Include detailed iOS and Android platform setup - Add comprehensive troubleshooting section - Include IDE recommendations and terminal aliases - Add contributing guidelines and best practices - Cover different macOS versions and setup scenarios This provides a complete onboarding experience for macOS developers wanting to contribute to mobile automation features. --- DEVELOPMENT.md | 364 ++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 283 insertions(+), 81 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index edbd972..cef798b 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,140 +1,342 @@ -# Mobile MCP Development Setup +# Mobile MCP Development Setup - macOS Guide -## ✅ Your Environment Status +This guide will help you set up a complete development environment for Mobile MCP on macOS, covering both iOS simulators and Android emulators. -**System Information:** -- **OS**: macOS (Darwin 24.5.0) -- **Node.js**: v24.2.0 ✅ -- **npm**: 11.3.0 ✅ -- **Git**: 2.48.1 ✅ -- **TypeScript**: Installed globally ✅ +## 📋 Prerequisites -**Platform Tools:** -- **iOS Simulators**: Available (iOS 18.2, 18.4) ✅ -- **Android ADB**: v1.0.41 (Version 35.0.2) ✅ -- **go-ios**: Installed ✅ -- **Xcode CLI Tools**: Available ✅ +### System Requirements +- **macOS**: 10.15+ (Catalina or later) +- **Xcode**: Latest version from App Store +- **Node.js**: v18+ (v20+ recommended) +- **Git**: For version control -**Project Status:** -- **Dependencies**: Installed ✅ -- **Build**: Successful ✅ -- **Linting**: Passing ✅ +### Quick Environment Check +```bash +# Verify your current setup +node --version # Should be >= 18 +npm --version # Should be >= 8 +git --version # Any recent version +xcode-select -p # Should show Xcode path +``` -## 🚀 Development Workflow +## 🛠️ Initial Setup + +### 1. Install Core Development Tools -### Quick Start Commands +**Install Xcode Command Line Tools:** ```bash -# Build and watch for changes -npm run watch +xcode-select --install +``` -# Build once -npm run build +**Install Node.js (if not already installed):** +```bash +# Option 1: Using Homebrew (recommended) +brew install node -# Run linting -npm run lint +# Option 2: Download from nodejs.org +# https://nodejs.org/en/download/ -# Test specific components -npx mocha --require ts-node/register test/iphone-simulator.ts -npx mocha --require ts-node/register test/android.ts +# Option 3: Using nvm for version management +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash +nvm install --lts +nvm use --lts ``` -### Testing the MCP Server +**Install TypeScript globally:** ```bash -# Test the built server -node lib/index.js --help +npm install -g typescript +``` -# Start server in stdio mode (default) -node lib/index.js +### 2. Clone and Setup Project -# Start server with SSE on port 3000 -node lib/index.js --port 3000 +```bash +# Clone the repository +git clone https://github.com/mobile-next/mobile-mcp.git +cd mobile-mcp + +# Install dependencies +npm install + +# Build the project +npm run build + +# Verify installation +node lib/index.js --help ``` -## 📱 Device Testing +## 📱 Platform-Specific Setup -### iOS Simulator Testing +### iOS Development Setup + +**1. Verify iOS Simulator Access:** ```bash # List available simulators xcrun simctl list devices # Boot a simulator for testing -xcrun simctl boot "iPhone 16" +xcrun simctl boot "iPhone 15" # or any available device +``` -# Verify simulator is booted -xcrun simctl list devices | grep Booted +**2. Install go-ios (for physical iOS devices):** +```bash +# Install globally via npm +npm install -g go-ios + +# Verify installation +ios version ``` -### Android Emulator Testing +**Alternative go-ios installation methods:** ```bash -# Check connected devices -adb devices +# Using Homebrew +brew install go-ios -# If you have Android Studio, start an emulator: -# emulator -avd YOUR_AVD_NAME +# Manual installation from releases +# Download from: https://github.com/danielpaulus/go-ios/releases ``` -## 🛠️ Development Tips +**3. WebDriverAgent Setup:** +For iOS automation, WebDriverAgent needs to be running. This typically requires: +- Xcode project setup (see [iOS Wiki](https://github.com/mobile-next/mobile-mcp/wiki)) +- Signing certificates for physical devices +- Port forwarding setup + +### Android Development Setup -### Project Structure -- `src/server.ts` - Main MCP server logic -- `src/robot.ts` - Core device abstraction -- `src/android.ts` - Android implementation -- `src/ios.ts` - iOS physical device implementation -- `src/iphone-simulator.ts` - iOS simulator implementation +**1. Install Android SDK Platform Tools:** +```bash +# Option 1: Using Homebrew +brew install android-platform-tools -### Making Changes -1. Edit source files in `src/` -2. Watch mode will auto-rebuild (`npm run watch`) -3. Test changes with `node lib/index.js` -4. Run specific tests for your changes +# Option 2: Using Android Studio +# Download Android Studio and install SDK through the IDE -### Testing Your Changes +# Option 3: Manual download +# Download from: https://developer.android.com/tools/releases/platform-tools +``` + +**2. Set Environment Variables:** +```bash +# Add to your ~/.zshrc or ~/.bash_profile +export ANDROID_HOME="$HOME/Library/Android/sdk" +export PATH="$PATH:$ANDROID_HOME/platform-tools" + +# Reload your shell +source ~/.zshrc # or source ~/.bash_profile +``` + +**3. Verify ADB Installation:** +```bash +adb version +adb devices # Should list connected devices/emulators +``` + +**4. Setup Android Emulator (Optional):** +```bash +# If using Android Studio, create an AVD through the IDE +# Or use command line: +avdmanager create avd -n "Mobile_MCP_Test" -k "system-images;android-33;google_apis;arm64-v8a" +emulator -avd Mobile_MCP_Test +``` + +## 🚀 Development Workflow + +### Building and Testing ```bash -# Test with MCP client like Cursor/Cline by updating your config: +# Development with auto-rebuild +npm run watch + +# Single build +npm run build + +# Run linting +npm run lint + +# Run tests (requires devices/simulators) +npm test + +# Test specific components +npx mocha --require ts-node/register test/iphone-simulator.ts +npx mocha --require ts-node/register test/android.ts +``` + +### Testing the MCP Server +```bash +# Test help command +node lib/index.js --help + +# Start server in stdio mode (default) +node lib/index.js + +# Start server with SSE on custom port +node lib/index.js --port 3000 +``` + +### Integration Testing +Test your local development version with MCP clients: + +**Cursor/Cline Configuration:** +```json { "mcpServers": { "mobile-mcp-dev": { "command": "node", - "args": ["/Users/rbs_saiful_mac_mini/office_projects/mobile-mcp/lib/index.js"] + "args": ["~/path/to/mobile-mcp/lib/index.js"] } } } ``` -## 🔧 IDE Recommendations +## 📂 Project Structure -### VS Code Extensions -- TypeScript Importer -- ESLint -- Prettier -- GitLens +``` +src/ +├── server.ts # Main MCP server logic & tool registration +├── index.ts # CLI entry point +├── robot.ts # Core device abstraction interface +├── android.ts # Android implementation (ADB + UIAutomator) +├── ios.ts # iOS physical device (go-ios + WebDriverAgent) +├── iphone-simulator.ts # iOS simulator (simctl + WebDriverAgent) +├── webdriver-agent.ts # WebDriverAgent HTTP client +├── image-utils.ts # Image processing utilities +├── png.ts # PNG handling +└── logger.ts # Logging utilities + +test/ # Test suites for each platform +lib/ # Compiled JavaScript output +``` + +## 🔧 IDE Setup Recommendations -### Settings +### VS Code Configuration ```json // .vscode/settings.json { "typescript.preferences.importModuleSpecifier": "relative", "editor.codeActionsOnSave": { "source.fixAll.eslint": true - } + }, + "editor.formatOnSave": true, + "editor.rulers": [120], + "typescript.preferences.quoteStyle": "double" } ``` -## 🐛 Troubleshooting +**Recommended VS Code Extensions:** +- TypeScript Importer +- ESLint +- Prettier - Code formatter +- GitLens — Git supercharged +- Error Lens +- Auto Rename Tag + +### Terminal Setup +```bash +# Add helpful aliases to ~/.zshrc or ~/.bash_profile +alias mcp-build="npm run build" +alias mcp-watch="npm run watch" +alias mcp-test="npm test" +alias mcp-lint="npm run lint" +alias mcp-start="node lib/index.js" + +# iOS simulator helpers +alias ios-list="xcrun simctl list devices" +alias ios-boot="xcrun simctl boot" + +# Android helpers +alias android-devices="adb devices" +alias android-emulator="emulator -list-avds && emulator -avd" +``` + +## 🐛 Common Issues & Troubleshooting + +### iOS Issues +**Problem**: `WebDriverAgent is not running on simulator` +```bash +# Solution: Ensure Xcode is properly set up +sudo xcode-select -s /Applications/Xcode.app/Contents/Developer +xcrun simctl list devices +``` + +**Problem**: `go-ios` command not found +```bash +# Solution: Install go-ios and verify PATH +npm install -g go-ios +which ios # Should show installation path +``` + +### Android Issues +**Problem**: `adb: command not found` +```bash +# Solution: Install platform tools and set PATH +brew install android-platform-tools +echo 'export PATH="$PATH:$(brew --prefix)/bin"' >> ~/.zshrc +``` + +**Problem**: `ANDROID_HOME` not set +```bash +# Solution: Set environment variable +export ANDROID_HOME="$HOME/Library/Android/sdk" +export PATH="$PATH:$ANDROID_HOME/platform-tools" +``` + +### Build Issues +**Problem**: TypeScript compilation errors +```bash +# Solution: Clean and rebuild +npm run clean +npm install +npm run build +``` + +**Problem**: ESLint errors +```bash +# Solution: Auto-fix common issues +npm run lint -- --fix +``` + +### Testing Issues +**Problem**: Tests fail with device connection errors +```bash +# Solution: Ensure devices are connected and accessible +# For iOS: +xcrun simctl list devices | grep Booted + +# For Android: +adb devices +``` + +## 🚀 Contributing + +### Before Making Changes +1. Create a feature branch: `git checkout -b feature/your-feature-name` +2. Make your changes +3. Test on both iOS and Android if applicable +4. Run linting: `npm run lint` +5. Build successfully: `npm run build` + +### Testing Your Changes +1. Test with simulators/emulators +2. Verify MCP tool integration works +3. Test with different device types if possible + +### Submitting Changes +1. Commit with descriptive messages +2. Push to your fork +3. Create a pull request with clear description -### Common Issues -1. **Tests failing with 'ios ENOENT'**: Install go-ios globally -2. **WebDriverAgent not found**: Ensure you have Xcode installed -3. **Android ADB issues**: Check ANDROID_HOME environment variable +## 📚 Additional Resources -### Getting Help -- Check the [wiki](https://github.com/mobile-next/mobile-mcp/wiki) -- Join [Slack community](http://mobilenexthq.com/join-slack) -- Review existing [GitHub issues](https://github.com/mobile-next/mobile-mcp/issues) +- **Project Wiki**: [GitHub Wiki](https://github.com/mobile-next/mobile-mcp/wiki) +- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/) +- **iOS Setup Guide**: [Wiki - iOS Setup](https://github.com/mobile-next/mobile-mcp/wiki/) +- **Community**: [Slack Channel](http://mobilenexthq.com/join-slack) +- **Issues**: [GitHub Issues](https://github.com/mobile-next/mobile-mcp/issues) --- -**Next Steps:** -1. Try making a small change in `src/server.ts` -2. Test with a simulator/emulator -3. Consider adding new MCP tools or improving existing ones \ No newline at end of file +**Ready to start developing?** 🎉 +1. Follow the setup steps above +2. Start with `npm run watch` +3. Make a small test change +4. Join the community for support! \ No newline at end of file From c8d87450ab3db6e3e7b93e8bdfaba7778d7b7ff8 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 12:12:38 +0600 Subject: [PATCH 03/22] docs: Add complete feature development walkthrough - Add comprehensive 11-step feature contribution guide - Include practical 'Get Device Info' implementation example - Show TypeScript interface design and cross-platform implementation - Provide testing procedures and quality check guidelines - Add PR best practices with detailed template - Include feature ideas categorized by difficulty level - Add platform-specific development resources - Demonstrate proper git workflow and commit conventions This enables new contributors to understand exactly how to add features to Mobile MCP from start to finish. --- DEVELOPMENT.md => MACOS_DEVELOPMENT.md | 302 +++++++++++++++++++++++++ 1 file changed, 302 insertions(+) rename DEVELOPMENT.md => MACOS_DEVELOPMENT.md (52%) diff --git a/DEVELOPMENT.md b/MACOS_DEVELOPMENT.md similarity index 52% rename from DEVELOPMENT.md rename to MACOS_DEVELOPMENT.md index cef798b..6f673b1 100644 --- a/DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -325,6 +325,308 @@ adb devices 2. Push to your fork 3. Create a pull request with clear description +## 🛠️ Contributing a New Feature - Complete Walkthrough + +### Example: Adding "Get Device Info" Feature + +Let's walk through adding a new MCP tool that returns detailed device information. This demonstrates the complete development workflow. + +#### Step 1: Setup and Planning +```bash +# 1. Fork the repository on GitHub +# 2. Clone your fork +git clone https://github.com/YOUR_USERNAME/mobile-mcp.git +cd mobile-mcp + +# 3. Follow the setup guide above to install dependencies +npm install +npm run build + +# 4. Create feature branch +git checkout -b feature/get-device-info +``` + +#### Step 2: Understand the Architecture + +**Key Files for MCP Tools:** +- `src/server.ts` - Register new MCP tools +- `src/robot.ts` - Add interface method if needed +- `src/android.ts` - Android implementation +- `src/ios.ts` - iOS physical device implementation +- `src/iphone-simulator.ts` - iOS simulator implementation + +#### Step 3: Define the Interface + +**Add to `src/robot.ts`:** +```typescript +export interface DeviceInfo { + platform: "ios" | "android"; + osVersion: string; + deviceModel: string; + screenResolution: string; + batteryLevel?: number; + isSimulator: boolean; +} + +export interface Robot { + // ... existing methods ... + + /** + * Get detailed device information + */ + getDeviceInfo(): Promise; +} +``` + +#### Step 4: Implement for Each Platform + +**Android Implementation (`src/android.ts`):** +```typescript +public async getDeviceInfo(): Promise { + const model = this.adb("shell", "getprop", "ro.product.model").toString().trim(); + const osVersion = this.adb("shell", "getprop", "ro.build.version.release").toString().trim(); + const screenSize = await this.getScreenSize(); + + return { + platform: "android", + osVersion, + deviceModel: model, + screenResolution: `${screenSize.width}x${screenSize.height}`, + isSimulator: false, // Could detect emulator vs physical + }; +} +``` + +**iOS Implementation (`src/ios.ts`):** +```typescript +public async getDeviceInfo(): Promise { + const info = await this.ios("info"); + const json = JSON.parse(info); + const screenSize = await this.getScreenSize(); + + return { + platform: "ios", + osVersion: json.ProductVersion, + deviceModel: json.ProductType, + screenResolution: `${screenSize.width}x${screenSize.height}`, + isSimulator: false, + }; +} +``` + +**iOS Simulator Implementation (`src/iphone-simulator.ts`):** +```typescript +public async getDeviceInfo(): Promise { + const screenSize = await this.getScreenSize(); + // Get simulator info from simctl + const deviceInfo = execFileSync("xcrun", ["simctl", "list", "devices", "-j"]); + + return { + platform: "ios", + osVersion: "Simulator", + deviceModel: "iPhone Simulator", + screenResolution: `${screenSize.width}x${screenSize.height}`, + isSimulator: true, + }; +} +``` + +#### Step 5: Register the MCP Tool + +**Add to `src/server.ts`:** +```typescript +tool( + "mobile_get_device_info", + "Get detailed information about the connected device including platform, OS version, model, and screen resolution", + { + noParams + }, + async () => { + requireRobot(); + const deviceInfo = await robot!.getDeviceInfo(); + + return JSON.stringify({ + platform: deviceInfo.platform, + osVersion: deviceInfo.osVersion, + deviceModel: deviceInfo.deviceModel, + screenResolution: deviceInfo.screenResolution, + batteryLevel: deviceInfo.batteryLevel, + isSimulator: deviceInfo.isSimulator, + }, null, 2); + } +); +``` + +#### Step 6: Test Your Implementation + +**Build and test:** +```bash +# Build the project +npm run build + +# Test with a device connected +node lib/index.js + +# In another terminal, test with MCP client or direct testing +``` + +**Testing script example:** +```typescript +// test/device-info.ts +import { describe, it } from "mocha"; +import { AndroidRobot } from "../src/android"; + +describe("device-info", () => { + it("should get Android device info", async () => { + // Test implementation + }); + + it("should get iOS device info", async () => { + // Test implementation + }); +}); +``` + +#### Step 7: Test with MCP Client + +**Cursor/Cline config:** +```json +{ + "mcpServers": { + "mobile-mcp-dev": { + "command": "node", + "args": ["~/mobile-mcp/lib/index.js"] + } + } +} +``` + +**Test the tool:** +``` +> Use the mobile_get_device_info tool to get information about my device +``` + +#### Step 8: Quality Checks + +```bash +# Run linting +npm run lint + +# Fix any issues +npm run lint -- --fix + +# Run tests +npm test + +# Test specific components +npx mocha --require ts-node/register test/device-info.ts +``` + +#### Step 9: Documentation + +**Update appropriate files:** +- Add tool description to README.md +- Document any new dependencies +- Add examples in wiki if complex + +#### Step 10: Commit and Submit + +```bash +# Commit your changes +git add . +git commit -m "feat: add mobile_get_device_info tool + +- Add getDeviceInfo interface to Robot +- Implement device info collection for Android, iOS, and simulators +- Return platform, OS version, model, screen resolution +- Add comprehensive device information MCP tool +- Include tests for all platforms + +Closes #123" # if there was an issue + +# Push to your fork +git push origin feature/get-device-info + +# Create pull request on GitHub +``` + +#### Step 11: Pull Request Best Practices + +**PR Description Template:** +```markdown +## 🚀 Feature: Get Device Info Tool + +### What does this PR do? +Adds a new MCP tool `mobile_get_device_info` that returns detailed device information. + +### Changes Made +- ✅ Added `getDeviceInfo()` interface to Robot +- ✅ Implemented for Android devices +- ✅ Implemented for iOS devices +- ✅ Implemented for iOS simulators +- ✅ Added MCP tool registration +- ✅ Added tests +- ✅ Updated documentation + +### Testing +- [x] Tested on iOS simulator +- [x] Tested on Android emulator +- [ ] Tested on physical iOS device +- [ ] Tested on physical Android device + +### Screenshots/Output +```json +{ + "platform": "ios", + "osVersion": "17.0", + "deviceModel": "iPhone15,2", + "screenResolution": "1179x2556", + "isSimulator": false +} +``` + +### Breaking Changes +None + +### Related Issues +Closes #123 +``` + +### 🎯 Key Takeaways for Contributors + +1. **Follow the pattern**: Study existing tools in `server.ts` +2. **Implement across platforms**: Android, iOS, iOS Simulator +3. **Add proper TypeScript types**: Update `robot.ts` interface +4. **Test thoroughly**: Multiple devices and scenarios +5. **Document your changes**: README, code comments +6. **Follow conventions**: Naming, error handling, logging +7. **Write good commit messages**: Use conventional commits +8. **Create detailed PRs**: Help reviewers understand your changes + +### 💡 Feature Ideas for New Contributors + +**Easy features:** +- `mobile_get_battery_level` - Battery percentage +- `mobile_get_wifi_info` - WiFi network details +- `mobile_toggle_airplane_mode` - Airplane mode control + +**Medium features:** +- `mobile_install_app` - Install app from file +- `mobile_record_screen` - Screen recording +- `mobile_get_logs` - Device logs + +**Advanced features:** +- `mobile_simulate_location` - GPS mocking +- `mobile_test_performance` - Performance metrics +- `mobile_network_conditions` - Simulate network conditions + +### 🔗 Useful Resources for Feature Development + +- **MCP Spec**: [Model Context Protocol](https://modelcontextprotocol.io/) +- **Android ADB**: [ADB Shell Commands](https://developer.android.com/studio/command-line/adb) +- **iOS go-ios**: [go-ios Documentation](https://github.com/danielpaulus/go-ios) +- **WebDriverAgent**: [WDA Protocol](https://github.com/appium/WebDriverAgent) + ## 📚 Additional Resources - **Project Wiki**: [GitHub Wiki](https://github.com/mobile-next/mobile-mcp/wiki) From 62e641476e896c081c09f42dc0560085e9b21b34 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 12:17:48 +0600 Subject: [PATCH 04/22] docs: Add compelling introduction to motivate contributors - Add engaging project value proposition highlighting AI mobile automation - Explain what contributors will build and impact they'll have - Clearly outline what the guide covers with visual progression - Emphasize real-world applications for QA, developers, AI researchers - Create hook that connects passion for mobile/AI to contribution opportunity - Structure guide with clear sections and call-to-action This transforms the doc from technical setup to inspiring contribution guide. --- MACOS_DEVELOPMENT.md | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 6f673b1..6c723ec 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -1,4 +1,46 @@ -# Mobile MCP Development Setup - macOS Guide +# 📱 Mobile MCP Development - macOS Guide + +## 🚀 Like This Project? Want to Contribute? + +**Mobile MCP** is revolutionizing mobile automation by bringing AI agents to iOS and Android devices. If you're excited about: + +✨ **AI-driven mobile automation** - Let LLMs control real mobile apps +🤖 **Cross-platform development** - One API for iOS, Android, simulators & physical devices +🛠️ **Developer tools** - Building the future of mobile testing and automation +🌍 **Open source impact** - Contributing to tools used by thousands of developers + +**Then you're in the right place!** 🎉 + +### 🎯 What You'll Build + +Contributors to Mobile MCP create tools that enable AI agents to: +- **Automate complex workflows** across multiple mobile apps +- **Test mobile applications** with natural language instructions +- **Extract data** from any mobile interface +- **Simulate user interactions** for testing and automation +- **Control real devices** programmatically through simple commands + +### 💻 This Guide Will Show You: + +1. **🔧 Complete macOS setup** - Get your development environment ready +2. **📱 iOS & Android configuration** - Work with simulators, emulators, and real devices +3. **🛠️ Feature development walkthrough** - Add new tools step-by-step +4. **✅ Testing & quality practices** - Ensure your contributions are solid +5. **🚀 Contributing workflow** - From fork to merged pull request + +### 🌟 Why Mobile MCP Matters + +Mobile MCP bridges the gap between AI and mobile devices, enabling: +- **QA teams** to automate testing with natural language +- **Developers** to create sophisticated mobile automation scripts +- **AI researchers** to build agents that interact with real mobile apps +- **Businesses** to automate repetitive mobile workflows + +**Ready to build the future of mobile automation?** Let's get started! 👇 + +--- + +# Setup Guide for macOS Developers This guide will help you set up a complete development environment for Mobile MCP on macOS, covering both iOS simulators and Android emulators. From de18abdd8eef77546ccceed0f534c61ce44e70e1 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 12:19:29 +0600 Subject: [PATCH 05/22] docs: Finalize development guide - concise but powerful - Streamline setup to essential commands only - Condense feature walkthrough while keeping all key steps - Remove redundancy and verbose explanations - Maintain engaging tone and motivation - Focus on actionable content over lengthy descriptions - Keep all essential information in more digestible format - Strengthen call-to-action and community connection Result: Powerful contributor guide that's quick to read but complete in scope. --- MACOS_DEVELOPMENT.md | 643 ++++++------------------------------------- 1 file changed, 86 insertions(+), 557 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 6c723ec..c6e41df 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -2,427 +2,96 @@ ## 🚀 Like This Project? Want to Contribute? -**Mobile MCP** is revolutionizing mobile automation by bringing AI agents to iOS and Android devices. If you're excited about: - -✨ **AI-driven mobile automation** - Let LLMs control real mobile apps -🤖 **Cross-platform development** - One API for iOS, Android, simulators & physical devices -🛠️ **Developer tools** - Building the future of mobile testing and automation -🌍 **Open source impact** - Contributing to tools used by thousands of developers - -**Then you're in the right place!** 🎉 +**Mobile MCP** revolutionizes mobile automation by bringing AI agents to iOS and Android devices. Build tools that let LLMs control real mobile apps, automate testing with natural language, and create the future of mobile automation. ### 🎯 What You'll Build +- **AI-driven mobile automation** across iOS/Android +- **Cross-platform tools** for simulators & physical devices +- **Natural language testing** capabilities +- **Real-world solutions** used by QA teams and developers -Contributors to Mobile MCP create tools that enable AI agents to: -- **Automate complex workflows** across multiple mobile apps -- **Test mobile applications** with natural language instructions -- **Extract data** from any mobile interface -- **Simulate user interactions** for testing and automation -- **Control real devices** programmatically through simple commands - -### 💻 This Guide Will Show You: - -1. **🔧 Complete macOS setup** - Get your development environment ready -2. **📱 iOS & Android configuration** - Work with simulators, emulators, and real devices -3. **🛠️ Feature development walkthrough** - Add new tools step-by-step -4. **✅ Testing & quality practices** - Ensure your contributions are solid -5. **🚀 Contributing workflow** - From fork to merged pull request - -### 🌟 Why Mobile MCP Matters - -Mobile MCP bridges the gap between AI and mobile devices, enabling: -- **QA teams** to automate testing with natural language -- **Developers** to create sophisticated mobile automation scripts -- **AI researchers** to build agents that interact with real mobile apps -- **Businesses** to automate repetitive mobile workflows +### 💻 This Guide: Setup → Develop → Contribute +1. **🔧 macOS Environment** - Complete development setup +2. **📱 Platform Configuration** - iOS/Android tools +3. **🛠️ Feature Development** - Add new MCP tools +4. **🚀 Contribution Workflow** - From code to pull request -**Ready to build the future of mobile automation?** Let's get started! 👇 +**Ready to build the future of mobile automation?** Let's start! 👇 --- -# Setup Guide for macOS Developers - -This guide will help you set up a complete development environment for Mobile MCP on macOS, covering both iOS simulators and Android emulators. - -## 📋 Prerequisites - -### System Requirements -- **macOS**: 10.15+ (Catalina or later) -- **Xcode**: Latest version from App Store -- **Node.js**: v18+ (v20+ recommended) -- **Git**: For version control - -### Quick Environment Check -```bash -# Verify your current setup -node --version # Should be >= 18 -npm --version # Should be >= 8 -git --version # Any recent version -xcode-select -p # Should show Xcode path -``` - -## 🛠️ Initial Setup - -### 1. Install Core Development Tools - -**Install Xcode Command Line Tools:** -```bash -xcode-select --install -``` - -**Install Node.js (if not already installed):** -```bash -# Option 1: Using Homebrew (recommended) -brew install node - -# Option 2: Download from nodejs.org -# https://nodejs.org/en/download/ - -# Option 3: Using nvm for version management -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash -nvm install --lts -nvm use --lts -``` +## 🛠️ Quick Setup -**Install TypeScript globally:** +### Prerequisites ```bash -npm install -g typescript +# Verify your setup +node --version # >= 18 +npm --version # >= 8 +xcode-select -p # Xcode CLI tools ``` -### 2. Clone and Setup Project - +### Project Setup ```bash -# Clone the repository +# Clone and build git clone https://github.com/mobile-next/mobile-mcp.git cd mobile-mcp - -# Install dependencies -npm install - -# Build the project -npm run build +npm install && npm run build # Verify installation node lib/index.js --help ``` -## 📱 Platform-Specific Setup - -### iOS Development Setup +## 📱 Platform Setup -**1. Verify iOS Simulator Access:** +### iOS Development ```bash -# List available simulators +# Simulators (built-in) xcrun simctl list devices +xcrun simctl boot "iPhone 15" -# Boot a simulator for testing -xcrun simctl boot "iPhone 15" # or any available device -``` - -**2. Install go-ios (for physical iOS devices):** -```bash -# Install globally via npm +# Physical devices npm install -g go-ios - -# Verify installation ios version ``` -**Alternative go-ios installation methods:** -```bash -# Using Homebrew -brew install go-ios - -# Manual installation from releases -# Download from: https://github.com/danielpaulus/go-ios/releases -``` - -**3. WebDriverAgent Setup:** -For iOS automation, WebDriverAgent needs to be running. This typically requires: -- Xcode project setup (see [iOS Wiki](https://github.com/mobile-next/mobile-mcp/wiki)) -- Signing certificates for physical devices -- Port forwarding setup - -### Android Development Setup - -**1. Install Android SDK Platform Tools:** +### Android Development ```bash -# Option 1: Using Homebrew +# Platform tools brew install android-platform-tools - -# Option 2: Using Android Studio -# Download Android Studio and install SDK through the IDE - -# Option 3: Manual download -# Download from: https://developer.android.com/tools/releases/platform-tools -``` - -**2. Set Environment Variables:** -```bash -# Add to your ~/.zshrc or ~/.bash_profile -export ANDROID_HOME="$HOME/Library/Android/sdk" -export PATH="$PATH:$ANDROID_HOME/platform-tools" - -# Reload your shell -source ~/.zshrc # or source ~/.bash_profile -``` - -**3. Verify ADB Installation:** -```bash adb version -adb devices # Should list connected devices/emulators -``` - -**4. Setup Android Emulator (Optional):** -```bash -# If using Android Studio, create an AVD through the IDE -# Or use command line: -avdmanager create avd -n "Mobile_MCP_Test" -k "system-images;android-33;google_apis;arm64-v8a" -emulator -avd Mobile_MCP_Test -``` - -## 🚀 Development Workflow - -### Building and Testing -```bash -# Development with auto-rebuild -npm run watch - -# Single build -npm run build - -# Run linting -npm run lint - -# Run tests (requires devices/simulators) -npm test - -# Test specific components -npx mocha --require ts-node/register test/iphone-simulator.ts -npx mocha --require ts-node/register test/android.ts -``` - -### Testing the MCP Server -```bash -# Test help command -node lib/index.js --help -# Start server in stdio mode (default) -node lib/index.js - -# Start server with SSE on custom port -node lib/index.js --port 3000 -``` - -### Integration Testing -Test your local development version with MCP clients: - -**Cursor/Cline Configuration:** -```json -{ - "mcpServers": { - "mobile-mcp-dev": { - "command": "node", - "args": ["~/path/to/mobile-mcp/lib/index.js"] - } - } -} -``` - -## 📂 Project Structure - -``` -src/ -├── server.ts # Main MCP server logic & tool registration -├── index.ts # CLI entry point -├── robot.ts # Core device abstraction interface -├── android.ts # Android implementation (ADB + UIAutomator) -├── ios.ts # iOS physical device (go-ios + WebDriverAgent) -├── iphone-simulator.ts # iOS simulator (simctl + WebDriverAgent) -├── webdriver-agent.ts # WebDriverAgent HTTP client -├── image-utils.ts # Image processing utilities -├── png.ts # PNG handling -└── logger.ts # Logging utilities - -test/ # Test suites for each platform -lib/ # Compiled JavaScript output -``` - -## 🔧 IDE Setup Recommendations - -### VS Code Configuration -```json -// .vscode/settings.json -{ - "typescript.preferences.importModuleSpecifier": "relative", - "editor.codeActionsOnSave": { - "source.fixAll.eslint": true - }, - "editor.formatOnSave": true, - "editor.rulers": [120], - "typescript.preferences.quoteStyle": "double" -} -``` - -**Recommended VS Code Extensions:** -- TypeScript Importer -- ESLint -- Prettier - Code formatter -- GitLens — Git supercharged -- Error Lens -- Auto Rename Tag - -### Terminal Setup -```bash -# Add helpful aliases to ~/.zshrc or ~/.bash_profile -alias mcp-build="npm run build" -alias mcp-watch="npm run watch" -alias mcp-test="npm test" -alias mcp-lint="npm run lint" -alias mcp-start="node lib/index.js" - -# iOS simulator helpers -alias ios-list="xcrun simctl list devices" -alias ios-boot="xcrun simctl boot" - -# Android helpers -alias android-devices="adb devices" -alias android-emulator="emulator -list-avds && emulator -avd" -``` - -## 🐛 Common Issues & Troubleshooting - -### iOS Issues -**Problem**: `WebDriverAgent is not running on simulator` -```bash -# Solution: Ensure Xcode is properly set up -sudo xcode-select -s /Applications/Xcode.app/Contents/Developer -xcrun simctl list devices -``` - -**Problem**: `go-ios` command not found -```bash -# Solution: Install go-ios and verify PATH -npm install -g go-ios -which ios # Should show installation path -``` - -### Android Issues -**Problem**: `adb: command not found` -```bash -# Solution: Install platform tools and set PATH -brew install android-platform-tools -echo 'export PATH="$PATH:$(brew --prefix)/bin"' >> ~/.zshrc -``` - -**Problem**: `ANDROID_HOME` not set -```bash -# Solution: Set environment variable +# Environment export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` -### Build Issues -**Problem**: TypeScript compilation errors -```bash -# Solution: Clean and rebuild -npm run clean -npm install -npm run build -``` +## 🛠️ Adding a New Feature -**Problem**: ESLint errors -```bash -# Solution: Auto-fix common issues -npm run lint -- --fix -``` +### Example: "Get Device Info" Tool -### Testing Issues -**Problem**: Tests fail with device connection errors +**1. Create feature branch:** ```bash -# Solution: Ensure devices are connected and accessible -# For iOS: -xcrun simctl list devices | grep Booted - -# For Android: -adb devices -``` - -## 🚀 Contributing - -### Before Making Changes -1. Create a feature branch: `git checkout -b feature/your-feature-name` -2. Make your changes -3. Test on both iOS and Android if applicable -4. Run linting: `npm run lint` -5. Build successfully: `npm run build` - -### Testing Your Changes -1. Test with simulators/emulators -2. Verify MCP tool integration works -3. Test with different device types if possible - -### Submitting Changes -1. Commit with descriptive messages -2. Push to your fork -3. Create a pull request with clear description - -## 🛠️ Contributing a New Feature - Complete Walkthrough - -### Example: Adding "Get Device Info" Feature - -Let's walk through adding a new MCP tool that returns detailed device information. This demonstrates the complete development workflow. - -#### Step 1: Setup and Planning -```bash -# 1. Fork the repository on GitHub -# 2. Clone your fork -git clone https://github.com/YOUR_USERNAME/mobile-mcp.git -cd mobile-mcp - -# 3. Follow the setup guide above to install dependencies -npm install -npm run build - -# 4. Create feature branch git checkout -b feature/get-device-info ``` -#### Step 2: Understand the Architecture - -**Key Files for MCP Tools:** -- `src/server.ts` - Register new MCP tools -- `src/robot.ts` - Add interface method if needed -- `src/android.ts` - Android implementation -- `src/ios.ts` - iOS physical device implementation -- `src/iphone-simulator.ts` - iOS simulator implementation - -#### Step 3: Define the Interface - -**Add to `src/robot.ts`:** +**2. Define interface (`src/robot.ts`):** ```typescript export interface DeviceInfo { platform: "ios" | "android"; osVersion: string; deviceModel: string; screenResolution: string; - batteryLevel?: number; isSimulator: boolean; } export interface Robot { - // ... existing methods ... - - /** - * Get detailed device information - */ getDeviceInfo(): Promise; } ``` -#### Step 4: Implement for Each Platform +**3. Implement for platforms:** -**Android Implementation (`src/android.ts`):** +**Android (`src/android.ts`):** ```typescript public async getDeviceInfo(): Promise { const model = this.adb("shell", "getprop", "ro.product.model").toString().trim(); @@ -434,12 +103,12 @@ public async getDeviceInfo(): Promise { osVersion, deviceModel: model, screenResolution: `${screenSize.width}x${screenSize.height}`, - isSimulator: false, // Could detect emulator vs physical + isSimulator: false, }; } ``` -**iOS Implementation (`src/ios.ts`):** +**iOS (`src/ios.ts` & `src/iphone-simulator.ts`):** ```typescript public async getDeviceInfo(): Promise { const info = await this.ios("info"); @@ -456,231 +125,91 @@ public async getDeviceInfo(): Promise { } ``` -**iOS Simulator Implementation (`src/iphone-simulator.ts`):** -```typescript -public async getDeviceInfo(): Promise { - const screenSize = await this.getScreenSize(); - // Get simulator info from simctl - const deviceInfo = execFileSync("xcrun", ["simctl", "list", "devices", "-j"]); - - return { - platform: "ios", - osVersion: "Simulator", - deviceModel: "iPhone Simulator", - screenResolution: `${screenSize.width}x${screenSize.height}`, - isSimulator: true, - }; -} -``` - -#### Step 5: Register the MCP Tool - -**Add to `src/server.ts`:** +**4. Register MCP tool (`src/server.ts`):** ```typescript tool( "mobile_get_device_info", - "Get detailed information about the connected device including platform, OS version, model, and screen resolution", - { - noParams - }, + "Get detailed device information including platform, OS version, model, and screen resolution", + { noParams }, async () => { requireRobot(); - const deviceInfo = await robot!.getDeviceInfo(); - - return JSON.stringify({ - platform: deviceInfo.platform, - osVersion: deviceInfo.osVersion, - deviceModel: deviceInfo.deviceModel, - screenResolution: deviceInfo.screenResolution, - batteryLevel: deviceInfo.batteryLevel, - isSimulator: deviceInfo.isSimulator, - }, null, 2); + const info = await robot!.getDeviceInfo(); + return JSON.stringify(info, null, 2); } ); ``` -#### Step 6: Test Your Implementation - -**Build and test:** +**5. Test and validate:** ```bash -# Build the project npm run build - -# Test with a device connected -node lib/index.js - -# In another terminal, test with MCP client or direct testing -``` - -**Testing script example:** -```typescript -// test/device-info.ts -import { describe, it } from "mocha"; -import { AndroidRobot } from "../src/android"; - -describe("device-info", () => { - it("should get Android device info", async () => { - // Test implementation - }); - - it("should get iOS device info", async () => { - // Test implementation - }); -}); -``` - -#### Step 7: Test with MCP Client - -**Cursor/Cline config:** -```json -{ - "mcpServers": { - "mobile-mcp-dev": { - "command": "node", - "args": ["~/mobile-mcp/lib/index.js"] - } - } -} -``` - -**Test the tool:** -``` -> Use the mobile_get_device_info tool to get information about my device -``` - -#### Step 8: Quality Checks - -```bash -# Run linting npm run lint - -# Fix any issues -npm run lint -- --fix - -# Run tests -npm test - -# Test specific components -npx mocha --require ts-node/register test/device-info.ts +node lib/index.js # Test the tool ``` -#### Step 9: Documentation - -**Update appropriate files:** -- Add tool description to README.md -- Document any new dependencies -- Add examples in wiki if complex - -#### Step 10: Commit and Submit - +**6. Submit contribution:** ```bash -# Commit your changes git add . git commit -m "feat: add mobile_get_device_info tool -- Add getDeviceInfo interface to Robot -- Implement device info collection for Android, iOS, and simulators +- Add getDeviceInfo interface and cross-platform implementation - Return platform, OS version, model, screen resolution -- Add comprehensive device information MCP tool -- Include tests for all platforms +- Support Android, iOS, and iOS simulators" -Closes #123" # if there was an issue - -# Push to your fork git push origin feature/get-device-info - # Create pull request on GitHub ``` -#### Step 11: Pull Request Best Practices - -**PR Description Template:** -```markdown -## 🚀 Feature: Get Device Info Tool - -### What does this PR do? -Adds a new MCP tool `mobile_get_device_info` that returns detailed device information. - -### Changes Made -- ✅ Added `getDeviceInfo()` interface to Robot -- ✅ Implemented for Android devices -- ✅ Implemented for iOS devices -- ✅ Implemented for iOS simulators -- ✅ Added MCP tool registration -- ✅ Added tests -- ✅ Updated documentation - -### Testing -- [x] Tested on iOS simulator -- [x] Tested on Android emulator -- [ ] Tested on physical iOS device -- [ ] Tested on physical Android device - -### Screenshots/Output -```json -{ - "platform": "ios", - "osVersion": "17.0", - "deviceModel": "iPhone15,2", - "screenResolution": "1179x2556", - "isSimulator": false -} -``` - -### Breaking Changes -None +## 🔧 Development Workflow -### Related Issues -Closes #123 -``` +```bash +# Development mode +npm run watch # Auto-rebuild on changes -### 🎯 Key Takeaways for Contributors +# Quality checks +npm run lint # Code linting +npm test # Run test suite -1. **Follow the pattern**: Study existing tools in `server.ts` -2. **Implement across platforms**: Android, iOS, iOS Simulator -3. **Add proper TypeScript types**: Update `robot.ts` interface -4. **Test thoroughly**: Multiple devices and scenarios -5. **Document your changes**: README, code comments -6. **Follow conventions**: Naming, error handling, logging -7. **Write good commit messages**: Use conventional commits -8. **Create detailed PRs**: Help reviewers understand your changes +# Testing with MCP clients +node lib/index.js # Start server locally +``` -### 💡 Feature Ideas for New Contributors +## 🎯 Architecture Overview -**Easy features:** -- `mobile_get_battery_level` - Battery percentage -- `mobile_get_wifi_info` - WiFi network details -- `mobile_toggle_airplane_mode` - Airplane mode control +``` +src/ +├── server.ts # MCP tool registration +├── robot.ts # Cross-platform interface +├── android.ts # Android implementation +├── ios.ts # iOS physical devices +├── iphone-simulator.ts # iOS simulators +└── webdriver-agent.ts # iOS automation client +``` -**Medium features:** -- `mobile_install_app` - Install app from file -- `mobile_record_screen` - Screen recording -- `mobile_get_logs` - Device logs +## 💡 Feature Ideas -**Advanced features:** -- `mobile_simulate_location` - GPS mocking -- `mobile_test_performance` - Performance metrics -- `mobile_network_conditions` - Simulate network conditions +**Beginner:** Battery level, WiFi info, device orientation +**Intermediate:** App installation, screen recording, device logs +**Advanced:** Location simulation, performance metrics, network conditions -### 🔗 Useful Resources for Feature Development +## 🚀 Contributing Best Practices -- **MCP Spec**: [Model Context Protocol](https://modelcontextprotocol.io/) -- **Android ADB**: [ADB Shell Commands](https://developer.android.com/studio/command-line/adb) -- **iOS go-ios**: [go-ios Documentation](https://github.com/danielpaulus/go-ios) -- **WebDriverAgent**: [WDA Protocol](https://github.com/appium/WebDriverAgent) +1. **Follow the pattern** - Study existing tools in `server.ts` +2. **Cross-platform** - Implement for Android, iOS, simulators +3. **TypeScript types** - Update `robot.ts` interface +4. **Test thoroughly** - Multiple devices and scenarios +5. **Quality first** - Linting, tests, documentation +6. **Clear commits** - Conventional commit messages +7. **Detailed PRs** - Help reviewers understand changes -## 📚 Additional Resources +## 🔗 Resources -- **Project Wiki**: [GitHub Wiki](https://github.com/mobile-next/mobile-mcp/wiki) -- **MCP Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/) -- **iOS Setup Guide**: [Wiki - iOS Setup](https://github.com/mobile-next/mobile-mcp/wiki/) -- **Community**: [Slack Channel](http://mobilenexthq.com/join-slack) -- **Issues**: [GitHub Issues](https://github.com/mobile-next/mobile-mcp/issues) +- **Project**: [GitHub Repository](https://github.com/mobile-next/mobile-mcp) +- **Community**: [Slack Channel](http://mobilenexthq.com/join-slack) +- **MCP Docs**: [Model Context Protocol](https://modelcontextprotocol.io/) +- **Platform APIs**: [Android ADB](https://developer.android.com/studio/command-line/adb) | [iOS go-ios](https://github.com/danielpaulus/go-ios) --- -**Ready to start developing?** 🎉 -1. Follow the setup steps above -2. Start with `npm run watch` -3. Make a small test change -4. Join the community for support! \ No newline at end of file +**🌟 Ready to contribute?** Fork the repo, follow this guide, and build amazing mobile automation tools! Your contributions help developers worldwide create better mobile experiences with AI. + +**Questions?** Join our [Slack community](http://mobilenexthq.com/join-slack) - we're here to help! 🤝 \ No newline at end of file From 7a869567132c8864c4ac855f597fefd23ff23d4b Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:11:51 +0600 Subject: [PATCH 06/22] docs: Enhance macOS development guide with structured content and troubleshooting - Add a comprehensive table of contents for easy navigation - Include detailed setup instructions for Node, npm, Xcode, and Homebrew - Expand platform setup section with additional notes on Apple Developer accounts and Android Studio - Introduce a FAQ & Troubleshooting section addressing common issues - Clarify development workflow and testing procedures with actionable commands This update improves the onboarding experience for macOS developers contributing to the project. --- MACOS_DEVELOPMENT.md | 81 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 16 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index c6e41df..158b0a9 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -1,5 +1,26 @@ # 📱 Mobile MCP Development - macOS Guide +--- + +## 📑 Table of Contents + +1. [Like This Project? Want to Contribute?](#-like-this-project-want-to-contribute) +2. [Quick Setup](#️-quick-setup) + - [Prerequisites](#prerequisites) + - [Project Setup](#project-setup) +3. [Platform Setup](#-platform-setup) + - [iOS Development](#ios-development) + - [Android Development](#android-development) +4. [Adding a New Feature](#️-adding-a-new-feature) +5. [Development Workflow](#-development-workflow) +6. [Architecture Overview](#-architecture-overview) +7. [Feature Ideas](#-feature-ideas) +8. [Contributing Best Practices](#-contributing-best-practices) +9. [Resources](#-resources) +10. [FAQ & Troubleshooting](#faq--troubleshooting) + +--- + ## 🚀 Like This Project? Want to Contribute? **Mobile MCP** revolutionizes mobile automation by bringing AI agents to iOS and Android devices. Build tools that let LLMs control real mobile apps, automate testing with natural language, and create the future of mobile automation. @@ -25,10 +46,13 @@ ### Prerequisites ```bash # Verify your setup -node --version # >= 18 -npm --version # >= 8 +node --version # >= 18.x recommended +npm --version # >= 8.x recommended xcode-select -p # Xcode CLI tools +brew --version # Homebrew (for macOS package management) ``` +- Install Xcode CLI tools if missing: `xcode-select --install` +- Install Homebrew if missing: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` ### Project Setup ```bash @@ -39,6 +63,9 @@ npm install && npm run build # Verify installation node lib/index.js --help + +# Run tests to verify setup +npm run test ``` ## 📱 Platform Setup @@ -50,6 +77,7 @@ xcrun simctl list devices xcrun simctl boot "iPhone 15" # Physical devices +# You may need an Apple Developer account for some features npm install -g go-ios ios version ``` @@ -58,6 +86,8 @@ ios version ```bash # Platform tools brew install android-platform-tools +# (Optional) Install Android Studio for emulator management +# https://developer.android.com/studio adb version # Environment @@ -143,6 +173,7 @@ tool( ```bash npm run build npm run lint +npm run test node lib/index.js # Test the tool ``` @@ -162,14 +193,14 @@ git push origin feature/get-device-info ## 🔧 Development Workflow ```bash -# Development mode -npm run watch # Auto-rebuild on changes +# Development mode (auto-rebuild on changes) +npm run watch # Quality checks npm run lint # Code linting -npm test # Run test suite +npm run test # Run test suite -# Testing with MCP clients +# Testing with MCP clients (see README for examples) node lib/index.js # Start server locally ``` @@ -177,12 +208,15 @@ node lib/index.js # Start server locally ``` src/ -├── server.ts # MCP tool registration -├── robot.ts # Cross-platform interface -├── android.ts # Android implementation -├── ios.ts # iOS physical devices -├── iphone-simulator.ts # iOS simulators -└── webdriver-agent.ts # iOS automation client +├── server.ts # MCP tool registration and API endpoints +├── robot.ts # Cross-platform interface definitions +├── android.ts # Android implementation +├── ios.ts # iOS physical device implementation +├── iphone-simulator.ts # iOS simulator implementation +├── webdriver-agent.ts # iOS automation client +├── image-utils.ts # Image processing utilities +├── logger.ts # Logging utilities +├── png.ts # PNG image helpers ``` ## 💡 Feature Ideas @@ -196,10 +230,11 @@ src/ 1. **Follow the pattern** - Study existing tools in `server.ts` 2. **Cross-platform** - Implement for Android, iOS, simulators 3. **TypeScript types** - Update `robot.ts` interface -4. **Test thoroughly** - Multiple devices and scenarios -5. **Quality first** - Linting, tests, documentation -6. **Clear commits** - Conventional commit messages -7. **Detailed PRs** - Help reviewers understand changes +4. **Test thoroughly** - Multiple devices and scenarios, add/update tests in `test/` +5. **Quality first** - Linting (`npm run lint`), tests, documentation +6. **Consistent code style** - Use Prettier/ESLint (see `eslint.config.mjs`) +7. **Clear commits** - Conventional commit messages +8. **Detailed PRs** - Help reviewers understand changes ## 🔗 Resources @@ -208,6 +243,20 @@ src/ - **MCP Docs**: [Model Context Protocol](https://modelcontextprotocol.io/) - **Platform APIs**: [Android ADB](https://developer.android.com/studio/command-line/adb) | [iOS go-ios](https://github.com/danielpaulus/go-ios) +## FAQ & Troubleshooting + +**Q: I get a permissions error with Xcode or Homebrew.** +A: Try running the command with `sudo`, or check your user permissions for `/usr/local` and `/Applications`. + +**Q: Android device not detected by adb?** +A: Ensure USB debugging is enabled, and run `adb devices`. Try reconnecting the device or restarting adb (`adb kill-server && adb start-server`). + +**Q: Tests are failing after setup.** +A: Make sure all dependencies are installed, and your Node/npm versions match the prerequisites. Try `npm install` again. + +**Q: Where can I get help?** +A: Join our [Slack community](http://mobilenexthq.com/join-slack) or open an issue on GitHub. + --- **🌟 Ready to contribute?** Fork the repo, follow this guide, and build amazing mobile automation tools! Your contributions help developers worldwide create better mobile experiences with AI. From 42afa3d3e8bbfcb5bce8a240fb05c0ff44406e3f Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:15:01 +0600 Subject: [PATCH 07/22] docs: Revise macOS development guide for clarity and conciseness - Update title and structure for a quick reference format - Streamline table of contents and section headings - Simplify setup instructions for Node, npm, Xcode, and Homebrew - Condense feature addition and development workflow sections - Enhance FAQ with concise troubleshooting tips - Improve overall readability and engagement for contributors This update aims to provide a more efficient onboarding experience for macOS developers. --- MACOS_DEVELOPMENT.md | 293 +++++++++---------------------------------- 1 file changed, 60 insertions(+), 233 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 158b0a9..f787e37 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -1,264 +1,91 @@ -# 📱 Mobile MCP Development - macOS Guide +# 📱 Mobile MCP Development – macOS Quick Guide --- ## 📑 Table of Contents - -1. [Like This Project? Want to Contribute?](#-like-this-project-want-to-contribute) -2. [Quick Setup](#️-quick-setup) - - [Prerequisites](#prerequisites) - - [Project Setup](#project-setup) -3. [Platform Setup](#-platform-setup) - - [iOS Development](#ios-development) - - [Android Development](#android-development) -4. [Adding a New Feature](#️-adding-a-new-feature) -5. [Development Workflow](#-development-workflow) -6. [Architecture Overview](#-architecture-overview) -7. [Feature Ideas](#-feature-ideas) -8. [Contributing Best Practices](#-contributing-best-practices) -9. [Resources](#-resources) -10. [FAQ & Troubleshooting](#faq--troubleshooting) - ---- - -## 🚀 Like This Project? Want to Contribute? - -**Mobile MCP** revolutionizes mobile automation by bringing AI agents to iOS and Android devices. Build tools that let LLMs control real mobile apps, automate testing with natural language, and create the future of mobile automation. - -### 🎯 What You'll Build -- **AI-driven mobile automation** across iOS/Android -- **Cross-platform tools** for simulators & physical devices -- **Natural language testing** capabilities -- **Real-world solutions** used by QA teams and developers - -### 💻 This Guide: Setup → Develop → Contribute -1. **🔧 macOS Environment** - Complete development setup -2. **📱 Platform Configuration** - iOS/Android tools -3. **🛠️ Feature Development** - Add new MCP tools -4. **🚀 Contribution Workflow** - From code to pull request - -**Ready to build the future of mobile automation?** Let's start! 👇 +1. [Project Setup](#project-setup) +2. [Platform Setup](#platform-setup) +3. [Add a Feature](#add-a-feature) +4. [Workflow](#workflow) +5. [Architecture](#architecture) +6. [Contributing](#contributing) +7. [FAQ](#faq) --- -## 🛠️ Quick Setup - -### Prerequisites +## 🚀 Project Setup ```bash -# Verify your setup -node --version # >= 18.x recommended -npm --version # >= 8.x recommended +# Prerequisites +node --version # >= 18 +# If not installed: brew install node +npm --version # >= 8 +# If not installed: brew install npm xcode-select -p # Xcode CLI tools -brew --version # Homebrew (for macOS package management) -``` -- Install Xcode CLI tools if missing: `xcode-select --install` -- Install Homebrew if missing: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` - -### Project Setup -```bash -# Clone and build -git clone https://github.com/mobile-next/mobile-mcp.git -cd mobile-mcp -npm install && npm run build - -# Verify installation -node lib/index.js --help - -# Run tests to verify setup -npm run test +# If not installed: xcode-select --install +brew --version # Homebrew +# If not installed: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +# Clone & build + git clone https://github.com/mobile-next/mobile-mcp.git + cd mobile-mcp + npm install && npm run build && npm run test ``` ## 📱 Platform Setup - -### iOS Development ```bash -# Simulators (built-in) +# iOS Simulators xcrun simctl list devices +# If not installed: Install Xcode from App Store xcrun simctl boot "iPhone 15" - -# Physical devices -# You may need an Apple Developer account for some features -npm install -g go-ios -ios version -``` - -### Android Development -```bash -# Platform tools -brew install android-platform-tools -# (Optional) Install Android Studio for emulator management -# https://developer.android.com/studio +# iOS Devices +go-ios version +# If not installed: npm install -g go-ios +# Android adb version - -# Environment +# If not installed: brew install android-platform-tools export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` -## 🛠️ Adding a New Feature - -### Example: "Get Device Info" Tool +## 🛠️ Add a Feature +1. `git checkout -b feature/your-feature` +2. Update `src/robot.ts` (interface) +3. Implement in `src/android.ts`, `src/ios.ts`, or `src/iphone-simulator.ts` +4. Register in `src/server.ts` +5. Add tests in `test/` +6. `npm run build && npm run test` +7. PR: clear commits, describe changes -**1. Create feature branch:** +## 🔄 Workflow ```bash -git checkout -b feature/get-device-info -``` - -**2. Define interface (`src/robot.ts`):** -```typescript -export interface DeviceInfo { - platform: "ios" | "android"; - osVersion: string; - deviceModel: string; - screenResolution: string; - isSimulator: boolean; -} - -export interface Robot { - getDeviceInfo(): Promise; -} -``` - -**3. Implement for platforms:** - -**Android (`src/android.ts`):** -```typescript -public async getDeviceInfo(): Promise { - const model = this.adb("shell", "getprop", "ro.product.model").toString().trim(); - const osVersion = this.adb("shell", "getprop", "ro.build.version.release").toString().trim(); - const screenSize = await this.getScreenSize(); - - return { - platform: "android", - osVersion, - deviceModel: model, - screenResolution: `${screenSize.width}x${screenSize.height}`, - isSimulator: false, - }; -} -``` - -**iOS (`src/ios.ts` & `src/iphone-simulator.ts`):** -```typescript -public async getDeviceInfo(): Promise { - const info = await this.ios("info"); - const json = JSON.parse(info); - const screenSize = await this.getScreenSize(); - - return { - platform: "ios", - osVersion: json.ProductVersion, - deviceModel: json.ProductType, - screenResolution: `${screenSize.width}x${screenSize.height}`, - isSimulator: false, - }; -} +npm run watch # Auto-rebuild +npm run lint # Lint code +npm run test # Run tests +node lib/index.js # Start server ``` -**4. Register MCP tool (`src/server.ts`):** -```typescript -tool( - "mobile_get_device_info", - "Get detailed device information including platform, OS version, model, and screen resolution", - { noParams }, - async () => { - requireRobot(); - const info = await robot!.getDeviceInfo(); - return JSON.stringify(info, null, 2); - } -); -``` - -**5. Test and validate:** -```bash -npm run build -npm run lint -npm run test -node lib/index.js # Test the tool -``` - -**6. Submit contribution:** -```bash -git add . -git commit -m "feat: add mobile_get_device_info tool - -- Add getDeviceInfo interface and cross-platform implementation -- Return platform, OS version, model, screen resolution -- Support Android, iOS, and iOS simulators" - -git push origin feature/get-device-info -# Create pull request on GitHub -``` - -## 🔧 Development Workflow - -```bash -# Development mode (auto-rebuild on changes) -npm run watch - -# Quality checks -npm run lint # Code linting -npm run test # Run test suite - -# Testing with MCP clients (see README for examples) -node lib/index.js # Start server locally -``` - -## 🎯 Architecture Overview - +## 🗂️ Architecture ``` src/ -├── server.ts # MCP tool registration and API endpoints -├── robot.ts # Cross-platform interface definitions -├── android.ts # Android implementation -├── ios.ts # iOS physical device implementation -├── iphone-simulator.ts # iOS simulator implementation -├── webdriver-agent.ts # iOS automation client -├── image-utils.ts # Image processing utilities -├── logger.ts # Logging utilities -├── png.ts # PNG image helpers +├── server.ts # Tool registration +├── robot.ts # Cross-platform interface +├── android.ts # Android logic +├── ios.ts # iOS device logic +├── iphone-simulator.ts # iOS simulator logic ``` -## 💡 Feature Ideas - -**Beginner:** Battery level, WiFi info, device orientation -**Intermediate:** App installation, screen recording, device logs -**Advanced:** Location simulation, performance metrics, network conditions - -## 🚀 Contributing Best Practices - -1. **Follow the pattern** - Study existing tools in `server.ts` -2. **Cross-platform** - Implement for Android, iOS, simulators -3. **TypeScript types** - Update `robot.ts` interface -4. **Test thoroughly** - Multiple devices and scenarios, add/update tests in `test/` -5. **Quality first** - Linting (`npm run lint`), tests, documentation -6. **Consistent code style** - Use Prettier/ESLint (see `eslint.config.mjs`) -7. **Clear commits** - Conventional commit messages -8. **Detailed PRs** - Help reviewers understand changes - -## 🔗 Resources +## 🤝 Contributing +- Follow patterns in `server.ts` +- Cross-platform support preferred +- Update types, add tests +- Lint, test, document +- Use clear, conventional commits -- **Project**: [GitHub Repository](https://github.com/mobile-next/mobile-mcp) -- **Community**: [Slack Channel](http://mobilenexthq.com/join-slack) -- **MCP Docs**: [Model Context Protocol](https://modelcontextprotocol.io/) -- **Platform APIs**: [Android ADB](https://developer.android.com/studio/command-line/adb) | [iOS go-ios](https://github.com/danielpaulus/go-ios) - -## FAQ & Troubleshooting - -**Q: I get a permissions error with Xcode or Homebrew.** -A: Try running the command with `sudo`, or check your user permissions for `/usr/local` and `/Applications`. - -**Q: Android device not detected by adb?** -A: Ensure USB debugging is enabled, and run `adb devices`. Try reconnecting the device or restarting adb (`adb kill-server && adb start-server`). - -**Q: Tests are failing after setup.** -A: Make sure all dependencies are installed, and your Node/npm versions match the prerequisites. Try `npm install` again. - -**Q: Where can I get help?** -A: Join our [Slack community](http://mobilenexthq.com/join-slack) or open an issue on GitHub. +## ❓ FAQ +- **Xcode/Homebrew error?** Try `sudo` or check permissions. +- **adb not detecting device?** Enable USB debugging, restart adb. +- **Tests failing?** Check Node/npm versions, reinstall deps. +- **Need help?** [Slack](http://mobilenexthq.com/join-slack) or GitHub Issues. --- - -**🌟 Ready to contribute?** Fork the repo, follow this guide, and build amazing mobile automation tools! Your contributions help developers worldwide create better mobile experiences with AI. - -**Questions?** Join our [Slack community](http://mobilenexthq.com/join-slack) - we're here to help! 🤝 \ No newline at end of file +**Build the future of mobile automation. Contribute, test, and make an impact!** \ No newline at end of file From 3e04eaab4e677c1a553b57e1c95abd0409ddf202 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:16:57 +0600 Subject: [PATCH 08/22] docs: Update macOS development guide with Homebrew installation check - Add instructions to verify Homebrew installation - Include command for installing Homebrew if not present - Enhance project setup section for improved clarity This update aims to streamline the onboarding process for macOS developers by ensuring essential tools are properly installed. --- MACOS_DEVELOPMENT.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index f787e37..b49e23b 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -14,6 +14,16 @@ --- ## 🚀 Project Setup + +**First, check if Homebrew is installed:** +```bash +brew --version +``` +If you see a version number, you're good! If you get "command not found", install Homebrew: +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +``` + ```bash # Prerequisites node --version # >= 18 @@ -23,7 +33,6 @@ npm --version # >= 8 xcode-select -p # Xcode CLI tools # If not installed: xcode-select --install brew --version # Homebrew -# If not installed: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # Clone & build git clone https://github.com/mobile-next/mobile-mcp.git From dcac7f390224024a8a2c066947e8a6b525c124fc Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:18:16 +0600 Subject: [PATCH 09/22] docs: Add git installation check to macOS development guide - Include instructions to verify git installation - Provide commands for installing git if not present This update enhances the onboarding process for macOS developers by ensuring that git is properly installed before proceeding with project setup. --- MACOS_DEVELOPMENT.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index b49e23b..b655867 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -24,6 +24,16 @@ If you see a version number, you're good! If you get "command not found", instal /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` +**Next, check if git is installed:** +```bash +git --version +``` +If you see a version number, you're good! If you get "command not found", install git: +```bash +brew install git +# Or: xcode-select --install +``` + ```bash # Prerequisites node --version # >= 18 @@ -34,6 +44,9 @@ xcode-select -p # Xcode CLI tools # If not installed: xcode-select --install brew --version # Homebrew +git --version # Git +# If not installed: brew install git + # Clone & build git clone https://github.com/mobile-next/mobile-mcp.git cd mobile-mcp From 55cee1fc929b683ed5434af58947193a63394775 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:19:52 +0600 Subject: [PATCH 10/22] docs: Enhance macOS development guide with prerequisites table - Add a structured table listing essential tools, their check commands, and installation commands - Improve clarity of installation instructions for Homebrew, git, Node.js, npm, Xcode CLI, go-ios, and adb - Streamline onboarding process for macOS developers by providing clear, actionable steps This update aims to facilitate a smoother setup experience for new contributors. --- MACOS_DEVELOPMENT.md | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index b655867..251e38c 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -15,42 +15,53 @@ ## 🚀 Project Setup +### Prerequisites Table + +| Tool | Check Command | Install Command | +|--------------|----------------------|----------------------------------------| +| Homebrew | `brew --version` | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | +| git | `git --version` | `brew install git` or `xcode-select --install` | +| Node.js | `node --version` | `brew install node` | +| npm | `npm --version` | `brew install npm` | +| Xcode CLI | `xcode-select -p` | `xcode-select --install` | +| go-ios | `go-ios version` | `npm install -g go-ios` | +| adb | `adb version` | `brew install android-platform-tools` | + +--- + **First, check if Homebrew is installed:** ```bash brew --version ``` -If you see a version number, you're good! If you get "command not found", install Homebrew: -```bash -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" -``` +> **If not installed:** +> `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` **Next, check if git is installed:** ```bash git --version ``` -If you see a version number, you're good! If you get "command not found", install git: -```bash -brew install git -# Or: xcode-select --install -``` +> **If not installed:** +> `brew install git` +> or: `xcode-select --install` ```bash # Prerequisites node --version # >= 18 -# If not installed: brew install node +# 👉 If not installed: brew install node npm --version # >= 8 -# If not installed: brew install npm +# 👉 If not installed: brew install npm xcode-select -p # Xcode CLI tools -# If not installed: xcode-select --install +# 👉 If not installed: xcode-select --install brew --version # Homebrew +# 👉 If not installed: see above git --version # Git -# If not installed: brew install git +# 👉 If not installed: see above # Clone & build - git clone https://github.com/mobile-next/mobile-mcp.git - cd mobile-mcp - npm install && npm run build && npm run test +git clone https://github.com/mobile-next/mobile-mcp.git +cd mobile-mcp +npm install && npm run build && npm run test ``` ## 📱 Platform Setup From 1f06d2cee4d6f384c0ed597ca3d1e1a548dd1bae Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:21:29 +0600 Subject: [PATCH 11/22] docs: Revise macOS development guide prerequisites for clarity and structure - Transform prerequisites section into a more organized format with clear headings - Provide installation checks and commands for Homebrew, git, Node.js, npm, Xcode CLI, go-ios, and adb - Enhance readability and usability for new contributors setting up their development environment This update aims to streamline the onboarding process for macOS developers by offering straightforward and actionable setup instructions. --- MACOS_DEVELOPMENT.md | 80 ++++++++++++++++++++++++++++---------------- 1 file changed, 52 insertions(+), 28 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 251e38c..bf0404f 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -15,36 +15,61 @@ ## 🚀 Project Setup -### Prerequisites Table - -| Tool | Check Command | Install Command | -|--------------|----------------------|----------------------------------------| -| Homebrew | `brew --version` | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | -| git | `git --version` | `brew install git` or `xcode-select --install` | -| Node.js | `node --version` | `brew install node` | -| npm | `npm --version` | `brew install npm` | -| Xcode CLI | `xcode-select -p` | `xcode-select --install` | -| go-ios | `go-ios version` | `npm install -g go-ios` | -| adb | `adb version` | `brew install android-platform-tools` | +### Prerequisites + +- **Homebrew** + - Check: `brew --version` + - If not installed: + ```bash + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + ``` + +- **git** + - Check: `git --version` + - If not installed: + ```bash + brew install git + # or + xcode-select --install + ``` + +- **Node.js** + - Check: `node --version` (>= 18) + - If not installed: + ```bash + brew install node + ``` + +- **npm** + - Check: `npm --version` (>= 8) + - If not installed: + ```bash + brew install npm + ``` + +- **Xcode CLI** + - Check: `xcode-select -p` + - If not installed: + ```bash + xcode-select --install + ``` + +- **go-ios** + - Check: `go-ios version` + - If not installed: + ```bash + npm install -g go-ios + ``` + +- **adb** + - Check: `adb version` + - If not installed: + ```bash + brew install android-platform-tools + ``` --- -**First, check if Homebrew is installed:** -```bash -brew --version -``` -> **If not installed:** -> `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` - -**Next, check if git is installed:** -```bash -git --version -``` -> **If not installed:** -> `brew install git` -> or: `xcode-select --install` - -```bash # Prerequisites node --version # >= 18 # 👉 If not installed: brew install node @@ -62,7 +87,6 @@ git --version # Git git clone https://github.com/mobile-next/mobile-mcp.git cd mobile-mcp npm install && npm run build && npm run test -``` ## 📱 Platform Setup ```bash From 3e041012a0a0a23a92d6a46ed08e67e16851102f Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:23:46 +0600 Subject: [PATCH 12/22] docs: Update macOS development guide with enhanced installation checks - Revise prerequisites section to include formatted installation checks for Homebrew, git, Node.js, npm, Xcode CLI, go-ios, and adb - Improve clarity and usability of setup instructions for new contributors - Streamline the cloning and building process with clear command formatting This update aims to further simplify the onboarding experience for macOS developers by providing clear, actionable setup steps. --- MACOS_DEVELOPMENT.md | 57 ++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index bf0404f..d246365 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -15,17 +15,23 @@ ## 🚀 Project Setup -### Prerequisites +Before you start, make sure you have these tools installed: - **Homebrew** - - Check: `brew --version` + - Check: + ```bash + brew --version + ``` - If not installed: ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` - **git** - - Check: `git --version` + - Check: + ```bash + git --version + ``` - If not installed: ```bash brew install git @@ -33,36 +39,51 @@ xcode-select --install ``` -- **Node.js** - - Check: `node --version` (>= 18) +- **Node.js** (>= 18) + - Check: + ```bash + node --version + ``` - If not installed: ```bash brew install node ``` -- **npm** - - Check: `npm --version` (>= 8) +- **npm** (>= 8) + - Check: + ```bash + npm --version + ``` - If not installed: ```bash brew install npm ``` - **Xcode CLI** - - Check: `xcode-select -p` + - Check: + ```bash + xcode-select -p + ``` - If not installed: ```bash xcode-select --install ``` - **go-ios** - - Check: `go-ios version` + - Check: + ```bash + go-ios version + ``` - If not installed: ```bash npm install -g go-ios ``` - **adb** - - Check: `adb version` + - Check: + ```bash + adb version + ``` - If not installed: ```bash brew install android-platform-tools @@ -70,23 +91,13 @@ --- -# Prerequisites -node --version # >= 18 -# 👉 If not installed: brew install node -npm --version # >= 8 -# 👉 If not installed: brew install npm -xcode-select -p # Xcode CLI tools -# 👉 If not installed: xcode-select --install -brew --version # Homebrew -# 👉 If not installed: see above - -git --version # Git -# 👉 If not installed: see above +### Clone & Build -# Clone & build +```bash git clone https://github.com/mobile-next/mobile-mcp.git cd mobile-mcp npm install && npm run build && npm run test +``` ## 📱 Platform Setup ```bash From 5457fe770e582da62ae21d1286bcc015169d31bc Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:26:46 +0600 Subject: [PATCH 13/22] docs: Expand macOS development guide with detailed iOS and Android setup instructions - Add sections for checking and booting iOS simulators and devices - Include installation commands for go-ios and adb if not present - Enhance clarity of Android environment variable setup This update aims to provide comprehensive setup instructions for both iOS and Android development, improving the onboarding experience for new contributors. --- MACOS_DEVELOPMENT.md | 39 +++++++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index d246365..fdd6f45 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -100,17 +100,44 @@ npm install && npm run build && npm run test ``` ## 📱 Platform Setup + +### iOS Simulators + +Check available simulators: ```bash -# iOS Simulators xcrun simctl list devices -# If not installed: Install Xcode from App Store +``` +> If not installed: Install Xcode from the App Store + +Boot a simulator: +```bash xcrun simctl boot "iPhone 15" -# iOS Devices +``` + +### iOS Devices + +Check go-ios: +```bash go-ios version -# If not installed: npm install -g go-ios -# Android +``` +> If not installed: +```bash +npm install -g go-ios +``` + +### Android + +Check adb: +```bash adb version -# If not installed: brew install android-platform-tools +``` +> If not installed: +```bash +brew install android-platform-tools +``` + +Set Android environment variables: +```bash export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` From 8b45fa25b399250bcf4e0b68810a963b9ad390f9 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:31:35 +0600 Subject: [PATCH 14/22] docs: Update macOS development guide with improved section headings and emoji placement - Reorganize section titles for better clarity and visual appeal - Enhance readability by repositioning emojis to follow section titles - Maintain engaging tone while ensuring essential information is easily accessible This update aims to improve the overall structure and user experience of the macOS development guide for contributors. --- MACOS_DEVELOPMENT.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index fdd6f45..623a389 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -11,9 +11,7 @@ 6. [Contributing](#contributing) 7. [FAQ](#faq) ---- - -## 🚀 Project Setup +## Project Setup 🚀 Before you start, make sure you have these tools installed: @@ -99,7 +97,7 @@ cd mobile-mcp npm install && npm run build && npm run test ``` -## 📱 Platform Setup +## Platform Setup 📱 ### iOS Simulators @@ -142,7 +140,7 @@ export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` -## 🛠️ Add a Feature +## Add a Feature 🛠️ 1. `git checkout -b feature/your-feature` 2. Update `src/robot.ts` (interface) 3. Implement in `src/android.ts`, `src/ios.ts`, or `src/iphone-simulator.ts` @@ -151,7 +149,7 @@ export PATH="$PATH:$ANDROID_HOME/platform-tools" 6. `npm run build && npm run test` 7. PR: clear commits, describe changes -## 🔄 Workflow +## Workflow 🔄 ```bash npm run watch # Auto-rebuild npm run lint # Lint code @@ -159,7 +157,7 @@ npm run test # Run tests node lib/index.js # Start server ``` -## 🗂️ Architecture +## Architecture 🗂️ ``` src/ ├── server.ts # Tool registration @@ -169,18 +167,18 @@ src/ ├── iphone-simulator.ts # iOS simulator logic ``` -## 🤝 Contributing +## Contributing 🤝 - Follow patterns in `server.ts` - Cross-platform support preferred - Update types, add tests - Lint, test, document - Use clear, conventional commits -## ❓ FAQ +## FAQ ❓ - **Xcode/Homebrew error?** Try `sudo` or check permissions. - **adb not detecting device?** Enable USB debugging, restart adb. - **Tests failing?** Check Node/npm versions, reinstall deps. - **Need help?** [Slack](http://mobilenexthq.com/join-slack) or GitHub Issues. --- -**Build the future of mobile automation. Contribute, test, and make an impact!** \ No newline at end of file +Build the future of mobile automation. Contribute, test, and make an impact! \ No newline at end of file From 3c47efe138708a616ec27d87d3ea2d8ac8635133 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:33:24 +0600 Subject: [PATCH 15/22] docs: Update macOS development guide table of contents with improved link formatting - Adjust section links in the table of contents to include trailing hyphens for consistency - Enhance navigation clarity for contributors This update aims to improve the usability of the macOS development guide by ensuring all links are uniformly formatted. --- MACOS_DEVELOPMENT.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 623a389..7cc74ed 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -3,13 +3,13 @@ --- ## 📑 Table of Contents -1. [Project Setup](#project-setup) -2. [Platform Setup](#platform-setup) -3. [Add a Feature](#add-a-feature) -4. [Workflow](#workflow) -5. [Architecture](#architecture) -6. [Contributing](#contributing) -7. [FAQ](#faq) +1. [Project Setup](#project-setup-) +2. [Platform Setup](#platform-setup-) +3. [Add a Feature](#add-a-feature-) +4. [Workflow](#workflow-) +5. [Architecture](#architecture-) +6. [Contributing](#contributing-) +7. [FAQ](#faq-) ## Project Setup 🚀 From f6ad70c8ee7c26c24f1cb1c15d8e9d74109d16ff Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:35:26 +0600 Subject: [PATCH 16/22] docs: Revise macOS development guide for feature contribution clarity - Enhance the feature addition section with clearer instructions and formatting - Provide specific commands for creating branches and implementing features - Improve overall structure and readability for contributors looking to add new tools This update aims to streamline the process for contributors by offering clear, actionable steps for feature development in the macOS environment. --- MACOS_DEVELOPMENT.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 7cc74ed..1af49b4 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -141,13 +141,25 @@ export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` ## Add a Feature 🛠️ -1. `git checkout -b feature/your-feature` -2. Update `src/robot.ts` (interface) -3. Implement in `src/android.ts`, `src/ios.ts`, or `src/iphone-simulator.ts` -4. Register in `src/server.ts` -5. Add tests in `test/` -6. `npm run build && npm run test` -7. PR: clear commits, describe changes + +Want to contribute a new tool or capability? Here's how: + +1. Create a new branch: + ```bash + git checkout -b feature/your-feature + ``` +2. Update the interface in `src/robot.ts` +3. Implement your feature in: + - `src/android.ts` + - `src/ios.ts` + - or `src/iphone-simulator.ts` +4. Register your tool in `src/server.ts` +5. Add or update tests in `test/` +6. Build and test: + ```bash + npm run build && npm run test + ``` +7. Open a pull request with clear commits and a helpful description. ## Workflow 🔄 ```bash @@ -158,6 +170,8 @@ node lib/index.js # Start server ``` ## Architecture 🗂️ + +Project structure: ``` src/ ├── server.ts # Tool registration From e8e569270fc7abd8b761eba0f026fc38d8bd06bc Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:42:22 +0600 Subject: [PATCH 17/22] docs: Clean up macOS development guide table of contents and remove redundant npm installation checks - Remove trailing hyphens from table of contents links for consistency - Eliminate unnecessary npm installation checks to streamline the setup instructions This update aims to enhance the clarity and usability of the macOS development guide for contributors. --- MACOS_DEVELOPMENT.md | 24 +++++++----------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 1af49b4..75e7e66 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -3,13 +3,13 @@ --- ## 📑 Table of Contents -1. [Project Setup](#project-setup-) -2. [Platform Setup](#platform-setup-) -3. [Add a Feature](#add-a-feature-) -4. [Workflow](#workflow-) -5. [Architecture](#architecture-) -6. [Contributing](#contributing-) -7. [FAQ](#faq-) +1. [Project Setup](#project-setup) +2. [Platform Setup](#platform-setup) +3. [Add a Feature](#add-a-feature) +4. [Workflow](#workflow) +5. [Architecture](#architecture) +6. [Contributing](#contributing) +7. [FAQ](#faq) ## Project Setup 🚀 @@ -47,16 +47,6 @@ Before you start, make sure you have these tools installed: brew install node ``` -- **npm** (>= 8) - - Check: - ```bash - npm --version - ``` - - If not installed: - ```bash - brew install npm - ``` - - **Xcode CLI** - Check: ```bash From 13f395c38177672181d99952874f6659d3106adc Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:44:14 +0600 Subject: [PATCH 18/22] docs: Refine section headings in macOS development guide for consistency - Remove spaces before emojis in section titles for uniformity - Enhance visual appeal and readability of the document This update aims to improve the overall presentation of the macOS development guide, making it more engaging for contributors. --- MACOS_DEVELOPMENT.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 75e7e66..177d86d 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -11,7 +11,7 @@ 6. [Contributing](#contributing) 7. [FAQ](#faq) -## Project Setup 🚀 +## Project Setup🚀 Before you start, make sure you have these tools installed: @@ -87,7 +87,7 @@ cd mobile-mcp npm install && npm run build && npm run test ``` -## Platform Setup 📱 +## Platform Setup📱 ### iOS Simulators @@ -130,7 +130,7 @@ export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` -## Add a Feature 🛠️ +## Add a Feature🛠️ Want to contribute a new tool or capability? Here's how: @@ -151,7 +151,7 @@ Want to contribute a new tool or capability? Here's how: ``` 7. Open a pull request with clear commits and a helpful description. -## Workflow 🔄 +## Workflow🔄 ```bash npm run watch # Auto-rebuild npm run lint # Lint code @@ -159,7 +159,7 @@ npm run test # Run tests node lib/index.js # Start server ``` -## Architecture 🗂️ +## Architecture🗂️ Project structure: ``` @@ -171,14 +171,14 @@ src/ ├── iphone-simulator.ts # iOS simulator logic ``` -## Contributing 🤝 +## Contributing🤝 - Follow patterns in `server.ts` - Cross-platform support preferred - Update types, add tests - Lint, test, document - Use clear, conventional commits -## FAQ ❓ +## FAQ❓ - **Xcode/Homebrew error?** Try `sudo` or check permissions. - **adb not detecting device?** Enable USB debugging, restart adb. - **Tests failing?** Check Node/npm versions, reinstall deps. From 60f0c3ff66a9ce0bdfc49d7d4b6977c1038fbbc6 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:47:30 +0600 Subject: [PATCH 19/22] docs: Update section emojis in macOS development guide for improved visual consistency MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Change tool addition emoji from 🛠️ to 🔨 for better representation - Update architecture emoji from 🗂️ to 📁 to enhance clarity This update aims to refine the visual elements of the macOS development guide, contributing to a more engaging experience for contributors. --- MACOS_DEVELOPMENT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index 177d86d..d0176c5 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -130,7 +130,7 @@ export ANDROID_HOME="$HOME/Library/Android/sdk" export PATH="$PATH:$ANDROID_HOME/platform-tools" ``` -## Add a Feature🛠️ +## Add a Feature🔨 Want to contribute a new tool or capability? Here's how: @@ -159,7 +159,7 @@ npm run test # Run tests node lib/index.js # Start server ``` -## Architecture🗂️ +## Architecture📁 Project structure: ``` From 6cbece002ae3670a5532c878868aeded149ff149 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 13:51:43 +0600 Subject: [PATCH 20/22] docs: Update README.md with Visual Sense clarification and contributing guidelines - Clarify the description of the Visual Sense feature for better understanding - Add a new section on contributing to the project, including links to development guides for macOS and Windows/Linux This update aims to enhance the documentation by providing clearer information on features and encouraging community contributions. --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1423c9f..1a7575f 100644 --- a/README.md +++ b/README.md @@ -58,7 +58,7 @@ How we help to scale mobile automation: - 🚀 **Fast and lightweight**: Uses native accessibility trees for most interactions, or screenshot based coordinates where a11y labels are not available. - 🤖 **LLM-friendly**: No computer vision model required in Accessibility (Snapshot). -- 🧿 **Visual Sense**: Evaluates and analyses what’s actually rendered on screen to decide the next action. If accessibility data or view-hierarchy coordinates are unavailable, it falls back to screenshot-based analysis. +- 🧿 **Visual Sense**: Evaluates and analyses what's actually rendered on screen to decide the next action. If accessibility data or view-hierarchy coordinates are unavailable, it falls back to screenshot-based analysis. - 📊 **Deterministic tool application**: Reduces ambiguity found in purely screenshot-based approaches by relying on structured data whenever possible. - 📺 **Extract structured data**: Enables you to extract structred data from anything visible on screen. @@ -199,6 +199,13 @@ On iOS, you'll need Xcode and to run the Simulator before using Mobile MCP with - `xcrun simctl list` - `xcrun simctl boot "iPhone 16"` +## Contributing + +We welcome contributions to Mobile MCP! If you're interested in adding new features, fixing bugs, or improving documentation, please get started by reading our development guide for your platform. + +- **macOS:** [macOS Development Guide](MACOS_DEVELOPMENT.md) +- **Windows/Linux:** Contributions for development guides are welcome! + # Thanks to all contributors ❤️ ### We appreciate everyone who has helped improve this project. From 613b82dac6843841c3b0f4001be8cb118ebce061 Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 14:13:20 +0600 Subject: [PATCH 21/22] docs: fix go-ios command name in setup guide The actual command is 'ios', not 'go-ios' after npm install. Added clarification note to prevent confusion. --- MACOS_DEVELOPMENT.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index d0176c5..b3c11b1 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -60,8 +60,9 @@ Before you start, make sure you have these tools installed: - **go-ios** - Check: ```bash - go-ios version + ios version ``` + > Note: The command is `ios`, not `go-ios` - If not installed: ```bash npm install -g go-ios @@ -106,7 +107,7 @@ xcrun simctl boot "iPhone 15" Check go-ios: ```bash -go-ios version +ios version ``` > If not installed: ```bash From d64e7c0cf1737dd0ffee69f2d791e3ffd85f399d Mon Sep 17 00:00:00 2001 From: MD SAIFUL HOSSAIN Date: Tue, 24 Jun 2025 14:36:35 +0600 Subject: [PATCH 22/22] docs: comprehensive developer experience improvements --- MACOS_DEVELOPMENT.md | 159 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 155 insertions(+), 4 deletions(-) diff --git a/MACOS_DEVELOPMENT.md b/MACOS_DEVELOPMENT.md index b3c11b1..87b9c6f 100644 --- a/MACOS_DEVELOPMENT.md +++ b/MACOS_DEVELOPMENT.md @@ -6,10 +6,13 @@ 1. [Project Setup](#project-setup) 2. [Platform Setup](#platform-setup) 3. [Add a Feature](#add-a-feature) -4. [Workflow](#workflow) -5. [Architecture](#architecture) -6. [Contributing](#contributing) -7. [FAQ](#faq) +4. [Local Development & Testing](#local-development--testing) +5. [Common Setup Pain Points & Solutions](#common-setup-pain-points--solutions) +6. [Unclear Workflow Steps - Clarified](#unclear-workflow-steps---clarified) +7. [Workflow](#workflow) +8. [Architecture](#architecture) +9. [Contributing](#contributing) +10. [FAQ](#faq) ## Project Setup🚀 @@ -152,6 +155,154 @@ Want to contribute a new tool or capability? Here's how: ``` 7. Open a pull request with clear commits and a helpful description. +## Local Development & Testing🧪 + +### **Setting Up Local Development** + +To test your features locally in Cursor or other MCP clients: + +1. **Configure MCP for Local Development**: + Edit your MCP config file (`~/.cursor/mcp.json` for Cursor): + ```json + { + "mcpServers": { + "mobile-mcp": { + "command": "node", + "args": ["/path/to/your/mobile-mcp/lib/index.js", "--stdio"], + "cwd": "/path/to/your/mobile-mcp" + } + } + } + ``` + + Replace `/path/to/your/mobile-mcp` with your actual project path. + +2. **Development Workflow**: + ```bash + # Start continuous build (optional) + npm run watch + + # Or build manually after changes + npm run build + + # Restart your MCP client (Cursor/Claude Desktop) to pick up changes + ``` + +### **Testing Your Features** + +1. **Prepare Test Device**: + ```bash + # For iOS Simulator + xcrun simctl boot "iPhone 15" + + # For Android (connect device with USB debugging) + adb devices + ``` + +2. **Test Feature Workflow**: + - Make code changes + - Build: `npm run build` + - Restart MCP client + - Test your new tools! + +### **Example: Testing New Feature** + +```bash +# 1. Implement your feature in TypeScript files +# 2. Build the project +npm run build + +# 3. In Cursor: Cmd+Shift+P → "MCP: Restart Servers" +# 4. Test your tools: +# - mobile_use_default_device +# - your_new_feature_tool +``` + +### **Debugging Tips** + +- **Tool not found?** Restart your MCP client after building +- **Build issues?** Check TypeScript errors: `npm run build` +- **MCP config issues?** Verify the path in your config file +- **Test with multiple platforms** to ensure cross-platform compatibility + +## Common Setup Pain Points & Solutions🩹 + +### **Pain Point 1: Command Name Confusion** +**Issue**: Documentation says `go-ios version` but command not found +```bash +$ go-ios version +zsh: command not found: go-ios +``` +**Solution**: The actual command is `ios`, not `go-ios` +```bash +$ ios version # ✅ Correct command +``` + +### **Pain Point 2: MCP Client Uses Published Package** +**Issue**: Your new tools don't appear even after building +**Root Cause**: MCP client is using `@mobilenext/mobile-mcp@latest` from npm +**Solution**: Update MCP config to point to your local build: +```json +{ + "mcpServers": { + "mobile-mcp": { + "command": "node", + "args": ["/your/path/mobile-mcp/lib/index.js", "--stdio"], + "cwd": "/your/path/mobile-mcp" + } + } +} +``` + +### **Pain Point 3: npm Global Package PATH Issues** +**Issue**: Package installs but command not found +**Check**: Verify npm global bin directory is in PATH +```bash +npm config get prefix # Should show /opt/homebrew or similar +echo $PATH | grep $(npm config get prefix)/bin # Should return a match +``` + +## Unclear Workflow Steps - Clarified🔍 + +### **The Build → Test Cycle** +**What's Not Obvious**: `npm run watch` rebuilds code, but MCP client doesn't auto-reload + +**Complete Workflow**: +```bash +# 1. Make code changes +# 2. Code builds automatically (if watch running) OR: +npm run build + +# 3. ⚠️ CRITICAL STEP: Restart MCP client +# In Cursor: Cmd+Shift+P → "MCP: Restart Servers" +# In Claude Desktop: Restart the app + +# 4. Test your tools +``` + +### **When Tools Don't Appear** +**Symptoms**: Built successfully, but new tools missing in MCP client +**Checklist**: +1. ✅ Code compiles without errors +2. ✅ MCP config points to local build (not npm package) +3. ✅ Restarted MCP client after building +4. ✅ Tool registered in `src/server.ts` with correct name + +### **Development vs Production Setup** +**Development** (your local features): +```json +"command": "node", +"args": ["/path/to/mobile-mcp/lib/index.js", "--stdio"] +``` + +**Production** (published package): +```json +"command": "npx", +"args": ["-y", "@mobilenext/mobile-mcp@latest"] +``` + +**Switch easily**: Just update your `~/.cursor/mcp.json` file + ## Workflow🔄 ```bash npm run watch # Auto-rebuild