npm package: @shaykec/appxray-mcp-server
Description: MCP server providing inside-out app intelligence tools for AI coding agents
Latest version: 0.2.1

# @shaykec/appxray-mcp-server

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

[![npm](https://img.shields.io/npm/v/@shaykec/appxray-mcp-server)](https://www.npmjs.com/package/@shaykec/appxray-mcp-server)

## 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):
>    ```json
>    { "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](https://modelcontextprotocol.io).

## Setup

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

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

Or install globally:

```bash
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`](https://www.npmjs.com/package/@shaykec/appxray-web) |
| Node.js (Express/Fastify) | [`@shaykec/appxray-node`](https://www.npmjs.com/package/@shaykec/appxray-node) |
| React Native | [`@shaykec/appxray-react-native`](https://www.npmjs.com/package/@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:

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

## Related Packages

- [`@shaykec/appxray-protocol`](https://www.npmjs.com/package/@shaykec/appxray-protocol) — Shared protocol types
- [`@shaykec/appxray-web`](https://www.npmjs.com/package/@shaykec/appxray-web) — Web SDK
- [`@shaykec/appxray-node`](https://www.npmjs.com/package/@shaykec/appxray-node) — Node.js SDK
- [`@shaykec/appxray-react-native`](https://www.npmjs.com/package/@shaykec/appxray-react-native) — React Native SDK

## License

MIT