@golemui/gui-mcp 1.0.3 → 1.1.1-rc.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 1.1.0 (2026-07-21)
+
+### 🚀 Features
+
+- `$fn` host functions for reactive expressions ([#227](https://github.com/golemui/golemui/pull/227))
+- range time and range date time inputs ([#225](https://github.com/golemui/golemui/pull/225))
+- add $item / $index scope to repeater templates ([#222](https://github.com/golemui/golemui/pull/222))
+- add time and date-time inputs and input error localizable messages ([#220](https://github.com/golemui/golemui/pull/220))
+- add date time input ([#218](https://github.com/golemui/golemui/pull/218))
+- add time input ([#217](https://github.com/golemui/golemui/pull/217))
+
+### ❤️ Thank You
+
+- Mud Scientist @mudscientist
+- Raúl Jiménez @Elecash
+
+## 1.0.3 (2026-07-02)
+
+This was a version bump only for gui-mcp to align it with other projects, there were no code changes.
+
 ## 1.0.2 (2026-06-26)
 
 ### 🩹 Fixes

package/README.md

@@ -68,6 +68,22 @@ 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:
+
+```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
+```
+
+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`

package/cli-commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `golemui-mcp` CLI subcommands — the same two terminal checks the MCP serves
+ * (`json_validate_form_definition`, `dx_check_code`), runnable as one-off shell
+ * commands (`npx -y @golemui/gui-mcp <cmd> <file>`) so agents can verify a form
+ * without an MCP connector. Designed for agentic use: non-interactive, structured
+ * JSON on stdout, diagnostics on stderr, documented exit codes.
+ *
+ * Exit codes: 0 = check passed · 1 = check found problems · 2 = usage/file error.
+ */
+export interface CliIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/**
+ * Run one CLI subcommand. Returns the process exit code; never throws.
+ * `argv` is `process.argv.slice(2)`.
+ */
+export declare function runCli(argv: string[], io?: CliIo): Promise<number>;

package/cli.js

@@ -5,8 +5,89 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-import { r as resolveDxFramework, f as listDxFactoriesCatalog, b as DX_LIST_FACTORIES_TOOL, g as getDxSpec, a as DX_GET_SPEC_TOOL, d as checkDxCode, D as DX_CHECK_CODE_TOOL } from "./list-dx-factories-C-Z5Sc5E.js";
-import { v as validateFormDefinition, c as JSON_VALIDATE_FORM_DEFINITION_TOOL, g as generateFromJsonSchema, a as JSON_GENERATE_FROM_SCHEMA_TOOL, d as generateFromOpenapi, J as JSON_GENERATE_FROM_OPENAPI_TOOL, f as getWidgetSpec, b as JSON_GET_WIDGET_SPEC_TOOL, e as getConcept, G as GET_CONCEPT_TOOL } from "./get-concept-Py3iLVmb.js";
+import { d as checkDxCode, r as resolveDxFramework, f as listDxFactoriesCatalog, b as DX_LIST_FACTORIES_TOOL, g as getDxSpec, a as DX_GET_SPEC_TOOL, D as DX_CHECK_CODE_TOOL } from "./list-dx-factories-Dwy_BYZi.js";
+import { v as validateFormDefinition, c as JSON_VALIDATE_FORM_DEFINITION_TOOL, g as generateFromJsonSchema, a as JSON_GENERATE_FROM_SCHEMA_TOOL, d as generateFromOpenapi, J as JSON_GENERATE_FROM_OPENAPI_TOOL, f as getWidgetSpec, b as JSON_GET_WIDGET_SPEC_TOOL, e as getConcept, G as GET_CONCEPT_TOOL } from "./get-concept-DRFSt-XX.js";
+const USAGE = `Usage: golemui-mcp [command]
+
+Validate GolemUI forms from the command line (no MCP client needed).
+With no command, starts the MCP server on stdio.
+
+Commands:
+  validate-json <file.json>   Validate a JSON form definition ({ "form": [...] })
+                              against the bundled GolemUI JSON Schemas.
+  check-dx <file.ts>          Type-check a gui.* TypeScript snippet against the
+                              real @golemui type declarations.
+  help, --help, -h            Show this help.
+
+Output: a single JSON result on stdout.
+  validate-json → { valid, errors, warnings, expressionWarnings, interpolationWarnings }
+  check-dx      → { ok, diagnostics, expressionWarnings }
+
+Exit codes: 0 = valid/ok · 1 = invalid (fix the reported problems and re-run) ·
+2 = usage or file error.
+
+Examples:
+  npx -y @golemui/gui-mcp validate-json signup-form.json
+  npx -y @golemui/gui-mcp check-dx src/forms/signup.ts`;
+function readFileOr2(path, what, io) {
+  if (!path) {
+    io.err(`Error: missing <file> argument — the path of the ${what} to check.`);
+    io.err(USAGE);
+    return 2;
+  }
+  try {
+    return readFileSync(path, "utf-8");
+  } catch (e) {
+    io.err(`Error: cannot read ${path}: ${e.message}`);
+    return 2;
+  }
+}
+const defaultIo = {
+  out: (line) => process.stdout.write(line + "\n"),
+  err: (line) => process.stderr.write(line + "\n")
+};
+async function runCli(argv, io = defaultIo) {
+  const [command, fileArg] = argv;
+  switch (command) {
+    case "help":
+    case "--help":
+    case "-h": {
+      io.out(USAGE);
+      return 0;
+    }
+    case "validate-json": {
+      const raw = readFileOr2(fileArg, "JSON form definition", io);
+      if (typeof raw === "number") return raw;
+      let formDefinition;
+      try {
+        formDefinition = JSON.parse(raw);
+      } catch (e) {
+        io.err(`Error: ${fileArg} is not valid JSON: ${e.message}`);
+        return 2;
+      }
+      const result = validateFormDefinition({ formDefinition });
+      io.out(JSON.stringify(result, null, 2));
+      return result.valid ? 0 : 1;
+    }
+    case "check-dx": {
+      const code = readFileOr2(fileArg, "gui.* TypeScript snippet", io);
+      if (typeof code === "number") return code;
+      try {
+        const result = await checkDxCode({ code });
+        io.out(JSON.stringify(result, null, 2));
+        return result.ok ? 0 : 1;
+      } catch (e) {
+        io.err(`Error: ${e.message}`);
+        return 2;
+      }
+    }
+    default: {
+      io.err(`Error: unknown command "${command}". Valid commands: validate-json, check-dx, help.`);
+      io.err(USAGE);
+      return 2;
+    }
+  }
+}
 const DX_INSTRUCTIONS = "Writing GolemUI as DX code (the `gui.*` fluent builder in TypeScript) instead of a JSON definition? GolemUI is not in any model training data, so `gui.*` code is easy to fabricate — do NOT guess the API. FIRST call `dx_list_factories` once: it is the COMPLETE reference — every factory with its signature, a compile-verified example, and its gotchas, plus the cross-cutting patterns and common rules. Its imports + render snippet are tailored to your target framework (" + resolveDxFramework() + ") — use them verbatim; import `gui` ONLY from `@golemui/gui-shared`, never hand-write raw `{ kind, type, path }` widget JSON or cast to `any`. Keep it in context and write your whole form from it; it is self-sufficient for most forms. `dx_get_spec` is only a rare single-factory deep-dive — you usually will not need it, and you do NOT need `json_get_widget_spec` here (that is the JSON surface). Then ALWAYS finish by calling `dx_check_code` with the snippet — it type-checks against the real `@golemui` declarations and returns `{ ok, diagnostics }` (each with a fix `hint` for recognized mistakes). Treat `ok: false` as blocking: apply the fixes and re-check until `ok` is true. Use `dx_check_code` for `gui.*` *code* and `json_validate_form_definition` for a JSON *definition object* — they are not interchangeable.\n\n";
 function defineTool(tool, handler) {
   return { tool, run: (args) => handler(args) };
@@ -72,6 +153,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length > 0) {
+    process.exit(await runCli(argv));
+  }
   const transport = new StdioServerTransport();
   await server.connect(transport);
   process.stderr.write(`${PKG_NAME} v${PKG_VERSION} ready on stdio

package/dx/dx-specs.d.ts

@@ -9,10 +9,13 @@
  * compile gate is the cure.)
  */
 export type DxNamespace = 'inputs' | 'actions' | 'displays' | 'layouts';
+/** Widgets-reference URL group per namespace: `widgets-reference/<group>/<docSlug>.md`. */
+export declare const DOC_GROUP: Record<DxNamespace, string>;
 export interface DxSpec {
     /** Factory name, e.g. `textInput`. */
     factory: string;
     namespace: DxNamespace;
+    docSlug: string;
     /** Human-readable calling convention. */
     call: string;
     /** A compiling `gui.*` snippet (verified by the suite). */
@@ -20,6 +23,8 @@ export interface DxSpec {
     /** Authoring notes and gotchas. */
     notes: string[];
 }
+/** The absolute widgets-reference page URL for a factory (dx or json flavor). */
+export declare function dxDocUrl(spec: DxSpec, dsl?: 'dx' | 'json'): string;
 /**
  * A cross-cutting authoring pattern that is NOT a single factory — e.g. conditional
  * visibility, which is a common field available on every `gui.*` item. Same compile
@@ -67,4 +72,11 @@ export interface DxCatalog {
  */
 export declare function dxCatalog(framework?: DxFramework): DxCatalog;
 export declare function dxCommonNote(framework?: DxFramework): string;
+/**
+ * The per-framework host-wiring lines (imports + render + submit event), keyed by framework.
+ * The MCP serves one (selected by `GOLEMUI_FRAMEWORK`); the skill generator prints all five,
+ * since an installed skill serves whatever framework the host project uses.
+ */
+export declare function dxFrameworkSetup(): Record<DxFramework, string>;
+export declare function listDxFrameworks(): readonly DxFramework[];
 export declare function dxPatterns(): DxPattern[];