> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# State Management

> Expose application state as MCP resources and actions as MCP tools

`@frontmcp/react/state` bridges your application state with MCP. State slices become MCP resources that agents can read, and actions become MCP tools that agents can call.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { useStoreResource, useReduxResource, useValtioResource } from '@frontmcp/react/state';
```

## useStoreResource

The generic hook that works with any state management library. `useReduxResource` and `useValtioResource` are thin wrappers around it.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { useStoreResource } from '@frontmcp/react/state';

function StoreProvider() {
  useStoreResource({
    name: 'app',
    getState: () => store.getState(),
    subscribe: (cb) => store.subscribe(cb),
    selectors: {
      count: (state) => (state as { count: number }).count,
      user: (state) => (state as { user: unknown }).user,
    },
    actions: {
      increment: () => store.dispatch({ type: 'INCREMENT' }),
      reset: () => store.dispatch({ type: 'RESET' }),
    },
  });

  return null;
}
```

### What Gets Registered

| MCP Entity | URI / Name | Description |
| - | - | - |
| Resource | `state://{name}` | Full state snapshot |
| Resource | `state://{name}/{selectorKey}` | Each selector as a sub-resource |
| Tool | `{name}_{actionKey}` | Each action as a callable tool |

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | — | **Required.** Name prefix for resources and tools |
| `getState` | `() => unknown` | — | **Required.** Returns current state snapshot |
| `subscribe` | `(cb: () => void) => () => void` | — | **Required.** Subscribe to changes, return unsubscribe |
| `selectors` | `Record<string, (state) => unknown>` | — | Named selectors, each becomes a sub-resource |
| `actions` | `Record<string, (...args) => unknown>` | — | Named actions, each becomes a tool |
| `server` | `string` | — | Target a named server |

### Live Updates

When the store changes, the main resource's read function automatically returns fresh state. The hook subscribes to your store and notifies the `DynamicRegistry` on every change so consumers re-read the latest value.

***

## useReduxResource

A thin wrapper for Redux stores. Automatically binds `getState`, `subscribe`, and wraps action creators to auto-dispatch.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { useReduxResource } from '@frontmcp/react/state';
import { store } from './store';
import { increment, addTodo } from './slices';

function ReduxBridge() {
  useReduxResource({
    store,
    name: 'redux',
    selectors: {
      todos: (state) => (state as { todos: unknown }).todos,
      count: (state) => (state as { counter: { value: number } }).counter.value,
    },
    actions: {
      increment: () => increment(),
      addTodo: (text: unknown) => addTodo(text as string),
    },
  });

  return null;
}
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `store` | `{ getState, dispatch, subscribe }` | — | **Required.** Redux store |
| `name` | `string` | `'redux'` | Name prefix |
| `selectors` | `Record<string, (state) => unknown>` | — | Named selectors |
| `actions` | `Record<string, (...args) => action>` | — | Action creators (auto-dispatched) |
| `server` | `string` | — | Target a named server |

***

## useValtioResource

