jui-tools-mcp-server 2.5.0

package/dist/data/derived.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Derived / static content that the MCP server exposes alongside attribute definitions.
+ *
+ * These values do not depend on
+ * attribute_definitions.json — they encode platform conventions (modifier order,
+ * binding syntax, cross-platform value mapping). Kept in TS so the MCP can serve
+ * them at startup without any build step.
+ */
+export declare function categorizeCommonAttributes(commonAttrs: Record<string, any>): any;
+export declare const MODIFIER_ORDER: {
+    description: string;
+    swift: {
+        order: string[];
+        criticalRules: string[];
+    };
+    kotlin: {
+        order: string[];
+        criticalRules: string[];
+    };
+    react: {
+        note: string;
+        classOrder: string[];
+        dynamicStyles: string;
+    };
+};
+export declare const BINDING_RULES: {
+    description: string;
+    format: {
+        bindingExpression: string;
+        negation: string;
+        defaultValue: string;
+        nestedPath: string;
+    };
+    directions: {
+        "two-way": {
+            description: string;
+            swift: string;
+            kotlin: string;
+            react: string;
+            applicableAttributes: string[];
+        };
+        "read-only": {
+            description: string;
+            swift: string;
+            kotlin: string;
+            react: string;
+            applicableAttributes: string[];
+        };
+    };
+    criticalRules: string[];
+};
+export declare const PLATFORM_MAPPING: {
+    description: string;
+    values: {
+        matchParent: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        wrapContent: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+    contentMode: {
+        aspectFit: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        aspectFill: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        scaleToFill: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+    textAlign: {
+        left: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        center: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        right: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+    fontWeight: {
+        bold: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        light: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        thin: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        medium: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        semibold: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+    orientation: {
+        horizontal: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        vertical: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        none: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+    gravity: {
+        center: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        centerHorizontal: {
+            swift_vertical: string;
+            kotlin_vertical: string;
+            react: string;
+        };
+        centerVertical: {
+            swift_horizontal: string;
+            kotlin_horizontal: string;
+            react: string;
+        };
+    };
+    types: {
+        String: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Int: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Float: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Double: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Bool: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Array: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+        Dictionary: {
+            swift: string;
+            kotlin: string;
+            react: string;
+        };
+    };
+};

package/dist/data/derived.js

@@ -0,0 +1,293 @@
+/**
+ * Derived / static content that the MCP server exposes alongside attribute definitions.
+ *
+ * These values do not depend on
+ * attribute_definitions.json — they encode platform conventions (modifier order,
+ * binding syntax, cross-platform value mapping). Kept in TS so the MCP can serve
+ * them at startup without any build step.
+ */
+// ----- categorizeCommonAttributes ----------------------------------------
+const CATEGORY_KEYS = {
+    sizing: new Set([
+        "width", "height", "minWidth", "maxWidth", "minHeight", "maxHeight",
+        "weight", "widthWeight", "heightWeight", "maxWidthWeight", "maxHeightWeight",
+        "minWidthWeight", "minHeightWeight", "aspectWidth", "aspectHeight",
+        "aspectRatio", "frame", "rect", "wrapContent",
+    ]),
+    spacing: new Set([
+        "padding", "paddings", "paddingTop", "paddingBottom", "paddingLeft",
+        "paddingRight", "paddingStart", "paddingEnd", "rightPadding", "leftPadding",
+        "minTopPadding", "minBottomPadding", "minLeftPadding", "minRightPadding",
+        "maxTopPadding", "maxBottomPadding", "maxLeftPadding", "maxRightPadding",
+        "margins", "topMargin", "bottomMargin", "leftMargin", "rightMargin",
+        "startMargin", "endMargin", "minTopMargin", "minBottomMargin",
+        "minLeftMargin", "minRightMargin", "maxTopMargin", "maxBottomMargin",
+        "maxLeftMargin", "maxRightMargin", "innerPadding", "insets", "insetHorizontal",
+    ]),
+    visual: new Set([
+        "background", "tapBackground", "highlightBackground", "disabledBackground",
+        "defaultBackground", "cornerRadius", "borderWidth", "borderColor",
+        "borderStyle", "alpha", "opacity", "shadow", "clipToBounds", "tintColor",
+        "effectStyle",
+    ]),
+    visibility: new Set(["visibility", "hidden"]),
+    interaction: new Set([
+        "onclick", "onClick", "onLongPress", "onPan", "onPinch", "canTap",
+        "enabled", "userInteractionEnabled", "touchDisabledState",
+        "touchEnabledViewIds",
+    ]),
+    layout: new Set([
+        "centerInParent", "centerVertical", "centerHorizontal", "alignTop",
+        "alignBottom", "alignLeft", "alignRight", "alignTopOfView",
+        "alignBottomOfView", "alignLeftOfView", "alignRightOfView",
+        "alignTopView", "alignBottomView", "alignLeftView", "alignRightView",
+        "alignCenterVerticalView", "alignCenterHorizontalView", "toView",
+        "gravity", "indexBelow", "indexAbove",
+        "keyBottomView", "keyTopView", "keyLeftView", "keyRightView",
+    ]),
+    lifecycle: new Set(["onAppear", "onDisappear"]),
+    accessibility: new Set(["id", "testId", "className", "tag"]),
+    binding: new Set([
+        "binding", "bind", "binding_id", "binding_group", "propertyName",
+        "bindingScript", "data", "shared_data",
+    ]),
+};
+export function categorizeCommonAttributes(commonAttrs) {
+    const categories = {
+        sizing: {},
+        spacing: {},
+        visual: {},
+        visibility: {},
+        interaction: {},
+        layout: {},
+        lifecycle: {},
+        accessibility: {},
+        binding: {},
+        other: {},
+    };
+    for (const [key, attrDef] of Object.entries(commonAttrs)) {
+        if (key.startsWith("_"))
+            continue;
+        let placed = false;
+        for (const [category, keys] of Object.entries(CATEGORY_KEYS)) {
+            if (keys.has(key)) {
+                categories[category][key] = attrDef;
+                placed = true;
+                break;
+            }
+        }
+        if (!placed)
+            categories.other[key] = attrDef;
+    }
+    // Drop empty categories
+    const filtered = {};
+    for (const [name, attrs] of Object.entries(categories)) {
+        if (Object.keys(attrs).length > 0)
+            filtered[name] = attrs;
+    }
+    return {
+        description: "Common attributes shared across all components",
+        source: "attribute_definitions.json common section",
+        categories: filtered,
+    };
+}
+// ----- modifier order (platform rendering) -------------------------------
+export const MODIFIER_ORDER = {
+    description: "Platform-specific modifier application order. Order affects rendering.",
+    swift: {
+        order: [
+            "centerAlignment",
+            "edgeAlignment",
+            "padding",
+            "frameConstraints (min/max)",
+            "frameSize (width/height)",
+            "insets/insetHorizontal",
+            "background",
+            "cornerRadius",
+            "border",
+            "margins",
+            "alpha/opacity",
+            "shadow",
+            "clipping",
+            "offset",
+            "visibility (hidden/opacity ternary)",
+            "safeAreaInsets",
+            "disabled",
+            "tag (for TabView)",
+            "tintColor",
+            "onClick/onTapGesture",
+            "lifecycle (onAppear/onDisappear)",
+            "confirmationDialog",
+            "accessibilityIdentifier",
+        ],
+        criticalRules: [
+            "background MUST come after padding (background includes padding area)",
+            "border MUST come after cornerRadius (for rounded border)",
+            "frame MUST come before margins (size before external spacing)",
+            "Image: .resizable() must come first, then .aspectRatio",
+            "Label: .leading alignment added to frame for textAlign to work",
+        ],
+    },
+    kotlin: {
+        order: [
+            "testTag",
+            "margins",
+            "weight (caller applies)",
+            "size (width/height, matchParent/wrapContent, min/max/aspectRatio)",
+            "alpha/opacity",
+            "shadow/elevation",
+            "background (cornerRadius -> clip -> border -> bgColor)",
+            "clickable",
+            "padding",
+            "alignment (RowScope/ColumnScope/BoxScope)",
+        ],
+        criticalRules: [
+            "Modifier.then() chains left-to-right; order matters",
+            "margins before size (outside to inside)",
+            "cornerRadius must be applied as clip before background",
+        ],
+    },
+    react: {
+        note: "React uses Tailwind CSS classes; ordering is less strict",
+        classOrder: [
+            "layout (flex, flex-col/row)",
+            "sizing (w-*, h-*)",
+            "spacing (p-*, m-*)",
+            "typography (text-*, font-*)",
+            "visual (bg-*, rounded-*, border-*, shadow-*)",
+            "opacity",
+            "overflow",
+            "cursor/interaction",
+        ],
+        dynamicStyles: "Values not mappable to Tailwind use inline style objects",
+    },
+};
+// ----- binding rules -----------------------------------------------------
+export const BINDING_RULES = {
+    description: "JsonUI binding syntax rules",
+    format: {
+        bindingExpression: "@{propertyName}",
+        negation: "@{!propertyName} (boolean value attributes only — validator error elsewhere)",
+        defaultValue: "@{propertyName ?? default} (one ?? max; string default in single or double quotes, or true/false/number; null = unresolved)",
+        nestedPath: "@{user.name} / @{items[0].title} (dot path + bracket index — canonical on all platforms; see semantics)",
+    },
+    directions: {
+        "two-way": {
+            description: "Component state changes reflect back to data model",
+            swift: "$data.propertyName",
+            kotlin: "mutableStateOf + updateData(mapOf(key to value))",
+            react: "value={data.prop} + auto-generated onChange handler",
+            applicableAttributes: [
+                "TextField.text",
+                "TextView.text",
+                "Switch.isOn",
+                "Toggle.isOn",
+                "CheckBox.checked",
+                "Slider.value",
+                "Segment.selectedIndex",
+                "Radio.selectedIndex",
+                "SelectBox.selectedIndex",
+                "TabView.selectedIndex",
+            ],
+        },
+        "read-only": {
+            description: "Display data values only (no write-back)",
+            swift: "data.propertyName",
+            kotlin: "data[propertyName]",
+            react: "{data.propertyName}",
+            applicableAttributes: [
+                "Label.text",
+                "*.width / *.height (frame values)",
+                "*.enabled",
+                "*.hidden / *.visibility",
+                "*.background / *.fontColor",
+                "*.fontSize",
+                "*.opacity / *.alpha",
+            ],
+        },
+    },
+    criticalRules: [
+        "Two-way binding expressions must be a single flat identifier — no dots, brackets, ??, or ! (binding-two-way-complex)",
+        "Frame values (width, height, etc.) MUST be read-only (data.). $data. is NOT allowed",
+        "Two-way binding is only for stateful input components",
+        "React auto-generates onPropertyNameChange for two-way bindings",
+        "Kotlin Dynamic uses updateData(mapOf(key to value)) for data updates",
+        "onclick (lowercase) = selector format (string), onClick (camelCase) = binding format (@{handler})",
+    ],
+};
+// ----- platform mapping (cross-platform value conversion) ----------------
+export const PLATFORM_MAPPING = {
+    description: "Cross-platform attribute value conversion mapping",
+    values: {
+        matchParent: {
+            swift: ".infinity (frame maxWidth/maxHeight)",
+            kotlin: "fillMaxWidth() / fillMaxHeight()",
+            react: "w-full / h-full",
+        },
+        wrapContent: {
+            swift: "Default (no frame specified)",
+            kotlin: "wrapContentWidth() / wrapContentHeight()",
+            react: "w-fit / h-fit",
+        },
+    },
+    contentMode: {
+        aspectFit: { swift: ".fit", kotlin: "ContentScale.Fit", react: "object-contain" },
+        aspectFill: { swift: ".fill", kotlin: "ContentScale.Crop", react: "object-cover" },
+        scaleToFill: {
+            swift: ".fill (no aspectRatio)",
+            kotlin: "ContentScale.FillBounds",
+            react: "object-fill",
+        },
+    },
+    textAlign: {
+        left: { swift: ".leading", kotlin: "TextAlign.Start", react: "text-left" },
+        center: { swift: ".center", kotlin: "TextAlign.Center", react: "text-center" },
+        right: { swift: ".trailing", kotlin: "TextAlign.End", react: "text-right" },
+    },
+    fontWeight: {
+        bold: { swift: ".bold", kotlin: "FontWeight.Bold", react: "font-bold" },
+        light: { swift: ".light", kotlin: "FontWeight.Light", react: "font-light" },
+        thin: { swift: ".thin", kotlin: "FontWeight.Thin", react: "font-thin" },
+        medium: { swift: ".medium", kotlin: "FontWeight.Medium", react: "font-medium" },
+        semibold: {
+            swift: ".semibold",
+            kotlin: "FontWeight.SemiBold",
+            react: "font-semibold",
+        },
+    },
+    orientation: {
+        horizontal: { swift: "HStack", kotlin: "Row", react: "flex flex-row" },
+        vertical: { swift: "VStack", kotlin: "Column", react: "flex flex-col" },
+        none: { swift: "ZStack", kotlin: "Box", react: "relative" },
+    },
+    gravity: {
+        center: {
+            swift: ".center",
+            kotlin: "Alignment.Center",
+            react: "items-center justify-center",
+        },
+        centerHorizontal: {
+            swift_vertical: ".center HStack alignment",
+            kotlin_vertical: "Alignment.CenterHorizontally",
+            react: "items-center (flex-col)",
+        },
+        centerVertical: {
+            swift_horizontal: ".center VStack alignment",
+            kotlin_horizontal: "Alignment.CenterVertically",
+            react: "items-center (flex-row)",
+        },
+    },
+    types: {
+        String: { swift: "String", kotlin: "String", react: "string" },
+        Int: { swift: "Int", kotlin: "Int", react: "number" },
+        Float: { swift: "CGFloat", kotlin: "Float", react: "number" },
+        Double: { swift: "Double", kotlin: "Double", react: "number" },
+        Bool: { swift: "Bool", kotlin: "Boolean", react: "boolean" },
+        Array: { swift: "[T]", kotlin: "List<T>", react: "T[]" },
+        Dictionary: {
+            swift: "[String: Any]",
+            kotlin: "Map<String, Any>",
+            react: "Record<string, any>",
+        },
+    },
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SpecLoader, mcpRootFromImportMetaUrl } from "./spec_loader.js";
+import { ServerConfig } from "./config.js";
+// --- Group A: Component Spec Lookup ---
+import { register as registerLookupComponent } from "./tools/spec/lookup_component.js";
+import { register as registerLookupAttribute } from "./tools/spec/lookup_attribute.js";
+import { register as registerSearchComponents } from "./tools/spec/search_components.js";
+import { register as registerGetModifierOrder } from "./tools/spec/get_modifier_order.js";
+import { register as registerGetBindingRules } from "./tools/spec/get_binding_rules.js";
+import { register as registerGetScreenIdentity } from "./tools/spec/get_screen_identity.js";
+import { register as registerGetPlatformMapping } from "./tools/spec/get_platform_mapping.js";
+import { register as registerGetDataSource } from "./tools/spec/get_data_source.js";
+// --- Group B: Project Context ---
+import { register as registerGetProjectConfig } from "./tools/context/get_project_config.js";
+import { register as registerListScreenSpecs } from "./tools/context/list_screen_specs.js";
+import { register as registerListComponentSpecs } from "./tools/context/list_component_specs.js";
+import { register as registerListLayouts } from "./tools/context/list_layouts.js";
+import { register as registerReadSpecFile } from "./tools/context/read_spec_file.js";
+import { register as registerReadLayoutFile } from "./tools/context/read_layout_file.js";
+// --- Group C: jui CLI ---
+import { register as registerJuiInit } from "./tools/jui/jui_init.js";
+import { register as registerJuiGenerateProject } from "./tools/jui/jui_generate_project.js";
+import { register as registerJuiGenerateScreen } from "./tools/jui/jui_generate_screen.js";
+import { register as registerJuiGenerateConverter } from "./tools/jui/jui_generate_converter.js";
+import { register as registerJuiBuild } from "./tools/jui/jui_build.js";
+import { register as registerJuiVerify } from "./tools/jui/jui_verify.js";
+import { register as registerJuiMigrateLayouts } from "./tools/jui/jui_migrate_layouts.js";
+import { register as registerJuiSyncTool } from "./tools/jui/jui_sync_tool.js";
+// --- Group E: API Model Discovery ---
+import { register as registerListApiSpecs } from "./tools/api/list_api_specs.js";
+import { register as registerListApiModels } from "./tools/api/list_api_models.js";
+import { register as registerPreviewApiModelSync } from "./tools/api/preview_api_model_sync.js";
+// --- Group D: jsonui-doc CLI ---
+import { register as registerDocInitSpec } from "./tools/doc/doc_init_spec.js";
+import { register as registerDocInitComponent } from "./tools/doc/doc_init_component.js";
+import { register as registerDocValidateSpec } from "./tools/doc/doc_validate_spec.js";
+import { register as registerDocValidateComponent } from "./tools/doc/doc_validate_component.js";
+import { register as registerDocGenerateSpec } from "./tools/doc/doc_generate_spec.js";
+import { register as registerDocGenerateComponent } from "./tools/doc/doc_generate_component.js";
+import { register as registerDocGenerateHtml } from "./tools/doc/doc_generate_html.js";
+import { register as registerDocRulesInit } from "./tools/doc/doc_rules_init.js";
+import { register as registerDocRulesShow } from "./tools/doc/doc_rules_show.js";
+// --- Group F: jsonui-test CLI ---
+import { register as registerTestValidate } from "./tools/test/test_validate.js";
+import { register as registerTestGenerateScreen } from "./tools/test/test_generate_screen.js";
+import { register as registerTestGenerateFlow } from "./tools/test/test_generate_flow.js";
+import { register as registerTestGenerateDescription } from "./tools/test/test_generate_description.js";
+import { register as registerTestReport } from "./tools/test/test_report.js";
+import { register as registerTestMockGenerate } from "./tools/test/test_mock_generate.js";
+import { register as registerTestArtifactsPull } from "./tools/test/test_artifacts_pull.js";
+import { register as registerTestArtifactsStatus } from "./tools/test/test_artifacts_status.js";
+function log(message) {
+    console.error(`[jui-tools] ${new Date().toISOString()} ${message}`);
+}
+log("Server starting...");
+const server = new McpServer({
+    name: "jui-tools",
+    version: "2.0.0",
+});
+// Initialize spec loader for Group A
+// Resolves attribute_definitions.json via 4-layer fallback:
+// JSONUI_CLI_PATH env > ./.jsonui-cli/ > ~/.jsonui-cli/ > bundled snapshot in data/.
+const mcpRoot = mcpRootFromImportMetaUrl(import.meta.url);
+const loader = new SpecLoader(mcpRoot);
+const source = loader.getDataSource();
+log(`attribute_definitions: [${source.attributeDefinitions.layer}] ${source.attributeDefinitions.path} (${source.attributeDefinitions.freshness})`);
+log(`component_metadata:    [${source.componentMetadata.layer}] ${source.componentMetadata.path} (${source.componentMetadata.freshness})`);
+log(`Loaded ${source.componentCount} components, ${source.commonAttributeCount} common attributes`);
+// Initialize server config for Groups B/C/D
+const config = new ServerConfig();
+// Register Group A: Component Spec Lookup (7 tools)
+registerLookupComponent(server, loader);
+registerLookupAttribute(server, loader);
+registerSearchComponents(server, loader);
+registerGetModifierOrder(server, loader);
+registerGetBindingRules(server, loader);
+registerGetScreenIdentity(server, loader);
+registerGetPlatformMapping(server, loader);
+registerGetDataSource(server, loader);
+// Register Group B: Project Context (6 tools)
+registerGetProjectConfig(server, config);
+registerListScreenSpecs(server, config);
+registerListComponentSpecs(server, config);
+registerListLayouts(server, config);
+registerReadSpecFile(server, config);
+registerReadLayoutFile(server, config);
+// Register Group C: jui CLI (8 tools)
+registerJuiInit(server, config);
+registerJuiGenerateProject(server, config);
+registerJuiGenerateScreen(server, config);
+registerJuiGenerateConverter(server, config);
+registerJuiBuild(server, config);
+registerJuiVerify(server, config);
+registerJuiMigrateLayouts(server, config);
+registerJuiSyncTool(server, config);
+// Register Group D: jsonui-doc CLI (9 tools)
+registerDocInitSpec(server, config);
+registerDocInitComponent(server, config);
+registerDocValidateSpec(server, config);
+registerDocValidateComponent(server, config);
+registerDocGenerateSpec(server, config);
+registerDocGenerateComponent(server, config);
+registerDocGenerateHtml(server, config);
+registerDocRulesInit(server, config);
+registerDocRulesShow(server, config);
+// Register Group E: API Model Discovery (3 tools)
+registerListApiSpecs(server, config);
+registerListApiModels(server, config);
+registerPreviewApiModelSync(server, config);
+// Register Group F: jsonui-test CLI (8 tools)
+// mock serve is intentionally NOT exposed (long-running local HTTP server that
+// executes run-targets — kept to direct CLI use only). test_mock_generate
+// covers both scaffold (default) and drift-check (check=true) modes.
+registerTestValidate(server, config);
+registerTestGenerateScreen(server, config);
+registerTestGenerateFlow(server, config);
+registerTestGenerateDescription(server, config);
+registerTestReport(server, config);
+registerTestMockGenerate(server, config);
+registerTestArtifactsPull(server, config);
+registerTestArtifactsStatus(server, config);
+log(`Registered 41 tools (7 spec + 6 context + 8 jui + 9 doc + 3 api + 8 test)`);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log("Server connected and ready.");
+}
+main().catch(console.error);