Skip to content
{gui.}
TS APIJSON API

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. You can author a form two ways, and the server grounds both: as a JSON form definition, or as typed gui.* builder code in TypeScript. Either way your assistant calls the server to look up the real API, generate from an existing JSON Schema or OpenAPI operation, and check its work against the bundled GolemUI schemas — 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”

The server exposes eight tools across two authoring surfaces — a JSON form definition and the typed gui.* builder (TypeScript). Each surface has its own grounding lookups and its own validator.

ToolSurfaceWhat it does
json_generate_from_schemaJSONMap a JSON Schema (e.g. an API request body) to a validated form.
json_generate_from_openapiJSONMap a specific OpenAPI 3.x operation to a validated form.
json_get_widget_specJSONLook up one widget’s kind, props, and validator shape.
get_conceptJSONExplain a cross-cutting concept that spans widgets (e.g. states).
json_validate_form_definitionJSONCheck a JSON form definition against the bundled schemas.
dx_list_factoriesgui.*The complete gui.* builder reference in one call — call first when writing DX code.
dx_get_specgui.*Deep-dive on a single gui.* factory (rarely needed).
dx_check_codegui.*Type-check gui.* builder code against the real @golemui types.

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 look-up / generate → validate loop. Pick the surface that matches how you’re writing the form.

Writing a JSON form definition

Section titled “Writing a JSON form definition”
  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 json_generate_from_schema. For an OpenAPI 3.x spec, call json_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 json_get_widget_spec, and behavior that spans widgets — conditional rendering, per-state prop overrides — with get_concept.
  3. Always finish by calling json_validate_form_definition. Treat errors as blocking: fix them and re-validate until valid is true. warnings and expressionWarnings are advisory.

Writing typed gui.* builder code

Section titled “Writing typed gui.* builder code”

GolemUI isn’t in any model’s training data, so gui.* code is easy to fabricate — don’t guess the API.

  1. Call dx_list_factories first. It’s the complete reference in one call: every factory with a compile-verified example and its gotchas, the cross-cutting patterns, and imports tailored to your target framework. Write your whole form from it, importing gui only from @golemui/gui-shared. Reach for dx_get_spec only for a rare single-factory deep-dive.
  2. Always finish by calling dx_check_code. It type-checks the snippet against the real @golemui declarations and returns { ok, diagnostics } (each diagnostic carries a fix hint). Treat ok: false as blocking and re-check until ok is true.

dx_check_code is for gui.* code; json_validate_form_definition is for a JSON object — they are not interchangeable.

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

Next steps

Section titled “Next steps”