@golemui/gui-mcp 0.16.0 → 0.16.2

package/lib.d.ts

@@ -0,0 +1,7 @@
+export { validateFormDefinition, VALIDATE_FORM_DEFINITION_TOOL, } from './tools/validate-form-definition';
+export type { ValidateInput, ValidateResult } from './tools/validate-form-definition';
+export { generateFromJsonSchema, GENERATE_FROM_JSON_SCHEMA_TOOL, } from './tools/generate-from-json-schema';
+export type { GenerateFromJsonSchemaInput, GenerateFromJsonSchemaResult, } from './tools/generate-from-json-schema';
+export { generateFromOpenapi, GENERATE_FROM_OPENAPI_TOOL } from './tools/generate-from-openapi';
+export { getWidgetSpec, GET_WIDGET_SPEC_TOOL } from './tools/get-widget-spec';
+export { getConcept, GET_CONCEPT_TOOL } from './tools/get-concept';

package/lib.js

@@ -0,0 +1,13 @@
+import { G, b, f, d, V, g, a, e, c, v } from "./get-concept-CHgtnDXr.js";
+export {
+  G as GENERATE_FROM_JSON_SCHEMA_TOOL,
+  b as GENERATE_FROM_OPENAPI_TOOL,
+  f as GET_CONCEPT_TOOL,
+  d as GET_WIDGET_SPEC_TOOL,
+  V as VALIDATE_FORM_DEFINITION_TOOL,
+  g as generateFromJsonSchema,
+  a as generateFromOpenapi,
+  e as getConcept,
+  c as getWidgetSpec,
+  v as validateFormDefinition
+};

package/lint/reactive-expressions.d.ts

@@ -0,0 +1,18 @@
+export type ExpressionFinding = {
+    path: string;
+    expression: string;
+    message: string;
+    suggestion?: string;
+};
+/**
+ * Lints reactive expressions inside a form definition without executing them.
+ * GolemUI expressions are evaluated by the `subscript` package; here we only catch
+ * mistakes that are obvious from the syntax:
+ *   - empty expressions
+ *   - unbalanced parentheses / brackets / braces
+ *   - missing `$form` prefix (LLMs sometimes write bare property names)
+ *   - common operator typos (`=` instead of `===`, `&` instead of `&&`)
+ *
+ * We deliberately don't try to fully parse: too easy to get false positives, too little gain.
+ */
+export declare function lintReactiveExpressions(formDefinition: unknown): ExpressionFinding[];

package/lint/string-interpolation.d.ts

@@ -0,0 +1,16 @@
+export type InterpolationFinding = {
+    path: string;
+    slot: string;
+    message: string;
+    suggestion?: string;
+};
+/**
+ * Lints `{{...}}` string interpolation templates inside a form definition without executing them.
+ * Catches mistakes that are obvious from the syntax:
+ *   - empty slots
+ *   - slots with no scope reference ($form, $meta, $errors, $formIsInvalid)
+ *   - unbalanced `{{` / `}}` delimiters
+ *   - assignment operator inside a slot (likely meant `===`)
+ *   - nested `{{` inside a slot (copy-paste error)
+ */
+export declare function lintStringInterpolations(formDefinition: unknown): InterpolationFinding[];

package/mapping/json-schema-to-gui.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic mapping from a JSON Schema (the form-data shape) to a GolemUI form definition.
+ *
+ * Handles the practical 80% of API/Zod-derived schemas:
+ *   - primitive properties (string/number/integer/boolean) with formats and constraints
+ *   - enum strings as `select` (≤ 6 options) or `dropdown` (more)
+ *   - nested objects rendered inline as `flex` layouts
+ *   - arrays of objects as `repeater` with a `flex` template
+ *
+ * Constructs unmapped: anything we can't cleanly express. They're returned as `unmapped[]`
+ * so the caller (and any LLM) can surface a partial form rather than a hard failure.
+ */
+export type JsonSchemaLike = {
+    type?: string | string[];
+    format?: string;
+    title?: string;
+    description?: string;
+    enum?: unknown[];
+    const?: unknown;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    default?: unknown;
+    required?: string[];
+    properties?: Record<string, JsonSchemaLike>;
+    items?: JsonSchemaLike;
+    oneOf?: JsonSchemaLike[];
+    anyOf?: JsonSchemaLike[];
+    $ref?: string;
+    [k: string]: unknown;
+};
+export type MapOptions = {
+    submitAction?: boolean;
+    submitLabel?: string;
+    layout?: 'vertical' | 'horizontal' | 'grid';
+};
+export type Unmapped = {
+    path: string;
+    reason: string;
+};
+export type MapResult = {
+    formDefinition: {
+        $schema: string;
+        form: unknown[];
+    };
+    unmapped: Unmapped[];
+};
+export declare function jsonSchemaToGui(schema: JsonSchemaLike, opts?: MapOptions): MapResult;

