@golemui/gui-mcp

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

GolemUI 动态窗体的 MCP 服务器:给 AI 编码助手 schema 验证,并为 GolemUI 格式定义提供形式生成. 开源 (MIT).

中文使用文档
文档目录20 节
  1. 两个出入口(一个表面,两个写法)
  2. 安装
  3. 克劳德代码
  4. Cursor / Windsurf / 其他 MCP 有能力的IDEs
  5. 校验
  6. CLI( 不需要 MCP 客户端)
  7. 工具
  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. 图书馆使用情况
  17. 其他运行时间和浏览器
  18. 发展
  19. 与 MCP 检查员的互动测试
  20. 其他开发命令

@golemui/ gui- mcp (英语)

A 类 示范背景协议 给 AI 编码的服务器 助手(Claude Code, Cursor, Windsurf,.) 决定性的策略验证和形式 生成用于 戈莱姆UI 形式定义.

GolemUI形式是便携式的JSON schemas——小到一个LLM可以干净地发出它们, 严格到一个错误的属性名称打破运行时间。 此服务器会关闭空格 : 你的人工智能称它 验证 它写了什么 生成 从现有窗体 JSON Schemas或OpenAPI操作,以捆绑的GolemUI schemas为真源.

两个出入口(一个表面,两个写法)

一个GolemUI表可以写作两种方式,MCP服务两种方式:

  • (单位:千美元) JSON 形式定义: 可序列对象 { form: [...widgets], states?: {...} }· ;
  • gui.* DX 代码: 流畅的 TypeScript 构建器 生产 同一个定义.

没有切换。 连接服务器时, 发送一个方向块( MCP) initialize.instructions 字段, SERVER_INSTRUCTIONS 内 src/cli.ts和代理 自我路线是什么 生产:

  1. JSON 路径: 生成或手写,然后 总是用 json_validate_form_definition。 。 。 .
  2. gui.* 路径: 调用 dx_list_factories 第一个 (完整的参考文献),写表格,然后 总是用 dx_check_code。 。 。 .

两次终端检查不能互换: dx_check_code 验证 gui.* 代码, (中文(简体) ), json_validate_form_definition 验证 JSON 对象。每个工具本身 description 强化路径 (例如:. json_get_widget_spec 告诉一个 gui.* 作者不需要这样). 阅读客户端实际看到的东西,运行 npm run start:mcp (MCP检查员).

拆分是结构的, 不仅仅是文字的: 两条路径在不同的模块中运行 (单位:千美元)src/json/ 财务报告和审定财务报表 src/dx/在一个小共享地表上 (单位:千美元)src/shared/; 既不进口另一个.

安装

服务器是一个独立的节点CLI,在npm上分发. 添加到您的 IDE 的 MCP 配置中.. 不需要安装工程 .

克劳德代码

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

或把它贴入 ~/.claude/settings.json (或您的项目) .mcp.json:

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

Cursor / Windsurf / 其他 MCP 有能力的IDEs

相同的配置 - 点 an mcpServers.golemui 输入时间 npx -y @golemui/gui-mcp。 。 。 .

校验

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

CLI( 不需要 MCP 客户端)

这两个终端检查也是同一机箱的平面子命令,所以任何外壳——一个CI step, git hook, 或没有MCP连接器的AI代理——可以验证一种形式:

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

每个印出一个JSON在stdout上的结果(形状与相应的MCP工具相同) 和退出点 0 传球时, 1 当发现问题时, 2 使用或文件错误。 单位 限制环境,安装为可依赖性(npm i -D @golemui/gui-mcp)和 相同命令解析项目本地本位, 没有运行时的网络 .

工具

json_validate_form_definition

