flutter-skill-mcp 0.2.13 → 0.2.15

package/README.md

@@ -1,70 +1,322 @@
-# flutter-skill-mcp
+# Flutter Skill
 
-> MCP Server for Flutter app automation - Give your AI Agent eyes and hands inside your Flutter app
+> **Give your AI Agent eyes and hands inside your Flutter app.**
 
-[![npm version](https://badge.fury.io/js/flutter-skill-mcp.svg)](https://www.npmjs.com/package/flutter-skill-mcp)
-[![pub version](https://img.shields.io/pub/v/flutter_skill.svg)](https://pub.dev/packages/flutter_skill)
+![Version](https://img.shields.io/pub/v/flutter_skill.svg)
+![npm](https://img.shields.io/npm/v/flutter-skill-mcp.svg)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Platform](https://img.shields.io/badge/Platform-Flutter-02569B)
 
-## Installation
+**Flutter Skill** is a bridge that connects AI Agents (like Claude Code, Cursor, Windsurf) directly to running Flutter applications via the MCP (Model Context Protocol). It provides 30+ tools for UI automation, inspection, and testing.
+
+## Quick Start
+
+### 1. Install (choose one)
 
 ```bash
+# npm (recommended - includes native binary for instant startup)
 npm install -g flutter-skill-mcp
-# or use directly with npx
-npx flutter-skill-mcp
-```
 
-**Prerequisites**: [Flutter SDK](https://docs.flutter.dev/get-started/install) or [Dart SDK](https://dart.dev/get-dart)
+# Homebrew (macOS/Linux)
+brew tap ai-dashboad/flutter-skill
+brew install flutter-skill
 
-## MCP Configuration
+# Dart
+dart pub global activate flutter_skill
+
+# IDE Extensions
+# - VSCode: Search "Flutter Skill" in Extensions
+# - IntelliJ/Android Studio: Search "Flutter Skill" in Plugins
+```
 
-Add to your MCP config (Cursor, Windsurf, Claude Desktop):
+### 2. Configure AI Agent
 
+Add to your AI agent's MCP config:
+
+**Claude Code** (`~/.claude/settings.json`):
 ```json
 {
-  "flutter-skill": {
-    "command": "npx",
-    "args": ["flutter-skill-mcp"]
+  "mcpServers": {
+    "flutter-skill": {
+      "command": "flutter-skill",
+      "args": ["server"]
+    }
   }
 }
 ```
 
-Or if installed globally:
-
+**Cursor** (`~/.cursor/mcp.json`):
 ```json
 {
-  "flutter-skill": {
-    "command": "flutter-skill-mcp"
+  "mcpServers": {
+    "flutter-skill": {
+      "command": "flutter-skill",
+      "args": ["server"]
+    }
   }
 }
 ```
 
+### 3. Use
+
+```javascript
+// Option 1: Launch app with environment variables
+flutter-skill.launch_app({
+  project_path: "/path/to/flutter/project",
+  dart_defines: ["ENV=staging", "DEBUG=true"],
+  flavor: "staging"
+})
+
+// Option 2: Connect to already running app (auto-detect)
+flutter-skill.scan_and_connect()
+
+// Now use any tool
+flutter-skill.screenshot()
+flutter-skill.tap({ text: "Login" })
+flutter-skill.inspect()
+```
+
+---
+
 ## Features
 
-- **UI Inspection**: Widget tree, text content, element properties
-- **Interactions**: Tap, double tap, long press, swipe, drag, scroll
-- **State Validation**: Text values, checkbox state, wait for elements
-- **Screenshots**: Full app or specific elements
-- **Navigation**: Routes, go back, navigation stack
-- **Debug**: Logs, errors, performance metrics
-
-## 25+ MCP Tools
-
-| Category | Tools |
-|----------|-------|
-| Connection | `connect_app`, `launch_app` |
-| UI Inspection | `inspect`, `get_widget_tree`, `get_widget_properties`, `get_text_content`, `find_by_type` |
-| Interactions | `tap`, `double_tap`, `long_press`, `swipe`, `drag`, `scroll_to`, `enter_text` |
-| State | `get_text_value`, `get_checkbox_state`, `get_slider_value`, `wait_for_element`, `wait_for_gone` |
-| Screenshot | `screenshot`, `screenshot_element` |
-| Navigation | `get_current_route`, `go_back`, `get_navigation_stack` |
-| Debug | `get_logs`, `get_errors`, `get_performance`, `clear_logs` |
-| Dev | `hot_reload`, `pub_search` |
+### App Lifecycle Management
+| Tool | Description |
+|------|-------------|
+| `launch_app` | Launch Flutter app with dart_defines, flavor, target, extra_args |
+| `scan_and_connect` | Auto-scan ports and connect to first running Flutter app |
+| `list_running_apps` | List all running Flutter apps (VM Services) |
+| `connect_app` | Connect to specific VM Service URI |
+| `stop_app` | Stop the currently running app |
+| `disconnect` | Disconnect without stopping the app |
+| `get_connection_status` | Get connection info and suggestions |
+| `hot_reload` | Fast reload (keeps state) |
+| `hot_restart` | Full restart (resets state) |
+
+### UI Inspection
+| Tool | Description |
+|------|-------------|
+| `inspect` | Get interactive elements with coordinates, size, and center point |
+| `get_widget_tree` | Get widget tree structure with depth control |
+| `get_widget_properties` | Get properties of a widget (size, position, visibility) |
+| `get_text_content` | Extract all visible text from the screen |
+| `find_by_type` | Find widgets by type (e.g., ElevatedButton) |
+
+### Interactions
+| Tool | Description |
+|------|-------------|
+| `tap` | Tap a widget by Key or Text (returns success/failure) |
+| `double_tap` | Double tap a widget |
+| `long_press` | Long press with configurable duration |
+| `swipe` | Swipe gesture (up/down/left/right) |
+| `edge_swipe` | Swipe from screen edge (for drawer menus, back gestures) |
+| `drag` | Drag from one element to another |
+| `scroll_to` | Scroll to make an element visible |
+| `enter_text` | Enter text into a text field (returns success/failure) |
+
+### State & Validation
+| Tool | Description |
+|------|-------------|
+| `get_text_value` | Get current value of a text field |
+| `get_checkbox_state` | Get checked state of a checkbox/switch |
+| `get_slider_value` | Get current value of a slider |
+| `wait_for_element` | Wait for an element to appear (with timeout) |
+| `wait_for_gone` | Wait for an element to disappear |
+
+### Screenshots
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Take full app screenshot (quality, max_width options) |
+| `screenshot_region` | Take screenshot of specific region (x, y, width, height) |
+| `screenshot_element` | Take screenshot of specific element |
+
+### Navigation
+| Tool | Description |
+|------|-------------|
+| `get_current_route` | Get the current route name |
+| `go_back` | Navigate back |
+| `get_navigation_stack` | Get the navigation stack |
+
+### Debug & Logs
+| Tool | Description |
+|------|-------------|
+| `get_logs` | Get application logs |
+| `get_errors` | Get application errors |
+| `clear_logs` | Clear logs and errors |
+| `get_performance` | Get performance metrics |
+
+### Utilities
+| Tool | Description |
+|------|-------------|
+| `pub_search` | Search Flutter packages on pub.dev |
+
+---
+
+## Installation Methods
+
+| Method | Command | Auto-Update | Native Binary |
+|--------|---------|-------------|---------------|
+| npm | `npm install -g flutter-skill-mcp` | Manual | Auto-download |
+| Homebrew | `brew install ai-dashboad/flutter-skill/flutter-skill` | `brew upgrade` | Pre-compiled |
+| VSCode | Extensions → "Flutter Skill" | Auto | Auto-download |
+| IntelliJ | Plugins → "Flutter Skill" | Auto | Auto-download |
+| pub.dev | `dart pub global activate flutter_skill` | Manual | Dart runtime |
+
+### Native Binary Performance
+| Version | Startup Time |
+|---------|--------------|
+| Dart JIT | ~1 second |
+| Native Binary | ~0.01 second |
+
+Native binaries are automatically downloaded on first use for supported platforms:
+- macOS (Apple Silicon & Intel)
+- Linux (x64)
+- Windows (x64)
+
+---
+
+## Flutter App Setup
+
+For the MCP tools to work, your Flutter app needs the `flutter_skill` package:
+
+### Automatic Setup (Recommended)
+```bash
+flutter-skill launch /path/to/project
+# Automatically adds dependency and initializes
+```
+
+### Manual Setup
+1. Add dependency:
+```yaml
+dependencies:
+  flutter_skill: ^0.2.15
+```
+
+2. Initialize in main.dart:
+```dart
+import 'package:flutter_skill/flutter_skill.dart';
+
+void main() {
+  FlutterSkillBinding.ensureInitialized();
+  runApp(MyApp());
+}
+```
+
+---
+
+## Example Workflows
+
+### E2E Testing with Environment Variables
+```javascript
+// Launch staging environment
+flutter-skill.launch_app({
+  project_path: "./",
+  dart_defines: ["ENV=staging", "API_URL=https://staging.api.com"],
+  flavor: "staging",
+  target: "lib/main_staging.dart"
+})
+
+// Wait for app to load
+flutter-skill.wait_for_element({ text: "Welcome" })
+
+// Take screenshot
+flutter-skill.screenshot()
+
+// Perform login
+flutter-skill.tap({ text: "Login" })
+flutter-skill.enter_text({ key: "email_field", text: "test@example.com" })
+flutter-skill.enter_text({ key: "password_field", text: "password123" })
+flutter-skill.tap({ text: "Submit" })
+
+// Verify success
+flutter-skill.wait_for_element({ text: "Dashboard" })
+```
+
+### Connect to Running App
+```javascript
+// List all running Flutter apps
+flutter-skill.list_running_apps()
+// Returns: { apps: ["ws://127.0.0.1:50123/ws", ...], count: 2 }
+
+// Auto-connect to first one
+flutter-skill.scan_and_connect()
+
+// Or connect to specific one
+flutter-skill.connect_app({ uri: "ws://127.0.0.1:50123/ws" })
+```
+
+### Debug a UI Issue
+```javascript
+// Get widget tree
+flutter-skill.get_widget_tree({ max_depth: 5 })
+
+// Find specific widgets
+flutter-skill.find_by_type({ type: "ElevatedButton" })
+
+// Inspect interactive elements
+flutter-skill.inspect()
+
+// Check if element is visible
+flutter-skill.wait_for_element({ key: "submit_button", timeout: 3000 })
+```
+
+---
+
+## IDE Extensions
+
+### VSCode Extension
+- Auto-detects Flutter projects
+- Prompts to add `flutter_skill` dependency
+- Auto-downloads native binary
+- Status bar shows connection state
+- Commands: Launch, Inspect, Screenshot
+
+### IntelliJ/Android Studio Plugin
+- Same features as VSCode
+- Integrates with IDE notifications
+- Tool window for status
+
+---
+
+## Troubleshooting
+
+### "Not connected to Flutter app"
+```javascript
+// Check status and get suggestions
+flutter-skill.get_connection_status()
+
+// This returns:
+// - Current connection state
+// - List of available apps
+// - Actionable suggestions
+```
+
+### "Unknown method ext.flutter.flutter_skill.xxx"
+Your Flutter app doesn't have the `flutter_skill` package. Add it:
+```bash
+flutter pub add flutter_skill
+```
+Then restart the app (hot reload is not enough).
+
+### MCP server slow to start
+The native binary should auto-download. If not:
+```bash
+# For npm
+npm update -g flutter-skill-mcp
+
+# For Homebrew
+brew upgrade flutter-skill
+```
+
+---
 
 ## Links
 
 - [GitHub](https://github.com/ai-dashboad/flutter-skill)
 - [pub.dev](https://pub.dev/packages/flutter_skill)
-- [Documentation](https://github.com/ai-dashboad/flutter-skill#readme)
+- [npm](https://www.npmjs.com/package/flutter-skill-mcp)
+- [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=ai-dashboad.flutter-skill)
+- [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/PLUGIN_ID)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flutter-skill-mcp",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "MCP Server for Flutter app automation - Give your AI Agent eyes and hands inside your Flutter app",
   "main": "index.js",
   "bin": {