Specter MCP

<p align="center"> <img src="logo.png" alt="Specter MCP Logo" width="400"> </p> <h1 align="center">Specter MCP</h1> <p align="center"> <strong>KMM Diagnostic & Execution Engine</strong><br> An MCP server providing "hands and eyes" for AI agents working with Kotlin Multiplatform Mobile projects. </p> <p align="center"> <a href="https://www.npmjs.com/package/specter-mcp"><img src="https://img.shields.io/npm/v/specter-mcp.svg" alt="npm version"></a> <a href="https://www.npmjs.com/package/specter-mcp"><img src="https://img.shields.io/npm/dm/specter-mcp.svg" alt="npm downloads"></a> <a href="https://github.com/abd3lraouf/specter-mcp/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/specter-mcp.svg" alt="license"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/specter-mcp.svg" alt="node version"></a> </p> --- ## What is Specter MCP? Specter MCP enables AI agents (Claude, GPT, etc.) to **build, test, debug, and interact** with Android and iOS applications through the [Model Context Protocol](https://modelcontextprotocol.io). Think of it as giving your AI assistant the ability to: - Build and deploy your mobile apps - Take screenshots and interact with UI elements - Run unit tests and E2E tests (Maestro) - Analyze crash logs and debug issues - Inspect app state (preferences, databases, logs) ## Prerequisites | Requirement | Version | Verify Command | |-------------|---------|----------------| | Node.js | 20+ | `node --version` | | Android SDK | Any | `adb --version` | | Xcode CLI (macOS) | Any | `xcrun --version` | | Maestro (optional) | Any | `maestro --version` | ### Quick Setup ```bash # 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 ``` ## Installation ### Option 1: npm (Recommended) ```bash npm install -g specter-mcp ``` ### Option 2: From Source ```bash git clone https://github.com/abd3lraouf/specter-mcp.git cd specter-mcp npm install && npm run build ``` ## Configuration ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "specter-mcp": { "command": "specter-mcp" } } } ``` ### Claude Code Add to your project's `.mcp.json`: ```json { "mcpServers": { "specter-mcp": { "command": "specter-mcp" } } } ``` ### With Environment Variables ```json { "mcpServers": { "specter-mcp": { "command": "specter-mcp", "env": { "SPECTER_DEBUG": "true", "ANDROID_SDK_ROOT": "/path/to/android/sdk" } } } } ``` ### From Source ```json { "mcpServers": { "specter-mcp": { "command": "node", "args": ["/absolute/path/to/specter-mcp/dist/index.js"] } } } ``` ## Available Tools (15) | Category | Tool | Description | |----------|------|-------------| | **Build** | `build_app` | Build Android/iOS app (debug/release) | | | `install_app` | Install APK or .app on device | | | `launch_app` | Launch installed app | | **UI** | `get_ui_context` | Screenshot + UI hierarchy | | | `interact_with_ui` | Tap, swipe, input text | | **Testing** | `run_unit_tests` | Run unit tests | | | `run_maestro_flow` | Run Maestro E2E flows | | | `run_linter` | Detekt, SwiftLint, ktlint | | **Environment** | `list_devices` | List emulators/simulators | | | `manage_env` | Boot/shutdown devices | | | `clean_project` | Clean build caches | | **Debug** | `analyze_crash` | Parse crash logs, symbolicate | | | `inspect_logs` | Filter device logs | | | `inspect_app_state` | Read prefs, databases | | **Navigation** | `deep_link_navigate` | Open deep links | ## Usage Examples ### Build & Deploy ``` 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") ``` ### Debug a Crash ``` 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") ``` ### UI Testing ``` 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") ``` ### Run E2E Tests ``` 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") ``` ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `SPECTER_DEBUG` | `false` | Enable debug logging | | `SPECTER_LOG_LEVEL` | `info` | Log level (error/warn/info/debug) | | `SPECTER_TIMEOUT` | `60000` | Default timeout (ms) | | `ANDROID_SDK_ROOT` | auto | Android SDK path | | `SPECTER_ANDROID_DEVICE` | - | Default Android device | | `SPECTER_IOS_DEVICE` | `booted` | Default iOS simulator | ## Troubleshooting ### "adb: command not found" ```bash export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools" ``` ### "No devices found" ```bash # Android: Start emulator emulator -avd Pixel_6_API_34 # iOS: Boot simulator xcrun simctl boot "iPhone 15 Pro" ``` ### "xcrun: error: unable to find utility" ```bash xcode-select --install ``` ### Debug Mode ```json { "env": { "SPECTER_DEBUG": "true", "SPECTER_LOG_LEVEL": "debug" } } ``` ## Project Structure ``` 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 ``` ## Development ```bash 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 ``` ## Documentation - [API Reference](./docs/API.md) — All 15 tools with parameters - [Configuration Guide](./docs/configuration.md) — Environment variables & setup - [Getting Started](./docs/getting-started.md) — First steps ## License [MIT](./LICENSE) © Specter MCP Contributors