jui-tools-mcp-server 2.5.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "jui-tools-mcp-server",
+  "version": "2.5.0",
+  "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "fetch-definitions": "node scripts/fetch-definitions.js",
+    "postinstall": "node scripts/fetch-definitions.js"
+  },
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.9"
+  }
+}

package/scripts/fetch-definitions.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Post-install hook: fetch the data files from the pinned jsonui-cli release
+ * tag and write them into `data/`. These populate the 4th-layer fallback
+ * in spec_loader.ts (the bundled snapshot).
+ *
+ * The list of files lives in ./fetch-manifest.js (side-effect-free, so the
+ * test suite can assert its completeness without triggering a fetch).
+ *
+ * Users who install jsonui-cli separately will prefer that checkout via the
+ * higher-priority fallback layers; users who don't have jsonui-cli installed
+ * get a working MCP with the bundled snapshots.
+ *
+ * The fetch is best-effort. If the network is unavailable at install time
+ * (CI sandbox, offline install, etc.) and no existing snapshot is present,
+ * the script exits 0 anyway — the MCP will surface a clear error at
+ * startup if none of the 4 layers resolve.
+ */
+
+import dns from "dns";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+import { FILES } from "./fetch-manifest.js";
+
+// raw.githubusercontent.com's IPv6 edge sometimes serves stale 404 responses
+// for newly-pushed files for ~5 min while the IPv4 edge is already fresh.
+// Prefer IPv4 to avoid spurious postinstall failures on fresh installs.
+dns.setDefaultResultOrder("ipv4first");
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, "..");
+const DATA_DIR = join(PROJECT_ROOT, "data");
+
+// The jsonui-cli release tag this snapshot is pinned to. Pinning (instead of
+// `main`) means an install never bundles definitions newer than the CLI a
+// user gets — the snapshot only moves when the pin moves.
+//
+// Bump procedure (the pin update IS the review point, same idea as the
+// JSONUI_CLI_REF SHA pin in JsonUIDocument's deploy.yml):
+//   1. jsonui-cli: land the shared/core / conformance change and cut the tag
+//   2. update JSONUI_CLI_TAG here
+//   3. `npm run fetch-definitions` and commit the data/ diff together with
+//      this pin in one commit
+// JSONUI_CLI_RAW_BASE still overrides the whole base URL for manual testing.
+const JSONUI_CLI_TAG = "v1.4.0";
+const BASE_URL =
+  process.env.JSONUI_CLI_RAW_BASE ||
+  `https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/${JSONUI_CLI_TAG}`;
+
+async function fetchOne(spec) {
+  const target = join(DATA_DIR, spec.local);
+  const url = spec.envOverride || `${BASE_URL}/${spec.remote}`;
+
+  try {
+    console.error(`[fetch-definitions] GET ${url}`);
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+    const text = await res.text();
+    JSON.parse(text); // Validate before writing.
+    writeFileSync(target, text, "utf-8");
+    console.error(`[fetch-definitions] wrote ${target} (${text.length} bytes)`);
+    return true;
+  } catch (err) {
+    if (existsSync(target)) {
+      console.error(
+        `[fetch-definitions] fetch failed (${err.message}); keeping existing snapshot at ${target}.`
+      );
+    } else {
+      console.error(
+        `[fetch-definitions] fetch failed for ${spec.local} (${err.message}); no bundled snapshot written.`
+      );
+    }
+    return false;
+  }
+}
+
+async function main() {
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+
+  const results = await Promise.all(FILES.map(fetchOne));
+  const allMissing = results.every((ok, i) => {
+    return !ok && !existsSync(join(DATA_DIR, FILES[i].local));
+  });
+
+  if (allMissing) {
+    console.error(
+      "[fetch-definitions] no bundled snapshots available.\n" +
+        "  The MCP will try JSONUI_CLI_PATH / ./.jsonui-cli/ / ~/.jsonui-cli/ at startup.\n" +
+        "  If none resolve, the server will exit with a clear error."
+    );
+  }
+  // Do not fail install on fetch errors — the layered fallback handles it.
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error(`[fetch-definitions] unexpected error: ${err?.stack || err}`);
+  process.exit(0);
+});

