state-bridge-mcp

state-bridge-mcp

MCP server + client SDK for bridging Zustand stores over WebSocket. Lets any MCP-capable AI inspect and manipulate your app's live state.

How it works

┌─────────────┐   WebSocket   ┌──────────────┐   stdio   ┌──────────┐
│  Your App   │──────────────▶│  MCP Server  │◀─────────▶│  Claude  │
│  (client)   │◀──────────────│  (server)    │           │          │
└─────────────┘               └──────────────┘           └──────────┘

The server runs as an MCP server (launched by Claude, Cursor, etc.) and opens a WebSocket port. Your app connects as a client and exposes its Zustand stores. The AI can then list stores, read state, write state, and call actions.

Installation

npm install state-bridge-mcp

Server Setup

Add to your .mcp.json (or equivalent MCP config):

{
  "mcpServers": {
    "app-state": {
      "command": "npx",
      "args": ["state-bridge-mcp"]
    }
  }
}

Custom port

{
  "mcpServers": {
    "app-state": {
      "command": "npx",
      "args": ["state-bridge-mcp", "--port", "9000"]
    }
  }
}

Or via environment variable: STATE_BRIDGE_PORT=9000

Default port: 8098

Client Usage

import { createStateBridge } from 'state-bridge-mcp/client';
import { useSessionStore, useAppStore } from './store';

const bridge = createStateBridge({
  stores: {
    session: useSessionStore,
    app: useAppStore,
  },
  url: 'ws://localhost:8098',
});

// Later, to tear down:
bridge.stop();

React Native (Android emulator)

For Android emulator, use 10.0.2.2 to reach the host machine:

const bridge = createStateBridge({
  stores: { session: useSessionStore, app: useAppStore },
  url: 'ws://10.0.2.2:8098',
});

Client Config

| Option | Type | Default | Description | |--------|------|---------|-------------| | stores | Record<string, StoreEntry> | required | Named map of Zustand stores | | url | string | ws://localhost:8098 | WebSocket URL of the MCP server | | reconnectInterval | number | 3000 | Auto-reconnect interval in ms. 0 to disable. | | onConnect | () => void | — | Called when WebSocket opens | | onDisconnect | () => void | — | Called when WebSocket closes |

MCP Tools

Once connected, the AI has access to these tools:

| Tool | Description | |------|-------------| | connection_status | Check if a client app is connected | | list_stores | List all stores and their top-level state keys | | get_state | Read state from a store (supports dot-paths like settings.theme) | | set_state | Write a value at a dot-path (supports arbitrary depth) | | call_action | Invoke a store action function by name |

Store Compatibility

Any object with getState() and setState() works. Zustand stores satisfy this out of the box:

type StoreEntry = {
  getState: () => Record<string, unknown>;
  setState: (partial: Record<string, unknown>) => void;
};

License

MIT