使用说明

移动自动化iOS MCP服务器

基于FastMCP 2.0和简洁架构构建的现代iOS自动化服务器

基于FastMCP 2.0构建的生产就绪iOS自动化MCP服务器，具有 干净的模块化架构 平台完全隔离。已准备好跨平台扩展，iOS特定和共享组件已正确分离。

📺 演示视频

🎬 观看完整演示: 移动自动化iOS MCP服务器在行动

✨ 特性

🚀 FastMCP 2.0 -现代Python第一MCP实现
🌐 云部署 -已为铁路、Heroku或其他平台做好准备
📱 真正的iOS自动化 -Appium+WebDriver Agent集成
🏗️ 干净的模块化架构 -完整的平台隔离和SOLID原则
🔄 跨平台就绪 -面向未来Android/其他平台的共享实用程序
🎨 美丽的日志 -带有表情符号的彩色控制台输出
🔧 类型安全 -全面的类型提示贯穿始终
🔌 可扩展 -模块化配置的插件式工具系统
📦 零代码重复 -共享公用设施的干燥原则

🚀 快速开始

选项1：远程服务器（推荐）

在Railway上使用托管版本-无需本地设置：

{
  "mcpServers": {
    "ios-automation-railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-server-demo-production.up.railway.app/sse/"
      ]
    }
  }
}

方案2：地方发展

先决条件
- macOS（iOS自动化所需）
- Python 3.11+
- 紫外线（推荐）或pip
- Xcode与iOS模拟器
- Node.js（适用于Appium）

安装

git clone https://github.com/iHackSubhodip/mcp-server-demo.git
cd mcp-server-demo

# Using uv (recommended)
uv sync

# Or using pip (legacy)
pip install -e .

Claude桌面配置

{
  "mcpServers": {
    "ios-automation-local": {
      "command": "uv",
      "args": ["run", "python", "mobile-automation-mcp-server/fastmcp_server.py"],
      "cwd": "/path/to/mcp-server-demo"
    }
  }
}

🏗️ 建筑

移动自动化iOS MCP服务器具有 干净的模块化架构 通过全面的6阶段重构实现了完全的平台隔离。这种设计实现了最大的可维护性、零代码重复和无缝的跨平台扩展。

✨ 建筑成就

🎯 完全平台隔离

跨平台实用程序 隔离在 shared/ 包裹
iOS特定代码 包含的 platforms/ios/ 包裹
清洁分离 所有组件的关注点
为未来做好准备 适用于Android platforms/android/

🔄 应用干燥原理

共享公用设施：记录器、异常、命令运行器
基本配置：AppiumConfig、ServerConfig以供重用
平台配置：iOS特定设置分开
零重复 当前/未来平台之间

🛡️ 可维护和可扩展

独立平台：每个平台完全独立
统一接口：单一配置入口点
向后兼容：保留所有现有接口
专业结构：企业级组织

目录结构

mobile-automation-mcp-server/
├── fastmcp_server.py          # 🚀 FastMCP 2.0 server (main entry)
├── config/
│   └── settings.py           # 🔧 Unified configuration interface
├── shared/                   # 🌐 Cross-platform utilities & config
│   ├── utils/               # 🛠️ Platform-agnostic utilities  
│   │   ├── logger.py       # 📝 Colored logging with emojis
│   │   ├── exceptions.py   # ⚠️ Exception hierarchy
│   │   └── command_runner.py # 💻 Shell command execution
│   └── config/             # ⚙️ Base configuration classes
│       └── base_settings.py # 📋 AppiumConfig, ServerConfig
├── platforms/ios/          # 🍎 iOS-specific platform code
│   ├── automation/         # 🤖 iOS automation services
│   │   ├── appium_client.py # 📱 iOS automation client
│   │   ├── screenshot_service.py # 📸 Screenshot handling
│   │   └── simulator_manager.py # 🎮 Simulator management
│   ├── tools/             # 🔨 iOS-specific MCP tools
│   │   ├── appium_tap_type_tool.py # ⌨️ Text field automation
│   │   ├── find_and_tap_tool.py    # 👆 Advanced element finding
│   │   ├── launch_app_tool.py      # 🚀 App launching
│   │   └── screenshot_tool.py      # 📷 Screenshot capture
│   └── config/            # ⚙️ iOS-specific configuration
│       └── ios_settings.py # 🍎 iOSConfig (XCUITest, iPhone)
├── screenshots/             # 📁 Screenshot storage
├── Dockerfile              # 🐳 Container deployment
├── Procfile                # 🚂 Railway deployment
└── pyproject.toml          # 📦 Dependencies & project config

