@shaykec/appxray-mcp-server

MCP server that gives AI coding agents inside-out access to running applications.

Instant Setup — Paste This to Your AI Agent

Copy the following prompt into Cursor, Claude Code, or any MCP-capable AI agent chat:

Integrate appxray into my project. Install the appxray MCP server and the right SDK for my app's platform. Here's how:

1. Add to my MCP config (.cursor/mcp.json or equivalent):

   { "mcpServers": { "appxray": { "command": "npx", "args": ["-y", "@shaykec/appxray-mcp-server"], "env": { "APPXRAY_AUTO_CONNECT": "true" } } } }

2. Detect my app's platform and install the matching SDK:
   • Web (Vite/React/Next.js/Vue): npm install @shaykec/appxray-web — add appxrayVite() to vite.config plugins, or import "@shaykec/appxray-web/auto" in the entry file
   • Node.js (Express/Fastify): npm install @shaykec/appxray-node — add app.use(appxrayMiddleware()) and AppXrayNode.init({ app, appName: "MyApp" })
   • React Native: npm install @shaykec/appxray-react-native — call appxray.init() in a useEffect
   • iOS/macOS: Add Swift Package https://github.com/shayke-cohen/appxray.git — call AppXray.shared.start() in init
   • Android: debugImplementation("com.appxray:sdk-android:0.1.0") — auto-inits in debug
   • Flutter: flutter pub add --dev appxray — wrap with AppXrayApp(child: MyApp())
3. Verify the build succeeds and the app is discoverable.

The agent will auto-detect your platform, install everything, and verify the connection.

What It Does

AI coding agents are blind to what's happening inside your running app. They rely on screenshots and guesswork. appxray connects them directly to your app's internals — component tree, live state, network traffic, storage, navigation, and more.

This package is the MCP server. It discovers appxray-enabled apps on your machine and exposes 14 aggregate tools (55+ operations) via the Model Context Protocol.

Setup

Add to your AI agent's MCP config (Cursor, Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "appxray": {
      "command": "npx",
      "args": ["-y", "@shaykec/appxray-mcp-server"],
      "env": { "APPXRAY_AUTO_CONNECT": "true" }
    }
  }
}

Or install globally:

npm install -g @shaykec/appxray-mcp-server

Tools

| Tool | Operations | |------|-----------| | session | discover, connect, disconnect, info, list, switch | | inspect | tree, state, network, storage, routes, errors, schema, metrics, bindings, logs, accessibility, profile, timeline, renders | | act | setState, trigger, input, navigate, emit | | interact | find, tap, doubleTap, longPress, type, swipe, drag, screenshot, waitFor, fillForm, record | | batch | Execute multiple operations in one call | | mock | install, remove, clear, list, override, removeOverride, listOverrides | | config | get, set, list, reset (feature flags, env vars) | | timetravel | checkpoint, restore, history | | chaos | start, stop, list | | advanced | eval, coverage, subscribe, events, storageWrite, storageClear | | diagnose | One-call health check: errors, network, performance, a11y | | diff | snapshot, compare, list | | suggest | Root cause analysis with ranked hypotheses | | trace | render, stateChange, dataFlow, whyEmpty |

Every tool response includes a live snapshot with screenshot, component tree, console logs, errors, network activity, and state summary.

SDK Required

Your app needs an appxray SDK embedded to be discoverable. Available SDKs:

| Platform | Package | |----------|---------| | Web (React/Next.js/Vue) | @shaykec/appxray-web | | Node.js (Express/Fastify) | @shaykec/appxray-node | | React Native | @shaykec/appxray-react-native | | iOS/macOS | Swift Package (source) | | Android | Kotlin library (source) | | Flutter | Dart package (source) |

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | APPXRAY_AUTO_CONNECT | false | Auto-connect to the first discovered app | | APPXRAY_PORT_MIN | 19400 | Port range start for discovery | | APPXRAY_PORT_MAX | 19499 | Port range end for discovery | | APPXRAY_AUTH_TOKEN | — | Pre-shared auth token for app connections |

CLI: Test Runner

The package also ships appxray-run, a YAML-based test runner:

npx @shaykec/appxray-mcp-server appxray-run tests/login-flow.yaml

Related Packages

• @shaykec/appxray-protocol — Shared protocol types
• @shaykec/appxray-web — Web SDK
• @shaykec/appxray-node — Node.js SDK
• @shaykec/appxray-react-native — React Native SDK

License

MIT