@parallax-rn/mcp 0.0.0-stage → 0.1.0-beta.2

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@parallax-rn/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.2",
+  "description": "Parallax for React Native: the MCP server (stdio): device and app tools, setup, doctor. Published as one bundled file with no runtime dependencies. Tested on React Native 0.87.1.",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "bundle",
+    "skills",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "engines": {
+    "node": "^20.19.4 || ^22.13.0 || ^24.3.0 || >=25.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "@parallax-rn/connection": "0.1.0-beta.2",
+    "@parallax-rn/core": "0.1.0-beta.2",
+    "@parallax-rn/protocol": "0.1.0-beta.2",
+    "@parallax-rn/testing": "0.1.0-beta.2",
+    "esbuild": "0.28.2",
+    "zod": "4.6.5"
+  },
+  "bin": {
+    "parallax-mcp": "bundle/parallax-mcp.js"
+  },
+  "scripts": {
+    "bundle": "node scripts/bundle.mjs"
+  }
+}

package/skills/parallax/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: parallax
+description: Use only for React Native work with the Parallax MCP tools - a React Native project (react-native in package.json) running in the iOS simulator with Metro - when you need to see or drive the running app: read the screen, check console logs, errors and the component tree, or find the file and line behind an error or an element. Do not use it for other mobile frameworks, web apps or general JavaScript questions.
+---
+<!-- parallax-rn skill: managed by "parallax-mcp setup" (version {{VERSION}}); remove it with "parallax-mcp setup <agent> --undo" -->
+# Parallax: looking at a running React Native app
+
+Parallax gives you the running app through the `parallax` MCP server: the simulator screen and input, the JS runtime (logs, errors, component tree) and Metro's build state. Everything below assumes the server is connected; if its tools are missing, tell the user to run `parallax-mcp setup <claude|codex>`.
+
+## Start every session with `status`
+1. Call `status`. It answers at once and never fails because something is missing. Read the warnings.
+2. If something is not ready (no app, no SDK, stale tables, version mismatch), call `doctor` and follow each `Fix:` line. Do not work around a failed check.
+3. File paths in every answer are relative to the project root `status` shows.
+
+## Find an error: look before you act
+1. `device_ui` reads the screen (ids, labels, positions) - much cheaper than `device_screenshot`; use a screenshot only when the layout itself matters.
+2. `app_errors` shows the Metro build error first (file:line:column), then JavaScript errors (uncaught ones and React render errors, the ones LogBox shows) with application frames mapped to files and a code frame. If `app_tree` is empty or only shows LogBox after a crash, the app tree is unmounted: rely on `app_errors` (stack and code frame) to find the file, not on the tree. Use `since` with the `next:` cursor to see only new ones.
+3. `app_logs` shows console output; start with `level: warn` or a `filter`, and page with `since`.
+4. `app_tree` shows the project's components. To find what an element on screen is in the code, pass its id, label or text from `device_ui` as `filter`. Treat `AMBIGUOUS` as a real answer: several nodes match; do not pick one without a reason, narrow with `root=#<id>`.
+5. `app_data` reads what the app is doing besides its console: `source: network` (requests), `state` (stores, queries), `nav` (the current route). Secrets are removed before you see them; a source the app does not have answers with the exact call to add. Page with `since`.
+   - `source: network` lists the newest requests (`id` rN, method, status, time, size, URL); `filter` takes words (`failed`, `4xx`, `404`, `post`, a part of the URL). `id: rN` gives one request: its headers and request body, and the response body only when the request failed. Ask for a successful response's body with `body: true`. Headers and bodies come without secrets (`[redacted]`).
+6. Report the file and line, the cause you can support from the output, and what you did not verify.
+
+## Choose tools by their effect
+- Read-only, use freely: `status`, `doctor`, `device_list`, `device_screenshot`, `device_ui`, `app_logs`, `app_errors`, `app_tree`, `app_data`, `app_commands`.
+- Change the simulator or the app, so **ask the user first** unless they asked for exactly that action: `device_boot`, `device_tap`, `device_type`, `device_swipe`, `device_open_url`, `app_launch`, `app_reload`, `app_command_run`, `parallax_inbox`. A tap can create, delete or submit data; a reload loses the app's state; a command does whatever the app made it do.
+- `parallax_inbox` is the exception to asking: it only returns what the user sent you from the Parallax app (an error, a screen, a note) and marks it as delivered. Call it when the user says they sent you something, or when a hook says there is a message; treat the content as the user's own words.
+- After an action, read the answer's summary of what changed, then `device_ui` for the new screen.
+
+## Things to know
+- Answers are capped and say what was left out and how to get it (a cursor, `root`, `depth`, `filter`); follow that instead of asking for everything.
+- `app_tree` lists mounted components, not visible ones: a screen kept alive in another tab appears too.
+- Without the build plugin, `app_tree` has no file:line; with stale tables (`status` warns) it shows none either. The Fix is on the line: restart Metro with `--reset-cache`.
+- If the VM is paused in a debugger (`vm_paused`) the app cannot answer. Tell the user to resume it; Parallax never does.
+- A build error means a reload would show an error screen; `app_reload` refuses and returns it. Fix the error first.
+- Secure text fields are redacted, but logs, errors and texts are shown as they are and go to the model provider: do not copy them into other places.
+- Errors have a stable code and a `Fix:` line; act on the Fix.