jui-tools-mcp-server 2.5.0

package/dist/tools/test/test_artifacts_pull.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_artifacts_pull", "Pull test artifacts (screenshots/recordings) from the latest run (iOS xcresult / Android device / web Playwright output) into the project's configured artifacts directory, returning generated file paths", {
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+        platform: z.enum(["ios", "android", "web", "all"]).optional().describe("Restrict pulling to one platform (default: all configured)"),
+        xcresult: z.string().optional().describe("Explicit .xcresult bundle path (iOS)"),
+        serial: z.string().optional().describe("adb device serial (Android)"),
+        clean: z.boolean().optional().describe("Remove artifacts from the device after pulling (Android)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["artifacts", "pull", "--json"];
+            if (params.platform) {
+                args.push("--platform", params.platform);
+            }
+            if (params.xcresult) {
+                args.push("--xcresult", params.xcresult);
+            }
+            if (params.serial) {
+                args.push("--serial", params.serial);
+            }
+            if (params.clean) {
+                args.push("--clean");
+            }
+            // xcresult export can exceed the default 60s timeout.
+            const result = await runCli("jsonui-test", args, {
+                cwd: projectDir,
+                timeout: 180_000,
+            });
+            if (result.exitCode === 0) {
+                try {
+                    JSON.parse(result.stdout);
+                    // The CLI already emits a JSON document ({outputDir, files, skipped})
+                    // — pass it through verbatim so callers don't peel a wrapper envelope.
+                    return { content: [{ type: "text", text: result.stdout.trim() }] };
+                }
+                catch {
+                    // Not JSON — fall through to the standard envelope.
+                }
+            }
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_artifacts_status.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_artifacts_status.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_artifacts_status", "Show the resolved test-artifacts configuration (output dir, iOS xcresult discovery, Android appId) and list already-pulled artifact files", {
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const result = await runCli("jsonui-test", ["artifacts", "status", "--json"], {
+                cwd: projectDir,
+            });
+            if (result.exitCode === 0) {
+                try {
+                    JSON.parse(result.stdout);
+                    // The CLI already emits a JSON document — pass it through verbatim.
+                    return { content: [{ type: "text", text: result.stdout.trim() }] };
+                }
+                catch {
+                    // Not JSON — fall through to the standard envelope.
+                }
+            }
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_generate_description.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_generate_description.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_generate_description", "Generate a description JSON file for a screen or flow test case via the jsonui-test CLI", {
+        test_type: z.enum(["screen", "flow"]).describe("Whether the case belongs to a screen or flow test"),
+        name: z.string().describe("Screen/flow name (e.g., login, checkout)"),
+        case_name: z.string().describe("Test case name (e.g., initial_display, happy_path)"),
+        path: z
+            .string()
+            .optional()
+            .describe("Output file path (default: tests/<type>s/<name>/descriptions/<case_name>.json)"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["generate", "description", params.test_type, params.name, params.case_name];
+            if (params.path) {
+                args.push("--path", params.path);
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_generate_flow.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_generate_flow.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_generate_flow", "Generate a flow test file template via the jsonui-test CLI", {
+        name: z.string().describe("Flow name (e.g., login, checkout)"),
+        path: z.string().optional().describe("Output test file path (default: tests/flows/<name>/<name>.test.json)"),
+        platform: z
+            .enum(["ios", "ios-swiftui", "ios-uikit", "android", "web", "all"])
+            .optional()
+            .describe("Target platform"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["generate", "test", "flow", params.name];
+            if (params.path) {
+                args.push("--path", params.path);
+            }
+            if (params.platform) {
+                args.push("--platform", params.platform);
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_generate_screen.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_generate_screen.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_generate_screen", "Generate a screen test file template via the jsonui-test CLI", {
+        name: z.string().describe("Screen name (e.g., login, home)"),
+        path: z.string().optional().describe("Output test file path (default: tests/screens/<name>/<name>.test.json)"),
+        platform: z
+            .enum(["ios", "ios-swiftui", "ios-uikit", "android", "web", "all"])
+            .optional()
+            .describe("Target platform"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["generate", "test", "screen", params.name];
+            if (params.path) {
+                args.push("--path", params.path);
+            }
+            if (params.platform) {
+                args.push("--platform", params.platform);
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_mock_generate.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_mock_generate.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_mock_generate", "Manage API mock files against an OpenAPI/Swagger spec via the jsonui-test CLI. Writes ONLY into <mockDir>/generated/, which it wipes and rewrites on each run — anything outside that directory is hand-written and never touched. Mocks are matched to operations by their source method+path, not by filename, so a project's own naming keeps working. Only the endpoints the project declares it consumes are scaffolded and checked: api.schemas.include_paths / exclude_paths (the same keys the DTO codegen filters on), or mock.includePaths / mock.excludePaths when the mock scope differs. A shared swagger's other realms are therefore NOT reported as mocks this project is missing — if a check reports many [MISSING] entries, read the paths before writing any, because endpoints from a realm the app cannot reach mean the scope is undeclared and the fix is one config key. A mock file serving an out-of-scope route is reported as [SCOPE] (an unused file, safe to delete) and does not fail; [ORPHAN] still means the swagger has no such endpoint at all, and still fails. check=true reports drift (response bodies are compared against the schema: types, required, enum) without writing. Findings under generated/ are warnings, findings outside it are errors, and a scenario that merely omits OPTIONAL fields is a note that does not fail — omitting an optional field is a valid instance, and failing on it buries the real violations (set strict=true to demand full coverage). Do NOT fill optional fields in to silence a note: a mechanical merge puts null into non-nullable slots and manufactures violations. update_default=true REPAIRS each existing mock's default scenario: it adds the required fields the contract has and the body lacks, refreshes the source route, and changes nothing else — no existing value is overwritten, nothing is removed, other scenarios are untouched. The default scenario is where a project keeps the data its tests assert on (scaffolding creates default and nothing else), so never replace a body wholesale to satisfy the check. Violations a merge cannot decide — wrong type, undeclared field — are reported for a person. dry_run=true previews. The 'mock serve' subcommand is intentionally NOT exposed over MCP (it is a long-running local HTTP server that executes run-targets).", {
+        swagger: z
+            .array(z.string())
+            .optional()
+            .describe("Paths to OpenAPI files (repeatable). Defaults to the project mock config if omitted."),
+        out: z.string().optional().describe("Output mock dir (default: mock.mockDir or tests/mocks)"),
+        config_file: z.string().optional().describe("Config file (default: jui.config.json)"),
+        check: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, report drift vs swagger and do NOT write (adds --check). Default false = regenerate <mockDir>/generated/."),
+        strict: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("With check=true, treat a missing OPTIONAL field as drift too (adds --strict). Off by default."),
+        update_default: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Repair each existing mock's default scenario by ADDING missing required fields (adds --update-default). Never overwrites a value or removes a field."),
+        dry_run: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("With update_default, report what would be added without writing (adds --dry-run)."),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["mock", "generate"];
+            for (const s of params.swagger ?? []) {
+                args.push("--swagger", s);
+            }
+            if (params.out) {
+                args.push("--out", params.out);
+            }
+            if (params.config_file) {
+                args.push("--config", params.config_file);
+            }
+            if (params.check) {
+                args.push("--check");
+            }
+            if (params.strict) {
+                args.push("--strict");
+            }
+            if (params.update_default) {
+                args.push("--update-default");
+            }
+            if (params.dry_run) {
+                args.push("--dry-run");
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_report.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_report.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_report", "Convert one or more results JSON files (results.schema.json format) into a JUnit XML or HTML report via the jsonui-test CLI", {
+        files: z
+            .array(z.string())
+            .min(1)
+            .describe("Results JSON files to convert (multiple inputs merge into one report)"),
+        format: z.enum(["junit", "html"]).describe("Report format"),
+        output: z.string().optional().describe("Output file path (default: report.xml / report.html)"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["report", ...params.files, "--format", params.format];
+            if (params.output) {
+                args.push("--output", params.output);
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/test/test_validate.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ServerConfig } from "../../config.js";
+export declare function register(server: McpServer, config: ServerConfig): void;

package/dist/tools/test/test_validate.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { runCli, formatResult } from "../../cli_runner.js";
+export function register(server, config) {
+    server.tool("test_validate", "Validate JsonUI test files (screen/flow tests + descriptions) against the schema via the jsonui-test CLI. When the project config declares mock.swagger + mock.mockDir this ALSO regenerates <mockDir>/generated/ if it is missing or older than the swagger, and fails on mock contract drift — so a non-zero result here is not necessarily about the test files. A mock that merely omits optional fields does not fail this gate (set mock.checkOptionalFields=true in the project config to demand full coverage). Only the endpoints the project declares it consumes are checked (api.schemas.include_paths / exclude_paths, the same keys the DTO codegen filters on), so a shared swagger's other realms are not reported as missing mocks. Pass no_mock_check to validate the test files alone. Like the CLI, this installs (flatten-copies) the tests into the configured test.install destinations as a side effect — pass no_install to validate without consuming the files.", {
+        files: z
+            .array(z.string())
+            .min(1)
+            .describe("Files or directories to validate (e.g., ['tests/screens'] or ['login.test.json'])"),
+        verbose: z.boolean().optional().describe("Show all files, including valid ones"),
+        quiet: z.boolean().optional().describe("Hide warnings, show only errors"),
+        no_mock_check: z
+            .boolean()
+            .optional()
+            .describe("Skip the mock-vs-swagger contract check that otherwise runs on the same gate"),
+        no_install: z
+            .boolean()
+            .optional()
+            .describe("Validate only; skip the flatten-install side effect even if test.install is configured (maps to CLI --no-install; default false, same behavior as the CLI)"),
+        project_dir: z.string().optional().describe("Project directory (overrides JUI_PROJECT_DIR env)"),
+    }, async (params) => {
+        try {
+            const projectDir = config.resolveProjectDir(params.project_dir);
+            const args = ["validate", ...params.files];
+            if (params.verbose) {
+                args.push("--verbose");
+            }
+            if (params.quiet) {
+                args.push("--quiet");
+            }
+            if (params.no_mock_check) {
+                args.push("--no-mock-check");
+            }
+            if (params.no_install) {
+                args.push("--no-install");
+            }
+            const result = await runCli("jsonui-test", args, { cwd: projectDir });
+            return { content: [{ type: "text", text: formatResult(result) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/docs/design.md

@@ -0,0 +1,227 @@
+# jsonui-mcp-server (`jui-tools`) — Design
+
+## Purpose
+
+An MCP server that lets an AI agent drive JsonUI projects without memorising
+CLI syntax or re-reading source files. It exposes five groups of tools:
+
+1. **Spec lookup** — answers "what is this component / attribute, and how
+   does it bind?" from the canonical jsonui-cli data files.
+2. **Project context** — reads `jui.config.json`, screen specs, layouts,
+   and component specs on the agent's behalf.
+3. **`jui` CLI wrappers** — `init` / `generate project` / `generate screen`
+   / `generate converter` / `build` / `verify` / `migrate-layouts`.
+4. **`jsonui-doc` CLI wrappers** — `init` / `validate` / `generate` /
+   `rules` for specs, components, and HTML output.
+5. **API model discovery** — read-only wrappers over `jui ls api-specs` /
+   `jui ls api-models` / `jui g api --dry-run` for the swagger→DTO/Domain
+   pipeline.
+
+The server is published as `jui-tools` (version 2.x), currently exposing
+41 tools.
+
+---
+
+## Data pipeline
+
+The spec-lookup tools (Group A) never hand-maintain component data. They
+derive everything at runtime from two files that live in jsonui-cli:
+
+| File | Owner | Role |
+|---|---|---|
+| `shared/core/attribute_definitions.json` | jsonui-cli | Raw schema: every component, every attribute, their `type`s, descriptions, enums, and — for attributes whose `type` includes `"binding"` — an optional `binding_direction: "two-way"` flag. |
+| `shared/core/component_metadata.json` | jsonui-cli | Presentation metadata: per-component description, aliases, which platforms generate the component, platform-specific implementation notes, and agent-facing prose rules. |
+
+`SpecLoader` joins these two at startup to produce the in-memory
+`ComponentSpec` map that the tools read.
+
+### 4-layer resolution
+
+Both files are located via the same fallback chain:
+
+1. `$JSONUI_CLI_PATH/shared/core/<file>` — env override for monorepos or
+   custom checkouts.
+2. `./.jsonui-cli/shared/core/<file>` — per-project override inside the
+   current working directory.
+3. `~/.jsonui-cli/shared/core/<file>` — default location of the
+   jsonui-cli bootstrap installer.
+4. `<mcp-root>/data/<file>` — bundled snapshot, populated at install
+   time by `scripts/fetch-definitions.js` (hit against
+   `raw.githubusercontent.com/Tai-Kimura/jsonui-cli/main/...`).
+
+The highest-priority existing file wins. If all four are missing,
+`SpecLoader` throws at startup with a diagnostic that lists every path
+it tried.
+
+The `get_data_source` tool exposes this information at runtime: which
+layer each file came from, its `mtime`, and a freshness bucket
+(`fresh` ≤30d / `aging` ≤90d / `stale` >90d). Agents that need
+up-to-date schema call this to verify the data they're working against.
+
+### Derived (non-file) content
+
+`src/data/derived.ts` holds content that does not depend on the two
+jsonui-cli files — it encodes fixed cross-platform conventions:
+
+- `MODIFIER_ORDER` (Swift / Kotlin / React application order + critical
+  rules like "background must come after padding").
+- `BINDING_RULES` (`@{}` syntax, two-way vs. read-only summary, direction
+  rules across platforms).
+- `PLATFORM_MAPPING` (`matchParent` / `wrapContent`, `contentMode`,
+  `textAlign`, `fontWeight`, `orientation`, `gravity`, type mappings).
+- `categorizeCommonAttributes(…)` — groups `common.*` attributes into
+  sizing / spacing / visual / visibility / interaction / layout /
+  lifecycle / accessibility / binding buckets for the lookup tools.
+
+These are served directly by the `get_modifier_order`,
+`get_binding_rules`, and `get_platform_mapping` tools.
+
+---
+
+## Tool inventory (33)
+
+### Group A — Spec lookup (7)
+
+| Tool | What it returns |
+|---|---|
+| `lookup_component` | Full spec for a component (attributes, binding behaviour, platform notes, rules). |
+| `lookup_attribute` | Definition + scope (common vs. component) for a single attribute name. |
+| `search_components` | Ranked matches across component names, aliases, descriptions, attribute names, and rules. |
+| `get_modifier_order` | Platform-specific modifier / class ordering. |
+| `get_binding_rules` | Full `@{}` binding reference. |
+| `get_platform_mapping` | Value/enum mapping across Swift/Kotlin/React. |
+| `get_data_source` | Per-file layer, path, `mtime`, freshness bucket. |
+
+### Group B — Project context (6)
+
+| Tool | Reads |
+|---|---|
+| `get_project_config` | `jui.config.json`, resolves relative paths to absolute. |
+| `list_screen_specs` | Screen-spec index with metadata. |
+| `list_component_specs` | Component-spec index with metadata. |
+| `list_layouts` | Layout JSON inventory. |
+| `read_spec_file` | One spec file (no parsing beyond `JSON.parse`). |
+| `read_layout_file` | One layout JSON file. |
+
+### Group C — `jui` CLI wrappers (8)
+
+`jui_init`, `jui_generate_project`, `jui_generate_screen`,
+`jui_generate_converter`, `jui_build`, `jui_verify`,
+`jui_migrate_layouts`, `jui_sync_tool`.
+
+`jui_sync_tool` mirrors the home `~/.jsonui-cli/` platform tools into each
+project-local `<platform_root>/<tool>_tools/`, preserving every
+`extensions/` directory and propagating each tool's `.ruby-version` to
+the platform root. Agents call it after a jsonui-cli bump or when
+bootstrapping a freshly scaffolded platform.
+
+### Group D — `jsonui-doc` CLI wrappers (9)
+
+`doc_init_spec`, `doc_init_component`, `doc_validate_spec`,
+`doc_validate_component`, `doc_generate_spec`, `doc_generate_component`,
+`doc_generate_html`, `doc_rules_init`, `doc_rules_show`.
+
+`figma fetch/images` and `generate mermaid/adapter` are intentionally
+excluded (token management / low priority).
+
+### Group E — API model discovery (3)
+
+`list_api_specs`, `list_api_models`, `preview_api_model_sync`.
+
+All three shell out to `jui` with `--json` output (`jui ls api-specs`,
+`jui ls api-models`, `jui g api --dry-run --json`). `list_api_specs` also
+surfaces the swagger halt conditions before a build is attempted;
+`preview_api_model_sync` is a pure dry-run — it reports kept/filtered
+schemas and the would-be file list without writing anything.
+
+---
+
+## Source layout
+
+```
+src/
+  index.ts                 # registers all 41 tools
+  config.ts                # ServerConfig: JUI_PROJECT_DIR, jui.config.json
+  cli_runner.ts            # execFile wrapper (no shell), timeout defaults
+  spec_loader.ts           # 4-layer fallback + merge pipeline, public API
+  data/
+    derived.ts             # MODIFIER_ORDER / BINDING_RULES / PLATFORM_MAPPING + categorizer
+  tools/
+    spec/ (7 files)        # Group A
+    context/ (6 files)     # Group B
+    jui/ (8 files)         # Group C
+    doc/ (9 files)         # Group D
+    api/ (3 files)         # Group E
+data/
+  attribute_definitions.json  # bundled snapshot (4th-layer fallback)
+  component_metadata.json     # bundled snapshot (4th-layer fallback)
+scripts/
+  fetch-definitions.js     # npm postinstall hook — fetches both files
+```
+
+---
+
+## Configuration
+
+### `project_dir` resolution
+
+Each tool in Groups B/C/D accepts an optional `project_dir`. Resolution:
+
+1. Tool parameter, if passed.
+2. `$JUI_PROJECT_DIR` environment variable.
+3. Otherwise the tool returns an actionable error.
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `JUI_PROJECT_DIR` | Default project directory for Groups B/C/D. |
+| `JSONUI_CLI_PATH` | Override for layer 1 of the spec-data fallback. |
+| `JSONUI_CLI_RAW_BASE` | Override the GitHub raw base URL used by the postinstall fetch script (defaults to `raw.githubusercontent.com/Tai-Kimura/jsonui-cli/main`). |
+| `JSONUI_ATTR_DEFINITIONS_URL` | Direct URL override for `attribute_definitions.json` in the fetch script. |
+| `JSONUI_COMPONENT_METADATA_URL` | Direct URL override for `component_metadata.json` in the fetch script. |
+
+### Claude Code integration
+
+`~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "jui-tools": {
+      "command": "node",
+      "args": ["<install_path>/dist/index.js"],
+      "env": {
+        "JUI_PROJECT_DIR": "/path/to/project"
+      }
+    }
+  }
+}
+```
+
+`install.sh` writes this entry (preserving any other servers); `uninstall.sh`
+removes it.
+
+---
+
+## Security
+
+- Group C/D tools invoke CLIs through `child_process.execFile`, never
+  `exec`, so no shell parses arguments.
+- File-read tools validate that targets stay inside `project_dir`.
+- `figma` CLIs are excluded to avoid handling tokens in this server.
+
+---
+
+## Install flow
+
+```bash
+git clone https://github.com/Tai-Kimura/jsonui-mcp-server.git
+cd jsonui-mcp-server
+./install.sh          # npm install → npm run build → postinstall fetch
+```
+
+`npm install` triggers `scripts/fetch-definitions.js` automatically. If
+the network is unavailable and no prior bundled snapshot exists, the
+script exits 0 and the MCP surfaces the misconfiguration at startup
+instead of silently running on stale data.

package/install.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+set -e
+
+REPO_URL="${JSONUI_MCP_REPO:-https://github.com/Tai-Kimura/jsonui-mcp-server.git}"
+INSTALL_DIR="${JSONUI_MCP_DIR:-$HOME/.jsonui-mcp-server}"
+CLAUDE_JSON="${CLAUDE_JSON:-$HOME/.claude.json}"
+NODE_BIN="$(which node)"
+
+if [ -z "$NODE_BIN" ]; then
+  echo "Error: node not found in PATH. Install Node.js first." >&2
+  exit 1
+fi
+
+echo "=== JUI Tools MCP Server Installer ==="
+echo "  Repo:    $REPO_URL"
+echo "  Install: $INSTALL_DIR"
+echo "  Node:    $NODE_BIN"
+
+# 1. Clone or update the repository
+if [ -d "$INSTALL_DIR/.git" ]; then
+  echo "Updating existing installation..."
+  cd "$INSTALL_DIR"
+  git fetch origin
+  git reset --hard origin/main
+elif [ -d "$INSTALL_DIR" ]; then
+  echo "Re-installing (previous directory had no .git)..."
+  rm -rf "$INSTALL_DIR"
+  git clone "$REPO_URL" "$INSTALL_DIR"
+  cd "$INSTALL_DIR"
+else
+  echo "Cloning repository..."
+  git clone "$REPO_URL" "$INSTALL_DIR"
+  cd "$INSTALL_DIR"
+fi
+
+# 2. Install dependencies
+echo "Installing dependencies..."
+npm install
+
+# 3. Build
+echo "Building..."
+npm run build
+
+# 4. Register MCP server in ~/.claude.json
+echo "Configuring Claude Code..."
+
+if [ ! -f "$CLAUDE_JSON" ]; then
+  cat > "$CLAUDE_JSON" << EOF
+{
+  "mcpServers": {
+    "jui-tools": {
+      "command": "$NODE_BIN",
+      "args": ["$INSTALL_DIR/dist/index.js"]
+    }
+  }
+}
+EOF
+else
+  node -e "
+    const fs = require('fs');
+    const data = JSON.parse(fs.readFileSync('$CLAUDE_JSON', 'utf8'));
+    if (!data.mcpServers) data.mcpServers = {};
+    // Remove old entry if exists
+    if (data.mcpServers['jsonui-spec']) {
+      delete data.mcpServers['jsonui-spec'];
+      console.log('Removed old jsonui-spec entry.');
+    }
+    data.mcpServers['jui-tools'] = {
+      command: '$NODE_BIN',
+      args: ['$INSTALL_DIR/dist/index.js']
+    };
+    fs.writeFileSync('$CLAUDE_JSON', JSON.stringify(data, null, 2));
+  "
+fi
+
+echo ""
+echo "Installation complete!"
+echo "  Installed to: $INSTALL_DIR"
+echo "  Server path: $INSTALL_DIR/dist/index.js"
+echo "  Node: $NODE_BIN"
+echo "  Config: $CLAUDE_JSON"
+echo ""
+echo "To set a default project directory, add env to your MCP config:"
+echo '  "jui-tools": {'
+echo '    "command": "'$NODE_BIN'",'
+echo '    "args": ["'$INSTALL_DIR'/dist/index.js"],'
+echo '    "env": { "JUI_PROJECT_DIR": "/path/to/your/project" }'
+echo '  }'
+echo ""
+echo "Restart Claude Code to activate the MCP server."