# @golemui/gui-mcp 中文文档

规范地址：https://npmcn.com/package/%40golemui/gui-mcp/

版本：2\.2\.1
npm 元数据更新时间：2026-11-16T10:58:56.633Z
中文译文更新时间：2026-11-16T19:06:39.741Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40golemui/gui-mcp
原文对照：https://npmcn.com/package/%40golemui/gui-mcp/?lang=original
项目主页：https://github.com/golemui/golemui#readme
源码仓库：https://github.com/golemui/golemui

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.1 MB，108 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：13 个
- 首次发布：2026-05-26T08:55:04.028Z
- 最新版本发布：2026-11-16T10:58:56.176Z
- 近 30 天下载量：2927（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：60（近 12 个月 60 个）

## 中文简介

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

## 安装

```sh
npm install @golemui/gui-mcp
```

也可以使用：`pnpm add @golemui/gui-mcp`、`yarn add @golemui/gui-mcp`、`bun add @golemui/gui-mcp`

## README

# @golemui/ gui- mcp (英语)

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

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`](https://npmcn.com/package/%40golemui/gui-mcp/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/`](https://npmcn.com/package/%40golemui/gui-mcp/src/json) 财务报告和审定财务报表 [`src/dx/`](https://npmcn.com/package/%40golemui/gui-mcp/src/dx)在一个小共享地表上 (单位:千美元)[`src/shared/`](https://npmcn.com/package/%40golemui/gui-mcp/src/shared); 既不进口另一个.

## 安装

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

### 克劳德代码

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

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

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

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

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

### 校验

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

## CLI( 不需要 MCP 客户端)

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

```bash
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请求机构 `$ref`s在文档中,像 `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代码)表面—— 见 [两个切入点](https://npmcn.com/package/%40golemui/gui-mcp/#readme-two-entry-points-one-surface-two-ways-to-author-it)。 。 。 .

### `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服务器的其他库.

```bash
npm install @golemui/gui-mcp
```

```ts
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`数字 :

```ts
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 (英语)](http://localhost:5173/)

```bash
npm run start:mcp
```

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

#### 用克洛德密码CLI

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

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

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

#### 使用 Claude 代码扩展

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

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

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

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

### 其他开发命令

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

## 常见问题

### @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 和提交记录判断。