package/mapping/validator.d.ts

@@ -0,0 +1,29 @@
+import { JsonSchemaLike } from './json-schema-to-gui';
+export type StringValidator = {
+    type: 'string';
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    const?: unknown;
+    enum?: unknown[];
+};
+export type NumberValidator = {
+    type: 'number' | 'integer';
+    required?: boolean;
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+};
+export type BooleanValidator = {
+    type: 'boolean';
+    required?: boolean;
+    const?: unknown;
+};
+export type Validator = StringValidator | NumberValidator | BooleanValidator;
+export declare function buildStringValidator(s: JsonSchemaLike, required: boolean): StringValidator | undefined;
+export declare function buildNumberValidator(s: JsonSchemaLike, required: boolean, t: 'number' | 'integer'): NumberValidator | undefined;
+export declare function buildBooleanValidator(s: JsonSchemaLike, required: boolean): BooleanValidator | undefined;

package/package.json

@@ -1,23 +1,28 @@
 {
   "name": "@golemui/gui-mcp",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "Model Context Protocol server for GolemUI — gives AI coding assistants deterministic schema validation and form generation for GolemUI form definitions.",
   "type": "module",
-  "main": "./index.js",
-  "module": "./index.js",
-  "types": "./index.d.ts",
+  "main": "./lib.js",
+  "module": "./lib.js",
+  "types": "./lib.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
+      "types": "./lib.d.ts",
+      "import": "./lib.js"
     }
   },
   "bin": {
-    "golemui-mcp": "./index.js"
+    "golemui-mcp": "./cli.js"
   },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "*.js",
