JsonUI
← Toolsjsonui-mcp-serverFifty-seven typed tools grouped into eight families. The agents use them to inspect any JsonUI project — specs, layouts, components, builds, runtime sync, API model discovery, test tooling, the jui viz server and the server room's infrastructure model — without each agent needing to re-implement parse, schema-lookup, or file I/O.~12 min read
What MCP isModel Context Protocol is Anthropic's standard for exposing tools to an LLM agent. jsonui-mcp-server is our implementation: it runs as a subprocess that Claude Code (or Codex) spawns on project load, and it publishes a manifest of 57 named tools. Each tool has a typed input schema, a typed output shape, and a brief description. The agent calls them by name; we own the server that answers.
The typed surfaceBecause each tool returns structured data, agents can ask questions like 'what are Collection's attributes?' and get a parseable answer, not prose. The cost of an agent learning a new component is a single call, not a file-tree scan. The cost of reviewing whether the agent used the attribute correctly is one shape-check, not a diff review.
lookup_component (example response)
{
"tool": "lookup_component",
"input": { "name": "Collection" },
"output": {
"name": "Collection",
"platforms": ["ios", "android", "web"],
"attributes": [
{ "name": "items", "type": ["CollectionDataSource", "binding"], "required": true },
{ "name": "cellIdProperty", "type": "String" },
{ "name": "sections", "type": "[CollectionSection]" }
]
}
}
Tool catalogHand-authored catalog kept in sync with the MCP server's 8-group tool list (57 tools currently — A:10 / B:7 / C:7 / D:9 / E:3 / F:10 / G:5 / H:6). Per-tool parameter docs live at /reference/mcp-tools.
Aget_project_config
Read jui.config.json + platform roots.
Alist_screen_specs
Enumerate every *.spec.json under docs/screens/json/. A parent spec's `subSpecs` are inlined as `screen_sub_spec` rows (name / description / parent), so a split screen's structure is visible without opening the parent file.
Asearch_specs
Keyword-search across ALL spec files — screen specs, sub-specs in subdirectories, component specs — returning file + JSON path + snippet per match. The fast way to find which spec (or which sub-spec of a split screen) covers a topic. It searches the spec JSON only: text held in a texts file (`.texts.yaml`) is not searched, so a reference's key is found but not the words it points to.
Alist_layouts
Enumerate every layout JSON under docs/screens/layouts/ with its screen / cell / partial classification (responsive variant files fold under their base entry).
Alist_component_specs
Enumerate every custom component spec under docs/components/json/.
Alookup_component
Return a built-in or custom component's attribute schema. A type spelling the build accepts for another component resolves to that component and says so in `typeSynonym` — `ProgressBar` returns Progress, `HStack` returns View with `implies: { orientation: horizontal }`.
Alookup_attribute
Return a single attribute's definition (type, enum, default, required) plus the platform truth around it: `platform` (the declared surface), `platform_reasons` (why an excluded platform was excluded, straight from the SSoT), and `implementationGaps` (declared pairs the codegen does not read yet, with their ledger notes).
Asearch_components
Fuzzy search across the component index for exploration. Task-phrase queries ("ios only", "platform override" and their Japanese spellings) surface a guide pointer — { guide: "platform_rules", nextTool: "get_platform_rules" } — at the top, so the mechanism is reachable without knowing any attribute name.
Aget_platform_rules
Return the platform-scoping rulebook for layouts: the node-level `platform` object form (merge attributes into one platform only), the string form (drop the node on non-matching platforms; language tokens accepted), the layout-root `platforms` whitelist, precedence (platform override > inline attribute > style value), and how all of this differs from `responsive`.
Aget_data_source
Report where the server loaded every canonical data file from — attribute_definitions.json, component_metadata.json, screen_identity.json, binding_semantics.json, type_synonyms.json and the rest — with layer, path, file mtime and freshness, so agents can confirm the data is current.
Bdoc_validate_spec
Validate a screen_spec.json against the schema.
Bdoc_validate_component
Validate a component_spec.json against the schema.
Bdoc_rules_init
Seed .jsonui-doc-rules.json with the project defaults.
Bdoc_rules_show
Print the active .jsonui-doc-rules.json.
Bjui_verify
Diff on-disk layouts against what the spec would generate (drift gate).
Bget_binding_rules
Return the canonical binding semantics (shared binding_semantics.json) + platform restrictions.
Bget_screen_identity
Return the canonical screen-identity rules (shared screen_identity.json): what counts as a screen, how ids are derived, the runtime marker and the assert:"screen" vocabulary.
Cdoc_init_spec
Create an empty screen_spec.json at the given path with a template shape.
Cdoc_init_component
Create an empty component_spec.json with a template shape.
Cdoc_generate_spec
Emit an HTML doc page for a screen spec. (wraps jsonui-doc CLI — see /tools/doc)
Cdoc_generate_component
Emit an HTML doc page for a component spec. (wraps jsonui-doc CLI — see /tools/doc)
Cdoc_generate_html
Bulk-generate HTML docs across specs — including multi-app whole sites (apps) and extra markdown doc dirs. (wraps jsonui-doc CLI — see /tools/doc)
Cjui_generate_project
Scaffold Layout + ViewModelBase + hook + navigation stubs from a spec. A Layout JSON that already exists and differs from what the spec generates is kept and named — `Kept existing layout: … --force replaces it` (measured: a hand edit survives a re-run). Called over MCP the command never asks, so without force an existing layout is kept.
Cjui_generate_screen
Scaffold a new spec + its initial Layout + VM pair in one step.
Djui_init
Bootstrap a fresh JsonUI project (directories, jui.config.json).
Djui_build
Distribute layouts + styles + strings to every platform and run the per-platform build.
Djui_sync_tool
Pull the latest rjui_tools / sjui_tools / kjui_tools from ~/.jsonui-cli/.
Djui_generate_converter
Scaffold a custom component converter from its spec. The command's input is closed when it starts, so on an existing component with neither skip_existing nor force it does not wait on the overwrite prompt until the server's timeout (the server's own record).
Djui_migrate_layouts
Run the CLI's layout migration sweeps for scheduled breaking changes.
Dread_spec_file
Read a screen or component spec back by filename. A spec whose prose fields point into a texts file (`{"md": "key"}`) comes back with each reference expanded to `{"md": …, "text": …}`, followed by a summary block naming the texts files it read and any reference it could not resolve; the `text` key is for reading only — edit the YAML file. A spec without references is returned byte for byte. Used by read-only agents like jsonui-debug.
Dread_layout_file
Read a layout JSON back by path.
Dget_platform_mapping
Return the spec-type → platform-type map (FeaturedLink → SwiftUI struct vs TS interface, etc.).
Dget_modifier_order
Return the canonical modifier order for styling attributes (padding, margin, …).
Elist_api_specs
Discover swagger files in `docs/api/` with title / version / schema_count / endpoint_count metadata, plus any parser halts.
Elist_api_models
Per-platform inventory of generated DTOs, Domain scaffolds, and orphans (the same set `jui ls api-models` reports).
Epreview_api_model_sync
Dry-run filter changes — returns `kept_schemas` / `filtered_out` / `skip_domain_matches` / `halts` as JSON without writing files.
Ftest_validate
Validate screen/flow test files + descriptions against the schema; when `test.install` is configured, installs the validated tests to the platform test dirs.
Ftest_generate_screen
Scaffold a screen test template for a named screen.
Ftest_generate_flow
Scaffold a flow test template spanning multiple screens.
Ftest_generate_description
Scaffold a description JSON for one screen/flow test case.
Ftest_report
Convert results JSON (results.schema.json) into a JUnit XML or HTML report.
Ftest_mock_generate
Scaffold API mock files from OpenAPI into `<mockDir>/generated/`; `check:true` reports drift without writing, comparing scenario bodies against the schema for their status code. (`mock serve` stays CLI-only.)
Ftest_generate_branch_tests
Generate unit-level branch tests from a spec's branchContracts (vitest / Kotlin JUnit4 + Robolectric / Swift XCTest). A screen with no branchContracts is an error, not a no-op.
Ftest_contracts_coverage
Report which API response statuses the branch contracts answer — per screen and platform, each status the OpenAPI documents for an operation the screen reaches, bucketed as answered, excluded with a reason, not evaluated, or uncovered. Read-only and not a gate; the CLI's JSON comes back as is, and its `exit` is the verdict.
Ftest_artifacts_pull
Collect run artifacts — iOS xcresult attachments, Android on-device files, and web Playwright videos / screenshots — into the configured artifacts dir; returns absolute paths.
Ftest_artifacts_status
Show the resolved `test.artifacts` config and what has already been collected.
Gviz_status
Whether the jui viz server is running (pid, URL), how many of the 18 hooks are in `~/.claude/settings.json`, and whether the permission relay is registered (`relay: false` skips that check). Wraps `jui viz status --json [--with-relay]`.
Gviz_doctor
Checks the viz environment: the Python packages, the hooks and the Python they run, the port, the claude CLI. Wraps `jui viz doctor --json`.
Gviz_start
Starts the server in the background and returns its URL once `/health` answers; a server already running is returned as `alreadyRunning`, not started again. Wraps `jui viz start --json [--port N]`.
Gviz_stop
Stops only the server jui recorded. Wraps `jui viz stop`.
Gviz_open
Opens the running server's page in the browser; fails when no server runs (call viz_start first). Wraps `jui viz open`.
Hinfra_validate
Whether the server-room model can be read (and why not), the files used, the counts, the number of flows, and the problems counted by severity and code with the first 20. In a room with migration plans (`docs/infra/migrations/<name>`) also each plan's problems, counts and step order (`plan` checks one). Wraps `jsonui-doc validate infra <project> --json [--migration <name>]`.
Hinfra_load_validate
The load scenarios (id, environment, month, hours, rows, edges) and their problems, with node, hour and quantity. Wraps `jsonui-doc validate infra-load <project> --json`.
Hinfra_prices_validate
The room's price files, the number of prices, and the problems. Wraps `jsonui-doc validate infra-prices <project> --json`.
Hinfra_seed
Drafts a model from IaC, settings files and code: counts, nodes, what was read, what could not be placed (unmatched), what was skipped, notes. By default it writes to a temporary folder and reads it back, leaving the project unchanged (`write: true` writes `<infra.dir>/seed`). Wraps `jsonui-doc seed infra <project> -o <dir> [--force]`.
Hinfra_check
The results of the declared `builtin:infra-iac` / `infra-code` / `infra-load` checks: status, counts, the first 20 results that are not ok, the report's path. Wraps `jsonui-doc check infra -p <project> --json`.
Hinfra_cost
The month's total, totals by provider (or node), the top nodes, the dearest day, what has no price, no rule or no load, the hours over capacity, and notes; `date` gives one day (each top node's meters with amounts and price layers, the peak hour). Load problems and price warnings too. `plan` gives a migration plan's old / new / difference (by node, largest change first; by provider; by step, with what moved in it) and names changed nodes left unpriced (unpricedChanged); `account: true` adds the account's month. Wraps `jsonui-doc cost infra <project> --json [--scenario] [--date] [--by] [--migration <name> [--account]]`.
Group semanticsA (Lookup, 10): read-only introspection of specs, layouts, the component index, and the data-source the server itself is using. B (Validation, 7): schema and drift checks — the gate logic agents run before declaring a change done. C (Generation, 7): create the empty shapes the agent will fill in — specs, scaffolds, HTML docs. D (Build + Runtime, 9): orchestrate the per-platform build, sync the tooling, and read files back so read-only agents (jsonui-debug) can work without spawning shell commands. E (API Model Discovery, 3): list_api_specs / list_api_models / preview_api_model_sync — for inspecting and dry-running the swagger → DTO + Domain pipeline. F (Test Tooling, 10): test_validate / test_generate_screen / test_generate_flow / test_generate_description / test_report / test_mock_generate / test_generate_branch_tests / test_contracts_coverage / test_artifacts_pull / test_artifacts_status — for validating, scaffolding, reporting, mocking, and collecting run artifacts (screenshots / recordings) of JsonUI tests (the long-running `mock serve` stays CLI-only). G (jui viz, 5): viz_status / viz_doctor / viz_start / viz_stop / viz_open — run, check and open the local viewer of Claude Code sessions. They run in the home folder and do not use JUI_PROJECT_DIR; installing the hooks and the relay writes `~/.claude/settings.json` and the MCP settings, so it stays CLI-only. H (Server room, 6): infra_validate / infra_load_validate / infra_prices_validate / infra_seed / infra_check / infra_cost — check, draft and price the model under docs/infra, each wrapping a `jsonui-doc … --json` command; fetching cloud prices goes to the network and stays CLI-only. The server registers all 57; it installs from npm (jui-tools-mcp-server) or with install.sh. Each group is one conceptual step in the spec-first loop; each tool is one bounded responsibility.
Keep reading
Agents for Claude / CodexThe clients that call these tools — nine agents with named responsibilities./tools/agents
jsonui-cliThe jui orchestrator and per-platform builders that the MCP tools delegate to for heavy lifting./tools/cli