@react-webmcp-kit/react-hook-form 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,81 @@
-# Temporary Holding Version
+# @react-webmcp-kit/react-hook-form
 
-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.
+Expose **[React Hook Form](https://react-hook-form.com/)** fields and submit handlers as **[WebMCP](https://developer.chrome.com/docs/ai/webmcp)** tools so agents can fill and submit forms safely.
+
+Requires [`@react-webmcp-kit/core`](https://www.npmjs.com/package/@react-webmcp-kit/core).
+
+## Install
+
+```bash
+pnpm add @react-webmcp-kit/react-hook-form @react-webmcp-kit/core react-hook-form use-webmcp-tool zod
+```
+
+## Usage
+
+Render inside `McpProvider`. Hoist field defs at module scope when possible.
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { z } from 'zod';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { McpFormTools, useMcpSubmitTool } from '@react-webmcp-kit/react-hook-form';
+
+const schema = z.object({
+  email: z.string().email(),
+  fullName: z.string().min(1),
+});
+
+type FormValues = z.infer<typeof schema>;
+
+const fields = [
+  { name: 'email' as const, description: 'Set checkout email' },
+  { name: 'fullName' as const, description: 'Set full name' },
+];
+
+export function CheckoutForm() {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(schema),
+    defaultValues: { email: '', fullName: '' },
+  });
+
+  useMcpSubmitTool({
+    name: 'submit_checkout',
+    description: 'Submit the checkout form',
+    form,
+    enabled: form.formState.isValid,
+    onSubmit: async (values) => {
+      // persist / navigate
+      return { success: true, values };
+    },
+  });
+
+  return (
+    <>
+      <McpFormTools form={form} fields={fields} />
+      <form onSubmit={form.handleSubmit((v) => console.log(v))}>{/* inputs */}</form>
+    </>
+  );
+}
+```
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `McpFormTools` | One `fill_*` tool per field (`toolName` optional; default `fill_<path>`) |
+| `useMcpSubmitTool` | Registers a submit tool that runs validation then your `onSubmit` |
+| `McpFormFieldDef` | `{ name, description, toolName?, schema? }` |
+
+Default field schema is `z.object({ value: z.string() })`. Pass a custom Zod schema when the agent should send structured values.
+
+Gate tools with `enabled` (e.g. disable submit until the cart is non-empty).
+
+## Demo
+
+See `apps/demo-checkout` in [webmcp-kit-react](https://github.com/stubbies/webmcp-kit-react).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import * as react from 'react';
+import { FieldValues, FieldPath, UseFormReturn } from 'react-hook-form';
+import { z } from 'zod';
+
+type McpFormFieldDef<T extends FieldValues> = {
+    name: FieldPath<T>;
+    description: string;
+    toolName?: string;
+    schema?: z.ZodTypeAny;
+};
+type McpFormToolsProps<T extends FieldValues> = {
+    form: UseFormReturn<T>;
+    fields: McpFormFieldDef<T>[];
+    enabled?: boolean;
+};
+/** Register one WebMCP tool per form field (render inside McpProvider). */
+declare function McpFormTools<T extends FieldValues>({ form, fields, enabled, }: McpFormToolsProps<T>): react.JSX.Element;
+type UseMcpSubmitToolOptions<T extends FieldValues> = {
+    form: UseFormReturn<T>;
+    name: string;
+    description: string;
+    enabled?: boolean;
+    onValidSubmit?: (values: T) => unknown | Promise<unknown>;
+};
+declare function useMcpSubmitTool<T extends FieldValues>({ form, name, description, enabled, onValidSubmit, }: UseMcpSubmitToolOptions<T>): {
+    supported: boolean;
+    registered: boolean;
+    error: Error | null;
+};
+/** @deprecated Use McpFormTools component instead (hooks cannot run in a loop). */
+declare function useMcpFormTools<T extends FieldValues>(_options: UseMcpFormToolsOptions<T>): void;
+type UseMcpFormToolsOptions<T extends FieldValues> = McpFormToolsProps<T>;
+
+export { type McpFormFieldDef, McpFormTools, type McpFormToolsProps, type UseMcpFormToolsOptions, type UseMcpSubmitToolOptions, useMcpFormTools, useMcpSubmitTool };

package/dist/index.js

@@ -0,0 +1,67 @@
+'use client';
+
+// src/index.tsx
+import { z } from "zod";
+import { useMcpTool } from "@react-webmcp-kit/core";
+import { Fragment, jsx } from "react/jsx-runtime";
+var DEFAULT_FIELD_SCHEMA = z.object({ value: z.string().describe("Field value") });
+function McpFormFieldTool({
+  form,
+  field,
+  enabled
+}) {
+  const toolName = field.toolName ?? `fill_${String(field.name).replace(/\./g, "_")}`;
+  const schema = field.schema ?? DEFAULT_FIELD_SCHEMA;
+  useMcpTool({
+    name: toolName,
+    description: field.description,
+    schema,
+    enabled,
+    execute: ({ value }) => {
+      form.setValue(field.name, value, { shouldValidate: true, shouldDirty: true });
+      return { success: true, field: field.name, value };
+    }
+  });
+  return null;
+}
+function McpFormTools({
+  form,
+  fields,
+  enabled = true
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: fields.map((field) => /* @__PURE__ */ jsx(McpFormFieldTool, { form, field, enabled }, String(field.name))) });
+}
+function useMcpSubmitTool({
+  form,
+  name,
+  description,
+  enabled = true,
+  onValidSubmit
+}) {
+  return useMcpTool({
+    name,
+    description,
+    schema: z.object({}),
+    enabled,
+    execute: () => new Promise((resolve) => {
+      void form.handleSubmit(
+        async (values) => {
+          const result = onValidSubmit ? await onValidSubmit(values) : { success: true, values };
+          resolve(result);
+        },
+        (errors) => {
+          resolve({ success: false, errors });
+        }
+      )();
+    })
+  });
+}
+function useMcpFormTools(_options) {
+  throw new Error("useMcpFormTools is removed; render <McpFormTools /> instead.");
+}
+export {
+  McpFormTools,
+  useMcpFormTools,
+  useMcpSubmitTool
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["import type { FieldPath, FieldValues, UseFormReturn } from 'react-hook-form';\nimport { z } from 'zod';\nimport { useMcpTool } from '@react-webmcp-kit/core';\n\nexport type McpFormFieldDef<T extends FieldValues> = {\n  name: FieldPath<T>;\n  description: string;\n  toolName?: string;\n  schema?: z.ZodTypeAny;\n};\n\nexport type McpFormToolsProps<T extends FieldValues> = {\n  form: UseFormReturn<T>;\n  fields: McpFormFieldDef<T>[];\n  enabled?: boolean;\n};\n\nconst DEFAULT_FIELD_SCHEMA = z.object({ value: z.string().describe('Field value') });\n\nfunction McpFormFieldTool<T extends FieldValues>({\n  form,\n  field,\n  enabled,\n}: {\n  form: UseFormReturn<T>;\n  field: McpFormFieldDef<T>;\n  enabled: boolean;\n}) {\n  const toolName = field.toolName ?? `fill_${String(field.name).replace(/\\./g, '_')}`;\n  const schema = field.schema ?? DEFAULT_FIELD_SCHEMA;\n\n  useMcpTool({\n    name: toolName,\n    description: field.description,\n    schema,\n    enabled,\n    execute: ({ value }: { value: string }) => {\n      form.setValue(field.name, value as never, { shouldValidate: true, shouldDirty: true });\n      return { success: true, field: field.name, value };\n    },\n  });\n\n  return null;\n}\n\n/** Register one WebMCP tool per form field (render inside McpProvider). */\nexport function McpFormTools<T extends FieldValues>({\n  form,\n  fields,\n  enabled = true,\n}: McpFormToolsProps<T>) {\n  return (\n    <>\n      {fields.map((field) => (\n        <McpFormFieldTool key={String(field.name)} form={form} field={field} enabled={enabled} />\n      ))}\n    </>\n  );\n}\n\nexport type UseMcpSubmitToolOptions<T extends FieldValues> = {\n  form: UseFormReturn<T>;\n  name: string;\n  description: string;\n  enabled?: boolean;\n  onValidSubmit?: (values: T) => unknown | Promise<unknown>;\n};\n\nexport function useMcpSubmitTool<T extends FieldValues>({\n  form,\n  name,\n  description,\n  enabled = true,\n  onValidSubmit,\n}: UseMcpSubmitToolOptions<T>) {\n  return useMcpTool({\n    name,\n    description,\n    schema: z.object({}),\n    enabled,\n    execute: () =>\n      new Promise((resolve) => {\n        void form.handleSubmit(\n          async (values) => {\n            const result = onValidSubmit ? await onValidSubmit(values) : { success: true, values };\n            resolve(result);\n          },\n          (errors) => {\n            resolve({ success: false, errors });\n          },\n        )();\n      }),\n  });\n}\n\n/** @deprecated Use McpFormTools component instead (hooks cannot run in a loop). */\nexport function useMcpFormTools<T extends FieldValues>(_options: UseMcpFormToolsOptions<T>): void {\n  throw new Error('useMcpFormTools is removed; render <McpFormTools /> instead.');\n}\n\nexport type UseMcpFormToolsOptions<T extends FieldValues> = McpFormToolsProps<T>;\n"],"mappings":";;;AACA,SAAS,SAAS;AAClB,SAAS,kBAAkB;AAkDvB,mBAEI,WAFJ;AAnCJ,IAAM,uBAAuB,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;AAEnF,SAAS,iBAAwC;AAAA,EAC/C;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,QAAM,WAAW,MAAM,YAAY,QAAQ,OAAO,MAAM,IAAI,EAAE,QAAQ,OAAO,GAAG,CAAC;AACjF,QAAM,SAAS,MAAM,UAAU;AAE/B,aAAW;AAAA,IACT,MAAM;AAAA,IACN,aAAa,MAAM;AAAA,IACnB;AAAA,IACA;AAAA,IACA,SAAS,CAAC,EAAE,MAAM,MAAyB;AACzC,WAAK,SAAS,MAAM,MAAM,OAAgB,EAAE,gBAAgB,MAAM,aAAa,KAAK,CAAC;AACrF,aAAO,EAAE,SAAS,MAAM,OAAO,MAAM,MAAM,MAAM;AAAA,IACnD;AAAA,EACF,CAAC;AAED,SAAO;AACT;AAGO,SAAS,aAAoC;AAAA,EAClD;AAAA,EACA;AAAA,EACA,UAAU;AACZ,GAAyB;AACvB,SACE,gCACG,iBAAO,IAAI,CAAC,UACX,oBAAC,oBAA0C,MAAY,OAAc,WAA9C,OAAO,MAAM,IAAI,CAA+C,CACxF,GACH;AAEJ;AAUO,SAAS,iBAAwC;AAAA,EACtD;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EACV;AACF,GAA+B;AAC7B,SAAO,WAAW;AAAA,IAChB;AAAA,IACA;AAAA,IACA,QAAQ,EAAE,OAAO,CAAC,CAAC;AAAA,IACnB;AAAA,IACA,SAAS,MACP,IAAI,QAAQ,CAAC,YAAY;AACvB,WAAK,KAAK;AAAA,QACR,OAAO,WAAW;AAChB,gBAAM,SAAS,gBAAgB,MAAM,cAAc,MAAM,IAAI,EAAE,SAAS,MAAM,OAAO;AACrF,kBAAQ,MAAM;AAAA,QAChB;AAAA,QACA,CAAC,WAAW;AACV,kBAAQ,EAAE,SAAS,OAAO,OAAO,CAAC;AAAA,QACpC;AAAA,MACF,EAAE;AAAA,IACJ,CAAC;AAAA,EACL,CAAC;AACH;AAGO,SAAS,gBAAuC,UAA2C;AAChG,QAAM,IAAI,MAAM,8DAA8D;AAChF;","names":[]}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@react-webmcp-kit/react-hook-form",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React Hook Form adapters that expose fill and submit fields as WebMCP tools for AI agents",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stubbies/webmcp-kit-react.git",
+    "directory": "packages/rhf"
+  },
+  "homepage": "https://github.com/stubbies/webmcp-kit-react/tree/main/packages/rhf#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": {
+    "@react-webmcp-kit/core": "^0.1.0",
+    "react": ">=18",
+    "react-hook-form": ">=7",
+    "zod": ">=3"
+  },
+  "devDependencies": {
+    "@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-hook-form": "^7.54.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",
+    "react-hook-form",
+    "forms",
+    "ai-agents"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
 }