{"id":29142361,"url":"https://github.com/ihacksubhodip/mcp-server-demo","last_synced_at":"2025-06-30T19:37:26.686Z","repository":{"id":301069441,"uuid":"1008047183","full_name":"iHackSubhodip/mcp-server-demo","owner":"iHackSubhodip","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-25T02:18:17.000Z","size":44798,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T02:33:25.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iHackSubhodip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T00:19:08.000Z","updated_at":"2025-06-25T02:18:20.000Z","dependencies_parsed_at":"2025-06-25T02:43:58.720Z","dependency_job_id":null,"html_url":"https://github.com/iHackSubhodip/mcp-server-demo","commit_stats":null,"previous_names":["ihacksubhodip/mcp-server-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/iHackSubhodip/mcp-server-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmcp-server-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmcp-server-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmcp-server-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmcp-server-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iHackSubhodip","download_url":"https://codeload.github.com/iHackSubhodip/mcp-server-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iHackSubhodip%2Fmcp-server-demo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262839748,"owners_count":23372780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T19:37:24.778Z","updated_at":"2025-06-30T19:37:26.674Z","avatar_url":"https://github.com/iHackSubhodip.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iOS MCP Server\n\n\u003e Mobile automation server built with clean architecture and SOLID principles\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)\n\nA production-ready iOS automation MCP server that transforms monolithic automation scripts into maintainable, extensible architecture. Built following SOLID principles with comprehensive error handling, beautiful logging, and professional design patterns.\n\n## 📺 Demo Video\n\n[![iOS MCP Server Demo](https://img.youtube.com/vi/480AmvL9ziQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=480AmvL9ziQ)\n\n**🎬 Watch the Complete Demo**: [iOS MCP Server in Action](https://www.youtube.com/watch?v=480AmvL9ziQ)\n\nSee real iOS automation with Claude Desktop integration! The video demonstrates:\n- **Live iOS Automation** - Real device interaction\n- **Claude Desktop Integration** - Seamless MCP protocol usage  \n- **Advanced Element Finding** - Smart accessibility ID detection\n- **Auto-Dismiss Features** - Modal handling automation\n- **Complete Workflow** - End-to-end app testing\n\n## ✨ Features\n\n- 🏗️ **Clean Architecture** - SOLID principles and design patterns\n- 🎨 **Beautiful Logging** - Colored console output with emojis\n- 🔧 **Type-Safe** - Comprehensive type hints throughout\n- 📱 **Real iOS Automation** - Appium + WebDriverAgent integration\n- 🔌 **Extensible** - Plugin-style tool system\n- 🚀 **Production Ready** - Robust error handling and monitoring\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- macOS (required for iOS automation)\n- Python 3.11+\n- Xcode with iOS Simulator\n- Node.js (for Appium)\n\n### Installation\n\n1. **Clone the repository**\n```bash\n   git clone https://github.com/iHackSubhodip/mcp-server-demo.git\n   cd mcp-server-demo\n   ```\n\n2. **Start the server**\n```bash\n   ./start_ios_mcp.sh\n   ```\n\n3. **Connect to Claude Desktop**\n   \n   Add to your Claude Desktop config:\n```json\n{\n  \"mcpServers\": {\n    \"ios-automation\": {\n         \"command\": \"python\",\n         \"args\": [\"-m\", \"ios_mcp_server.main\"],\n         \"cwd\": \"/path/to/mcp-server-demo\"\n    }\n  }\n}\n```\n\n## 🏗️ Architecture\n\n### System Architecture\n![System Architecture](archDiagram.png)\n\n### Module Interactions\n![Module Interaction Diagram](moduleInteractionDiagram.png)\n\n### Sequence Flow\n![Sequence Diagram](sequenceDiagram.png)\n\n### Directory Structure\n```\nios_mcp_server/\n├── main.py                       # Entry point\n├── config/settings.py           # Configuration\n├── utils/                       # Shared utilities\n│   ├── logger.py               # Colored logging\n│   ├── exceptions.py           # Custom exceptions\n│   └── command_runner.py       # Async commands\n├── automation/                  # Core services\n│   ├── appium_client.py        # iOS automation\n│   ├── simulator_manager.py    # Simulator control\n│   └── screenshot_service.py   # Screenshots\n├── tools/                       # MCP tools\n│   ├── base_tool.py            # Abstract base\n│   ├── tool_registry.py        # Tool management\n│   ├── appium_tap_type_tool.py # Main automation\n│   ├── screenshot_tool.py      # Screenshot capture\n│   └── launch_app_tool.py      # App launcher\n└── server/mcp_server.py         # MCP protocol\n```\n\n## 🔧 Available Tools\n\n### `appium_tap_and_type`\nReal iOS automation with intelligent element finding\n```json\n{\n  \"text\": \"Hello World!\",\n  \"element_type\": \"textField\",\n  \"timeout\": 10\n}\n```\n\n### `take_screenshot`\nCapture high-quality iOS screenshots\n```json\n{\n  \"filename\": \"optional_name.png\"\n}\n```\n\n### `launch_app`\nLaunch iOS applications with validation\n```json\n{\n  \"bundle_id\": \"com.example.app\"\n}\n```\n\n## 🎮 Server Management\n\n### Start Server\n```bash\n./start_ios_mcp.sh\n```\n\n### Restart Server\n```bash\npkill -f \"ios_mcp_server\" || true\npkill -f appium || true\n./start_ios_mcp.sh\n```\n\n### Stop Server\n```bash\npkill -f \"ios_mcp_server|appium\"\n```\n\n### Check Status\n```bash\nps aux | grep -E \"(ios_mcp_server|appium)\" | grep -v grep\ncurl -s http://localhost:4723/status | python3 -m json.tool\n```\n\n## 🏭 Design Patterns\n\n- **Template Method**: `BaseTool` consistent execution\n- **Registry**: `ToolRegistry` centralized management  \n- **Factory**: Tool instantiation\n- **Strategy**: Multiple automation approaches\n- **Dependency Injection**: Configuration injection\n\n## 📊 Migration Benefits\n\n| Before | After |\n|--------|-------|\n| 414-line monolithic file | 20+ focused modules |\n| No error handling | Professional error handling |\n| Basic logging | Colored logging with emojis |\n| Hard to extend | Plugin-style architecture |\n| No type safety | 100% type-hinted |\n| Poor maintainability | SOLID principles |\n\n## 🛠️ Development Setup\n\n### Manual Setup\n```bash\n# Create virtual environment\npython -m venv ios_mcp_env\nsource ios_mcp_env/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Install Appium\nnpm install -g appium\nappium driver install xcuitest\n```\n\n### WebDriverAgent Setup\n```bash\ngit clone https://github.com/appium/WebDriverAgent.git\nopen WebDriverAgent/WebDriverAgent.xcodeproj\n```\n\nConfigure in Xcode:\n- Select your Apple Developer Team\n- Update Bundle IDs to be unique\n- Build and test the project\n\n## 🔍 Troubleshooting\n\n### Appium Connection Issues\n```bash\n# Check Appium status\ncurl http://localhost:4723/status\n\n# Restart Appium\npkill -f appium \u0026\u0026 appium server --port 4723\n```\n\n### Simulator Issues\n```bash\n# List simulators\nxcrun simctl list devices\n\n# Boot simulator\nxcrun simctl boot \"iPhone 16 Pro\"\n```\n\n### WebDriverAgent Issues\n```bash\ncd WebDriverAgent\nxcodebuild -project WebDriverAgent.xcodeproj \\\n  -scheme WebDriverAgentRunner \\\n  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' test\n```\n\n## 📝 Dependencies\n\n```\nmcp\u003e=1.0.0          # MCP protocol\naiohttp\u003e=3.9.0      # HTTP client for Appium\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihacksubhodip%2Fmcp-server-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fihacksubhodip%2Fmcp-server-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fihacksubhodip%2Fmcp-server-demo/lists"}