星战科技xingzhan.cloud
返回市场
MCP服务器示例

MCP服务器示例

作者：iHackSubhodip27 星标更新：2025-07-26
安装使用来源：spider==github.com

项目介绍

移动自动化 iOS MCP 服务器

使用 FastMCP 2.0 和干净架构构建的现代 iOS 自动化服务器

License: MIT Python 3.11+ Platform: macOS FastMCP Architecture

一个使用 FastMCP 2.0 构建的生产就绪的 iOS 自动化 MCP 服务器，具有干净模块化架构和完全的平台隔离。准备好进行跨平台扩展，iOS 特定组件和共享组件已适当分离。

📺 演示视频

移动自动化 iOS MCP 服务器演示

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

✨ 功能

  • 🚀 FastMCP 2.0 - 现代 Python 首选 MCP 实现
  • 🌐 云部署 - 准备在 Railway、Heroku 或其他平台上部署
  • 📱 真实的 iOS 自动化 - Appium + WebDriverAgent 集成
  • 🏗️ 干净模块化架构 - 完整的平台隔离及 SOLID 原则
  • 🔄 跨平台准备 - 用于未来 Android/其他平台的共享工具
  • 🎨 美观的日志记录 - 带有表情符号的彩色控制台输出
  • 🔧 类型安全 - 全面的类型提示
  • 🔌 可扩展性 - 插件式工具系统，具有模块化配置
  • 📦 零代码重复 - 通过共享工具实现 DRY 原则

🚀 快速开始

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

使用 Railway 上托管的版本 - 不需要本地设置：

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

选项 2：本地开发

  1. 先决条件

    • macOS（用于 iOS 自动化）
    • Python 3.11+
    • uv（推荐）或 pip
    • Xcode 和 iOS 模拟器
    • Node.js（用于 Appium）

  2. 安装

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

# 使用 uv（推荐）
uv sync

# 或使用 pip（旧版）
pip install -e .

  3. Claude Desktop 配置

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

🏗️ 架构

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

✨ 架构成就

🎯 完整的平台隔离

  • 跨平台工具隔离在 shared/ 包中
  • iOS 特定代码包含在 platforms/ios/ 包中
  • 清晰的职责分离贯穿所有组件
  • 面向未来的 Android 在 platforms/android/

🔄 应用 DRY 原则

  • 共享工具：日志记录器、异常处理、命令执行器
  • 基础配置：AppiumConfig、ServerConfig 以供复用
  • 平台配置：iOS 特定设置单独存放
  • 当前和未来平台之间无重复

🛡️ 维护性和可扩展性

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

目录结构

mobile-automation-mcp-server/
├── fastmcp_server.py          # 🚀 FastMCP 2.0 服务器（主入口）
├── config/
│   └── settings.py           # 🔧 统一配置接口
├── shared/                   # 🌐 跨平台工具及配置
│   ├── utils/               # 🛠️ 平台无关工具  
│   │   ├── logger.py       # 📝 带表情符号的彩色日志记录
│   │   ├── exceptions.py   # ⚠️ 异常层次结构
│   │   └── command_runner.py # 💻 命令执行
│   └── config/             # ⚙️ 基础配置类
│       └── base_settings.py # 📋 AppiumConfig, ServerConfig
├── platforms/ios/          # 🍎 iOS 特定平台代码
│   ├── automation/         # 🤖 iOS 自动化服务
│   │   ├── appium_client.py # 📱 iOS 自动化客户端
│   │   ├── screenshot_service.py # 📸 截图处理
│   │   └── simulator_manager.py # 🎮 模拟器管理
│   ├── tools/             # 🔨 iOS 特定 MCP 工具
│   │   ├── appium_tap_type_tool.py # ⌨️ 文本字段自动化
│   │   ├── find_and_tap_tool.py    # 👆 高级元素查找
│   │   ├── launch_app_tool.py      # 🚀 应用启动
│   │   └── screenshot_tool.py      # 📷 截图捕获
│   └── config/            # ⚙️ iOS 特定配置
│       └── ios_settings.py # 🍎 iOSConfig (XCUITest, iPhone)
├── screenshots/             # 📁 截图存储
├── Dockerfile              # 🐳 容器部署
├── Procfile                # 🚂 Railway 部署
└── pyproject.toml          # 📦 依赖项及项目配置

🎯 达到的好处

方面重构前重构后
结构混合 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 状态

{}

🛠️ 开发

本地开发命令

# 本地运行 FastMCP 服务器（使用 uv）
uv run python mobile-automation-mcp-server/fastmcp_server.py

# 安装依赖项（如果需要）
uv sync

# 开发模式（带开发依赖项）
uv sync --dev

Appium 设置

# 安装 Appium
npm install -g appium
appium driver install xcuitest

# 启动 Appium 服务器
appium server --port 4723

架构开发

# 模块化结构使得开发更容易：

# 工作于共享工具（影响所有平台）
cd shared/utils/

# 工作于 iOS 特定功能  
cd platforms/ios/

# 工作于配置
cd config/

# 添加新平台（未来）
mkdir platforms/android/

🌐 云部署

该服务器部署在 Railway 并可通过以下方式访问：

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

云部署模拟 iOS 自动化响应以供演示目的。

📊 关键改进

功能传统 MCPFastMCP 2.0 + 清洁架构
设置复杂配置简单的 Python 装饰器
架构单体模块化平台隔离
代码重用手动复制共享工具包
类型安全手动验证内置 Pydantic 模型
错误处理基本的 try-catch丰富的上下文和日志记录
部署仅本地通过 Railway 的云就绪
可扩展性难以扩展易于添加平台
维护性复杂清晰的职责分离

🔍 故障排除

模拟器问题

# 列出可用的模拟器
xcrun simctl list devices

# 启动模拟器
xcrun simctl boot "iPhone 16 Pro"

Appium 连接

# 检查 Appium 状态
curl http://localhost:4723/status

# 重启 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 - 数据验证

安装方法：

# 使用 uv（推荐）
uv sync

# 或使用 pip
pip install -e .

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支
  3. 遵循清洁架构模式：
    • 共享工具 放在 shared/
    • 特定平台代码 放在 platforms/{platform}/
    • 配置 遵循模块化层次
  4. 添加全面的错误处理
  5. 提交拉取请求

🚀 未来扩展

得益于清洁架构，添加新平台非常简单：

# 添加 Android 平台（示例）
mkdir -p platforms/android/{automation,tools,config}

# 重用共享工具
from shared.utils import get_logger, AutomationMCPError
from shared.config import AppiumConfig, ServerConfig

# 创建 Android 特定配置
from platforms.android.config import AndroidConfig

📄 许可证

本项目根据 MIT 许可证发布 - 查看 LICENSE 文件获取详情。