@react-webmcp-kit/redux 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-webmcp-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @react-webmcp-kit/redux
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**[WebMCP](https://developer.chrome.com/docs/ai/webmcp)** adapters for **Redux Toolkit** slice/thunk actions and **RTK Query** endpoints.
+
+Requires [`@react-webmcp-kit/core`](https://www.npmjs.com/package/@react-webmcp-kit/core). Render inside Redux `<Provider>` and `McpProvider`.
+
+## Install
+
+```bash
+pnpm add @react-webmcp-kit/redux @react-webmcp-kit/core @reduxjs/toolkit react-redux use-webmcp-tool zod
+```
+
+## Slice / thunk tools
+
+Hoist tool defs and Zod schemas at module scope.
+
+```tsx
+'use client';
+
+import { z } from 'zod';
+import { McpReduxTools } from '@react-webmcp-kit/redux';
+import { cartSlice, selectCart } from './cartSlice';
+
+const addToCartSchema = z.object({
+  productId: z.string(),
+  qty: z.number().int().min(1),
+});
+
+const cartTools = [
+  {
+    name: 'add_to_cart',
+    description: 'Add a line item to the cart',
+    schema: addToCartSchema,
+    execute: (args, { dispatch, getState, signal }) => {
+      if (signal.aborted) throw new Error('Aborted');
+      dispatch(cartSlice.actions.addItem(args));
+      return { success: true, cart: selectCart(getState()) };
+    },
+  },
+];
+
+export function CartMcpTools() {
+  return <McpReduxTools tools={cartTools} />;
+}
+```
+
+`execute` receives `{ dispatch, getState, signal }`.
+
+## RTK Query tools
+
+Bind `endpoint.initiate(args)`. For one-shot agent reads:
+
+```tsx
+initiate: (args) =>
+  ordersApi.endpoints.getOrder.initiate(args, { subscribe: false, forceRefetch: true }),
+```
+
+```tsx
+import { z } from 'zod';
+import { McpRtkQueryTools } from '@react-webmcp-kit/redux';
+
+<McpRtkQueryTools
+  tools={[
+    {
+      name: 'fetch_order',
+      description: 'Load order by id',
+      schema: z.object({ orderId: z.string() }),
+      kind: 'query',
+      initiate: (args) => ordersApi.endpoints.getOrder.initiate(args),
+    },
+    {
+      name: 'update_order',
+      description: 'Patch an order',
+      schema: patchOrderSchema,
+      kind: 'mutation',
+      initiate: (args) => ordersApi.endpoints.updateOrder.initiate(args),
+    },
+  ]}
+/>
+```
+
+- `kind: 'query'` → `readOnlyHint: true`
+- `kind: 'mutation'` → `consequentialHint: true`
+- Results normalized with `formatRtkQueryResult` → `{ success, data }` / `{ success: false, error }`
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `McpReduxTools` | Dispatch-based tools |
+| `McpRtkQueryTools` | RTK Query `initiate` tools |
+| `formatRtkQueryResult` | Normalize RTK results for agents |
+
+## Demo
+
+See `apps/demo-concierge` in [webmcp-kit-react](https://github.com/stubbies/webmcp-kit-react).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import * as react from 'react';
+import { Dispatch, UnknownAction } from '@reduxjs/toolkit';
+import { z } from 'zod';
+
+type ToolAnnotations = {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+    consequentialHint?: boolean;
+};
+type ReduxToolContext<RootState = unknown, AppDispatch extends Dispatch = Dispatch> = {
+    dispatch: AppDispatch;
+    getState: () => RootState;
+    signal: AbortSignal;
+};
+type McpReduxToolDef<TArgs = unknown, TResult = unknown, RootState = unknown, AppDispatch extends Dispatch = Dispatch> = {
+    name: string;
+    description: string;
+    schema: z.ZodType<TArgs>;
+    execute: (args: TArgs, ctx: ReduxToolContext<RootState, AppDispatch>) => TResult | Promise<TResult>;
+    enabled?: boolean;
+    annotations?: ToolAnnotations;
+};
+type McpRtkQueryToolDef<TArgs = unknown> = {
+    name: string;
+    description: string;
+    schema: z.ZodType<TArgs>;
+    kind: 'query' | 'mutation';
+    /** Returns the RTK Query initiate thunk/action for the given args. */
+    initiate: (args: TArgs) => UnknownAction;
+    enabled?: boolean;
+    annotations?: ToolAnnotations;
+};
+
+/** Minimal shape returned from `dispatch(api.endpoints.x.initiate(...))`. */
+type RtkQueryDispatchResult = {
+    data?: unknown;
+    error?: unknown;
+    isSuccess?: boolean;
+    isError?: boolean;
+};
+type FormattedRtkSuccess = {
+    success: true;
+    data: unknown;
+};
+type FormattedRtkFailure = {
+    success: false;
+    error: {
+        status?: number | string;
+        message: string;
+        data?: unknown;
+    };
+};
+type FormattedRtkQueryResult = FormattedRtkSuccess | FormattedRtkFailure;
+declare function formatRtkQueryResult(result: RtkQueryDispatchResult): FormattedRtkQueryResult;
+
+type McpReduxToolsProps<RootState = unknown, AppDispatch extends Dispatch = Dispatch> = {
+    tools: McpReduxToolDef<any, any, RootState, AppDispatch>[];
+};
+/** Register WebMCP tools that dispatch Redux actions (render inside McpProvider + Provider). */
+declare function McpReduxTools<RootState = unknown, AppDispatch extends Dispatch = Dispatch>({ tools, }: McpReduxToolsProps<RootState, AppDispatch>): react.JSX.Element;
+type McpRtkQueryToolsProps = {
+    tools: McpRtkQueryToolDef<any>[];
+};
+/** Register WebMCP tools bound to RTK Query `endpoint.initiate()` (render inside McpProvider + Provider). */
+declare function McpRtkQueryTools({ tools }: McpRtkQueryToolsProps): react.JSX.Element;
+
+export { type FormattedRtkFailure, type FormattedRtkQueryResult, type FormattedRtkSuccess, type McpReduxToolDef, McpReduxTools, type McpReduxToolsProps, type McpRtkQueryToolDef, McpRtkQueryTools, type McpRtkQueryToolsProps, type ReduxToolContext, type RtkQueryDispatchResult, type ToolAnnotations, formatRtkQueryResult };

package/dist/index.js

@@ -0,0 +1,105 @@
+'use client';
+
+// src/index.tsx
+import { useMcpTool } from "@react-webmcp-kit/core";
+import { useDispatch, useStore } from "react-redux";
+
+// src/formatRtkQueryResult.ts
+function serializeRtkError(error) {
+  if (error == null) {
+    return { message: "Unknown RTK Query error" };
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  if (typeof error === "object") {
+    const err = error;
+    const status = err.status;
+    const data = err.data;
+    const message = typeof err.error === "string" ? err.error : typeof err.message === "string" ? err.message : status !== void 0 ? `Request failed (${String(status)})` : "Request failed";
+    return { status, message, data };
+  }
+  return { message: String(error) };
+}
+function formatRtkQueryResult(result) {
+  if (result.error !== void 0 && result.error !== null) {
+    return { success: false, error: serializeRtkError(result.error) };
+  }
+  if (result.data !== void 0) {
+    return { success: true, data: result.data };
+  }
+  if (result.isError) {
+    return { success: false, error: serializeRtkError(result.error) };
+  }
+  return { success: true, data: null };
+}
+
+// src/index.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function McpReduxToolRegistrar({
+  def,
+  dispatch,
+  getState
+}) {
+  useMcpTool({
+    name: def.name,
+    description: def.description,
+    schema: def.schema,
+    enabled: def.enabled ?? true,
+    annotations: def.annotations,
+    execute: (args, { signal }) => {
+      const ctx = { dispatch, getState, signal };
+      return def.execute(args, ctx);
+    }
+  });
+  return null;
+}
+function McpReduxTools({
+  tools
+}) {
+  const dispatch = useDispatch();
+  const store = useStore();
+  const getState = store.getState.bind(store);
+  return /* @__PURE__ */ jsx(Fragment, { children: tools.map((def) => /* @__PURE__ */ jsx(
+    McpReduxToolRegistrar,
+    {
+      def,
+      dispatch,
+      getState
+    },
+    def.name
+  )) });
+}
+function rtkAnnotations(kind, extra) {
+  const base = kind === "query" ? { readOnlyHint: true } : { consequentialHint: true };
+  return { ...base, ...extra };
+}
+function McpRtkQueryToolRegistrar({
+  def,
+  dispatch
+}) {
+  useMcpTool({
+    name: def.name,
+    description: def.description,
+    schema: def.schema,
+    enabled: def.enabled ?? true,
+    annotations: rtkAnnotations(def.kind, def.annotations),
+    execute: async (args, { signal }) => {
+      if (signal.aborted) throw new Error("Aborted");
+      const action = def.initiate(args);
+      const result = await dispatch(action);
+      return formatRtkQueryResult(result);
+    }
+  });
+  return null;
+}
+function McpRtkQueryTools({ tools }) {
+  const dispatch = useDispatch();
+  return /* @__PURE__ */ jsx(Fragment, { children: tools.map((def) => /* @__PURE__ */ jsx(McpRtkQueryToolRegistrar, { def, dispatch }, def.name)) });
+}
+export {
+  McpReduxTools,
+  McpRtkQueryTools,
+  formatRtkQueryResult
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx","../src/formatRtkQueryResult.ts"],"sourcesContent":["import type { Dispatch } from '@reduxjs/toolkit';\nimport { useMcpTool } from '@react-webmcp-kit/core';\nimport { useDispatch, useStore } from 'react-redux';\nimport { formatRtkQueryResult } from './formatRtkQueryResult';\nimport type { McpReduxToolDef, McpRtkQueryToolDef, ReduxToolContext } from './types';\n\nexport { formatRtkQueryResult } from './formatRtkQueryResult';\nexport type {\n  FormattedRtkQueryResult,\n  FormattedRtkFailure,\n  FormattedRtkSuccess,\n  RtkQueryDispatchResult,\n} from './formatRtkQueryResult';\nexport type {\n  McpReduxToolDef,\n  McpRtkQueryToolDef,\n  ReduxToolContext,\n  ToolAnnotations,\n} from './types';\n\nfunction McpReduxToolRegistrar<\n  TArgs,\n  TResult,\n  RootState,\n  AppDispatch extends Dispatch,\n>({\n  def,\n  dispatch,\n  getState,\n}: {\n  def: McpReduxToolDef<TArgs, TResult, RootState, AppDispatch>;\n  dispatch: AppDispatch;\n  getState: () => RootState;\n}) {\n  useMcpTool({\n    name: def.name,\n    description: def.description,\n    schema: def.schema,\n    enabled: def.enabled ?? true,\n    annotations: def.annotations,\n    execute: (args: TArgs, { signal }) => {\n      const ctx: ReduxToolContext<RootState, AppDispatch> = { dispatch, getState, signal };\n      return def.execute(args, ctx);\n    },\n  });\n  return null;\n}\n\nexport type McpReduxToolsProps<\n  RootState = unknown,\n  AppDispatch extends Dispatch = Dispatch,\n> = {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  tools: McpReduxToolDef<any, any, RootState, AppDispatch>[];\n};\n\n/** Register WebMCP tools that dispatch Redux actions (render inside McpProvider + Provider). */\nexport function McpReduxTools<RootState = unknown, AppDispatch extends Dispatch = Dispatch>({\n  tools,\n}: McpReduxToolsProps<RootState, AppDispatch>) {\n  const dispatch = useDispatch<AppDispatch>();\n  const store = useStore<RootState>();\n  const getState = store.getState.bind(store);\n\n  return (\n    <>\n      {tools.map((def) => (\n        <McpReduxToolRegistrar\n          key={def.name}\n          def={def}\n          dispatch={dispatch}\n          getState={getState}\n        />\n      ))}\n    </>\n  );\n}\n\nfunction rtkAnnotations(kind: 'query' | 'mutation', extra?: McpRtkQueryToolDef['annotations']) {\n  const base =\n    kind === 'query'\n      ? { readOnlyHint: true as const }\n      : { consequentialHint: true as const };\n  return { ...base, ...extra };\n}\n\nfunction McpRtkQueryToolRegistrar<TArgs>({\n  def,\n  dispatch,\n}: {\n  def: McpRtkQueryToolDef<TArgs>;\n  dispatch: Dispatch;\n}) {\n  useMcpTool({\n    name: def.name,\n    description: def.description,\n    schema: def.schema,\n    enabled: def.enabled ?? true,\n    annotations: rtkAnnotations(def.kind, def.annotations),\n    execute: async (args: TArgs, { signal }) => {\n      if (signal.aborted) throw new Error('Aborted');\n      const action = def.initiate(args);\n      const result = await dispatch(action as Parameters<typeof dispatch>[0]);\n      return formatRtkQueryResult(result as { data?: unknown; error?: unknown; isError?: boolean });\n    },\n  });\n  return null;\n}\n\nexport type McpRtkQueryToolsProps = {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  tools: McpRtkQueryToolDef<any>[];\n};\n\n/** Register WebMCP tools bound to RTK Query `endpoint.initiate()` (render inside McpProvider + Provider). */\nexport function McpRtkQueryTools({ tools }: McpRtkQueryToolsProps) {\n  const dispatch = useDispatch();\n\n  return (\n    <>\n      {tools.map((def) => (\n        <McpRtkQueryToolRegistrar key={def.name} def={def} dispatch={dispatch} />\n      ))}\n    </>\n  );\n}\n","/** Minimal shape returned from `dispatch(api.endpoints.x.initiate(...))`. */\nexport type RtkQueryDispatchResult = {\n  data?: unknown;\n  error?: unknown;\n  isSuccess?: boolean;\n  isError?: boolean;\n};\n\nexport type FormattedRtkSuccess = { success: true; data: unknown };\nexport type FormattedRtkFailure = {\n  success: false;\n  error: { status?: number | string; message: string; data?: unknown };\n};\nexport type FormattedRtkQueryResult = FormattedRtkSuccess | FormattedRtkFailure;\n\nfunction serializeRtkError(error: unknown): FormattedRtkFailure['error'] {\n  if (error == null) {\n    return { message: 'Unknown RTK Query error' };\n  }\n  if (typeof error === 'string') {\n    return { message: error };\n  }\n  if (typeof error === 'object') {\n    const err = error as Record<string, unknown>;\n    const status = err.status as number | string | undefined;\n    const data = err.data;\n    const message =\n      typeof err.error === 'string'\n        ? err.error\n        : typeof err.message === 'string'\n          ? err.message\n          : status !== undefined\n            ? `Request failed (${String(status)})`\n            : 'Request failed';\n    return { status, message, data };\n  }\n  return { message: String(error) };\n}\n\nexport function formatRtkQueryResult(result: RtkQueryDispatchResult): FormattedRtkQueryResult {\n  if (result.error !== undefined && result.error !== null) {\n    return { success: false, error: serializeRtkError(result.error) };\n  }\n  if (result.data !== undefined) {\n    return { success: true, data: result.data };\n  }\n  if (result.isError) {\n    return { success: false, error: serializeRtkError(result.error) };\n  }\n  return { success: true, data: null };\n}\n"],"mappings":";;;AACA,SAAS,kBAAkB;AAC3B,SAAS,aAAa,gBAAgB;;;ACatC,SAAS,kBAAkB,OAA8C;AACvE,MAAI,SAAS,MAAM;AACjB,WAAO,EAAE,SAAS,0BAA0B;AAAA,EAC9C;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,EAAE,SAAS,MAAM;AAAA,EAC1B;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,UAAM,MAAM;AACZ,UAAM,SAAS,IAAI;AACnB,UAAM,OAAO,IAAI;AACjB,UAAM,UACJ,OAAO,IAAI,UAAU,WACjB,IAAI,QACJ,OAAO,IAAI,YAAY,WACrB,IAAI,UACJ,WAAW,SACT,mBAAmB,OAAO,MAAM,CAAC,MACjC;AACV,WAAO,EAAE,QAAQ,SAAS,KAAK;AAAA,EACjC;AACA,SAAO,EAAE,SAAS,OAAO,KAAK,EAAE;AAClC;AAEO,SAAS,qBAAqB,QAAyD;AAC5F,MAAI,OAAO,UAAU,UAAa,OAAO,UAAU,MAAM;AACvD,WAAO,EAAE,SAAS,OAAO,OAAO,kBAAkB,OAAO,KAAK,EAAE;AAAA,EAClE;AACA,MAAI,OAAO,SAAS,QAAW;AAC7B,WAAO,EAAE,SAAS,MAAM,MAAM,OAAO,KAAK;AAAA,EAC5C;AACA,MAAI,OAAO,SAAS;AAClB,WAAO,EAAE,SAAS,OAAO,OAAO,kBAAkB,OAAO,KAAK,EAAE;AAAA,EAClE;AACA,SAAO,EAAE,SAAS,MAAM,MAAM,KAAK;AACrC;;;ADeI,mBAEI,WAFJ;AA7CJ,SAAS,sBAKP;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,aAAW;AAAA,IACT,MAAM,IAAI;AAAA,IACV,aAAa,IAAI;AAAA,IACjB,QAAQ,IAAI;AAAA,IACZ,SAAS,IAAI,WAAW;AAAA,IACxB,aAAa,IAAI;AAAA,IACjB,SAAS,CAAC,MAAa,EAAE,OAAO,MAAM;AACpC,YAAM,MAAgD,EAAE,UAAU,UAAU,OAAO;AACnF,aAAO,IAAI,QAAQ,MAAM,GAAG;AAAA,IAC9B;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAWO,SAAS,cAA4E;AAAA,EAC1F;AACF,GAA+C;AAC7C,QAAM,WAAW,YAAyB;AAC1C,QAAM,QAAQ,SAAoB;AAClC,QAAM,WAAW,MAAM,SAAS,KAAK,KAAK;AAE1C,SACE,gCACG,gBAAM,IAAI,CAAC,QACV;AAAA,IAAC;AAAA;AAAA,MAEC;AAAA,MACA;AAAA,MACA;AAAA;AAAA,IAHK,IAAI;AAAA,EAIX,CACD,GACH;AAEJ;AAEA,SAAS,eAAe,MAA4B,OAA2C;AAC7F,QAAM,OACJ,SAAS,UACL,EAAE,cAAc,KAAc,IAC9B,EAAE,mBAAmB,KAAc;AACzC,SAAO,EAAE,GAAG,MAAM,GAAG,MAAM;AAC7B;AAEA,SAAS,yBAAgC;AAAA,EACvC;AAAA,EACA;AACF,GAGG;AACD,aAAW;AAAA,IACT,MAAM,IAAI;AAAA,IACV,aAAa,IAAI;AAAA,IACjB,QAAQ,IAAI;AAAA,IACZ,SAAS,IAAI,WAAW;AAAA,IACxB,aAAa,eAAe,IAAI,MAAM,IAAI,WAAW;AAAA,IACrD,SAAS,OAAO,MAAa,EAAE,OAAO,MAAM;AAC1C,UAAI,OAAO,QAAS,OAAM,IAAI,MAAM,SAAS;AAC7C,YAAM,SAAS,IAAI,SAAS,IAAI;AAChC,YAAM,SAAS,MAAM,SAAS,MAAwC;AACtE,aAAO,qBAAqB,MAAgE;AAAA,IAC9F;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAQO,SAAS,iBAAiB,EAAE,MAAM,GAA0B;AACjE,QAAM,WAAW,YAAY;AAE7B,SACE,gCACG,gBAAM,IAAI,CAAC,QACV,oBAAC,4BAAwC,KAAU,YAApB,IAAI,IAAoC,CACxE,GACH;AAEJ;","names":[]}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@react-webmcp-kit/redux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Redux Toolkit and RTK Query adapters that expose actions and endpoints as WebMCP tools",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stubbies/webmcp-kit-react.git",
+    "directory": "packages/redux"
+  },
+  "homepage": "https://github.com/stubbies/webmcp-kit-react/tree/main/packages/redux#readme",
+  "bugs": {
+    "url": "https://github.com/stubbies/webmcp-kit-react/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@reduxjs/toolkit": ">=2",
+    "@react-webmcp-kit/core": "^0.1.0",
+    "react": ">=18",
+    "react-redux": ">=8",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "@reduxjs/toolkit": "^2.5.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "jsdom": "^26.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-redux": "^9.2.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "use-webmcp-tool": "^0.3.0",
+    "vitest": "^3.0.0",
+    "zod": "^3.24.1",
+    "@react-webmcp-kit/core": "0.1.0"
+  },
+  "keywords": [
+    "webmcp",
+    "mcp",
+    "react",
+    "redux",
+    "rtk-query",
+    "ai-agents"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
 }