+    "*.d.ts",
+    "tools",
+    "mapping",
+    "schemas",
+    "utils",
+    "lint",
     "*.md"
   ],
   "keywords": [
@@ -29,10 +34,15 @@
     "json-schema"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
-    "@golemui/gui-schemas": "0.16.0"
+    "@golemui/gui-schemas": "0.16.2"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/schemas/ajv.d.ts

@@ -0,0 +1,5 @@
+import { default as Ajv2020 } from 'ajv/dist/2020.js';
+export type AjvInstance = Ajv2020;
+export declare function getAjv(): AjvInstance;
+export declare function getFormValidator(): import('ajv/dist/types').AnyValidateFunction<unknown>;
+export declare function getWidgetValidator(widgetSchemaId: string): import('ajv/dist/types').AnyValidateFunction<unknown> | undefined;

package/schemas/index.d.ts

@@ -0,0 +1,16 @@
+export type WidgetSchema = {
+    $id: string;
+    title?: string;
+    properties?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export declare const COMMON_SCHEMA: WidgetSchema;
+export declare const FORM_SCHEMA: WidgetSchema;
+export declare const LAYOUT_WIDGET_SCHEMA: WidgetSchema;
+export declare const VALIDATORS_SCHEMA: WidgetSchema;
+/**
+ * Component schemas, keyed by their widget `type` constant (the value of `properties.type.const`
+ * in each schema). These keys match the literal string a user puts in `type: '...'`.
+ */
+export declare const COMPONENT_SCHEMAS: Record<string, WidgetSchema>;
+export declare const ALL_SCHEMAS: WidgetSchema[];

package/schemas/shallow-validators.d.ts

@@ -0,0 +1,13 @@
+import { ValidateFunction } from 'ajv';
+export declare function getValidatorBranches(): readonly string[];
+/**
+ * Returns a validator that checks a GolemUI `validator` field against the branch corresponding
+ * to its `type` value (e.g. `type: 'string'` → stringValidator branch). Returns null if the
+ * validator's type isn't a known branch.
+ */
+export declare function getValidatorBranchValidator(validatorType: string): ValidateFunction | null;
+/**
+ * Returns a validator for the given widget type that checks the widget's own properties without
+ * recursing into nested widgets. Returns null if the widget type is unknown.
+ */
+export declare function getShallowWidgetValidator(widgetType: string): ValidateFunction | null;

package/tools/generate-from-json-schema.d.ts

@@ -0,0 +1,48 @@
+import { JsonSchemaLike } from '../mapping/json-schema-to-gui';
+import { validateFormDefinition } from './validate-form-definition';
+export type GenerateFromJsonSchemaInput = {
+    jsonSchema: JsonSchemaLike;
+    submitAction?: boolean;
+    submitLabel?: string;
+    layout?: 'vertical' | 'horizontal' | 'grid';
+};
+export type GenerateFromJsonSchemaResult = {
+    formDefinition: {
+        $schema: string;
+        form: unknown[];
+    };
+    unmapped: {
+        path: string;
+        reason: string;
+    }[];
+    validation: ReturnType<typeof validateFormDefinition>;
+};
+export declare function generateFromJsonSchema(input: GenerateFromJsonSchemaInput): GenerateFromJsonSchemaResult;
+export declare const GENERATE_FROM_JSON_SCHEMA_TOOL: {
+    readonly name: "generate_from_json_schema";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly jsonSchema: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+                readonly description: string;
+            };
+            readonly submitAction: {
+                readonly type: "boolean";
+                readonly description: "Append a submit button. Defaults to true.";
+            };
+            readonly submitLabel: {
+                readonly type: "string";
+                readonly description: "Label for the submit button when `submitAction` is true. Defaults to \"Submit\".";
+            };
+            readonly layout: {
+                readonly type: "string";
+                readonly enum: readonly ["vertical", "horizontal", "grid"];
+                readonly description: "Top-level layout. Defaults to vertical (one field per row).";
+            };
+        };
+        readonly required: readonly ["jsonSchema"];
+    };
+};

package/tools/generate-from-openapi.d.ts

@@ -0,0 +1,81 @@
+import { JsonSchemaLike } from '../mapping/json-schema-to-gui';
+import { validateFormDefinition } from './validate-form-definition';
+type OpenAPIDoc = {
+    openapi?: string;
+    components?: {
+        schemas?: Record<string, JsonSchemaLike>;
+    };
+    paths?: Record<string, Record<string, OpenAPIOperation>>;
+};
+type OpenAPIOperation = {
+    operationId?: string;
+    summary?: string;
+    requestBody?: {
+        content?: Record<string, {
+            schema?: JsonSchemaLike;
+        }>;
+    };
+    parameters?: Array<{
+        name: string;
+        in: string;
+        required?: boolean;
+        schema?: JsonSchemaLike;
+        description?: string;
+    }>;
+};
+export type GenerateFromOpenapiInput = {
+    document?: OpenAPIDoc;
+    documentUrl?: string;
+    operation: string;
+    submitAction?: boolean;
+    submitLabel?: string;
+};
+export type GenerateFromOpenapiResult = {
+    resolvedOperation: {
+        method: string;
+        path: string;
+        operationId?: string;
+    };
+    formDefinition: {
+        $schema: string;
+        form: unknown[];
+    };
+    unmapped: {
+        path: string;
+        reason: string;
+    }[];
+    validation: ReturnType<typeof validateFormDefinition>;
+};
+export declare function generateFromOpenapi(input: GenerateFromOpenapiInput): Promise<GenerateFromOpenapiResult>;
+export declare const GENERATE_FROM_OPENAPI_TOOL: {
+    readonly name: "generate_from_openapi";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly documentUrl: {
+                readonly type: "string";
+                readonly description: "URL of a JSON OpenAPI document. Either this or `document` is required.";
+            };
+            readonly document: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+                readonly description: "Parsed OpenAPI document (JSON object). Either this or `documentUrl` is required.";
+            };
+            readonly operation: {
+                readonly type: "string";
+                readonly description: string;
+            };
+            readonly submitAction: {
+                readonly type: "boolean";
+                readonly description: "Append a submit button. Defaults to true.";
+            };
+            readonly submitLabel: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["operation"];
+    };
+};
+export {};

