AI导哈

Kotlin多平台移动诊断执行引擎

Specter MCP是一款为AI代理提供Kotlin多平台移动项目构建、测试、调试和交互能力的MCP服务器。

  • by abd3lraouf
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 abd3lraouf/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）
  • 分析崩溃日志并调试问题
  • 检查应用程序状态（首选项、数据库、日志）

先决条件

要求 版本 验证命令
Node.js 20+ node --version
Android SDK 任何 adb --version
Xcode CLI（macOS） 任何 xcrun --version
Maestro（可选） 任何 maestro --version

快速设置

# 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）

类别 工具 描述
构建 build_app 构建Android/iOS应用程序（调试/发布）
install_app 在设备上安装APK或.app
launch_app 启动已安装的应用程序
用户界面 get_ui_context 屏幕截图+UI层次结构
interact_with_ui 点击、滑动、输入文本
测试 run_unit_tests 运行单元测试
run_maestro_flow 运行Maestro E2E流
run_linter Detekt、SwiftLint、ktlint
环境 list_devices 列出仿真器/模拟器
manage_env 启动/关闭设备
clean_project 清理构建缓存
调试 analyze_crash 解析崩溃日志，符号化
inspect_logs 过滤设备日志
inspect_app_state 读取首选项、数据库
导航 deep_link_navigate 打开深层链接

使用示例

构建和部署

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")

环境变量

变量 默认值 描述
SPECTER_DEBUG false 启用调试日志记录
SPECTER_LOG_LEVEL info 日志级别（错误/警告/信息/调试）
SPECTER_TIMEOUT 60000 默认超时（ms）
ANDROID_SDK_ROOT auto Android SDK路径
SPECTER_ANDROID_DEVICE - 默认Android设备
SPECTER_IOS_DEVICE booted 默认iOS模拟器

故障排除

“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

文档

许可证

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

相关 MCP