https://github.com/abd3lraouf/specter-mcp

KMM Diagnostic & Execution Engine - MCP server for AI agents working with Kotlin Multiplatform Mobile projects
https://github.com/abd3lraouf/specter-mcp

ai-agent android claude debugging developer-tools ios kotlin-multiplatform mcp mobile-development testing

Last synced: 6 months ago
JSON representation

KMM Diagnostic & Execution Engine - MCP server for AI agents working with Kotlin Multiplatform Mobile projects

Host: GitHub
URL: https://github.com/abd3lraouf/specter-mcp
Owner: abd3lraouf
License: mit
Created: 2025-12-21T00:37:28.000Z (6 months ago)
Default Branch: main
Last Pushed: 2025-12-21T06:32:59.000Z (6 months ago)
Last Synced: 2025-12-22T22:28:09.704Z (6 months ago)
Topics: ai-agent, android, claude, debugging, developer-tools, ios, kotlin-multiplatform, mcp, mobile-development, testing
Language: TypeScript
Size: 704 KB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

README

          


  



Specter MCP




  KMM Diagnostic & Execution Engine


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





  

  

  

  



---

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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/abd3lraouf/specter-mcp

Awesome Lists containing this project

README

Specter MCP