Skip to content
{gui.}

MCP Server

@golemui/gui-mcp is a Model Context Protocol server that gives AI coding assistants (Claude Code, Cursor, Windsurf, …) deterministic schema validation and form generation for GolemUI form definitions.

GolemUI forms are portable JSON — small enough that an LLM can emit them cleanly, strict enough that one wrong property name breaks the runtime. This server closes that gap: your assistant calls it to generate forms from existing JSON Schemas or OpenAPI operations, and to validate what it wrote against the bundled GolemUI schemas, which are the source of truth.

A form definition is a JSON-serializable object shaped as { form: [...widgets], states?: {...} }. See the Form Definition API for the full structure.

The tools at a glance

Section titled “The tools at a glance”
ToolWhat it does
generate_from_json_schemaMap a JSON Schema (e.g. an API request body) to a validated form.
generate_from_openapiMap a specific OpenAPI 3.x operation to a validated form.
get_widget_specLook up one widget’s kind, props, and validator shape.
get_conceptExplain a cross-cutting concept that spans widgets (e.g. states).
validate_form_definitionCheck a definition against the bundled JSON Schemas.

See the Tools Reference for inputs, outputs, and when to reach for each.

The workflow

Section titled “The workflow”

The server is built around a generate-then-validate loop:

  1. Starting from an existing schema? Use a generator — both return a pre-validated definition, so check the returned unmapped list and surface anything left over. For a raw JSON Schema (e.g. an API request body), call generate_from_json_schema. For an OpenAPI 3.x spec, call generate_from_openapi: pass operation as "METHOD /path" (e.g. "POST /users") or an exact operationId, plus the spec as a parsed document or a documentUrl to fetch — it resolves the operation’s request body, dereferences $refs, and falls back to the operation’s parameters when there is no request body.
  2. Building or editing by hand? Look up a single widget with get_widget_spec, and behavior that spans widgets — conditional rendering, per-state prop overrides — with get_concept.
  3. Always finish by calling validate_form_definition. Treat errors as blocking: fix them and re-validate until valid is true. warnings and expressionWarnings are advisory.

When the server is connected, the assistant receives this same workflow as part of the MCP handshake, so it knows the recommended order without reading these docs.

Next steps

Section titled “Next steps”