@golemui/gui-mcp 0.16.0 → 0.16.2

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 0.16.1 (2026-05-30)
+
+### 🚀 Features
+
+- **mcp:** expose tool functions as an importable library alongside the CLI ([#146](https://github.com/golemui/golemui/pull/146))
+
+### ❤️ Thank You
+
+- Mud Scientist
+
+## 0.16.0 (2026-05-30)
+
+### 🚀 Features
+
+- **core:** improved string interpolation with full expression support ([#143](https://github.com/golemui/golemui/pull/143))
+- **mcp:** add get_concept tool and fix reactive-expression lint ([#138](https://github.com/golemui/golemui/pull/138))
+
+### 🩹 Fixes
+
+- **schemas:** clean up and enrich JSON schema definitions ([#145](https://github.com/golemui/golemui/pull/145))
+
+### ❤️ Thank You
+
+- mudscientist
+- Raúl Jiménez @Elecash
+
 ## 0.15.1 (2026-05-27)
 
 This was a version bump only for gui-mcp to align it with other projects, there were no code changes.

package/README.md

@@ -82,6 +82,50 @@ single GolemUI widget. Cheaper than dumping the whole API into the model's conte
 **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. Use it when you need state-suffixed props
+(`"label.stateName": "..."`) or to reuse a condition across multiple widgets via
+`include`/`exclude`. Currently supported: `"states"`, `"string-interpolation"`.
+
+**Input:** `{ concept }` - one of `"states"`, `"string-interpolation"`
+
+## 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.
+
+```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 { form, unmapped } = generateFromJsonSchema({ jsonSchema: mySchema });
+
+// Generate a form from an OpenAPI spec
+const { form } = 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.
+
 ## How it stays accurate
 
 The server ships a frozen snapshot of the GolemUI JSON Schemas inside its npm package,
@@ -97,7 +141,7 @@ _grounding layer_ the host IDE's model calls into.
 
 ### Interactive testing with MCP Inspector
 
-Start the MCP server and open a local web UI at http://localhost:5173
+Start the MCP server and open a local web UI at <http://localhost:5173>
 
 ```bash
 npm run start:mcp
@@ -105,17 +149,17 @@ npm run start:mcp
 
 To use the server from within Claude Code conversations, register with local Claude Code:
 
-#### With the Calude code CLI
+#### With the Claude code CLI
 
 ```bash
-claude mcp add golemui-local -- node /Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/index.js
+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 Calude code extension
+#### With the Claude code extension
 
 Create or edit the project-level MCP config at .mcp.json in the workspace root:
 
@@ -124,7 +168,7 @@ 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/index.js"]
+      "args": ["/Users/{USER}/{...}/golem/golemui/dist/libs/gui/mcp/cli.js"]
     }
   }
 }

package/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+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 { V as VALIDATE_FORM_DEFINITION_TOOL, G as GENERATE_FROM_JSON_SCHEMA_TOOL, b as GENERATE_FROM_OPENAPI_TOOL, d as GET_WIDGET_SPEC_TOOL, f as GET_CONCEPT_TOOL, e as getConcept, c as getWidgetSpec, a as generateFromOpenapi, g as generateFromJsonSchema, v as validateFormDefinition } from "./get-concept-CHgtnDXr.js";
+function readPackageMeta() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [join(here, "package.json"), join(here, "..", "package.json")]) {
+    try {
+      const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+      if (pkg.name && pkg.version) return { name: pkg.name, version: pkg.version };
+    } catch {
+    }
+  }
+  return { name: "@golemui/gui-mcp", version: "0.0.0" };
+}
+const { name: PKG_NAME, version: PKG_VERSION } = readPackageMeta();
+const TOOLS = [
+  VALIDATE_FORM_DEFINITION_TOOL,
+  GENERATE_FROM_JSON_SCHEMA_TOOL,
+  GENERATE_FROM_OPENAPI_TOOL,
+  GET_WIDGET_SPEC_TOOL,
+  GET_CONCEPT_TOOL
+];
+const SERVER_INSTRUCTIONS = 'This server builds and validates GolemUI form definitions — declarative, JSON-serializable forms shaped as `{ form: [...widgets], states?: {...} }`. Its job is to help you produce a form definition that is guaranteed correct before the user pastes it into their codebase.\n\nRecommended workflow:\n1. 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 to the user. For a raw JSON Schema (e.g. an API request body), call `generate_from_json_schema`. For an OpenAPI 3.x spec, call `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 `$ref`s, and falls back to the operation\'s parameters when there is no request body.\n2. Building or editing by hand? Look up a single widget with `get_widget_spec` (its `kind`, `props`, and `validator` shape), and cross-cutting behavior that spans widgets — conditional rendering, per-state prop overrides — with `get_concept`.\n3. ALWAYS finish by calling `validate_form_definition`. It checks the definition against the bundled JSON Schemas and returns `{ valid, errors, warnings, expressionWarnings }`. Treat `errors` as blocking: fix them and re-validate until `valid` is true. `warnings` (likely-custom widgets) and `expressionWarnings` (linted reactive expressions) are advisory — surface them, but they do not flip `valid`.\n\nDo not hand a form definition to the user until `validate_form_definition` reports `valid: true`.';
+const server = new Server(
+  { name: PKG_NAME, version: PKG_VERSION },
+  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  try {
+    switch (name) {
+      case "validate_form_definition":
+        return ok(validateFormDefinition(args));
+      case "generate_from_json_schema":
+        return ok(generateFromJsonSchema(args));
+      case "generate_from_openapi":
+        return ok(await generateFromOpenapi(args));
+      case "get_widget_spec":
+        return ok(getWidgetSpec(args));
+      case "get_concept":
+        return ok(getConcept(args));
+      default:
+        return err(`Unknown tool: ${name}`);
+    }
+  } catch (e) {
+    return err(e.message);
+  }
+});
+function ok(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+  };
+}
+function err(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`${PKG_NAME} v${PKG_VERSION} ready on stdio
+`);
+}
+main().catch((e) => {
+  process.stderr.write(`${PKG_NAME} failed to start: ${e.stack ?? e}
+`);
+  process.exit(1);
+});