Specter MCP

Specter MCP

KMM Diagnostic & Execution Engine

An MCP server providing "hands and eyes" for AI agents working with Kotlin Multiplatform Mobile projects.

______________________________________________________________________

什么是Spectre MCP？

Spectre MCP使AI代理（Claude、GPT等）能够 构建、测试、调试和交互 通过Android和iOS应用程序 模型上下文协议。将其视为赋予您的AI助手以下能力：

• 构建和部署您的移动应用程序
• 截图并与UI元素交互
• 运行单元测试和E2E测试（Maestro）
• 分析崩溃日志并调试问题
• 检查应用程序状态（首选项、数据库、日志）

先决条件

快速设置

# Android SDK (if not installed via Android Studio)
export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"
export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools"

# iOS (macOS only)
xcode-select --install
sudo xcodebuild -license accept

# Maestro (optional, for E2E testing)
curl -Ls "https://get.maestro.mobile.dev" | bash

安装

选项1:npm（推荐）

npm install -g specter-mcp

选项2：来源

git clone https://github.com/abd3lraouf/specter-mcp.git
cd specter-mcp
npm install && npm run build

配置

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "specter-mcp": {
      "command": "specter-mcp"
    }
  }
}

克劳德代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "specter-mcp": {
      "command": "specter-mcp"
    }
  }
}

使用环境变量

{
  "mcpServers": {
    "specter-mcp": {
      "command": "specter-mcp",
      "env": {
        "SPECTER_DEBUG": "true",
        "ANDROID_SDK_ROOT": "/path/to/android/sdk"
      }
    }
  }
}

来自源头

{
  "mcpServers": {
    "specter-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/specter-mcp/dist/index.js"]
    }
  }
}

可用工具（15）

使用示例

构建和部署

You: Build my Android app in debug mode and install it

Claude: I'll build and deploy your app.
→ build_app(platform: "android", variant: "debug")
→ install_app(platform: "android", appPath: "...")
→ launch_app(platform: "android", appId: "com.example.app")

调试崩溃

You: My iOS app crashed, help me debug it

Claude: Let me analyze the crash.
→ analyze_crash(platform: "ios", appId: "com.example.app")
→ inspect_logs(platform: "ios", minLevel: "error")

用户界面测试

You: Take a screenshot and tap the login button

Claude: I'll capture the UI and interact with it.
→ get_ui_context(platform: "android")
→ interact_with_ui(platform: "android", action: "tap", element: "Login")

运行E2E测试

You: Run my login flow test on both platforms

Claude: Running Maestro flows.
→ run_maestro_flow(platform: "android", flowPath: "./maestro/login.yaml")
→ run_maestro_flow(platform: "ios", flowPath: "./maestro/login.yaml")

环境变量

故障排除

“adb：找不到命令”

export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools"

“未找到设备”

# Android: Start emulator
emulator -avd Pixel_6_API_34

# iOS: Boot simulator
xcrun simctl boot "iPhone 15 Pro"

“xcrun:错误：找不到实用程序”

xcode-select --install

调试模式

{
  "env": {
    "SPECTER_DEBUG": "true",
    "SPECTER_LOG_LEVEL": "debug"
  }
}

项目结构

src/
├── index.ts              # MCP server entry
├── config.ts             # Configuration
├── platforms/            # Android/iOS utilities
│   ├── android/          # ADB, Gradle, logcat
│   └── ios/              # simctl, xcodebuild, crash parsing
├── tools/                # MCP tool implementations
│   ├── build/            # build_app, install_app, launch_app
│   ├── ui/               # get_ui_context, interact_with_ui
│   ├── testing/          # run_unit_tests, run_maestro_flow, run_linter
│   ├── environment/      # list_devices, manage_env, clean_project
│   ├── crash/            # analyze_crash
│   ├── navigation/       # deep_link_navigate
│   └── observability/    # inspect_logs, inspect_app_state
└── utils/                # Shell, image processing, XML parsing

发展

npm install          # Install dependencies
npm run build        # Build TypeScript
npm test             # Run tests (695 tests)
npm run test:coverage # Coverage report
npm run lint         # ESLint
npm run typecheck    # Type check

文档

• API 参考 --所有15个带有参数的工具
• 配置指南 --环境变量和设置
• 入门指南 --第一步

许可证

麻省理工学院 ©Spectre MCP贡献者