{"id":36606331,"url":"https://github.com/abd3lraouf/specter-mcp","last_synced_at":"2026-01-12T08:45:43.022Z","repository":{"id":329655083,"uuid":"1120323029","full_name":"abd3lraouf/specter-mcp","owner":"abd3lraouf","description":"KMM Diagnostic \u0026 Execution Engine - MCP server for AI agents working with Kotlin Multiplatform Mobile projects","archived":false,"fork":false,"pushed_at":"2025-12-21T06:32:59.000Z","size":721,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T22:28:09.704Z","etag":null,"topics":["ai-agent","android","claude","debugging","developer-tools","ios","kotlin-multiplatform","mcp","mobile-development","testing"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abd3lraouf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-21T00:37:28.000Z","updated_at":"2025-12-21T08:15:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/abd3lraouf/specter-mcp","commit_stats":null,"previous_names":["abd3lraouf/specter-mcp"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/abd3lraouf/specter-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abd3lraouf%2Fspecter-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abd3lraouf%2Fspecter-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abd3lraouf%2Fspecter-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abd3lraouf%2Fspecter-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abd3lraouf","download_url":"https://codeload.github.com/abd3lraouf/specter-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abd3lraouf%2Fspecter-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","android","claude","debugging","developer-tools","ios","kotlin-multiplatform","mcp","mobile-development","testing"],"created_at":"2026-01-12T08:45:42.961Z","updated_at":"2026-01-12T08:45:43.015Z","avatar_url":"https://github.com/abd3lraouf.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"Specter MCP Logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSpecter MCP\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eKMM Diagnostic \u0026 Execution Engine\u003c/strong\u003e\u003cbr\u003e\n  An MCP server providing \"hands and eyes\" for AI agents working with Kotlin Multiplatform Mobile projects.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/specter-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/specter-mcp.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/specter-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/specter-mcp.svg\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/abd3lraouf/specter-mcp/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/specter-mcp.svg\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/node/v/specter-mcp.svg\" alt=\"node version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Specter MCP?\n\nSpecter 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:\n\n- Build and deploy your mobile apps\n- Take screenshots and interact with UI elements\n- Run unit tests and E2E tests (Maestro)\n- Analyze crash logs and debug issues\n- Inspect app state (preferences, databases, logs)\n\n## Prerequisites\n\n| Requirement | Version | Verify Command |\n|-------------|---------|----------------|\n| Node.js | 20+ | `node --version` |\n| Android SDK | Any | `adb --version` |\n| Xcode CLI (macOS) | Any | `xcrun --version` |\n| Maestro (optional) | Any | `maestro --version` |\n\n### Quick Setup\n\n```bash\n# Android SDK (if not installed via Android Studio)\nexport ANDROID_SDK_ROOT=\"$HOME/Library/Android/sdk\"\nexport PATH=\"$PATH:$ANDROID_SDK_ROOT/platform-tools\"\n\n# iOS (macOS only)\nxcode-select --install\nsudo xcodebuild -license accept\n\n# Maestro (optional, for E2E testing)\ncurl -Ls \"https://get.maestro.mobile.dev\" | bash\n```\n\n## Installation\n\n### Option 1: npm (Recommended)\n\n```bash\nnpm install -g specter-mcp\n```\n\n### Option 2: From Source\n\n```bash\ngit clone https://github.com/abd3lraouf/specter-mcp.git\ncd specter-mcp\nnpm install \u0026\u0026 npm run build\n```\n\n## Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"specter-mcp\": {\n      \"command\": \"specter-mcp\"\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"specter-mcp\": {\n      \"command\": \"specter-mcp\"\n    }\n  }\n}\n```\n\n### With Environment Variables\n\n```json\n{\n  \"mcpServers\": {\n    \"specter-mcp\": {\n      \"command\": \"specter-mcp\",\n      \"env\": {\n        \"SPECTER_DEBUG\": \"true\",\n        \"ANDROID_SDK_ROOT\": \"/path/to/android/sdk\"\n      }\n    }\n  }\n}\n```\n\n### From Source\n\n```json\n{\n  \"mcpServers\": {\n    \"specter-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/specter-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n## Available Tools (15)\n\n| Category | Tool | Description |\n|----------|------|-------------|\n| **Build** | `build_app` | Build Android/iOS app (debug/release) |\n| | `install_app` | Install APK or .app on device |\n| | `launch_app` | Launch installed app |\n| **UI** | `get_ui_context` | Screenshot + UI hierarchy |\n| | `interact_with_ui` | Tap, swipe, input text |\n| **Testing** | `run_unit_tests` | Run unit tests |\n| | `run_maestro_flow` | Run Maestro E2E flows |\n| | `run_linter` | Detekt, SwiftLint, ktlint |\n| **Environment** | `list_devices` | List emulators/simulators |\n| | `manage_env` | Boot/shutdown devices |\n| | `clean_project` | Clean build caches |\n| **Debug** | `analyze_crash` | Parse crash logs, symbolicate |\n| | `inspect_logs` | Filter device logs |\n| | `inspect_app_state` | Read prefs, databases |\n| **Navigation** | `deep_link_navigate` | Open deep links |\n\n## Usage Examples\n\n### Build \u0026 Deploy\n\n```\nYou: Build my Android app in debug mode and install it\n\nClaude: I'll build and deploy your app.\n→ build_app(platform: \"android\", variant: \"debug\")\n→ install_app(platform: \"android\", appPath: \"...\")\n→ launch_app(platform: \"android\", appId: \"com.example.app\")\n```\n\n### Debug a Crash\n\n```\nYou: My iOS app crashed, help me debug it\n\nClaude: Let me analyze the crash.\n→ analyze_crash(platform: \"ios\", appId: \"com.example.app\")\n→ inspect_logs(platform: \"ios\", minLevel: \"error\")\n```\n\n### UI Testing\n\n```\nYou: Take a screenshot and tap the login button\n\nClaude: I'll capture the UI and interact with it.\n→ get_ui_context(platform: \"android\")\n→ interact_with_ui(platform: \"android\", action: \"tap\", element: \"Login\")\n```\n\n### Run E2E Tests\n\n```\nYou: Run my login flow test on both platforms\n\nClaude: Running Maestro flows.\n→ run_maestro_flow(platform: \"android\", flowPath: \"./maestro/login.yaml\")\n→ run_maestro_flow(platform: \"ios\", flowPath: \"./maestro/login.yaml\")\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SPECTER_DEBUG` | `false` | Enable debug logging |\n| `SPECTER_LOG_LEVEL` | `info` | Log level (error/warn/info/debug) |\n| `SPECTER_TIMEOUT` | `60000` | Default timeout (ms) |\n| `ANDROID_SDK_ROOT` | auto | Android SDK path |\n| `SPECTER_ANDROID_DEVICE` | - | Default Android device |\n| `SPECTER_IOS_DEVICE` | `booted` | Default iOS simulator |\n\n## Troubleshooting\n\n### \"adb: command not found\"\n\n```bash\nexport PATH=\"$PATH:$ANDROID_SDK_ROOT/platform-tools\"\n```\n\n### \"No devices found\"\n\n```bash\n# Android: Start emulator\nemulator -avd Pixel_6_API_34\n\n# iOS: Boot simulator\nxcrun simctl boot \"iPhone 15 Pro\"\n```\n\n### \"xcrun: error: unable to find utility\"\n\n```bash\nxcode-select --install\n```\n\n### Debug Mode\n\n```json\n{\n  \"env\": {\n    \"SPECTER_DEBUG\": \"true\",\n    \"SPECTER_LOG_LEVEL\": \"debug\"\n  }\n}\n```\n\n## Project Structure\n\n```\nsrc/\n├── index.ts              # MCP server entry\n├── config.ts             # Configuration\n├── platforms/            # Android/iOS utilities\n│   ├── android/          # ADB, Gradle, logcat\n│   └── ios/              # simctl, xcodebuild, crash parsing\n├── tools/                # MCP tool implementations\n│   ├── build/            # build_app, install_app, launch_app\n│   ├── ui/               # get_ui_context, interact_with_ui\n│   ├── testing/          # run_unit_tests, run_maestro_flow, run_linter\n│   ├── environment/      # list_devices, manage_env, clean_project\n│   ├── crash/            # analyze_crash\n│   ├── navigation/       # deep_link_navigate\n│   └── observability/    # inspect_logs, inspect_app_state\n└── utils/                # Shell, image processing, XML parsing\n```\n\n## Development\n\n```bash\nnpm install          # Install dependencies\nnpm run build        # Build TypeScript\nnpm test             # Run tests (695 tests)\nnpm run test:coverage # Coverage report\nnpm run lint         # ESLint\nnpm run typecheck    # Type check\n```\n\n## Documentation\n\n- [API Reference](./docs/API.md) — All 15 tools with parameters\n- [Configuration Guide](./docs/configuration.md) — Environment variables \u0026 setup\n- [Getting Started](./docs/getting-started.md) — First steps\n\n## License\n\n[MIT](./LICENSE) © Specter MCP Contributors\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabd3lraouf%2Fspecter-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabd3lraouf%2Fspecter-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabd3lraouf%2Fspecter-mcp/lists"}