package/scripts/fetch-manifest.js

@@ -0,0 +1,60 @@
+/**
+ * The auto-fetch manifest: every file that `scripts/fetch-definitions.js`
+ * refreshes into `data/` at npm install time.
+ *
+ * This lives in its own side-effect-free module so the test suite can import
+ * the manifest without triggering a network fetch. The invariant it exists to
+ * enforce (tests/snapshot_completeness.test.ts):
+ *
+ *   every file bundled in data/  ⊆  this manifest  ⊆  files SpecLoader reads
+ *
+ * A data/ file missing from the manifest only ever refreshes by hand and
+ * silently goes stale (binding_semantics.json and coverage.json each fell
+ * into exactly this trap). A manifest entry SpecLoader never reads is dead
+ * weight fetched on every install. Adding a file here without wiring it into
+ * spec_loader.ts (or vice versa) fails the suite.
+ */
+
+export const FILES = [
+  {
+    remote: "shared/core/attribute_definitions.json",
+    local: "attribute_definitions.json",
+    envOverride: process.env.JSONUI_ATTR_DEFINITIONS_URL,
+  },
+  {
+    remote: "shared/core/component_metadata.json",
+    local: "component_metadata.json",
+    envOverride: process.env.JSONUI_COMPONENT_METADATA_URL,
+  },
+  // Canonical attribute-semantics contract (cross-effect rulings, plan 33).
+  // Same trap as binding_semantics below: bundled in data/ but hand-mirrored
+  // until the completeness guard caught it (third edition).
+  {
+    remote: "shared/core/attribute_semantics.json",
+    local: "attribute_semantics.json",
+  },
+  // Canonical binding-resolution semantics. This was bundled in data/ but
+  // missing from FILES, so the snapshot only ever refreshed by hand and
+  // silently went stale — the same trap the screen-identity asset would
+  // otherwise fall into.
+  {
+    remote: "shared/core/binding_semantics.json",
+    local: "binding_semantics.json",
+    envOverride: process.env.JSONUI_BINDING_SEMANTICS_URL,
+  },
+  // Canonical screen identity: what a screen is, how it is identified, how
+  // its presence is asserted.
+  {
+    remote: "shared/core/screen_identity.json",
+    local: "screen_identity.json",
+    envOverride: process.env.JSONUI_SCREEN_IDENTITY_URL,
+  },
+  // Conformance coverage ledger (declared-but-unimplemented gaps). The loader
+  // reads data/coverage.json as its fallback, so it must refresh with the rest
+  // — binding_semantics.json already fell into this exact stale-snapshot trap.
+  {
+    remote: "conformance/coverage.json",
+    local: "coverage.json",
+    envOverride: process.env.JSONUI_COVERAGE_URL,
+  },
+];

package/src/cli_runner.ts

@@ -0,0 +1,55 @@
+import { execFile } from "child_process";
+
+export interface CliResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export async function runCli(
+  command: string,
+  args: string[],
+  options: { cwd: string; timeout?: number }
+): Promise<CliResult> {
+  const timeout = options.timeout ?? 60_000;
+
+  return new Promise((resolve) => {
+    execFile(
+      command,
+      args,
+      {
+        cwd: options.cwd,
+        timeout,
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env, PYTHONIOENCODING: "utf-8" },
+      },
+      (error, stdout, stderr) => {
+        if (error && "killed" in error && error.killed) {
+          resolve({
+            exitCode: 1,
+            stdout: stdout || "",
+            stderr: `Command timed out after ${timeout / 1000}s`,
+          });
+          return;
+        }
+        resolve({
+          exitCode: error ? (error as any).code ?? 1 : 0,
+          stdout: stdout || "",
+          stderr: stderr || "",
+        });
+      }
+    );
+  });
+}
+
+export function formatResult(result: CliResult): string {
+  return JSON.stringify(
+    {
+      success: result.exitCode === 0,
+      output: result.stdout,
+      errors: result.stderr || undefined,
+    },
+    null,
+    2
+  );
+}

