mcpform-react

Frontend-only React library for schema-driven forms and MCP-compatible tool definitions.

Install

npm install mcpform-react

Peer dependencies:

• react >= 18
• react-dom >= 18

Quick Start

import { MCPForm, useMCPToolDefinition, type MCPSchema } from "mcpform-react";

const schema: MCPSchema = {
  fullName: { type: "string", required: true, description: "Customer full name" },
  age: { type: "number", description: "Customer age in years" },
  subscribed: { type: "boolean", description: "Newsletter opt-in" }
};

const tool = {
  name: "submit_profile",
  description: "Submit customer profile information"
};

export function ProfileForm(): JSX.Element {
  const toolDefinition = useMCPToolDefinition(tool, schema);

  return (
    <>
      <MCPForm
        tool={tool}
        schema={schema}
        onSubmit={(data) => {
          // Send data to your app logic.
          console.log(data);
        }}
        webMCP={{ mode: "both", autoSubmit: true }}
      />
      <pre>{JSON.stringify(toolDefinition, null, 2)}</pre>
    </>
  );
}

Public API

MCPForm

Schema-driven form component that:

• Renders inputs from a flat schema
• Validates required fields and primitive types
• Calls onSubmit with validated data
• Optionally exposes tools through WebMCP declarative and/or imperative mode

type MCPFormProps = {
  tool: {
    name: string;
    description?: string;
  };
  schema: MCPSchema;
  onSubmit: (data: Record<string, unknown>) => Promise<void> | void;
  webMCP?: {
    mode?: "declarative" | "imperative" | "both";
    autoSubmit?: boolean;
  };
};

useMCPToolDefinition(tool, schema)

Returns a memoized MCP-compatible tool definition:

const definition = useMCPToolDefinition(tool, schema);

Schema Model

type MCPField = {
  type: "string" | "number" | "boolean";
  required?: boolean;
  description?: string;
};

type MCPSchema = Record<string, MCPField>;

v1 constraints:

• Flat schema only
• No nested objects
• No arrays

Tool Definition Output

useMCPToolDefinition generates deterministic output with sorted properties:

{
  "name": "submit_profile",
  "description": "Submit customer profile information",
  "input_schema": {
    "type": "object",
    "properties": {
      "age": { "type": "number" },
      "fullName": { "type": "string" },
      "subscribed": { "type": "boolean" }
    },
    "required": ["fullName"]
  }
}

The package also exports utility helpers:

• generateInputSchema(schema)
• generateMCPToolDefinition(tool, schema)
• stringifyMCPToolDefinition(definition)
• validateMCPFormData(schema, values)

WebMCP Notes

webMCP.mode controls exposure strategy:

• "declarative": adds toolname, tooldescription, and toolparamdescription attributes
• "imperative": registers tool via navigator.modelContext
• "both" (default): enables both modes

webMCP.autoSubmit enables toolautosubmit attribute in declarative mode.

Links

• Full repository docs: https://github.com/mandarBadve/mcpform#readme
• Issues: https://github.com/mandarBadve/mcpform/issues

License

MIT