@shaykec/appxray-web

appxray SDK for React, Next.js, and Vue web applications — gives AI coding agents inside-out access to your running app.

Instant Setup — Paste This to Your AI Agent

Copy this into Cursor, Claude Code, or any MCP-capable AI agent chat and it will do the rest:

Integrate appxray into my web app:

1. Add to MCP config (.cursor/mcp.json): { "mcpServers": { "appxray": { "command": "npx", "args": ["-y", "@shaykec/appxray-mcp-server"], "env": { "APPXRAY_AUTO_CONNECT": "true" } } } }
2. Run npm install @shaykec/appxray-web
3. If using Vite: add appxrayVite() to the plugins array in vite.config.ts (import from @shaykec/appxray-web/vite)
4. If not using Vite: add import "@shaykec/appxray-web/auto" to the app's entry file
5. If using Zustand: wrap each store with appxrayMiddleware("storeName") (import from @shaykec/appxray-web/middleware/zustand)
6. Verify the build succeeds and the app is discoverable

What It Does

Embed this lightweight SDK in your web app, and AI agents (via the appxray MCP server) can:

• Inspect the component tree with props and state
• Read and write state stores (Zustand, Redux)
• Intercept network requests and responses
• Read/write localStorage and sessionStorage
• Navigate programmatically
• Interact with the UI — tap, type, swipe, fill forms
• Install API mocks without touching code
• Trace function calls and renders

Install

npm install @shaykec/appxray-web

Quick Start (Vite)

One line in your Vite config — no other code changes needed:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import appxrayVite from "@shaykec/appxray-web/vite";

export default defineConfig({
  plugins: [react(), appxrayVite()],
});

Start your app, and it's immediately discoverable by the MCP server.

Zustand Integration

Wrap your stores to expose state to the agent:

import { create } from "zustand";
import { appxrayMiddleware } from "@shaykec/appxray-web/middleware/zustand";

export const useTaskStore = create<TaskState>()(
  appxrayMiddleware("tasks")(
    (set) => ({
      tasks: [],
      addTask: (title) => set((s) => ({ tasks: [...s.tasks, { title }] })),
    })
  )
);

Exports

| Import Path | Description | |-------------|-------------| | @shaykec/appxray-web | Core SDK | | @shaykec/appxray-web/vite | Vite plugin (auto-injects SDK) | | @shaykec/appxray-web/react | React hooks and components | | @shaykec/appxray-web/auto | Auto-initialization | | @shaykec/appxray-web/middleware/zustand | Zustand store middleware | | @shaykec/appxray-web/middleware/redux | Redux middleware |

MCP Server Required

This SDK exposes your app's internals via WebSocket. To connect an AI agent, add the MCP server to your agent's config:

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

Related Packages

• @shaykec/appxray-mcp-server — MCP server (required for AI agent access)
• @shaykec/appxray-node — Node.js backend SDK
• @shaykec/appxray-react-native — React Native SDK

License

MIT