package/src/config.ts

@@ -0,0 +1,88 @@
+import { readFileSync, existsSync, realpathSync } from "fs";
+import { basename, dirname, join, resolve, isAbsolute, sep } from "path";
+
+/**
+ * Resolve symlinks on the longest existing prefix of an already lexically
+ * resolved path. Non-existent trailing segments are kept as-is so validation
+ * can run before existence checks without throwing; a dangling or missing
+ * path can't leak data (the read fails afterwards).
+ */
+function realpathLongestExistingPrefix(path: string): string {
+  let existing = path;
+  const missingSuffix: string[] = [];
+  while (!existsSync(existing)) {
+    const parent = dirname(existing);
+    if (parent === existing) return path; // no existing prefix at all
+    missingSuffix.unshift(basename(existing));
+    existing = parent;
+  }
+  return join(realpathSync(existing), ...missingSuffix);
+}
+
+export interface ProjectConfig {
+  project_name: string;
+  spec_directory: string;
+  layouts_directory: string;
+  styles_directory: string;
+  images_directory: string;
+  component_spec_directory: string;
+  strings_file: string;
+  type_map_file: string;
+  platforms: Record<string, any>;
+}
+
+export class ServerConfig {
+  private defaultProjectDir: string | undefined;
+
+  constructor() {
+    this.defaultProjectDir = process.env.JUI_PROJECT_DIR;
+  }
+
+  resolveProjectDir(override?: string): string {
+    const dir = override || this.defaultProjectDir;
+    if (!dir) {
+      throw new Error(
+        "No project directory specified. Set JUI_PROJECT_DIR environment variable or pass project_dir parameter."
+      );
+    }
+    const resolved = resolve(dir);
+    if (!existsSync(resolved)) {
+      throw new Error(`Project directory does not exist: ${resolved}`);
+    }
+    return resolved;
+  }
+
+  readProjectConfig(projectDir: string): ProjectConfig {
+    const configPath = join(projectDir, "jui.config.json");
+    if (!existsSync(configPath)) {
+      throw new Error(
+        `jui.config.json not found in ${projectDir}. Run jui_init first.`
+      );
+    }
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  }
+
+  resolveDir(config: ProjectConfig, field: keyof ProjectConfig, projectDir: string): string {
+    const value = config[field];
+    if (typeof value !== "string") return projectDir;
+    if (isAbsolute(value)) return value;
+    return join(projectDir, value);
+  }
+
+  validatePathInProject(filePath: string, projectDir: string): string {
+    const resolved = isAbsolute(filePath) ? filePath : join(projectDir, filePath);
+    // Realpath both sides so a symlink inside the project cannot smuggle the
+    // path outside it (lexical resolve() does not follow symlinks).
+    const normalizedProject = realpathLongestExistingPrefix(resolve(projectDir));
+    const normalizedPath = realpathLongestExistingPrefix(resolve(resolved));
+    // Compare on path-segment boundaries: a bare startsWith() would accept
+    // sibling dirs like "<project>-evil".
+    const isInside =
+      normalizedPath === normalizedProject ||
+      normalizedPath.startsWith(normalizedProject + sep);
+    if (!isInside) {
+      throw new Error(`Path traversal detected: ${filePath} is outside project directory`);
+    }
+    return normalizedPath;
+  }
+}

package/src/data/derived.ts

@@ -0,0 +1,305 @@
+/**
+ * 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: Record<string, Set<string>> = {
+  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: Record<string, any>): any {
+  const categories: Record<string, Record<string, any>> = {
+    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: Record<string, Record<string, any>> = {};
+  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>",
+    },
+  },
+};