@bdayadev/flutter-ultra-mcp 0.0.0

package/packages/flutter-ultra-native-mobile/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-native-mobile",
+  "version": "0.0.1",
+  "private": false,
+  "description": "MCP server for native mobile overlays: Android UIAutomator via adb, iOS XCUITest via xcrun + go-ios. Solves Chrome Custom Tabs / SafariViewController OAuth via Playwright + deep-link intent dispatch.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-native-mobile",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "packages/flutter-ultra-native-mobile"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "flutter-ultra",
+    "android",
+    "ios",
+    "adb",
+    "uiautomator",
+    "xcuitest",
+    "go-ios",
+    "oauth",
+    "chrome-custom-tabs"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-native-mobile": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@flutter-ultra/mcp-runtime": "^0.0.1",
+    "@flutter-ultra/state-store": "^0.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-xml-parser": "^4.5.0",
+    "playwright-core": "^1.49.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/flutter-ultra-patrol/README.md

@@ -0,0 +1,40 @@
+# @flutter-ultra/flutter-ultra-patrol
+
+MCP server orchestrating **Patrol E2E tests** across web, Android, iOS, and desktop. Wraps `patrol_cli` and bundles the [Bdaya patrol fork](https://github.com/Bdaya-Dev/patrol) as a submodule at `vendor/patrol/` so external contributors get the fork automatically with `git clone --recurse-submodules`.
+
+## Tool catalogue (13 tools per plan §17B.1)
+
+| Tool                           | Purpose                                                                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_tests`                   | Walk `integration_test/` + `patrol_test/`, return `[{file, testNames[], tags[]}]`.                                                      |
+| `start_patrol_test`            | MARATHON: spawn `patrol test ...`, return taskId immediately.                                                                           |
+| `poll_patrol_job`              | Non-blocking status + rolling log tail for any marathon job.                                                                            |
+| `get_patrol_result`            | Final structured `{passed, failed, skipped, durations, failures[]}` for a completed test job.                                           |
+| `cancel_patrol_job`            | SIGTERM + SIGKILL grace period. Idempotent.                                                                                             |
+| `start_patrol_develop`         | MARATHON: warm `patrol develop` session for repeat runs.                                                                                |
+| `patrol_develop_run`           | Dispatch named test inside the warm session (much faster than a fresh `patrol test`).                                                   |
+| `patrol_hot_reload`            | `r` / `R` to the develop session's stdin.                                                                                               |
+| `take_patrol_screenshot`       | CDP screenshot via the develop session (Bdaya `f26306f6`).                                                                              |
+| `start_patrol_recording`       | Bdaya CDP-based GIF/webm recorder.                                                                                                      |
+| `stop_patrol_recording`        | Finalize the active recording.                                                                                                          |
+| `get_patrol_browser_errors`    | CDP-captured browser console errors (Bdaya `b591a390`). Defaults to warm session, falls back to most recent test job, or pass `taskId`. |
+| `get_patrol_web_debugger_port` | Surfaces the CDP port the Bdaya fork prints at web target startup so Playwright / DevTools can co-attach.                               |
+
+## Environment contract (from plugin `.mcp.json`)
+
+| Var                         | Used for                                                                                                                                                                                                    |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FLUTTER_ULTRA_PATROL_FORK` | Absolute path to `vendor/patrol/`.                                                                                                                                                                          |
+| `FLUTTER_ULTRA_STATE_DIR`   | Future on-disk job persistence (in-memory in v1.0).                                                                                                                                                         |
+| `PATROL_WEB_BROWSER_ARGS`   | Comma-separated Chromium flags merged into every `--web-browser-args`. Default: `--enable-unsafe-swiftshader,--disable-renderer-backgrounding,--disable-background-timer-throttling`. |
+| `FLUTTER_ULTRA_LOG_LEVEL`   | `debug`/`info`/`warn`/`error`. Default `info`.                                                                                                                                                              |
+
+## Invocation strategy
+
+For each call we pick (in order):
+
+1. `useRawCli: true` → skip wrapper detection.
+2. `./scripts/run_patrol_web.ps1` (Windows) or `./scripts/run_patrol_web.sh` (Unix) at the project root → use it. Some projects standardize on this wrapper to pre-apply env vars + flags.
+3. Otherwise spawn `dart run patrol_cli` from the project root, which resolves through `pubspec_overrides.yaml` to `vendor/patrol/packages/patrol_cli`.
+
+Web invocations always set `--web-init-timeout 180000` by default (vs upstream's 60000 hardcode — see Bdaya fork PR #9 in `docs/UPSTREAM-PATROL-PRS.md`).

package/packages/flutter-ultra-patrol/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-patrol",
+  "version": "0.0.0",
+  "private": true,
+  "description": "MCP server for orchestrating patrol_cli E2E tests (web + Android + iOS) using the bundled Bdaya patrol fork.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-patrol": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/packages/flutter-ultra-runtime/README.md

@@ -0,0 +1,63 @@
+# @flutter-ultra/flutter-ultra-runtime
+
+MCP server for Flutter **runtime control**: discover + attach to `flutter run`
+debug sessions over DDS, introspect the widget tree (read-only), hot
+reload/restart, evaluate Dart, capture HTTP/gRPC traffic, tail logs.
+
+Part of the [flutter-ultra-mcp](https://github.com/Bdaya-Dev/flutter-ultra-mcp)
+plugin. See plan §5.2 for the full catalogue.
+
+## Tools (28)
+
+| Group                  | Tools                                                                                                                                                                                                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Discovery + lifecycle  | `discover_sessions`, `attach`, `detach`, `list_sessions`, `launch_app`, `poll_launch_app`, `stop_app`, `hot_reload`, `hot_restart`                                                                                                                         |
+| Inspection (read-only) | `get_widget_tree`, `get_widget_details`, `get_selected_widget`, `set_selected_widget`, `widget_exists` (rev 23), `find_widget` (rev 23), `count_widget_tree_nodes`, `screenshot`, `dump_render_tree`, `dump_layer_tree`, `dump_semantics_tree`, `evaluate` |
+| Toggles                | `toggle_debug_paint`, `toggle_perf_overlay`, `set_time_dilation`, `set_platform_override`                                                                                                                                                                  |
+| Logs                   | `get_logs`, `start_tail_logs`, `poll_tail_logs`, `stop_tail_logs`, `get_runtime_errors`, `log_buffer_stats`                                                                                                                                                |
+| HTTP / gRPC capture    | `start_http_capture`, `get_http_events`, `stop_http_capture`, `decode_grpc_message`                                                                                                                                                                        |
+
+All inspect tools are read-only side-effect-free; `widget_exists` / `find_widget`
+walk `ext.flutter.inspector.getRootWidgetSummaryTree` per AC-R5.
+
+## Session model
+
+Sessions persist to `${CLAUDE_PLUGIN_DATA}/state/sessions.json` so the
+gesture, devtools, and patrol servers can read the WS URI without IPC.
+This server is the sole writer. Each session is a `VmServiceClient`
+behind a reference-counted `SessionResource` — parallel tool calls share
+one WebSocket per plan §17.10.
+
+DDS multi-client coexistence with VS Code's Dart debugger is automatic;
+our connection sets `setClientName('flutter-ultra/runtime/<pid>')` per
+plan §7.2.
+
+## Discovery ladder
+
+Implemented per worker-P's empirical report
+([`docs/discovery-empirics.md`](../../docs/discovery-empirics.md)):
+
+1. Process scan for `dart` / `flutter` / `dartvm` / `chrome` with
+   `--enable-vm-service=<port>` in cmdline.
+2. HTTP GET the raw VM port — the body redirects us to the DDS URI.
+3. Convert `http://...` → `ws://.../ws`.
+4. Probe `getVM` to confirm the URI is alive before returning.
+
+## Acceptance criteria covered
+
+- **AC-R1**: `hot_reload` completes < 5 s; `get_widget_tree` returns the
+  post-reload tree without re-attach.
+- **AC-R2**: WS drop triggers exp-backoff reconnect inside
+  `@flutter-ultra/vm-service-client` (0.5/1/2/4/8/14.5 s).
+- **AC-R3**: Per-session `SessionResource<VmServiceClient>` keeps two
+  attached sessions strictly isolated.
+- **AC-R4**: `screenshot` returns a PNG ≥ 200 bytes.
+- **AC-R5 (rev 23)**: `widget_exists({kind:'key', value:'X'})` returns
+  `{exists, count, bounds?}` in < 300 ms on a 500-node tree without
+  triggering setState / hot-reload / route navigation side effects
+  (verified via the summary tree extension which is explicitly
+  side-effect-free).
+
+## License
+
+Apache-2.0.

package/packages/flutter-ultra-runtime/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@flutter-ultra/flutter-ultra-runtime",
+  "version": "0.0.1",
+  "private": false,
+  "description": "MCP server for Flutter runtime: discover + attach to flutter run sessions over DDS, introspect VM Service, hot reload, screenshots, HTTP/gRPC capture.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/packages/flutter-ultra-runtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "packages/flutter-ultra-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "flutter",
+    "dart",
+    "vm-service",
+    "dds",
+    "hot-reload"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "flutter-ultra-runtime": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@flutter-ultra/device-router": "^0.0.1",
+    "@flutter-ultra/mcp-runtime": "^0.0.1",
+    "@flutter-ultra/state-store": "^0.0.1",
+    "@flutter-ultra/vm-service-client": "^0.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "protobufjs": "^7.4.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/shared/contracts/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@flutter-ultra/contracts",
+  "version": "0.0.0",
+  "private": true,
+  "description": "JSON Schema contract definitions for ext.flutter.ultra.* wire format — single source of truth for TS↔Dart interop.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "ext-flutter-ultra",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "test:contract": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  }
+}

package/shared/device-router/README.md

@@ -0,0 +1,51 @@
+# @flutter-ultra/device-router
+
+Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.
+
+## Usage
+
+```typescript
+import { DeviceRouter } from '@flutter-ultra/device-router';
+
+const router = new DeviceRouter();
+
+// List available devices (local + WSL distros + SSH hosts)
+const devices = await router.listAvailable();
+
+// Connect to a WSL distro
+const { device, probe } = await router.connect({ kind: 'wsl', distro: 'Ubuntu-22.04' });
+
+// Run a command on the device
+const result = await device.exec(['flutter', 'build', 'linux', '--release']);
+
+// Forward a TCP port from the remote device to local
+const fwd = await device.forwardTcpPort('localhost', 8080);
+console.log(`VM service available at ws://localhost:${fwd.localPort}/ws`);
+
+// Clean up
+await fwd.close();
+await router.disconnect(device.id);
+```
+
+## Device types
+
+| Kind    | Transport             | Platform    | Use case                                |
+| ------- | --------------------- | ----------- | --------------------------------------- |
+| `local` | `child_process`       | Host OS     | Default — same machine                  |
+| `wsl`   | `wsl.exe -d <distro>` | Linux       | Flutter Linux builds/tests from Windows |
+| `ssh`   | SSH ControlMaster     | Linux/macOS | Flutter macOS builds via remote Mac     |
+
+## Legacy adapter
+
+Existing code using worker-J's v1 Device shape (`label/isLocal/exec/uploadFile/fileExists/openRpcStream`) can use the `LegacyDeviceAdapter`:
+
+```typescript
+import { LegacyDeviceAdapter } from '@flutter-ultra/device-router';
+
+const legacy = new LegacyDeviceAdapter(device);
+// legacy.label, legacy.isLocal, legacy.exec(), legacy.fileExists(), legacy.openRpcStream()
+```
+
+## License
+
+Apache-2.0

package/shared/device-router/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@flutter-ultra/device-router",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Device abstraction for flutter-ultra-mcp: run commands on local, WSL, or SSH-remote targets from a single interface.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/device-router",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/device-router"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "flutter",
+    "mcp",
+    "device",
+    "wsl",
+    "ssh",
+    "remote"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "execa": "^9.5.1",
+    "ssh-config": "^5.0.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/shared/keyring/README.md

@@ -0,0 +1,7 @@
+# @flutter-ultra/keyring
+
+OS-keyring-backed secret storage for plugin-managed credentials: signing certs, OIDC tokens, Sentry DSNs.
+
+**Status:** scaffold stub. Implementation owner: shared infra (wave 2).
+
+Cross-platform via native APIs — Windows Credential Manager, macOS Keychain, Linux Secret Service. Plain-filesystem fallback is intentionally absent to preserve the plan §19 security guarantee.

package/shared/keyring/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@flutter-ultra/keyring",
+  "version": "0.0.0",
+  "private": true,
+  "description": "OS-keyring-backed secret storage for plugin-managed credentials (signing certs, OIDC tokens, Sentry DSNs).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  }
+}

package/shared/mcp-runtime/README.md

@@ -0,0 +1,116 @@
+# @flutter-ultra/mcp-runtime
+
+Shared MCP server scaffolding for the flutter-ultra-mcp plugin's 8 servers.
+Encapsulates the recurring patterns — stdio transport boot, Zod-validated
+tools, watchdog/timeout enforcement, keep-alive against
+[Claude Code #58004](https://github.com/anthropics/claude-code/issues/58004),
+the cross-server session model, and the canonical FinderSpec for widget
+lookups — so each server's `src/index.ts` stays focused on its tool catalogue.
+
+## Quick start
+
+```ts
+import { createServer } from '@flutter-ultra/mcp-runtime';
+import { z } from 'zod';
+
+const server = createServer({
+  info: { name: 'flutter-ultra-runtime', version: '0.0.1' },
+});
+
+server.defineTool(
+  {
+    name: 'list_sessions',
+    description: 'List active Flutter sessions attached by this server.',
+    timeoutClass: 'instant',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+  },
+  async () => ({
+    sessions: [
+      /* ... */
+    ],
+  }),
+);
+
+server.defineTool(
+  {
+    name: 'hot_reload',
+    description: 'Trigger a hot reload on the given session.',
+    inputShape: { sessionId: z.string().min(8) },
+    timeoutClass: 'quick',
+    ceilingMs: 60_000,
+  },
+  async ({ sessionId }, { signal, sendProgress }) => {
+    sendProgress({ progress: 0, message: 'Sending reloadSources to VM service' });
+    // ... handler body with signal-aware aborts
+    return { ok: true, sessionId };
+  },
+);
+
+await server.start();
+process.on('SIGTERM', () => server.stop());
+```
+
+## Components
+
+| Module         | Exports                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------ |
+| `server.ts`    | `createServer`, `defineTool` — high-level builder over `@modelcontextprotocol/sdk`                     |
+| `watchdog.ts`  | `runWithWatchdog`, `TimeoutClass`, `DEFAULT_CEILINGS_MS` — per-tool hard cap + AbortSignal propagation |
+| `keepAlive.ts` | `startKeepAlive` — periodic `notifications/message` debug ping (plan §17.9)                            |
+| `logger.ts`    | `createLogger` — JSON-lines stderr logger with per-tool child loggers                                  |
+| `session.ts`   | `Session`, `SessionResource`, `SessionsFile` — cross-server session model                              |
+| `finder.ts`    | `FinderSchema`, `FinderSpec`, `matchesText` — shared discriminated union for widget lookups            |
+| `errors.ts`    | `ToolWatchdogTimeoutError`, `SessionNotFoundError`, etc.                                               |
+
+## Timeout classes (plan §17.2)
+
+| Class      | Ceiling | When to use                                                        |
+| ---------- | ------- | ------------------------------------------------------------------ |
+| `instant`  | 10 s    | < 1 s p95: `list_sessions`, `get_widget_tree` on small trees       |
+| `quick`    | 30 s    | 1–5 s p95: `hot_reload`, `screenshot`, `tap`                       |
+| `long`     | 55 s    | 5–55 s p95: `dump_render_tree`, `wait_for` (always emit progress)  |
+| `marathon` | 55 s    | > 55 s: MUST be split-tool (`start_*` / `poll_*` / `get_*_result`) |
+
+Per-tool override via env var: `FLUTTER_ULTRA_TOOL_TIMEOUT_<NAME_UPPER>=120000`.
+
+## Session model
+
+Sessions live as JSON in `${CLAUDE_PLUGIN_DATA}/state/sessions.json` (path
+resolved by `@flutter-ultra/state-store`). The runtime server is the sole
+writer; gesture / devtools / patrol read-only. Each session carries:
+
+```
+{ id, uri, source, clientName, attachedAt, lastSeenAt,
+  status, pid?, projectRoot?, device?, isolateIds?, appName? }
+```
+
+`SessionResource<T>` reference-counts an expensive per-session resource
+(e.g. the `VmServiceClient` WebSocket) so multiple parallel tool calls
+share one connection per plan §17.10.
+
+## FinderSpec
+
+Discriminated union used by both runtime (`widget_exists`, `find_widget`)
+and gesture (`tap`, `enter_text`, `wait_for`) so an agent's "is the widget
+in the tree?" check uses the exact same matcher as the subsequent tap:
+
+```ts
+type FinderSpec =
+  | { kind: 'key'; value: string }
+  | {
+      kind: 'text';
+      value: string;
+      matchType?: 'exact' | 'contains' | 'regex';
+      caseInsensitive?: boolean;
+    }
+  | { kind: 'type'; value: string }
+  | { kind: 'coords'; x: number; y: number }
+  | { kind: 'semanticsLabel'; value: string; matchType?: 'exact' | 'contains' | 'regex' }
+  | { kind: 'tooltip'; value: string; matchType?: 'exact' | 'contains' | 'regex' };
+```
+
+`matchesText(candidate, spec)` is the shared comparator both consumers use.
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/shared/mcp-runtime/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@flutter-ultra/mcp-runtime",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Shared MCP server scaffolding: stdio transport, watchdog/timeout, structured logging, session model, finder spec.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/tree/main/shared/mcp-runtime",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bdaya-Dev/flutter-ultra-mcp.git",
+    "directory": "shared/mcp-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Bdaya-Dev/flutter-ultra-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "flutter-ultra"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "typecheck": "tsc -b --noEmit",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}