package/tools/get-concept.d.ts

@@ -0,0 +1,30 @@
+export type GetConceptInput = {
+    concept: string;
+};
+export type ConceptPattern = {
+    name: string;
+    description: string;
+    example: unknown;
+};
+export type GetConceptResult = {
+    concept: string;
+    summary: string;
+    patterns: ConceptPattern[];
+    rules: string[];
+};
+export declare function getConcept(input: GetConceptInput): GetConceptResult;
+export declare const GET_CONCEPT_TOOL: {
+    readonly name: "get_concept";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly concept: {
+                readonly type: "string";
+                readonly description: "The concept to explain. Currently supported: `\"states\"`, `\"string-interpolation\"`.";
+                readonly enum: string[];
+            };
+        };
+        readonly required: readonly ["concept"];
+    };
+};

package/tools/get-widget-spec.d.ts

@@ -0,0 +1,28 @@
+import { WidgetSchema } from '../schemas/index';
+export type GetWidgetSpecInput = {
+    widgetType: string;
+};
+export type GetWidgetSpecResult = {
+    widgetType: string;
+    schema: WidgetSchema;
+    kind: string;
+    example: Record<string, unknown>;
+    notes: string[];
+};
+export declare function getWidgetSpec(input: GetWidgetSpecInput): GetWidgetSpecResult;
+export declare function listWidgetTypes(): string[];
+export declare function getValidatorsSchema(): WidgetSchema;
+export declare const GET_WIDGET_SPEC_TOOL: {
+    readonly name: "get_widget_spec";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly widgetType: {
+                readonly type: "string";
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["widgetType"];
+    };
+};

package/tools/validate-form-definition.d.ts

@@ -0,0 +1,29 @@
+import { FormattedError } from '../utils/errors';
+import { ExpressionFinding } from '../lint/reactive-expressions';
+import { InterpolationFinding } from '../lint/string-interpolation';
+export type ValidateInput = {
+    formDefinition: unknown;
+};
+export type ValidateResult = {
+    valid: boolean;
+    errors: FormattedError[];
+    warnings: FormattedError[];
+    expressionWarnings: ExpressionFinding[];
+    interpolationWarnings: InterpolationFinding[];
+};
+export declare function validateFormDefinition(input: ValidateInput): ValidateResult;
+export declare const VALIDATE_FORM_DEFINITION_TOOL: {
+    readonly name: "validate_form_definition";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly formDefinition: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["formDefinition"];
+    };
+};

package/utils/errors.d.ts

@@ -0,0 +1,28 @@
+import { ErrorObject } from 'ajv';
+export type FormattedError = {
+    path: string;
+    message: string;
+    suggestion?: string;
+    keyword: string;
+    params?: Record<string, unknown>;
+};
+export type FormattedResult = {
+    errors: FormattedError[];
+    warnings: FormattedError[];
+};
+declare const STRING_FORMATS: string[];
+/**
+ * Formats ajv error objects into AI-friendly messages with concrete fix suggestions.
+ * Designed for the case where an LLM produced the form and needs to self-correct on next turn.
+ *
+ * When `dataRoot` is provided, `oneOf` branches at widget positions are collapsed to just the
+ * closest-matching branch — without this, a single `type: 'buton'` typo emits ~30 errors (one per
+ * non-matching branch + a summary), most of which are noise.
+ */
+export declare function formatAjvErrors(errors: ErrorObject[] | null | undefined, dataRoot?: unknown): FormattedResult;
+/**
+ * Best-effort widget context: given a JSON Pointer path into a form definition, returns the
+ * widget's `type` if discoverable. Used to add "in widget X" context to error messages.
+ */
+export declare function describePath(path: string): string;
+export { STRING_FORMATS };