@golemui/gui-mcp

中文文档
2.2.1发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 2927

MCP server for GolemUI dynamic forms: gives AI coding assistants schema validation and form generation for GolemUI form definitions. Open source (MIT).

原始使用文档
文档目录20 节
  1. Two entry points (one surface, two ways to author it)
  2. Install
  3. Claude Code
  4. Cursor / Windsurf / other MCP-capable IDEs
  5. Verify
  6. CLI (no MCP client needed)
  7. Tools
  8. json_validate_form_definition
  9. json_generate_from_schema
  10. json_generate_from_openapi
  11. json_get_widget_spec
  12. get_concept
  13. dx_list_factories
  14. dx_get_spec
  15. dx_check_code
  16. Library usage
  17. Other runtimes and browsers
  18. Development
  19. Interactive testing with MCP Inspector
  20. Other development commands

@golemui/gui-mcp

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 schemas — small enough that an LLM can emit them cleanly, strict enough that one wrong property name breaks the runtime. This server closes the gap: your AI calls it to validate what it wrote and to generate forms from existing JSON Schemas or OpenAPI operations, with the bundled GolemUI schemas as the source of truth.

Two entry points (one surface, two ways to author it)

A GolemUI form can be written two ways, and the MCP serves both:

  • a JSON form definition: the serializable object { form: [...widgets], states?: {...} };
  • gui.* DX code: the fluent TypeScript builder that produces that same definition.

There is no toggle. On connect the server sends one block of guidance (the MCP initialize.instructions field, SERVER_INSTRUCTIONS in src/cli.ts) and the agent self-routes by what it is producing:

  1. JSON path: generate or hand-author, then always finish with json_validate_form_definition.
  2. gui.* path: call dx_list_factories first (the complete reference), write the form, then always finish with dx_check_code.

The two terminal checks are not interchangeable: dx_check_code validates gui.* code, json_validate_form_definition validates a JSON object. Each tool's own description reinforces the routing (e.g. json_get_widget_spec tells a gui.* author it isn't needed). To read what a client actually sees, run npm run start:mcp (the MCP Inspector).

The split is structural, not just textual: the two paths live in separate modules (src/json/ and src/dx/) over a small shared surface (src/shared/); neither imports the other.

Install

The server is a standalone Node CLI distributed on npm. Add it to your IDE's MCP config — no project install required.

Claude Code

claude mcp add golemui -- npx -y @golemui/gui-mcp

