vibeview 0.7.1 → 0.8.1

package/dist/server-S3D724K3.js

@@ -0,0 +1,367 @@
+#!/usr/bin/env node
+import {
+  AGENT_COMMANDS,
+  PLATFORM_DEVICE,
+  buildToolCall,
+  checkMetro,
+  decodeScreenshotResult,
+  isDevPlatform,
+  loadDevConfig,
+  readDevState,
+  renderEnvelope,
+  startDevSession
+} from "./chunk-WG2XR45H.js";
+import {
+  ApiClient,
+  resolveAuth
+} from "./chunk-YD2X6TQV.js";
+
+// src/mcp/server.ts
+import { writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import chalk from "chalk";
+var SESSION_ID_PROPERTY = {
+  type: "string",
+  description: "Session ID to target. Optional: falls back to the MCP-server-held dev_start session, then this project's `vibeview dev --detach` state, if either is available."
+};
+var DEV_PLATFORMS = ["ios", "android", "tvos", "androidtv"];
+function paramToProperty(param) {
+  return { type: param.type, description: param.description };
+}
+function toolNameFor(verb) {
+  return verb.replace(/-/g, "_");
+}
+function toolDefFromCommand(cmd) {
+  const properties = { session_id: SESSION_ID_PROPERTY };
+  const required = [];
+  for (const param of cmd.params) {
+    properties[param.name] = paramToProperty(param);
+    if (param.required) required.push(param.name);
+  }
+  if (cmd.verb === "screenshot") {
+    properties.inline = {
+      type: "boolean",
+      description: "Return the image itself so you can see it, not just the file path. Set this to true whenever you need to judge how the screen LOOKS, or whenever you cannot open files on the machine running this server \u2014 otherwise the screenshot is only written to disk and you never see it. It costs a lot of context, so skip it when you only need to confirm an action happened (the response already tells you what changed)."
+    };
+  }
+  return {
+    name: toolNameFor(cmd.verb),
+    description: cmd.summary,
+    mutating: cmd.mutating,
+    properties,
+    required
+  };
+}
+var DEV_START_DEF = {
+  name: "dev_start",
+  description: "Start a VibeView dev-loop session (device + tunnel) held in-process by this MCP server, and use it as the default session for every other tool call until dev_stop. Returns once the session accepts commands (device up, app installed) \u2014 call ui_tree right away, no readiness polling needed.",
+  mutating: true,
+  properties: {
+    session_id: SESSION_ID_PROPERTY,
+    platform: {
+      type: "string",
+      description: "Platform to run on.",
+      enum: [...DEV_PLATFORMS]
+    },
+    app: {
+      type: "string",
+      description: "Uploaded debug build (app_id) to run. Defaults to vibeview.json config."
+    },
+    metro_port: {
+      type: "number",
+      description: "Local Metro port (default: 8081, or vibeview.json)."
+    }
+  },
+  required: ["platform"]
+};
+var DEV_STOP_DEF = {
+  name: "dev_stop",
+  description: "Stop the dev-loop session started by dev_start.",
+  mutating: true,
+  properties: { session_id: SESSION_ID_PROPERTY },
+  required: []
+};
+var UPLOAD_APP_DEF = {
+  name: "upload_app",
+  description: "Upload an app build (zipped simulator .app for iOS, .apk for Android) and return its app_id for dev_start. The MCP equivalent of `vibeview upload-app`.",
+  mutating: true,
+  properties: {
+    file: {
+      type: "string",
+      description: "Path to the build file on this machine (.apk, or a zipped iOS simulator .app)."
+    },
+    name: {
+      type: "string",
+      description: "App name (auto-detected from the build if omitted)."
+    }
+  },
+  required: ["file"]
+};
+function buildToolDefinitions() {
+  return [...AGENT_COMMANDS.map(toolDefFromCommand), DEV_START_DEF, DEV_STOP_DEF, UPLOAD_APP_DEF];
+}
+function textResult(text, structuredContent, isError = false) {
+  return { content: [{ type: "text", text }], structuredContent, isError };
+}
+function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+function findCommand(toolName) {
+  return AGENT_COMMANDS.find((c) => toolNameFor(c.verb) === toolName);
+}
+async function handleToolCall(toolName, args, deps) {
+  if (toolName === "dev_start") {
+    return handleDevStart(args, deps);
+  }
+  if (toolName === "dev_stop") {
+    return handleDevStop(deps);
+  }
+  if (toolName === "upload_app") {
+    return handleUploadApp(args, deps);
+  }
+  const cmd = findCommand(toolName);
+  if (!cmd) {
+    return errorResult(`Unknown tool: ${toolName}`);
+  }
+  const sessionId = typeof args.session_id === "string" ? args.session_id : deps.resolveSessionId();
+  if (!sessionId) {
+    return errorResult(
+      "No session to target. Call dev_start first, or pass session_id (e.g. from a running `vibeview dev --detach`)."
+    );
+  }
+  let call;
+  try {
+    const { session_id: _sessionId, ...rest } = args;
+    const positionals = positionalsFor(cmd, rest);
+    const opts = optsFor(cmd, rest);
+    call = buildToolCall(cmd, positionals, opts);
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  let envelope;
+  try {
+    envelope = await deps.agentTool(sessionId, call.tool, call.args);
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (cmd.verb === "screenshot" && envelope.ok) {
+    return screenshotToolResult(envelope, args);
+  }
+  return textResult(renderEnvelope(envelope), envelope, !envelope.ok);
+}
+function screenshotToolResult(envelope, args) {
+  let imageBytes;
+  try {
+    imageBytes = decodeScreenshotResult(envelope.result);
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const outPath = typeof args.out === "string" && args.out ? args.out : join(tmpdir(), `vibeview-screenshot-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.png`);
+  try {
+    writeFileSync(outPath, imageBytes);
+  } catch (err) {
+    return errorResult(
+      `error: could not write screenshot to ${outPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const sanitized = {
+    ...envelope,
+    result: { written_to: outPath, bytes: imageBytes.length }
+  };
+  const content = [
+    { type: "text", text: `${renderEnvelope(sanitized)}
+screenshot written to ${outPath}` }
+  ];
+  if (args.inline === true) {
+    content.push({ type: "image", data: imageBytes.toString("base64"), mimeType: "image/png" });
+  }
+  return { content, structuredContent: sanitized };
+}
+function positionalsFor(cmd, args) {
+  return cmd.params.filter((p) => p.cli === "positional").map((p) => args[p.name] === void 0 ? void 0 : String(args[p.name])).filter((v) => v !== void 0);
+}
+function optsFor(cmd, args) {
+  const opts = {};
+  for (const param of cmd.params) {
+    if (param.cli === "positional") continue;
+    if (args[param.name] === void 0) continue;
+    const key = param.cli.replace(/^--/, "").replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const value = args[param.name];
+    opts[key] = cmd.verb === "wait" && key === "ms" && typeof value === "number" ? value * 1e3 : value;
+  }
+  return opts;
+}
+async function handleDevStart(args, deps) {
+  const platform = args.platform;
+  if (!isDevPlatform(platform)) {
+    return errorResult(
+      `dev_start: platform must be one of ${DEV_PLATFORMS.join(", ")}, got "${String(platform)}"`
+    );
+  }
+  try {
+    const result = await deps.devSession.start({
+      platform,
+      app: typeof args.app === "string" ? args.app : void 0,
+      metroPort: typeof args.metro_port === "number" ? args.metro_port : void 0
+    });
+    const payload = { session_id: result.sessionId, page_url: result.pageUrl };
+    return textResult(`dev session started: ${payload.session_id}
+${payload.page_url}`, payload);
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+async function handleDevStop(deps) {
+  const current = deps.devSession.current();
+  try {
+    await deps.devSession.stop();
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return textResult(current ? `dev session stopped: ${current.sessionId}` : "dev session stopped", {
+    session_id: current?.sessionId ?? null
+  });
+}
+async function handleUploadApp(args, deps) {
+  const file = args.file;
+  if (typeof file !== "string" || !file) {
+    return errorResult("upload_app: `file` is required \u2014 the path to a .apk or zipped iOS .app");
+  }
+  const name = typeof args.name === "string" && args.name ? args.name : void 0;
+  const upload = deps.uploadApp ?? (async (f, n) => {
+    const { uploadAppBuild } = await import("./upload-app-GAZVQZYR.js");
+    const { result: result2 } = await uploadAppBuild(f, { ...deps.auth, name: n });
+    return result2;
+  });
+  let result;
+  try {
+    result = await upload(file, name);
+  } catch (err) {
+    return errorResult(`error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const isNew = result.is_new !== false;
+  const warnings = result.warnings ?? [];
+  const payload = {
+    app_id: result.public_id,
+    name: result.name,
+    package_name: result.package_name,
+    platform: result.platform,
+    is_new: isNew,
+    warnings
+  };
+  const lines = [
+    `${isNew ? "New app created" : "Build added to existing app"}: ${result.name}`,
+    `app_id: ${result.public_id}  [${result.platform}]  ${result.package_name}`,
+    ...warnings.map((w) => `warning: ${w}`)
+  ];
+  return textResult(lines.join("\n"), payload);
+}
+function createDevSessionController(auth, webUrl) {
+  let handle = null;
+  return {
+    async start(cfg) {
+      if (handle) {
+        throw new Error(
+          `a dev session is already running (${handle.sessionId}) \u2014 call dev_stop first`
+        );
+      }
+      let devConfig = null;
+      try {
+        devConfig = loadDevConfig(process.cwd());
+      } catch {
+        devConfig = null;
+      }
+      const entry = devConfig?.platforms?.[cfg.platform];
+      const appId = cfg.app || entry?.appId;
+      if (!appId) {
+        throw new Error(
+          `dev_start: no app to run for platform "${cfg.platform}" \u2014 pass the app arg (an app id from list-apps) or run \`vibeview dev\` once in this project to write vibeview.json`
+        );
+      }
+      const metroPort = cfg.metroPort ?? devConfig?.metroPort ?? 8081;
+      const metro = await checkMetro(metroPort);
+      if (metro === "down") {
+        throw new Error(
+          `Metro isn't running on localhost:${metroPort} \u2014 start it in the project first (yarn start), or pass metro_port if Metro uses another port`
+        );
+      }
+      const isTv = PLATFORM_DEVICE[cfg.platform].tv;
+      handle = await startDevSession({
+        token: auth.token,
+        baseUrl: auth.baseUrl,
+        webUrl,
+        platform: cfg.platform,
+        appId,
+        deviceCategory: isTv ? "tv" : entry?.deviceCategory ?? "phone",
+        metroPort,
+        open: false
+      });
+      return handle;
+    },
+    async stop() {
+      await handle?.stop();
+      handle = null;
+    },
+    current() {
+      return handle ? { sessionId: handle.sessionId, pageUrl: handle.pageUrl } : null;
+    }
+  };
+}
+function makeSessionResolver(devSession) {
+  return () => devSession.current()?.sessionId ?? readDevState(process.cwd())?.session_id;
+}
+async function createMcpServer(opts) {
+  const [{ McpServer }, { z }] = await Promise.all([
+    import("@modelcontextprotocol/sdk/server/mcp.js"),
+    import("zod")
+  ]);
+  const auth = resolveAuth(opts);
+  const client = new ApiClient(auth.baseUrl, auth.token);
+  const devSession = createDevSessionController(auth, opts.webUrl);
+  const deps = {
+    auth,
+    resolveSessionId: makeSessionResolver(devSession),
+    agentTool: client.agentTool.bind(client),
+    devSession
+  };
+  const server = new McpServer({ name: "vibeview", version: "1.0.0" });
+  function zodShape(def) {
+    const shape = {};
+    for (const [key, prop] of Object.entries(def.properties)) {
+      const base = prop.enum ? z.enum(prop.enum) : z[prop.type]();
+      const described = base.describe(prop.description);
+      shape[key] = def.required.includes(key) ? described : described.optional();
+    }
+    return shape;
+  }
+  for (const def of buildToolDefinitions()) {
+    server.registerTool(
+      def.name,
+      {
+        description: def.description,
+        inputSchema: zodShape(def),
+        annotations: { readOnlyHint: !def.mutating }
+      },
+      async (args) => {
+        const result = await handleToolCall(def.name, args ?? {}, deps);
+        return result;
+      }
+    );
+  }
+  return server;
+}
+async function runMcpServer(opts) {
+  chalk.level = 0;
+  const [server, { StdioServerTransport }] = await Promise.all([
+    createMcpServer(opts),
+    import("@modelcontextprotocol/sdk/server/stdio.js")
+  ]);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+export {
+  buildToolDefinitions,
+  handleToolCall,
+  runMcpServer
+};

package/dist/upload-app-GAZVQZYR.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import {
+  uploadApp,
+  uploadAppBuild
+} from "./chunk-YD2X6TQV.js";
+export {
+  uploadApp,
+  uploadAppBuild
+};

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "vibeview",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "VibeView CLI -- run mobile tests from CI/CD pipelines",
   "type": "module",
   "bin": {
     "vibeview": "./dist/cli.js"
   },
   "files": [
-    "dist/cli.js"
+    "dist",
+    "skills"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/scriptx-com/vibeview.git",
-    "directory": "cli"
+  "homepage": "https://vibeview.io/docs/cli",
+  "bugs": {
+    "email": "support@vibeview.io"
   },
   "publishConfig": {
     "access": "public"
@@ -26,11 +26,13 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "chalk": "^5.0.0",
     "commander": "^14.0.0",
     "open": "^11.0.0",
     "ora": "^9.0.0",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/skills/vibeview-agent/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: vibeview-agent
+description: Verify a React Native change on a real running app — install/launch it on a live iOS or Android device via VibeView, drive the UI, and check the result. Use when asked to verify this change on a device, test my React Native app, or run it on a simulator.
+---
+
+# VibeView agent control
+
+Drive a live iOS/Android VibeView session from the CLI to verify a React
+Native change actually works, not just that it compiles. Requires the
+`vibeview` CLI installed and authenticated (`vibeview login`, or
+`VIBEVIEW_API_TOKEN` set).
+
+## 1. Build requirements
+
+Read before uploading anything — a build that violates these will install
+and then crash or refuse to boot:
+
+- **Android**: the debug APK must include an `x86_64` slice. Standard
+  `./gradlew assembleDebug` output includes it by default; only an issue if
+  the project filters ABIs.
+- **iOS**: upload a **simulator** debug build (not a device `.ipa`), and it
+  must include the `arm64` slice.
+
+Debug builds are auto-detected on upload — no separate flag needed. Upload
+warnings are the safety net: if a build is missing the right architecture,
+`upload-app` says so.
+
+Full detail: https://vibeview.io/docs/live-development and
+https://vibeview.io/docs/preparing-your-build.
+
+## 2. The loop
+
+1. Upload the debug build — **only after a native change** (new/updated
+   native module, Podfile/Gradle change). Everyday JS/asset edits never need
+   a re-upload:
+   ```bash
+   vibeview upload-app ./path/to/app-debug.apk
+   ```
+2. Start Metro in the React Native project (`yarn start` or equivalent) and
+   leave it running.
+3. Start a dev session in the background and get structured output:
+   ```bash
+   vibeview dev --detach --json
+   ```
+4. Parse the `session_ready` line from stdout:
+   ```json
+   {"event":"session_ready","session_id":"...","url":"...","pid":1234}
+   ```
+   Use `session_id` as `--session <id>` on every verb below. The event
+   fires once the session accepts commands (device up, app installed) —
+   no need to poll `dev-status` first. If the app ships no native changes
+   since the last run, skip step 1 and just do steps 2–4.
+
+Running `dev` writes two things into the project root: a `.vibeview/`
+directory (live session state — local machine state, never commit) and a
+`vibeview.json` (your platform/app/build choices, which teammates DO want).
+Make sure `.vibeview/` is in the project's `.gitignore`, adding it if
+missing. Leave `vibeview.json` tracked, but tell the developer you created
+it rather than letting it appear unexplained in their `git status`.
+
+## 3. Verifying
+
+- **Always run `ui-tree` first** — every ref (`@e5`) the UI exposes comes
+  from here. Never guess a ref.
+  ```bash
+  vibeview ui-tree --session <id>
+  ```
+  An empty or near-empty first tree usually means the app is still booting
+  (splash screen, fetching remote config) — NOT a broken session. Take a
+  screenshot to confirm, `wait`, and fetch the tree again before concluding
+  anything is wrong.
+- Act on the screen using refs from the tree:
+  ```bash
+  vibeview tap @e5 --session <id>
+  vibeview type "hello@example.com" --session <id>
+  vibeview scroll down --session <id>
+  vibeview press back --session <id>
+  ```
+- **Read the observation in every response before deciding the next
+  action.** Every mutating verb returns one of: screen unchanged, a
+  `+`/`~`/`-` diff with fresh `@e` refs, a full tree, or an "unavailable"
+  warning. Refs go stale the moment the screen changes — a stale ref is
+  refused. **The refusal does NOT include the current screen**: because the
+  action never ran, the observation comes back as "screen unchanged" with no
+  tree, so run `ui-tree` again to get live refs before retrying. Never reuse
+  a ref from a previous observation.
+- **Take a screenshot whenever you changed how something LOOKS.** The UI
+  tree proves an element exists, has the right text, and occupies the right
+  rect — it says nothing about colour, contrast, or whether something is
+  hidden behind another view, so a screen can pass every check the tree can
+  express and still be visibly broken (text the same colour as its
+  background, a view drawn on top of another). Tree for structure and refs;
+  screenshot for appearance.
+
+  **Actually look at the image** — confirming the file was written proves
+  nothing about how it renders.
+  ```bash
+  vibeview screenshot --out ./check.png --session <id>   # then open it
+  ```
+  Over MCP, `screenshot` only writes the file and returns its path unless
+  you pass `inline: true`, which returns the image itself. If you cannot
+  open files on the machine running the server, `inline: true` is the only
+  way you will ever see the screen. It costs a lot of context, so use it
+  when appearance matters — not to confirm a tap landed, which the
+  response's observation already tells you.
+- **Off-screen elements**: use `scroll-to <text>` rather than repeating
+  `scroll down`. It scrolls until an element whose label, value, or
+  accessibility id contains that text is visible, and stops early when the
+  content stops changing (end of list). Omit `--direction` for vertical
+  lists (it auto-detects); pass it explicitly for horizontal strips.
+  ```bash
+  vibeview scroll-to "Delete account" --session <id>
+  ```
+- **Precise two-point gestures** (sliders, drag-and-drop reorder, map
+  panning) need `drag` — `swipe`/`scroll` are direction-only and can't
+  express them. Each end is independently a ref or `x,y`:
+  ```bash
+  vibeview drag @e5 @e9 --session <id>
+  vibeview drag 100,400 300,400 --session <id>
+  vibeview drag @e5 300,400 --press-ms 500 --session <id>
+  ```
+  Use `--press-ms 500` or more for long-press-to-reorder lists, and
+  `--velocity 150` for slow, precise slider adjustments.
+- **iOS system alerts** (permission prompts and similar) sit above the app
+  and block it. Call `alert get` first to read the message and the exact
+  button labels, then act on one:
+  ```bash
+  vibeview alert get --session <id>
+  vibeview alert accept --button "Allow" --session <id>
+  ```
+- Use `open-url` to jump straight to a deep link instead of navigating by
+  hand:
+  ```bash
+  vibeview open-url "myapp://settings" --session <id>
+  ```
+- **TV apps**: start the session with `--platform tvos` (Apple TV) or
+  `--platform androidtv` (Android TV). Navigate with the d-pad via `press`
+  (`dpad_up`/`dpad_down`/`dpad_left`/`dpad_right`/`dpad_center`), or move
+  focus directly with `tap-focused` (moves focus AND activates) / `focus`
+  (moves focus only, no activation).
+
+## 4. Cleanup
+
+**Always** stop the session when done verifying — a running session bills
+streaming minutes even when idle:
+```bash
+vibeview dev-stop
+```
+
+## 5. Command reference
+
+Every verb accepts `--session <id>` to target a specific session (falls
+back to the current project's `vibeview dev --detach` session if omitted)
+and `--json` to print the raw response envelope as one JSON line instead of
+human-readable text.
+
+| Verb | Args | Purpose |
+|------|------|---------|
+| `ui-tree` | — | Fetch the ref-annotated UI tree for the current screen. |
+| `screenshot` | `[--out <path>]` | Capture a screenshot of the current screen and save it to disk. |
+| `tap` | `<target>` | Tap an element by ref (e.g. `@e5`), or raw coordinates (e.g. `100,200`). |
+| `long-press` | `<ref>` `[--ms <n>]` | Long-press (touch and hold) an element by its ref. |
+| `swipe` | `<direction>` `[--distance <short\|medium\|long>]` | Perform a scrollbar-semantic swipe gesture in one of four directions. |
+| `scroll` | `<direction>` | Scroll the current view up, down, left, or right using a gesture preset. |
+| `scroll-to` | `<text>` `[--direction <up\|down\|left\|right>] [--max-scrolls <n>] [--element-type <type>]` | Scroll until an element matching the text is visible. Stops at end of list. |
+| `drag` | `<from>` `<to>` `[--velocity <n>] [--press-ms <n>] [--hold-ms <n>]` | Drag between two points, each an `@ref` or `x,y`. The only precise two-point gesture. |
+| `alert` | `<get\|accept\|dismiss>` `[--button <label>]` | Inspect or respond to a visible iOS system alert. |
+| `type` | `<text>` | Type text into the currently focused input field. |
+| `clear-text` | — | Clear the text in the currently focused input field. |
+| `press` | `<button>` | Press a device button or perform a system gesture (home, back, d-pad, etc). |
+| `open-url` | `<url>` | Open a deep link or URL in the app under test. |
+| `wait` | `[--ms <n>]` | Wait for a specified number of seconds before continuing (default: 2s). |
+| `find` | `<text>` `[--below <text>] [--above <text>] [--near <text>]` | Find an element by text with optional spatial constraints. |
+| `tap-focused` | `<ref>` | TV: move focus to an element and press SELECT in one step. |
+| `focus` | `<ref>` | TV: move focus to an element without activating it. |
+
+Dev-loop lifecycle commands (not registry verbs, but needed for every run):
+
+| Command | Purpose |
+|---------|---------|
+| `dev --detach --json` | Start a device + Metro-tunnel session in the background, emitting `session_ready`/`warning`/`error` JSON events on stdout. |
+| `dev-status` | Check on the current project's detached dev session. |
+| `dev-stop` | End the current project's detached dev session. |
+
+## 6. If you're calling VibeView over MCP
+
+Everything above is also exposed as MCP tools by `vibeview mcp`, so an agent
+with no shell can run the whole loop. Tool names are the CLI verbs with
+hyphens replaced by underscores (`ui_tree`, `tap`, `scroll_to`, `long_press`,
+`clear_text`, `open_url`, `tap_focused`, ...), each taking its args by name
+(`tap {ref: "e5"}` or `tap {target: "100,200"}`, `scroll_to {text: "..."}`,
+`drag {from: "@e5", to: "300,400"}`, `alert {action: "get"}`) plus an
+optional `session_id`.
+
+Three tools exist **only** over MCP, with no registry verb — they cover the
+steps the CLI does with plain shell commands:
+
+| MCP tool | Args | Purpose |
+|----------|------|---------|
+| `upload_app` | `file` (required path), `name` | Upload a debug build. The MCP equivalent of `vibeview upload-app`, so step 1 of the loop needs no shell. Returns the `app_id` to pass to `dev_start`. |
+| `dev_start` | `platform` (required: `ios`/`android`/`tvos`/`androidtv`), `app`, `metro_port` | Start a dev-loop session held open by the MCP server. The MCP equivalent of `vibeview dev --detach`. |
+| `dev_stop` | — | Stop the session `dev_start` started. The MCP equivalent of `vibeview dev-stop`. |
+
+**`dev_start` is stateful — it changes the default session for every later
+call.** Once it succeeds, any tool called without an explicit `session_id`
+targets that session instead of whatever `vibeview dev --detach` state exists
+in the project directory. Only one such session can be held at a time
+(`dev_start` fails if one is already running), and it stays live — billing
+streaming minutes — until `dev_stop` or the MCP connection ends. Always call
+`dev_stop` when you finish verifying.