https://github.com/mark-nicepants/flutter_turbo_bridge
MCP Tools and unified logging
https://github.com/mark-nicepants/flutter_turbo_bridge
ai flutter llm logging mcp
Last synced: 15 days ago
JSON representation
MCP Tools and unified logging
- Host: GitHub
- URL: https://github.com/mark-nicepants/flutter_turbo_bridge
- Owner: mark-nicepants
- Created: 2026-05-21T07:31:39.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-10T14:52:29.000Z (16 days ago)
- Last Synced: 2026-06-10T15:05:53.913Z (16 days ago)
- Topics: ai, flutter, llm, logging, mcp
- Language: Dart
- Homepage:
- Size: 2.28 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Roadmap: docs/ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Flutter Turbo Bridge
Ultra-fast bridge between AI agents and Flutter apps. Enables LLMs to see, understand, and interact with running Flutter applications in real-time.
**Install from pub.dev:**
```bash
flutter pub add turbo_bridge
dart pub global activate turbo_bridge_mcp
```
If your app uses FVM, use `fvm flutter pub add turbo_bridge`.
Or use the helper script:
```bash
curl -fsSL https://raw.githubusercontent.com/mark-nicepants/flutter_turbo_bridge/main/install.sh | bash
```
```text
┌──────────────┐ stdio ┌──────────────────┐ HTTP ┌────────────────┐
│ LLM Host │◄──────────────►│ turbo_bridge_mcp │◄───────────►│ Flutter App │
│ (Claude, │ │ (MCP server) │ :8888 │ + turbo_bridge│
│ Cursor) │ └──────────────────┘ └────────────────┘
└──────────────┘ │
│ uses
▼
┌──────────────────┐
│turbo_bridge_client│
│ (Dart library) │
└──────────────────┘
```
## What Can AI Do With This?
- **See the app** — capture screenshots as PNG in <20ms
- **Understand the UI** — inspect the widget tree with layout bounds, or focus on a smaller subtree around screen coordinates
- **Find widgets** — server-side search by text, key, or type with coordinates
- **Interact** — tap, swipe, scroll, and enter text
- **Query state** — get app metadata, screen size, current route, platform info
## Packages
| Package | Description | Audience |
|---------|-------------|----------|
| [`turbo_bridge`](packages/turbo_bridge/) | In-app HTTP server for Flutter | Flutter developers |
| [`turbo_bridge_client`](packages/turbo_bridge_client/) | Pure Dart client library | Tool/CI builders |
| [`turbo_bridge_mcp`](packages/turbo_bridge_mcp/) | MCP server for LLM integration | AI/LLM developers |
## Quick Start (3 Steps)
### 1. Add the bridge to your Flutter app
```bash
# From your Flutter project root:
flutter pub add turbo_bridge
```
Then start the bridge in your `main.dart`:
```dart
import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:turbo_bridge/turbo_bridge.dart';
void main() {
runApp(const MyApp());
if (!kReleaseMode) {
unawaited(TurboBridge.start(ensureInitialized: false));
}
}
```
Only enable the bridge in non-release builds unless you explicitly want to expose it in production.
### 2. Connect your AI agent
Install the MCP server once on your machine:
```bash
dart pub global activate turbo_bridge_mcp
```
Add to `.vscode/mcp.json` (committable to version control):
```json
{
"servers": {
"turbo_bridge": {
"command": "turbo_bridge_mcp"
}
}
}
```
Or for Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"turbo_bridge": {
"command": "turbo_bridge_mcp"
}
}
}
```
> **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`.
### 3. Talk to your app
Once connected, ask the AI:
> "Take a screenshot and describe what you see"
> "Find the Submit button and tap it"
> "Scroll down in the list and find item 50"
> "Enter 'hello@example.com' in the email field"
### Alternative: Use the client library directly
```dart
import 'package:turbo_bridge_client/turbo_bridge_client.dart';
final client = TurboBridgeClient(host: '127.0.0.1', port: 8888);
final screenshot = await client.screenshot();
await client.tapByText('Submit');
final results = await client.find(text: 'Login');
await client.swipe(200, 600, 200, 200); // Swipe up
await client.enterText('hello@example.com');
```
## Performance
All operations are designed for <50ms round-trip latency:
| Operation | Target (p95) |
|-----------|-------------|
| Screenshot | <50ms |
| Widget tree | <40ms |
| Tap gesture | <30ms |
| Swipe | <30ms |
| Scroll | <30ms |
| Find widget | <20ms |
| Enter text | <30ms |
| App info | <10ms |
Historical benchmark trends with p50, p95, p99, and target lines are published at https://mark-nicepants.github.io/flutter_turbo_bridge/benchmarks/.
## MCP Timing Metadata
Turbo MCP tool and resource responses include a `_meta` object with UTC wall-clock stamps:
- `startedAtUtc` — when the MCP tool or resource began handling the request
- `completedAtUtc` — when the MCP tool or resource finished handling the request
- operation-specific timing fields when available, such as `captureTimeMs`, `searchTimeMs`, `executionTimeMs`, and `roundTripMs`
For 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.
## Development
This is a Dart/Flutter monorepo managed with [Melos](https://melos.invertase.dev/).
```bash
# Install melos
dart pub global activate melos
# Bootstrap all packages
melos bootstrap
# Run analysis
melos run analyze
# Run tests
melos run test:dart # Pure Dart packages
melos run test:flutter # Flutter package
# Format
melos run format
```
## CI/CD
- **CI** runs on every push/PR: shared package checks plus benchmark on macOS
- **Publish** triggered on `v*` tags: reruns the shared package checks, then publishes all packages to pub.dev via pub.dev trusted publishing (GitHub OIDC)
- **First release** of each package must still be published manually on pub.dev before GitHub Actions can publish later versions
- **Secrets** are not required for the GitHub Actions flow once automated publishing is enabled on each package's pub.dev admin page
## License
MIT