🎯 已实现的效益

方面	重构前	重构后
结构	混合iOS/共享代码	干净的平台隔离
可维护性	单片	模块化和自包含
可扩展性	仅限iOS	跨平台就绪
代码重用	可能重复	所有平台共享实用程序
配置	单个设置文件	模块化配置层次结构
组织	扁平化结构	专业化企业架构

🔧 可用工具

`take_screenshot`

捕获iOS模拟器屏幕截图

{
  "filename": "optional_name.png",
  "device_id": "booted"
}

`launch_app`

启动iOS应用程序

{
  "bundle_id": "com.apple.mobilesafari",
  "device_id": "booted"
}

`find_and_tap`

使用智能自动化查找和点击UI元素

{
  "accessibility_id": "submitButton",
  "take_screenshot": true,
  "dismiss_after_screenshot": false
}

`appium_tap_and_type`

通过元素查找增强文本输入

{
  "text": "Hello World!",
  "element_type": "textField",
  "timeout": 10
}

`list_simulators`

列出可用的iOS模拟器

{}

`get_server_status`

检查服务器和Appium状态

{}

🛠️ 发展

地方发展指挥部

# Run FastMCP server locally (with uv)
uv run python mobile-automation-mcp-server/fastmcp_server.py

# Install dependencies (if needed)
uv sync

# Development mode (with dev dependencies)
uv sync --dev

Appium设置

# Install Appium
npm install -g appium
appium driver install xcuitest

# Start Appium server
appium server --port 4723

结构开发

# The modular structure makes development easier:

# Work on shared utilities (affects all platforms)
cd shared/utils/

# Work on iOS-specific features  
cd platforms/ios/

# Work on configuration
cd config/

# Add new platforms (future)
mkdir platforms/android/

🌐 云部署

此服务器部署在Railway上，可通过以下方式访问：

HTTP端点: https://mcp-server-demo-production.up.railway.app/
SSE端点: https://mcp-server-demo-production.up.railway.app/sse/

云部署模拟iOS自动化响应以进行演示。

📊 关键改进

功能	传统MCP	FastMCP 2.0+清洁架构
设置	复杂的配置	简单的Python装饰器
建筑	单片	模块化平台隔离
代码重用	手动复制	共享实用程序包
类型安全	手动验证	内置Pydantic模型
错误处理	基本的try-catch	丰富的上下文和日志记录
部署	仅限本地	铁路云就绪
可扩展性	难以扩展	易于添加平台
可维护性	复杂	关注点的清晰分离

🔍 故障排除

模拟器问题

# List available simulators
xcrun simctl list devices

# Boot a simulator
xcrun simctl boot "iPhone 16 Pro"

Appium连接

# Check Appium status
curl http://localhost:4723/status

# Restart Appium
pkill -f appium && appium server --port 4723

📝 依赖项

通过以下方式管理核心依赖关系 pyproject.toml:

fastmcp>=2.9.2 -FastMCP 2.0框架
mcp>=1.0.0 -传统MCP协议
aiohttp>=3.9.0 -用于自动化的HTTP客户端
appium-python-client>=3.0.0 -iOS自动化
pydantic>=2.4.0 -数据验证

安装方式：

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

🤝 贡献

分叉存储库
创建要素分支
遵循干净的架构模式：
- 共享公用设施 进去 shared/
- 平台特定代码 进去 platforms/{platform}/
- 配置遵循模块化层次结构
添加全面的错误处理
提交拉取请求

🚀 未来的扩展

得益于干净的架构，添加新平台很简单：

# Add Android platform (example)
mkdir -p platforms/android/{automation,tools,config}

# Reuse shared utilities
from shared.utils import get_logger, AutomationMCPError
from shared.config import AppiumConfig, ServerConfig

# Create Android-specific config
from platforms.android.config import AndroidConfig

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。