A thin wrapper for [Valtio](https://github.com/pmndrs/valtio) proxies. Supports deep path selectors with dot notation.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { useValtioResource } from '@frontmcp/react/state';
import { subscribe } from 'valtio/utils';
import { state } from './store';

function ValtioBridge() {
  useValtioResource({
    proxy: state,
    subscribe,
    name: 'valtio',
    paths: {
      userName: 'user.profile.name',
      theme: 'settings.theme',
      cartCount: 'cart.items.length',
    },
    mutations: {
      setTheme: (theme: unknown) => {
        state.settings.theme = theme as string;
      },
      clearCart: () => {
        state.cart.items = [];
      },
    },
  });

  return null;
}
```

### Options

| Option | Type | Default | Description |
| - | - | - | - |
| `proxy` | `Record<string, unknown>` | — | **Required.** Valtio proxy object |
| `subscribe` | `(proxy, cb) => () => void` | — | **Required.** Valtio's subscribe function |
| `name` | `string` | `'valtio'` | Name prefix |
| `paths` | `Record<string, string>` | — | Deep path selectors (dot notation) |
| `mutations` | `Record<string, (...args) => void>` | — | Named mutations (each becomes a tool) |
| `server` | `string` | — | Target a named server |

<Note>
  You must pass valtio's `subscribe` function yourself since valtio is an optional peer dependency. Import it from `valtio/utils`.
</Note>

***

## Provider-Level Store Adapters

Instead of using hooks inside components, you can register stores directly on the `FrontMcpProvider` via the `stores` prop. This is useful when you want store registration to happen once at the top level.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { FrontMcpProvider, reduxStore, valtioStore, createStore } from '@frontmcp/react';

<FrontMcpProvider
  server={server}
  stores={[
    reduxStore({
      store: myReduxStore,
      selectors: { count: (s) => s.count },
      actions: { increment: () => increment() },
    }),
    valtioStore({
      proxy: state,
      subscribe,
      paths: { userName: 'user.name' },
    }),
    createStore({
      name: 'custom',
      getState: () => customState,
      subscribe: (cb) => customSubscribe(cb),
    }),
  ]}
>
  <App />
</FrontMcpProvider>
```

### reduxStore

Adapter factory for Redux stores. Wraps action creators to auto-dispatch.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { reduxStore } from '@frontmcp/react/state';

reduxStore({
  store: myReduxStore,
  name: 'redux',                    // optional, defaults to 'redux'
  selectors: { count: (s) => s.counter.value },
  actions: { increment: () => increment() },
})
```

| Option | Type | Default | Description |
| - | - | - | - |
| `store` | `{ getState, dispatch, subscribe }` | — | **Required.** Redux store |
| `name` | `string` | `'redux'` | Logical name |
| `selectors` | `Record<string, (state) => unknown>` | — | Named selectors |
| `actions` | `Record<string, (...args) => action>` | — | Action creators (auto-dispatched) |

### valtioStore

Adapter factory for Valtio proxies. Supports deep path selectors.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { valtioStore } from '@frontmcp/react/state';
import { subscribe } from 'valtio/utils';

valtioStore({
  proxy: state,
  subscribe,
  name: 'valtio',                   // optional, defaults to 'valtio'
  paths: { userName: 'user.profile.name' },
  mutations: { setName: (name) => { state.user.profile.name = name; } },
})
```

| Option | Type | Default | Description |
| - | - | - | - |
| `proxy` | `Record<string, unknown>` | — | **Required.** Valtio proxy |
| `subscribe` | `(proxy, cb) => () => void` | — | **Required.** Valtio subscribe |
| `name` | `string` | `'valtio'` | Logical name |
| `paths` | `Record<string, string>` | — | Deep path selectors (dot notation) |
| `mutations` | `Record<string, (...args) => void>` | — | Named mutations |

### createStore

Generic pass-through adapter for any custom store.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { createStore } from '@frontmcp/react/state';

createStore({
  name: 'myStore',
  getState: () => store.getState(),
  subscribe: (cb) => store.subscribe(cb),
  selectors: { count: (s) => s.count },
  actions: { reset: () => store.reset() },
})
```

| Option | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | — | **Required.** Logical name |
| `getState` | `() => unknown` | — | **Required.** Returns state snapshot |
| `subscribe` | `(cb) => () => void` | — | **Required.** Subscribe to changes |
| `selectors` | `Record<string, (state) => unknown>` | — | Named selectors |
| `actions` | `Record<string, (...args) => unknown>` | — | Named actions |

### StoreAdapter Interface

All adapter factories return a `StoreAdapter`:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface StoreAdapter {
  name: string;
  getState: () => unknown;
  subscribe: (cb: () => void) => () => void;
  selectors?: Record<string, (state: unknown) => unknown>;
  actions?: Record<string, (...args: unknown[]) => unknown>;
}
```

You can also create a `StoreAdapter` directly without using a factory.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.