@bdayadev/flutter-ultra-mcp 0.0.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +23 -0
- package/.claude-plugin/plugin.json +14 -14
- package/.mcp.json +67 -67
- package/CODE_OF_CONDUCT.md +83 -83
- package/CONTRIBUTING.md +108 -108
- package/LICENSE +201 -201
- package/README.md +77 -77
- package/SECURITY.md +19 -19
- package/dart/ultra_flutter/CHANGELOG.md +34 -34
- package/dart/ultra_flutter/EXTENSIONS.md +61 -61
- package/dart/ultra_flutter/README.md +109 -109
- package/dart/ultra_flutter/pubspec.yaml +37 -37
- package/dart/ultra_flutter_devtools/README.md +7 -7
- package/dart/ultra_flutter_devtools/pubspec.yaml +27 -27
- package/docs/UPSTREAM-PATROL-PRS.md +5 -5
- package/docs/UPSTREAM-SENTRY-PR.md +62 -62
- package/docs/discovery-empirics.md +435 -435
- package/examples/counter-app/README.md +24 -24
- package/examples/counter-app/pubspec.yaml +23 -23
- package/examples/oidc-app/README.md +48 -48
- package/examples/oidc-app/pubspec.yaml +24 -24
- package/package.json +82 -82
- package/packages/flutter-ultra-browser/README.md +29 -29
- package/packages/flutter-ultra-browser/package.json +39 -39
- package/packages/flutter-ultra-build/README.md +60 -60
- package/packages/flutter-ultra-build/package.json +38 -38
- package/packages/flutter-ultra-devtools/README.md +7 -7
- package/packages/flutter-ultra-devtools/package.json +36 -36
- package/packages/flutter-ultra-gesture/README.md +51 -51
- package/packages/flutter-ultra-gesture/package.json +58 -58
- package/packages/flutter-ultra-native-desktop/README.md +131 -131
- package/packages/flutter-ultra-native-desktop/package.json +81 -81
- package/packages/flutter-ultra-native-mobile/README.md +103 -103
- package/packages/flutter-ultra-native-mobile/package.json +72 -72
- package/packages/flutter-ultra-patrol/README.md +40 -40
- package/packages/flutter-ultra-patrol/package.json +38 -38
- package/packages/flutter-ultra-runtime/README.md +63 -63
- package/packages/flutter-ultra-runtime/package.json +69 -69
- package/shared/contracts/package.json +31 -31
- package/shared/device-router/README.md +51 -51
- package/shared/device-router/package.json +62 -62
- package/shared/keyring/README.md +7 -7
- package/shared/keyring/package.json +24 -24
- package/shared/mcp-runtime/README.md +116 -116
- package/shared/mcp-runtime/package.json +58 -58
- package/shared/state-store/README.md +66 -66
- package/shared/state-store/package.json +60 -60
- package/shared/vm-service-client/README.md +135 -135
- package/shared/vm-service-client/package.json +62 -62
- package/skills/_internal-on-tool-failure/SKILL.md +13 -13
- package/skills/_internal-session-bootstrap/SKILL.md +18 -18
- package/skills/debug/SKILL.md +20 -20
- package/skills/devtools/SKILL.md +21 -21
- package/skills/drive/SKILL.md +20 -20
- package/skills/scaffold/SKILL.md +21 -21
- package/skills/setup/SKILL.md +26 -26
- package/skills/test/SKILL.md +19 -19
- package/skills/tour/SKILL.md +22 -22
|
@@ -1,60 +1,60 @@
|
|
|
1
|
-
# @flutter-ultra/flutter-ultra-build
|
|
2
|
-
|
|
3
|
-
MCP server for Flutter **build-time** tasks: pubspec, codegen, analyze, format, tests, builds, signing, l10n, assets, web validators.
|
|
4
|
-
|
|
5
|
-
Part of the [flutter-ultra-mcp](https://github.com/Bdaya-Dev/flutter-ultra-mcp) plugin (8 specialized MCP servers for Flutter automation). This package focuses on _build-time_ surface area — it never connects to a running app. For runtime control (hot reload, widget inspection) see `@flutter-ultra/flutter-ultra-runtime`.
|
|
6
|
-
|
|
7
|
-
## Tool groups (~50 tools)
|
|
8
|
-
|
|
9
|
-
| Group | Representative tools |
|
|
10
|
-
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
11
|
-
| Project meta | `list_projects`, `project_info`, `list_flavors`, `list_dart_defines` |
|
|
12
|
-
| Analysis & format | `analyze`, `format`, `fix`, `fix_preview`, `flutter_doctor`, `flutter_clean`, `pub_cache_repair` |
|
|
13
|
-
| Pubspec & deps | `pub_get`, `pub_add`, `pub_remove`, `pub_upgrade`, `pub_outdated`, `pub_deps`, `pub_dev_search`, `pubspec_overrides_*`, `start_pub_upgrade_major` (+ poll / get / cancel) |
|
|
14
|
-
| Codegen | `start_build_runner_build` (+ poll / get / cancel), `start_build_runner_watch` (+ poll / stop), `flutter_gen_l10n` |
|
|
15
|
-
| Tests | `start_run_unit_tests`, `start_run_widget_tests`, `start_run_integration_tests`, `start_run_golden_tests`, `start_update_goldens` (each + poll / get / cancel), `test_filter` |
|
|
16
|
-
| Builds | `start_build_apk` / `start_build_appbundle` / `start_build_ipa` (Mac) / `start_build_web` / `start_build_windows` (Win) / `start_build_macos` (Mac) / `start_build_linux` (Linux), each with `poll_build_<plat>_job` / `get_*_result` / `cancel_*_job` |
|
|
17
|
-
| Mobile signing | `verify_android_signing`, `verify_ios_signing` (Mac-only), `set_bundle_id` (atomic Android+iOS update) |
|
|
18
|
-
| l10n / ARB | `list_missing_translations`, `arb_diff`, `arb_add_key`, `arb_remove_key` |
|
|
19
|
-
| Assets | `add_asset`, `validate_assets`, `list_orphan_assets` |
|
|
20
|
-
| Web pre-flight | `validate_web_redirect`, `validate_canvaskit_vs_html_consistency`, `flush_service_worker` |
|
|
21
|
-
|
|
22
|
-
All long-running tools (builds, codegen, tests, pub-upgrade-major) follow the **MARATHON split-tool pattern** documented in the plan §17.5: each exposes a `start_<x>` / `poll_<x>_job` / `get_<x>_result` / `cancel_<x>_job` quartet so no sync MCP call ever exceeds 55 s. Job state persists at `${CLAUDE_PLUGIN_DATA}/state/jobs/<jobId>.json` and survives MCP server restarts.
|
|
23
|
-
|
|
24
|
-
## Cross-cutting behavior
|
|
25
|
-
|
|
26
|
-
- **Watchdog**: every tool wrapped in `withWatchdog` with a per-tool ceiling. Host-side cancellation propagates to child processes via `SIGTERM` → 2 s grace → `SIGKILL`.
|
|
27
|
-
- **Logging**: stderr only, JSON-lines, respects `FLUTTER_ULTRA_LOG_LEVEL`. Stdout reserved for JSON-RPC framing.
|
|
28
|
-
- **Keep-alive**: 30 s `notifications/message` (debug) defeats the Bun-idle-SIGKILL bug ([claude-code #58004](https://github.com/anthropics/claude-code/issues/58004)).
|
|
29
|
-
- **Per-tool timeout overrides**: `FLUTTER_ULTRA_TOOL_TIMEOUT_<TOOL_NAME>=<ms>` env var raises the ceiling for power users.
|
|
30
|
-
|
|
31
|
-
## CLI dependencies
|
|
32
|
-
|
|
33
|
-
Tools shell out to:
|
|
34
|
-
|
|
35
|
-
- `dart` (required) — analysis, format, fix, pub, build_runner
|
|
36
|
-
- `flutter` (required for any Flutter-specific tool) — pub, gen-l10n, test, build
|
|
37
|
-
- `keytool` (optional, for `verify_android_signing`)
|
|
38
|
-
- `xcodebuild` (Mac-only, for `verify_ios_signing`)
|
|
39
|
-
|
|
40
|
-
Resolution order: env override (`FLUTTER_ULTRA_DART_BIN`, `FLUTTER_ULTRA_FLUTTER_BIN`) → PATH lookup. Missing CLIs raise `FlutterCliMissingError` with install hints.
|
|
41
|
-
|
|
42
|
-
## Running standalone
|
|
43
|
-
|
|
44
|
-
```jsonc
|
|
45
|
-
// .claude/mcp.json
|
|
46
|
-
{
|
|
47
|
-
"mcpServers": {
|
|
48
|
-
"flutter-ultra-build": {
|
|
49
|
-
"command": "node",
|
|
50
|
-
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/flutter-ultra-build/dist/index.js"],
|
|
51
|
-
},
|
|
52
|
-
},
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## References
|
|
57
|
-
|
|
58
|
-
- Plan §5.1 — tool catalogue (build server)
|
|
59
|
-
- Plan §16 — naming, schema, output conventions (binding for all servers)
|
|
60
|
-
- Plan §17 — timeout resilience model + split-tool pattern (binding)
|
|
1
|
+
# @flutter-ultra/flutter-ultra-build
|
|
2
|
+
|
|
3
|
+
MCP server for Flutter **build-time** tasks: pubspec, codegen, analyze, format, tests, builds, signing, l10n, assets, web validators.
|
|
4
|
+
|
|
5
|
+
Part of the [flutter-ultra-mcp](https://github.com/Bdaya-Dev/flutter-ultra-mcp) plugin (8 specialized MCP servers for Flutter automation). This package focuses on _build-time_ surface area — it never connects to a running app. For runtime control (hot reload, widget inspection) see `@flutter-ultra/flutter-ultra-runtime`.
|
|
6
|
+
|
|
7
|
+
## Tool groups (~50 tools)
|
|
8
|
+
|
|
9
|
+
| Group | Representative tools |
|
|
10
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
11
|
+
| Project meta | `list_projects`, `project_info`, `list_flavors`, `list_dart_defines` |
|
|
12
|
+
| Analysis & format | `analyze`, `format`, `fix`, `fix_preview`, `flutter_doctor`, `flutter_clean`, `pub_cache_repair` |
|
|
13
|
+
| Pubspec & deps | `pub_get`, `pub_add`, `pub_remove`, `pub_upgrade`, `pub_outdated`, `pub_deps`, `pub_dev_search`, `pubspec_overrides_*`, `start_pub_upgrade_major` (+ poll / get / cancel) |
|
|
14
|
+
| Codegen | `start_build_runner_build` (+ poll / get / cancel), `start_build_runner_watch` (+ poll / stop), `flutter_gen_l10n` |
|
|
15
|
+
| Tests | `start_run_unit_tests`, `start_run_widget_tests`, `start_run_integration_tests`, `start_run_golden_tests`, `start_update_goldens` (each + poll / get / cancel), `test_filter` |
|
|
16
|
+
| Builds | `start_build_apk` / `start_build_appbundle` / `start_build_ipa` (Mac) / `start_build_web` / `start_build_windows` (Win) / `start_build_macos` (Mac) / `start_build_linux` (Linux), each with `poll_build_<plat>_job` / `get_*_result` / `cancel_*_job` |
|
|
17
|
+
| Mobile signing | `verify_android_signing`, `verify_ios_signing` (Mac-only), `set_bundle_id` (atomic Android+iOS update) |
|
|
18
|
+
| l10n / ARB | `list_missing_translations`, `arb_diff`, `arb_add_key`, `arb_remove_key` |
|
|
19
|
+
| Assets | `add_asset`, `validate_assets`, `list_orphan_assets` |
|
|
20
|
+
| Web pre-flight | `validate_web_redirect`, `validate_canvaskit_vs_html_consistency`, `flush_service_worker` |
|
|
21
|
+
|
|
22
|
+
All long-running tools (builds, codegen, tests, pub-upgrade-major) follow the **MARATHON split-tool pattern** documented in the plan §17.5: each exposes a `start_<x>` / `poll_<x>_job` / `get_<x>_result` / `cancel_<x>_job` quartet so no sync MCP call ever exceeds 55 s. Job state persists at `${CLAUDE_PLUGIN_DATA}/state/jobs/<jobId>.json` and survives MCP server restarts.
|
|
23
|
+
|
|
24
|
+
## Cross-cutting behavior
|
|
25
|
+
|
|
26
|
+
- **Watchdog**: every tool wrapped in `withWatchdog` with a per-tool ceiling. Host-side cancellation propagates to child processes via `SIGTERM` → 2 s grace → `SIGKILL`.
|
|
27
|
+
- **Logging**: stderr only, JSON-lines, respects `FLUTTER_ULTRA_LOG_LEVEL`. Stdout reserved for JSON-RPC framing.
|
|
28
|
+
- **Keep-alive**: 30 s `notifications/message` (debug) defeats the Bun-idle-SIGKILL bug ([claude-code #58004](https://github.com/anthropics/claude-code/issues/58004)).
|
|
29
|
+
- **Per-tool timeout overrides**: `FLUTTER_ULTRA_TOOL_TIMEOUT_<TOOL_NAME>=<ms>` env var raises the ceiling for power users.
|
|
30
|
+
|
|
31
|
+
## CLI dependencies
|
|
32
|
+
|
|
33
|
+
Tools shell out to:
|
|
34
|
+
|
|
35
|
+
- `dart` (required) — analysis, format, fix, pub, build_runner
|
|
36
|
+
- `flutter` (required for any Flutter-specific tool) — pub, gen-l10n, test, build
|
|
37
|
+
- `keytool` (optional, for `verify_android_signing`)
|
|
38
|
+
- `xcodebuild` (Mac-only, for `verify_ios_signing`)
|
|
39
|
+
|
|
40
|
+
Resolution order: env override (`FLUTTER_ULTRA_DART_BIN`, `FLUTTER_ULTRA_FLUTTER_BIN`) → PATH lookup. Missing CLIs raise `FlutterCliMissingError` with install hints.
|
|
41
|
+
|
|
42
|
+
## Running standalone
|
|
43
|
+
|
|
44
|
+
```jsonc
|
|
45
|
+
// .claude/mcp.json
|
|
46
|
+
{
|
|
47
|
+
"mcpServers": {
|
|
48
|
+
"flutter-ultra-build": {
|
|
49
|
+
"command": "node",
|
|
50
|
+
"args": ["${CLAUDE_PLUGIN_ROOT}/servers/flutter-ultra-build/dist/index.js"],
|
|
51
|
+
},
|
|
52
|
+
},
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## References
|
|
57
|
+
|
|
58
|
+
- Plan §5.1 — tool catalogue (build server)
|
|
59
|
+
- Plan §16 — naming, schema, output conventions (binding for all servers)
|
|
60
|
+
- Plan §17 — timeout resilience model + split-tool pattern (binding)
|
|
@@ -1,38 +1,38 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@flutter-ultra/flutter-ultra-build",
|
|
3
|
-
"version": "0.0.0",
|
|
4
|
-
"private": true,
|
|
5
|
-
"description": "MCP server for Flutter build-time tasks: pubspec, codegen, analyze, format, tests, builds, l10n, assets.",
|
|
6
|
-
"license": "Apache-2.0",
|
|
7
|
-
"type": "module",
|
|
8
|
-
"main": "dist/index.js",
|
|
9
|
-
"types": "dist/index.d.ts",
|
|
10
|
-
"bin": {
|
|
11
|
-
"flutter-ultra-build": "dist/index.js"
|
|
12
|
-
},
|
|
13
|
-
"files": [
|
|
14
|
-
"dist",
|
|
15
|
-
"README.md"
|
|
16
|
-
],
|
|
17
|
-
"scripts": {
|
|
18
|
-
"build": "tsc -b",
|
|
19
|
-
"lint": "eslint src",
|
|
20
|
-
"test": "vitest run",
|
|
21
|
-
"typecheck": "tsc -b --noEmit",
|
|
22
|
-
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
23
|
-
},
|
|
24
|
-
"dependencies": {
|
|
25
|
-
"@modelcontextprotocol/sdk": "^1.18.0",
|
|
26
|
-
"execa": "^9.5.1",
|
|
27
|
-
"fs-extra": "^11.2.0",
|
|
28
|
-
"nanoid": "^5.0.9",
|
|
29
|
-
"proper-lockfile": "^4.1.2",
|
|
30
|
-
"yaml": "^2.6.1",
|
|
31
|
-
"zod": "^3.25.76"
|
|
32
|
-
},
|
|
33
|
-
"devDependencies": {
|
|
34
|
-
"@types/fs-extra": "^11.0.4",
|
|
35
|
-
"@types/proper-lockfile": "^4.1.4",
|
|
36
|
-
"vitest": "^2.1.9"
|
|
37
|
-
}
|
|
38
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@flutter-ultra/flutter-ultra-build",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"private": true,
|
|
5
|
+
"description": "MCP server for Flutter build-time tasks: pubspec, codegen, analyze, format, tests, builds, l10n, assets.",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"main": "dist/index.js",
|
|
9
|
+
"types": "dist/index.d.ts",
|
|
10
|
+
"bin": {
|
|
11
|
+
"flutter-ultra-build": "dist/index.js"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"dist",
|
|
15
|
+
"README.md"
|
|
16
|
+
],
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc -b",
|
|
19
|
+
"lint": "eslint src",
|
|
20
|
+
"test": "vitest run",
|
|
21
|
+
"typecheck": "tsc -b --noEmit",
|
|
22
|
+
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
23
|
+
},
|
|
24
|
+
"dependencies": {
|
|
25
|
+
"@modelcontextprotocol/sdk": "^1.18.0",
|
|
26
|
+
"execa": "^9.5.1",
|
|
27
|
+
"fs-extra": "^11.2.0",
|
|
28
|
+
"nanoid": "^5.0.9",
|
|
29
|
+
"proper-lockfile": "^4.1.2",
|
|
30
|
+
"yaml": "^2.6.1",
|
|
31
|
+
"zod": "^3.25.76"
|
|
32
|
+
},
|
|
33
|
+
"devDependencies": {
|
|
34
|
+
"@types/fs-extra": "^11.0.4",
|
|
35
|
+
"@types/proper-lockfile": "^4.1.4",
|
|
36
|
+
"vitest": "^2.1.9"
|
|
37
|
+
}
|
|
38
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
# @flutter-ultra/flutter-ultra-devtools
|
|
2
|
-
|
|
3
|
-
MCP server backing the **DevTools panel**: live MCP activity, attached sessions, recent tool calls, errors, screenshot grid. Tails `state/tool-events.jsonl` and pushes via WebSocket to the panel iframe.
|
|
4
|
-
|
|
5
|
-
**Status:** scaffold stub. Implementation owner: **wave-2 devtools worker** (see plan §12).
|
|
6
|
-
|
|
7
|
-
Pairs with the `ultra_flutter_devtools` Dart package (the DevTools extension UI) — see `packages/ultra_flutter_devtools/`.
|
|
1
|
+
# @flutter-ultra/flutter-ultra-devtools
|
|
2
|
+
|
|
3
|
+
MCP server backing the **DevTools panel**: live MCP activity, attached sessions, recent tool calls, errors, screenshot grid. Tails `state/tool-events.jsonl` and pushes via WebSocket to the panel iframe.
|
|
4
|
+
|
|
5
|
+
**Status:** scaffold stub. Implementation owner: **wave-2 devtools worker** (see plan §12).
|
|
6
|
+
|
|
7
|
+
Pairs with the `ultra_flutter_devtools` Dart package (the DevTools extension UI) — see `packages/ultra_flutter_devtools/`.
|
|
@@ -1,36 +1,36 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@flutter-ultra/flutter-ultra-devtools",
|
|
3
|
-
"version": "0.0.0",
|
|
4
|
-
"private": true,
|
|
5
|
-
"description": "MCP server backing the Flutter DevTools panel: live MCP activity, sessions, tool-call timeline.",
|
|
6
|
-
"license": "Apache-2.0",
|
|
7
|
-
"type": "module",
|
|
8
|
-
"main": "dist/index.js",
|
|
9
|
-
"types": "dist/index.d.ts",
|
|
10
|
-
"bin": {
|
|
11
|
-
"flutter-ultra-devtools": "dist/index.js"
|
|
12
|
-
},
|
|
13
|
-
"files": [
|
|
14
|
-
"dist",
|
|
15
|
-
"README.md"
|
|
16
|
-
],
|
|
17
|
-
"scripts": {
|
|
18
|
-
"build": "tsc -b",
|
|
19
|
-
"lint": "eslint src",
|
|
20
|
-
"test": "vitest run",
|
|
21
|
-
"typecheck": "tsc -b --noEmit",
|
|
22
|
-
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
23
|
-
},
|
|
24
|
-
"dependencies": {
|
|
25
|
-
"@flutter-ultra/mcp-runtime": "*",
|
|
26
|
-
"@flutter-ultra/state-store": "*",
|
|
27
|
-
"ws": "^8.18.0",
|
|
28
|
-
"zod": "^3.23.8"
|
|
29
|
-
},
|
|
30
|
-
"devDependencies": {
|
|
31
|
-
"@types/ws": "^8.5.13",
|
|
32
|
-
"rimraf": "^6.0.0",
|
|
33
|
-
"typescript": "^5.6.0",
|
|
34
|
-
"vitest": "^3.2.4"
|
|
35
|
-
}
|
|
36
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@flutter-ultra/flutter-ultra-devtools",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"private": true,
|
|
5
|
+
"description": "MCP server backing the Flutter DevTools panel: live MCP activity, sessions, tool-call timeline.",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"main": "dist/index.js",
|
|
9
|
+
"types": "dist/index.d.ts",
|
|
10
|
+
"bin": {
|
|
11
|
+
"flutter-ultra-devtools": "dist/index.js"
|
|
12
|
+
},
|
|
13
|
+
"files": [
|
|
14
|
+
"dist",
|
|
15
|
+
"README.md"
|
|
16
|
+
],
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc -b",
|
|
19
|
+
"lint": "eslint src",
|
|
20
|
+
"test": "vitest run",
|
|
21
|
+
"typecheck": "tsc -b --noEmit",
|
|
22
|
+
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
23
|
+
},
|
|
24
|
+
"dependencies": {
|
|
25
|
+
"@flutter-ultra/mcp-runtime": "*",
|
|
26
|
+
"@flutter-ultra/state-store": "*",
|
|
27
|
+
"ws": "^8.18.0",
|
|
28
|
+
"zod": "^3.23.8"
|
|
29
|
+
},
|
|
30
|
+
"devDependencies": {
|
|
31
|
+
"@types/ws": "^8.5.13",
|
|
32
|
+
"rimraf": "^6.0.0",
|
|
33
|
+
"typescript": "^5.6.0",
|
|
34
|
+
"vitest": "^3.2.4"
|
|
35
|
+
}
|
|
36
|
+
}
|
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
# @flutter-ultra/flutter-ultra-gesture
|
|
2
|
-
|
|
3
|
-
MCP server for **gesture dispatch** inside a running Flutter app via the in-app `ultra_flutter` mixin. Tools call `ext.flutter.ultra.*` service extensions registered by `UltraFlutterBinding` in the target app, so the app must include `package:ultra_flutter` and register the binding for any tool here to work.
|
|
4
|
-
|
|
5
|
-
## Prerequisites
|
|
6
|
-
|
|
7
|
-
- A Flutter app running in `--debug` mode with `package:ultra_flutter` ≥ 0.0.1 registered as a binding mixin.
|
|
8
|
-
- The runtime server (`@flutter-ultra/flutter-ultra-runtime`) attached to the session — it owns session discovery and publishes `state/sessions.json` + `state/session-<id>.json`. This server is a read-only consumer of that state.
|
|
9
|
-
|
|
10
|
-
## Tool catalogue (17)
|
|
11
|
-
|
|
12
|
-
| Tool | Maps to |
|
|
13
|
-
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
-
| `interactive_elements` | `ext.flutter.ultra.interactiveElements` (rev-23 tightened: no truncation by default, optional pagination, sortBy, `withinSubtree` + `kinds` + `hasKey` filters) |
|
|
15
|
-
| `tap` / `double_tap` / `long_press` | `ext.flutter.ultra.tap` / `.doubleTap` / `.longPress` |
|
|
16
|
-
| `enter_text` / `clear_text` | `ext.flutter.ultra.enterText` / `.clearText` |
|
|
17
|
-
| `swipe` / `pinch_zoom` | `ext.flutter.ultra.swipe` / `.pinchZoom` |
|
|
18
|
-
| `scroll_to` / `scroll_until_visible` | `ext.flutter.ultra.scrollTo` (server-side polling for `scroll_until_visible`) |
|
|
19
|
-
| `take_screenshots` | `ext.flutter.ultra.takeScreenshots` |
|
|
20
|
-
| `take_responsive_screenshots` | Delegates: web → `flutter-ultra-browser` (CDP `setDeviceMetricsOverride`); native → single-viewport fallback w/ `nativeMultiViewportUnavailable` warning |
|
|
21
|
-
| `start_screencast` / `stop_screencast` | `ext.flutter.ultra.startScreencast` / `.stopScreencast` |
|
|
22
|
-
| `call_custom_extension` | invokes any user-registered `registerUltraExtension(name, ...)` |
|
|
23
|
-
| `list_custom_extensions` | `ext.flutter.ultra.listExtensions` |
|
|
24
|
-
| `wait_for` | server-side polling: `interactiveElements` every 200ms with finder match |
|
|
25
|
-
|
|
26
|
-
## Finder spec
|
|
27
|
-
|
|
28
|
-
All matcher-accepting tools share `FinderSpec` (Zod discriminated union):
|
|
29
|
-
|
|
30
|
-
```ts
|
|
31
|
-
{ kind: 'key', value: string }
|
|
32
|
-
{ kind: 'text', value: string, matchType?: 'exact' | 'contains' | 'regex' } // default 'exact'
|
|
33
|
-
{ kind: 'type', value: string }
|
|
34
|
-
{ kind: 'coords', x: number, y: number }
|
|
35
|
-
{ kind: 'focused' }
|
|
36
|
-
{ kind: 'tooltip', value: string } // server-side filter via interactiveElements
|
|
37
|
-
{ kind: 'semantics', label: string, matchType?: 'exact' | 'contains' } // server-side filter
|
|
38
|
-
{ kind: 'descendant', of: FinderSpec, matching: FinderSpec } // server-side filter
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Server-side filters (`tooltip`/`semantics`/`descendant`) materialise the element list via `interactive_elements`, resolve a coordinate, then issue `ext.flutter.ultra.tap` with `{x, y}`. Native finders (`key`/`text`/`type`/`coords`/`focused`) call the extension directly.
|
|
42
|
-
|
|
43
|
-
## Configuration
|
|
44
|
-
|
|
45
|
-
Reads `state/sessions.json` and `state/session-<id>.json` written by `flutter-ultra-runtime`. Override the state directory with `FLUTTER_ULTRA_STATE_DIR` (defaults to `${FLUTTER_ULTRA_DATA:-~/.flutter-ultra-mcp}/state`).
|
|
46
|
-
|
|
47
|
-
DDS client name is `flutter-ultra/gesture/<pid>` so this server identifies as a distinct DDS client from the runtime server (per plan §7.2).
|
|
48
|
-
|
|
49
|
-
## Coordination
|
|
50
|
-
|
|
51
|
-
This server **never writes** to `sessions.json`. Session lifecycle is owned by `flutter-ultra-runtime`. We open our own VM-service WebSocket per session and cache one `VmServiceClient` per active session id. The cache is dropped when the runtime server marks the session `terminated`.
|
|
1
|
+
# @flutter-ultra/flutter-ultra-gesture
|
|
2
|
+
|
|
3
|
+
MCP server for **gesture dispatch** inside a running Flutter app via the in-app `ultra_flutter` mixin. Tools call `ext.flutter.ultra.*` service extensions registered by `UltraFlutterBinding` in the target app, so the app must include `package:ultra_flutter` and register the binding for any tool here to work.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- A Flutter app running in `--debug` mode with `package:ultra_flutter` ≥ 0.0.1 registered as a binding mixin.
|
|
8
|
+
- The runtime server (`@flutter-ultra/flutter-ultra-runtime`) attached to the session — it owns session discovery and publishes `state/sessions.json` + `state/session-<id>.json`. This server is a read-only consumer of that state.
|
|
9
|
+
|
|
10
|
+
## Tool catalogue (17)
|
|
11
|
+
|
|
12
|
+
| Tool | Maps to |
|
|
13
|
+
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `interactive_elements` | `ext.flutter.ultra.interactiveElements` (rev-23 tightened: no truncation by default, optional pagination, sortBy, `withinSubtree` + `kinds` + `hasKey` filters) |
|
|
15
|
+
| `tap` / `double_tap` / `long_press` | `ext.flutter.ultra.tap` / `.doubleTap` / `.longPress` |
|
|
16
|
+
| `enter_text` / `clear_text` | `ext.flutter.ultra.enterText` / `.clearText` |
|
|
17
|
+
| `swipe` / `pinch_zoom` | `ext.flutter.ultra.swipe` / `.pinchZoom` |
|
|
18
|
+
| `scroll_to` / `scroll_until_visible` | `ext.flutter.ultra.scrollTo` (server-side polling for `scroll_until_visible`) |
|
|
19
|
+
| `take_screenshots` | `ext.flutter.ultra.takeScreenshots` |
|
|
20
|
+
| `take_responsive_screenshots` | Delegates: web → `flutter-ultra-browser` (CDP `setDeviceMetricsOverride`); native → single-viewport fallback w/ `nativeMultiViewportUnavailable` warning |
|
|
21
|
+
| `start_screencast` / `stop_screencast` | `ext.flutter.ultra.startScreencast` / `.stopScreencast` |
|
|
22
|
+
| `call_custom_extension` | invokes any user-registered `registerUltraExtension(name, ...)` |
|
|
23
|
+
| `list_custom_extensions` | `ext.flutter.ultra.listExtensions` |
|
|
24
|
+
| `wait_for` | server-side polling: `interactiveElements` every 200ms with finder match |
|
|
25
|
+
|
|
26
|
+
## Finder spec
|
|
27
|
+
|
|
28
|
+
All matcher-accepting tools share `FinderSpec` (Zod discriminated union):
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
{ kind: 'key', value: string }
|
|
32
|
+
{ kind: 'text', value: string, matchType?: 'exact' | 'contains' | 'regex' } // default 'exact'
|
|
33
|
+
{ kind: 'type', value: string }
|
|
34
|
+
{ kind: 'coords', x: number, y: number }
|
|
35
|
+
{ kind: 'focused' }
|
|
36
|
+
{ kind: 'tooltip', value: string } // server-side filter via interactiveElements
|
|
37
|
+
{ kind: 'semantics', label: string, matchType?: 'exact' | 'contains' } // server-side filter
|
|
38
|
+
{ kind: 'descendant', of: FinderSpec, matching: FinderSpec } // server-side filter
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Server-side filters (`tooltip`/`semantics`/`descendant`) materialise the element list via `interactive_elements`, resolve a coordinate, then issue `ext.flutter.ultra.tap` with `{x, y}`. Native finders (`key`/`text`/`type`/`coords`/`focused`) call the extension directly.
|
|
42
|
+
|
|
43
|
+
## Configuration
|
|
44
|
+
|
|
45
|
+
Reads `state/sessions.json` and `state/session-<id>.json` written by `flutter-ultra-runtime`. Override the state directory with `FLUTTER_ULTRA_STATE_DIR` (defaults to `${FLUTTER_ULTRA_DATA:-~/.flutter-ultra-mcp}/state`).
|
|
46
|
+
|
|
47
|
+
DDS client name is `flutter-ultra/gesture/<pid>` so this server identifies as a distinct DDS client from the runtime server (per plan §7.2).
|
|
48
|
+
|
|
49
|
+
## Coordination
|
|
50
|
+
|
|
51
|
+
This server **never writes** to `sessions.json`. Session lifecycle is owned by `flutter-ultra-runtime`. We open our own VM-service WebSocket per session and cache one `VmServiceClient` per active session id. The cache is dropped when the runtime server marks the session `terminated`.
|
|
@@ -1,58 +1,58 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@flutter-ultra/flutter-ultra-gesture",
|
|
3
|
-
"version": "0.0.1",
|
|
4
|
-
"private":
|
|
5
|
-
"description": "MCP server for in-app gesture dispatch via the ultra_flutter mixin: tap, text entry, scroll, screenshot, screencast.",
|
|
6
|
-
"license": "Apache-2.0",
|
|
7
|
-
"homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-gesture",
|
|
8
|
-
"repository": {
|
|
9
|
-
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
|
|
11
|
-
"directory": "packages/flutter-ultra-gesture"
|
|
12
|
-
},
|
|
13
|
-
"bugs": {
|
|
14
|
-
"url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
|
|
15
|
-
},
|
|
16
|
-
"keywords": [
|
|
17
|
-
"flutter",
|
|
18
|
-
"mcp",
|
|
19
|
-
"ultra_flutter",
|
|
20
|
-
"gesture",
|
|
21
|
-
"tap",
|
|
22
|
-
"screencast"
|
|
23
|
-
],
|
|
24
|
-
"type": "module",
|
|
25
|
-
"main": "dist/index.js",
|
|
26
|
-
"types": "dist/index.d.ts",
|
|
27
|
-
"bin": {
|
|
28
|
-
"flutter-ultra-gesture": "dist/bin.js"
|
|
29
|
-
},
|
|
30
|
-
"files": [
|
|
31
|
-
"dist",
|
|
32
|
-
"README.md"
|
|
33
|
-
],
|
|
34
|
-
"scripts": {
|
|
35
|
-
"build": "tsc -b",
|
|
36
|
-
"lint": "eslint src",
|
|
37
|
-
"test": "vitest run",
|
|
38
|
-
"typecheck": "tsc -b --noEmit",
|
|
39
|
-
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
40
|
-
},
|
|
41
|
-
"dependencies": {
|
|
42
|
-
"@flutter-ultra/vm-service-client": "^0.0.1",
|
|
43
|
-
"@modelcontextprotocol/sdk": "^1.0.4",
|
|
44
|
-
"zod": "^3.23.8"
|
|
45
|
-
},
|
|
46
|
-
"devDependencies": {
|
|
47
|
-
"@types/node": "^22.0.0",
|
|
48
|
-
"rimraf": "^6.0.0",
|
|
49
|
-
"typescript": "^5.6.0",
|
|
50
|
-
"vitest": "^2.1.0"
|
|
51
|
-
},
|
|
52
|
-
"engines": {
|
|
53
|
-
"node": ">=20"
|
|
54
|
-
},
|
|
55
|
-
"publishConfig": {
|
|
56
|
-
"access": "public"
|
|
57
|
-
}
|
|
58
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@flutter-ultra/flutter-ultra-gesture",
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"private": true,
|
|
5
|
+
"description": "MCP server for in-app gesture dispatch via the ultra_flutter mixin: tap, text entry, scroll, screenshot, screencast.",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-gesture",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
|
|
11
|
+
"directory": "packages/flutter-ultra-gesture"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"flutter",
|
|
18
|
+
"mcp",
|
|
19
|
+
"ultra_flutter",
|
|
20
|
+
"gesture",
|
|
21
|
+
"tap",
|
|
22
|
+
"screencast"
|
|
23
|
+
],
|
|
24
|
+
"type": "module",
|
|
25
|
+
"main": "dist/index.js",
|
|
26
|
+
"types": "dist/index.d.ts",
|
|
27
|
+
"bin": {
|
|
28
|
+
"flutter-ultra-gesture": "dist/bin.js"
|
|
29
|
+
},
|
|
30
|
+
"files": [
|
|
31
|
+
"dist",
|
|
32
|
+
"README.md"
|
|
33
|
+
],
|
|
34
|
+
"scripts": {
|
|
35
|
+
"build": "tsc -b",
|
|
36
|
+
"lint": "eslint src",
|
|
37
|
+
"test": "vitest run",
|
|
38
|
+
"typecheck": "tsc -b --noEmit",
|
|
39
|
+
"clean": "rimraf dist .turbo *.tsbuildinfo"
|
|
40
|
+
},
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@flutter-ultra/vm-service-client": "^0.0.1",
|
|
43
|
+
"@modelcontextprotocol/sdk": "^1.0.4",
|
|
44
|
+
"zod": "^3.23.8"
|
|
45
|
+
},
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@types/node": "^22.0.0",
|
|
48
|
+
"rimraf": "^6.0.0",
|
|
49
|
+
"typescript": "^5.6.0",
|
|
50
|
+
"vitest": "^2.1.0"
|
|
51
|
+
},
|
|
52
|
+
"engines": {
|
|
53
|
+
"node": ">=20"
|
|
54
|
+
},
|
|
55
|
+
"publishConfig": {
|
|
56
|
+
"access": "public"
|
|
57
|
+
}
|
|
58
|
+
}
|