对照捆绑的JSON Schemas验证一个GolemUI形式定义. 回返 { valid: true } ,或带有 JSON 指针路径的结构化错误列表 和具体建议format: 'mail' 无效——你是说 'email'("). 也表示反应性表达式(include.when, (中文(简体) ), disabled.when) 常见错误 就像不见了一样 $form. 前缀, 单 = 平等检查, 和不平衡的括号.

输入 : { formDefinition: { form: [...], states?: {...} } }

json_generate_from_schema

将 JSON Schema( 窗体数据形状, 如 Zod- 衍生的 schema) 转换为 GolemUI 窗体定义,使用 fromJsonSchema 从 @golemui/schemas/json-schema 和贵来 预设从 @golemui/gui-schemas/json-schema它处理格式、enums、本地 $ref, (中文(简体) ), allOf、嵌入对象、阵列、歧视 oneOf编号 :anyOf,以及 if/then/else 财务报告和审定财务报表 dependent* 作为条件和形式。 结果在返回之前经过验证.

diagnostics 列出表单不能准确表达的内容,每个表单有一个 severity页:1 code, (中文(简体) ), 数据 path 和JSON关系 pointer 输入输入. unmapped 重复错误和 警告为 { path, reason }。 。 。 . rules 财务报告和审定财务报表 overrides 选择其他部件:见 @golemui/schemas 读取.

输入 : { jsonSchema, submitAction?, submitLabel?, layout?, rules?, overrides? }

json_generate_from_openapi

解析 OpenAPI 3.x 操作(例如:. "POST /users" 或一个 operationId和转换 其JSON请求机构 $refs在文档中,像 json_generate_from_schema。 。 。 . 在没有对象请求正文时倒回操作参数.

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

json_get_widget_spec

返回 JSON Schema, 类型, 最小工作示例, 并写入 a 单个 GolemUI 部件 。 比把整个API倒入模型的背景更便宜.

输入 : { widgetType } (一个部件) type 常数 - textinput, (中文(简体) ), dropdown, (中文(简体) ), repeater, (中文(简体) ), flex页:1

get_concept

返回交叉概念的详细指南——跨越多个部件的东西 并影响整个形式:有条件渲染(include编号 :exclude名称状态和 内入 when),状态后缀道具 ("label.stateName": "..."),反应范围 (单位:千美元)$form, (中文(简体) ), $meta, (中文(简体) ), $errors, (中文(简体) ), $formIsInvalid),和部件图标.

输入 : { concept } - 其中一个 "states", (中文(简体) ), "string-interpolation", (中文(简体) ), "reactive-scope", (中文(简体) ), "icons"

以上五种工具服务于 贾森 表面。 以下三者服务于 gui.* (DX代码)表面—— 见 两个切入点。 。 。 .

dx_list_factories

写作时先打这个 gui.* 代码. 返回完整数据 gui.* 一个呼叫中的 DX 引用: 每 工厂及其名称空间,呼叫会议,a 编译-核实 实例,以及其缺点——加上 交叉模式和共同的作者规则。 其进口品+成品片断为: 适应你的 目标框架 (单位:千美元)GOLEMUI_FRAMEWORK) (中文(简体) ). 多数形式自给自足;保持上下文并从其书写.

输入 : 无.

dx_get_spec

罕见的单因子深潜——一厂召会,例,和注. 通常不需要 (单位:千美元)dx_list_factories 所有工厂都已经搬走了 只能在这里重新确认一个被隔离的工厂.

输入 : { factory } - 骆驼Case名称(textInput, (中文(简体) ), dropdown, (中文(简体) ), radiogroup, (中文(简体) ), button(中文(简体) ).

dx_check_code

这个 gui.* 终端检查 - 对应方 json_validate_form_definition 页:1 代码 而不是一个JSON 对象。类型对照 真实 @golemui 类型声明 (汇编-真实:GolemUI) 没有在任何模型的训练数据, 所以生成 gui.* 常常是自信的编造 而不是 页:1 还捕获了两把编译器隐形脚枪——误用 include编号 :exclude 编号 gui.* 展开, 和反应表达错误 when 字符串。 回返 { ok, diagnostics };每个诊断带一个 修补 hint处理 ok: false 作为屏蔽.

输入 : { code } - 那个 gui.* 片断( 赤色) gui.inputs.* 数组是罚款;如果缺少,则添加导入.

图书馆使用情况

软件包还将所有工具导出为纯函数, 这样您就可以直接调用它们 从 Node.js 的应用程序,脚本,或者没有运行MCP服务器的其他库.

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',
});

工具描述对象(VALIDATE_FORM_DEFINITION_TOOL, (中文(简体) ), GENERATE_FROM_JSON_SCHEMA_TOOL, (...) (中文(简体) ) 如果您想要在自己的MCP服务器中注册这些工具,则导出.

其他运行时间和浏览器

@golemui/gui-mcp/json 没有节点的 JSON 工具 gui.* 类型检查,所以 随处都有包 包括Cloudflare工人. validateFormDefinition 有一个同步 并加载每个部件类型的验证符.

在浏览器中, 使用 @golemui/gui-mcp/json/lazy。每个部件类型都有自己的验证器模块, 财务报告和审定财务报表 validateFormDefinitionAsync 只装入窗体使用的( 约 50 KB gzipped for a) ,然后返回与 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);

运行时不编译验证器, 因此两个条目都在严格的内容安全下工作 政策(无) unsafe-eval) (中文(简体) ).

发展

与 MCP 检查员的互动测试

启动 MCP 服务器并打开本地网络用户界面 http://localhost:5173 (英语)

npm run start:mcp

要使用来自 Claude 代码对话的服务器, 请使用本地的 Claude 代码 注册 :

用克洛德密码CLI

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

然后重新启动或重新装入会话 。 这些工具出现在克洛德的工具列表中.

完成时用 Claude mcp 移除 golemui- local .

使用 Claude 代码扩展

在工作空间根 . mcp.json 创建或编辑工程级别 MCP 配置 :

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

然后重新装入VS代码窗口(Cmd+Shift+P - >"开发者:重新装入窗口"). 这些工具会出现在克洛德的工具列表中,用于这个工作空间.

完成时从.mcp.json中删除条目.

其他开发命令

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 是什么?

GolemUI 动态窗体的 MCP 服务器:给 AI 编码助手 schema 验证,并为 GolemUI 格式定义提供形式生成. 开源 (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 和提交记录判断。