{"id":50779807,"url":"https://github.com/mark-nicepants/flutter_turbo_bridge","last_synced_at":"2026-06-12T02:04:23.381Z","repository":{"id":359302786,"uuid":"1245402653","full_name":"mark-nicepants/flutter_turbo_bridge","owner":"mark-nicepants","description":"MCP Tools and unified logging","archived":false,"fork":false,"pushed_at":"2026-06-10T14:52:29.000Z","size":2392,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T15:05:53.913Z","etag":null,"topics":["ai","flutter","llm","logging","mcp"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mark-nicepants.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-21T07:31:39.000Z","updated_at":"2026-06-10T14:49:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mark-nicepants/flutter_turbo_bridge","commit_stats":null,"previous_names":["mark-nicepants/flutter_turbo_bridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mark-nicepants/flutter_turbo_bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-nicepants%2Fflutter_turbo_bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-nicepants%2Fflutter_turbo_bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-nicepants%2Fflutter_turbo_bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-nicepants%2Fflutter_turbo_bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mark-nicepants","download_url":"https://codeload.github.com/mark-nicepants/flutter_turbo_bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-nicepants%2Fflutter_turbo_bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34225374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","flutter","llm","logging","mcp"],"created_at":"2026-06-12T02:04:22.580Z","updated_at":"2026-06-12T02:04:23.373Z","avatar_url":"https://github.com/mark-nicepants.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flutter Turbo Bridge\n\nUltra-fast bridge between AI agents and Flutter apps. Enables LLMs to see, understand, and interact with running Flutter applications in real-time.\n\n**Install from pub.dev:**\n\n```bash\nflutter pub add turbo_bridge\ndart pub global activate turbo_bridge_mcp\n```\n\nIf your app uses FVM, use `fvm flutter pub add turbo_bridge`.\n\nOr use the helper script:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mark-nicepants/flutter_turbo_bridge/main/install.sh | bash\n```\n\n```text\n┌──────────────┐     stdio      ┌──────────────────┐    HTTP     ┌────────────────┐\n│   LLM Host   │◄──────────────►│ turbo_bridge_mcp │◄───────────►│  Flutter App   │\n│  (Claude,    │                │  (MCP server)    │   :8888     │  + turbo_bridge│\n│   Cursor)    │                └──────────────────┘             └────────────────┘\n└──────────────┘                         │\n                                         │ uses\n                                         ▼\n                                ┌──────────────────┐\n                                │turbo_bridge_client│\n                                │  (Dart library)  │\n                                └──────────────────┘\n```\n\n## What Can AI Do With This?\n\n- **See the app** — capture screenshots as PNG in \u003c20ms\n- **Understand the UI** — inspect the widget tree with layout bounds, or focus on a smaller subtree around screen coordinates\n- **Find widgets** — server-side search by text, key, or type with coordinates\n- **Interact** — tap, swipe, scroll, and enter text\n- **Query state** — get app metadata, screen size, current route, platform info\n\n## Packages\n\n| Package | Description | Audience |\n|---------|-------------|----------|\n| [`turbo_bridge`](packages/turbo_bridge/) | In-app HTTP server for Flutter | Flutter developers |\n| [`turbo_bridge_client`](packages/turbo_bridge_client/) | Pure Dart client library | Tool/CI builders |\n| [`turbo_bridge_mcp`](packages/turbo_bridge_mcp/) | MCP server for LLM integration | AI/LLM developers |\n\n## Quick Start (3 Steps)\n\n### 1. Add the bridge to your Flutter app\n\n```bash\n# From your Flutter project root:\nflutter pub add turbo_bridge\n```\n\nThen start the bridge in your `main.dart`:\n\n```dart\nimport 'dart:async';\n\nimport 'package:flutter/foundation.dart';\nimport 'package:turbo_bridge/turbo_bridge.dart';\n\nvoid main() {\n  runApp(const MyApp());\n\n  if (!kReleaseMode) {\n    unawaited(TurboBridge.start(ensureInitialized: false));\n  }\n}\n```\n\nOnly enable the bridge in non-release builds unless you explicitly want to expose it in production.\n\n### 2. Connect your AI agent\n\nInstall the MCP server once on your machine:\n\n```bash\ndart pub global activate turbo_bridge_mcp\n```\n\nAdd to `.vscode/mcp.json` (committable to version control):\n\n```json\n{\n  \"servers\": {\n    \"turbo_bridge\": {\n      \"command\": \"turbo_bridge_mcp\"\n    }\n  }\n}\n```\n\nOr for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"turbo_bridge\": {\n      \"command\": \"turbo_bridge_mcp\"\n    }\n  }\n}\n```\n\n\u003e **Tip:** The MCP server auto-connects to `localhost:8888`. Pass `--bridge-port` if you changed the default. If your MCP host does not inherit the Dart pub cache bin path, replace `turbo_bridge_mcp` with the absolute executable path reported by `dart pub global activate`.\n\n### 3. Talk to your app\n\nOnce connected, ask the AI:\n\n\u003e \"Take a screenshot and describe what you see\"\n\n\u003e \"Find the Submit button and tap it\"\n\n\u003e \"Scroll down in the list and find item 50\"\n\n\u003e \"Enter 'hello@example.com' in the email field\"\n\n### Alternative: Use the client library directly\n\n```dart\nimport 'package:turbo_bridge_client/turbo_bridge_client.dart';\n\nfinal client = TurboBridgeClient(host: '127.0.0.1', port: 8888);\nfinal screenshot = await client.screenshot();\nawait client.tapByText('Submit');\nfinal results = await client.find(text: 'Login');\nawait client.swipe(200, 600, 200, 200); // Swipe up\nawait client.enterText('hello@example.com');\n```\n\n## Performance\n\nAll operations are designed for \u003c50ms round-trip latency:\n\n| Operation | Target (p95) |\n|-----------|-------------|\n| Screenshot | \u003c50ms |\n| Widget tree | \u003c40ms |\n| Tap gesture | \u003c30ms |\n| Swipe | \u003c30ms |\n| Scroll | \u003c30ms |\n| Find widget | \u003c20ms |\n| Enter text | \u003c30ms |\n| App info | \u003c10ms |\n\nHistorical benchmark trends with p50, p95, p99, and target lines are published at https://mark-nicepants.github.io/flutter_turbo_bridge/benchmarks/.\n\n## MCP Timing Metadata\n\nTurbo MCP tool and resource responses include a `_meta` object with UTC wall-clock stamps:\n\n- `startedAtUtc` — when the MCP tool or resource began handling the request\n- `completedAtUtc` — when the MCP tool or resource finished handling the request\n- operation-specific timing fields when available, such as `captureTimeMs`, `searchTimeMs`, `executionTimeMs`, and `roundTripMs`\n\nFor multi-step runs, compute total wall-clock duration from the first response's `startedAtUtc` to the last response's `completedAtUtc`. Keep the lower-level timing fields separately for per-action analysis.\n\n## Development\n\nThis is a Dart/Flutter monorepo managed with [Melos](https://melos.invertase.dev/).\n\n```bash\n# Install melos\ndart pub global activate melos\n\n# Bootstrap all packages\nmelos bootstrap\n\n# Run analysis\nmelos run analyze\n\n# Run tests\nmelos run test:dart    # Pure Dart packages\nmelos run test:flutter # Flutter package\n\n# Format\nmelos run format\n```\n\n## CI/CD\n\n- **CI** runs on every push/PR: shared package checks plus benchmark on macOS\n- **Publish** triggered on `v*` tags: reruns the shared package checks, then publishes all packages to pub.dev via pub.dev trusted publishing (GitHub OIDC)\n- **First release** of each package must still be published manually on pub.dev before GitHub Actions can publish later versions\n- **Secrets** are not required for the GitHub Actions flow once automated publishing is enabled on each package's pub.dev admin page\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmark-nicepants%2Fflutter_turbo_bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmark-nicepants%2Fflutter_turbo_bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmark-nicepants%2Fflutter_turbo_bridge/lists"}