Or paste this into ~/.claude/settings.json (or your project's .mcp.json):

{
  "mcpServers": {
    "golemui": {
      "command": "npx",
      "args": ["-y", "@golemui/gui-mcp"]
    }
  }
}

Cursor / Windsurf / other MCP-capable IDEs

Same config — point an mcpServers.golemui entry at npx -y @golemui/gui-mcp.

Verify

npx -y @golemui/gui-mcp < /dev/null
# → @golemui/gui-mcp v0.0.1 ready on stdio

CLI (no MCP client needed)

The two terminal checks are also plain subcommands of the same bin, so any shell — a CI step, a git hook, or an AI agent without an MCP connector — can verify a form:

npx -y @golemui/gui-mcp validate-json signup-form.json  # JSON definition → bundled schemas
npx -y @golemui/gui-mcp check-dx src/forms/signup.ts    # gui.* code → real @golemui types
npx -y @golemui/gui-mcp --help

Each prints a single JSON result on stdout (the same shape as the corresponding MCP tool) and exits 0 on pass, 1 when problems were found, 2 on usage or file errors. In restricted environments, install it as a devDependency (npm i -D @golemui/gui-mcp) and the same commands resolve the project-local bin with no network at run time.

Tools

json_validate_form_definition

Validates a GolemUI form definition against the bundled JSON Schemas. Returns { valid: true } on success, or a structured list of errors with JSON Pointer paths and concrete fix suggestions ("format: 'mail' is not valid — did you mean 'email'?"). Also lints reactive expressions (include.when, disabled.when, …) for common mistakes like missing $form. prefixes, single = in equality checks, and unbalanced brackets.

Input: { formDefinition: { form: [...], states?: {...} } }

json_generate_from_schema

Converts a JSON Schema (the form-data shape, e.g. a Zod-derived schema) into a GolemUI form definition, with fromJsonSchema from @golemui/schemas/json-schema and the gui preset from @golemui/gui-schemas/json-schema. It handles formats, enums, local $ref, allOf, nested objects, arrays, discriminated oneOf/anyOf, and if/then/else and dependent* as conditions and form states. The result is validated before it is returned.

diagnostics lists what the form cannot express exactly, each with a severity, a code, the data path and the JSON pointer into the input. unmapped repeats its errors and warnings as { path, reason }. rules and overrides choose other widgets: see the @golemui/schemas README.

Input: { jsonSchema, submitAction?, submitLabel?, layout?, rules?, overrides? }

json_generate_from_openapi

Resolves an OpenAPI 3.x operation (e.g. "POST /users" or an operationId) and converts its JSON request body, with its $refs into the document, like json_generate_from_schema. Falls back to the operation parameters when there is no object request body.

Input: { document | documentUrl, operation, submitAction?, submitLabel?, rules?, overrides? }

json_get_widget_spec

Returns the JSON Schema, kind, a minimal working example, and authoring notes for a single GolemUI widget. Cheaper than dumping the whole API into the model's context.

Input: { widgetType } (one of the widget type constants — textinput, dropdown, repeater, flex, etc.)

get_concept

Returns a detailed guide for a cross-cutting concept — things that span multiple widgets and affect the whole form: conditional rendering (include/exclude, named-state and inline when), state-suffixed props ("label.stateName": "..."), the reactive scope ($form, $meta, $errors, $formIsInvalid), and widget icons.

Input: { concept } — one of "states", "string-interpolation", "reactive-scope", "icons"

The five tools above serve the JSON surface. The three below serve the gui.* (DX code) surface — see Two entry points.

dx_list_factories

Call this first when writing gui.* code. Returns the complete gui.* DX reference in one call: every factory with its namespace, calling convention, a compile-verified example, and its gotchas — plus the cross-cutting patterns and the common authoring rules. Its imports + render snippet are tailored to your target framework (GOLEMUI_FRAMEWORK). Self-sufficient for most forms; keep it in context and write from it.

Input: none.

dx_get_spec

A rare single-factory deep-dive — one factory's calling convention, example, and notes. Usually unneeded (dx_list_factories already carries every factory); reach here only to re-confirm one in isolation.

Input: { factory } — the camelCase name (textInput, dropdown, radiogroup, button, …).

dx_check_code

The gui.* terminal check — the counterpart of json_validate_form_definition for code instead of a JSON object. Type-checks the snippet against the real @golemui type declarations (compile-is-truth: GolemUI isn't in any model's training data, so generated gui.* is often a confident fabrication that doesn't compile). Also catches two compiler-invisible footguns — a misplaced include/exclude on a gui.* spread, and reactive-expression mistakes in when strings. Returns { ok, diagnostics }; each diagnostic carries a fix hint. Treat ok: false as blocking.

Input: { code } — the gui.* snippet (a bare gui.inputs.* array is fine; the import is added if missing).

Library usage

The package also exports all tools as plain functions, so you can call them directly from Node.js apps, scripts, or other libraries without running an MCP server.

npm install @golemui/gui-mcp
import {
  validateFormDefinition,
  generateFromJsonSchema,
  generateFromOpenapi,
  getWidgetSpec,
  getConcept,
} from '@golemui/gui-mcp';

// Validate a form definition
const result = validateFormDefinition({ formDefinition: myForm });
if (!result.valid) console.error(result.errors);

// Generate a form from a JSON Schema
const { formDefinition, diagnostics } = generateFromJsonSchema({ jsonSchema: mySchema });

// Generate a form from an OpenAPI spec
const { formDefinition: userForm } = await generateFromOpenapi({
  documentUrl: 'https://example.com/openapi.json',
  operation: 'POST /users',
});

The tool descriptor objects (VALIDATE_FORM_DEFINITION_TOOL, GENERATE_FROM_JSON_SCHEMA_TOOL, ...) are also exported if you want to register the tools in your own MCP server.

Other runtimes and browsers

@golemui/gui-mcp/json has the JSON tools without the Node-only gui.* type check, so it bundles anywhere, Cloudflare Workers included. validateFormDefinition there is synchronous and loads the validators of every widget type.

In a browser, use @golemui/gui-mcp/json/lazy. Each widget type has its own validator module, and validateFormDefinitionAsync loads only the ones the form uses (about 50 KB gzipped for a typical form), then returns the same result as validateFormDefinition:

import { preload, validateFormDefinitionAsync } from '@golemui/gui-mcp/json/lazy';

// Optional: start loading the common validators before the first form arrives.
preload(['textinput', 'select']);

const result = await validateFormDefinitionAsync({ formDefinition: myForm });
if (!result.valid) console.error(result.errors);

No validator is compiled at runtime, so both entries work under a strict Content Security Policy (no unsafe-eval).

Development

Interactive testing with MCP Inspector

Start the MCP server and open a local web UI at http://localhost:5173

npm run start:mcp

To use the server from within Claude Code conversations, register with local Claude Code:

With the Claude code CLI

claude mcp add golemui-local -- node /Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/cli.js

Then restart or reload the session. The tools appear in Claude's tool list.

Remove with claude mcp remove golemui-local when done.

With the Claude code extension

Create or edit the project-level MCP config at .mcp.json in the workspace root:

{
  "mcpServers": {
    "golemui-local": {
      "command": "node",
      "args": ["/Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/cli.js"]
    }
  }
}

Then reload the VS Code window (Cmd+Shift+P -> "Developer: Reload Window"). The tools will appear in Claude's tool list for this workspace.

Remove the entry from .mcp.json when done.

Other development commands

npx nx run gui-mcp:vite:test     # run the test suite

版本与发布记录

@golemui/gui-mcp 共发布 60 个版本,首次发布于 2026/05/26;过去 12 个月发布了 60 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
2.2.1latest2026/11/16今天
2.2.1-rc.0next2026/11/16今天
2.2.02026/11/133 天前
2.2.0-rc.22026/11/133 天前
2.2.0-rc.12026/11/134 天前
2.2.0-rc.02026/11/124 天前

关于 @golemui/gui-mcp 的常见问题

@golemui/gui-mcp 是什么?

MCP server for GolemUI dynamic forms: gives AI coding assistants schema validation and form generation for GolemUI form definitions. Open source (MIT).

如何安装 @golemui/gui-mcp?

在项目目录运行 npm install @golemui/gui-mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 golemui-mcp,可以用 npx golemui-mcp 直接运行。

@golemui/gui-mcp 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@golemui/gui-mcp 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@golemui/gui-mcp 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@golemui/gui-mcp 可以商用吗?

@golemui/gui-mcp 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@golemui/gui-mcp 的下载量有多少?

根据 npm 官方下载统计,@golemui/gui-mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,927 次,日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@golemui/gui-mcp 还在维护吗?

最新版本 2.2.1 发布于 2026/11/16(今天);至今共发布 60 个版本,其中过去 12 个月发布了 60 个;首次发布于 2026/05/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。