MCP tool API — JsonUI

← ReferenceMCP tool APIAll 45 MCP tools, grouped A–F (Lookup / Validation / Generation / Build + Runtime / API Model Discovery / Test Tooling), with their input schemas, return shapes, and one-line descriptions. Hand-authored catalog kept in sync with the MCP server's 6-group tool list.reference

Who reads thisPrimarily the agents and humans writing tooling on top of the MCP server. Day-to-day agent use happens via high-level verbs (jsonui-conductor routes, jsonui-define authors, etc.); the per-tool page is for the engineer who needs to know whether the input takes `name` or `component_name`, whether the return is `Attribute[]` or `{ name, type, ... }[]`, and so on.

Group semanticsA (8 tools, Lookup): read-only introspection. B (7, Validation): schema + drift checks. C (7, Generation): scaffold empty shapes. D (9, Build + Runtime): orchestrate builds, sync tooling, read files back. E (3, API Model Discovery): inspect + dry-run the swagger → DTO/Domain pipeline. F (8, Test Tooling): validate / scaffold / report / mock JsonUI tests + pull run artifacts (screenshots / recordings). Each group corresponds to a phase in the spec-first loop, so 'which group is this tool in' is also 'when do I call it'.

Reading a tool entryEach tool has four fields: name (the string you pass to the MCP client), description (one line, shown in manifest), inputSchema (JSON Schema for the arguments), and a notional output shape (the server types this but MCP does not return a schema — treat it as advisory). Required arguments sort first; optional second.

Tool stabilityTools under Group A / B are stable — those have been exercised across all three platforms. Group C / D tools are newer and may add optional fields over time; callers should not rely on an exhaustive struct destructure. Removals require a major version bump.

Tool catalogAll 45 tools, in the same order /tools/mcp lists them, with parameter signatures. Required parameters are bold-marked in the agent's view; optional ones default to omitted. `project_dir` repeats on most tools — when omitted, the server falls back to the JUI_PROJECT_DIR env var (or the cwd that spawned it).

Aget_project_config

Read jui.config.json + platform roots.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Alist_screen_specs

Enumerate every *.spec.json under docs/screens/json/. Since MCP 2.8.0 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.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

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. Added in MCP 2.8.0.Parameters

• query (string, required) — Search keyword; matched case-insensitively against keys and string values.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Alist_layouts

Enumerate every layout JSON under docs/screens/layouts/ with its screen / cell / partial classification (responsive variant files fold under their base entry).Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Alist_component_specs

Enumerate every custom component spec under docs/components/json/.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Alookup_component

Return a built-in or custom component's attribute schema.Parameters

• name (string, required) — Component name. e.g. 'TextField', 'Button', 'View'.

Alookup_attribute

Return a single attribute's definition (type, enum, default, required) plus, since MCP 2.4.0, 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).Parameters

• name (string, required) — Attribute name. e.g. 'fontSize', 'padding', 'onClick'.

Asearch_components

Fuzzy search across the component index for exploration. Since MCP 2.8.0, 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.Parameters

• query (string, required) — Search keyword. Matches component names and attribute names.

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`. Added in MCP 2.8.0.Parameters

No parameters — returns the platform-scoping rulebook (platform_semantics.json) as-is.

Aget_data_source

Report which attribute_definitions.json / component_metadata.json the server loaded — layer, file mtime, and freshness — so agents can confirm the data is current.Parameters

(no parameters)

Bdoc_validate_spec

Validate a screen_spec.json against the schema.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Bdoc_validate_component

Validate a component_spec.json against the schema.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Bdoc_rules_init

Seed .jsonui-doc-rules.json with the project defaults.Parameters

• flutter (boolean, optional) — Include Flutter-specific rules in the template.
• output_dir (string, optional) — Output directory for the .jsonui-doc-rules.json file (default: project root).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Bdoc_rules_show

Print the active .jsonui-doc-rules.json.Parameters

• directory (string, optional) — Directory to search for .jsonui-doc-rules.json (default: cwd, walks up).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Bjui_verify

Diff on-disk layouts against what the spec would generate (drift gate).Parameters

• detail (boolean, optional) — Include per-screen diff details in the report.
• fail_on_diff (boolean, optional) — Exit with error if any diff is detected; pair with CI gating.
• platform (string, optional) — Target platform (defaults to the first one in jui.config.json).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Bget_binding_rules

Return the canonical binding semantics (shared binding_semantics.json) + platform restrictions.Parameters

(no parameters)

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.Parameters

(no parameters)

Cdoc_init_spec

Create an empty screen_spec.json at the given path with a template shape.Parameters

• name (string, required) — Screen name in PascalCase. e.g. 'LoginScreen'.
• display_name (string, optional) — Display name (defaults to the PascalCase name).
• output_dir (string, optional) — Output directory (defaults to spec_directory in config).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Cdoc_init_component

Create an empty component_spec.json with a template shape.Parameters

• name (string, required) — Component name in PascalCase. e.g. 'CustomCard'.
• display_name (string, optional) — Display name.
• category (enum, optional) — Component category for grouping.
• output_dir (string, optional) — Output directory.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Cdoc_generate_spec

Emit an HTML doc page for a screen spec. (wraps jsonui-doc CLI — see /tools/doc)Parameters

• file (string, required) — Spec file or directory path. e.g. 'login.spec.json' or 'docs/screens/json'.
• output (string, optional) — Output file or directory path.
• format (enum, optional) — Output format: html | markdown (default: html).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Cdoc_generate_component

Emit an HTML doc page for a component spec. (wraps jsonui-doc CLI — see /tools/doc)Parameters

• file (string, required) — Component spec file or directory path.
• output (string, optional) — Output file or directory path.
• format (enum, optional) — Output format: html | markdown (default: html).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

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)Parameters

• input_dir (string, required) — Directory containing .test.json files.
• output_dir (string, optional) — Output directory for HTML files.
• title (string, optional) — Documentation title shown in the generated index.
• apps (string[], optional) — App sections as NAME:DIR entries (repeatable --app); for multi-app whole-site generation.
• docs_dirs (string[], optional) — Additional markdown doc directories (repeatable -d/--docs).
• figma_dir (string, optional) — Figma assets directory (-fig).
• layouts_dir (string, optional) — Layouts directory override (--layouts-dir).
• with_checks (boolean, optional) — Run doc contract checks during generation (--with-checks).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Cjui_generate_project

Scaffold Layout + ViewModelBase + hook + navigation stubs from a spec.Parameters

• force (boolean, optional) — Force overwrite of declaration files.
• skip_layout (boolean, optional) — Skip Layout JSON generation.
• dry_run (boolean, optional) — Show what would be generated without writing.
• platform (enum, optional) — Generate for a single platform only.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Cjui_generate_screen

Scaffold a new spec + its initial Layout + VM pair in one step.Parameters

• names (string[], required) — Screen names in PascalCase. e.g. ['LoginScreen', 'RegisterScreen'].
• display_name (string, optional) — Display name (only valid when names has exactly one entry).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Djui_init

Bootstrap a fresh JsonUI project (directories, jui.config.json).Parameters

• project_name (string, required) — Project name.
• ios_path (string, optional) — iOS project root relative path.
• ios_mode (enum, optional) — iOS rendering mode: swiftui | uikit (default: swiftui).
• android_path (string, optional) — Android project root relative path.
• android_mode (enum, optional) — Android rendering mode: compose | views (default: compose).
• package_name (string, optional) — Android package name. e.g. 'com.example.app'.
• web_path (string, optional) — Web project root relative path.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Djui_build

Distribute layouts + styles + strings to every platform and run the per-platform build.Parameters

• clean (boolean, optional) — Clean build; regenerate everything.
• platform (enum, optional) — Build a single platform only.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Djui_sync_tool

Pull the latest rjui_tools / sjui_tools / kjui_tools from ~/.jsonui-cli/.Parameters

• platform (enum, optional) — Sync only one platform (default: every platform in jui.config.json).
• dry_run (boolean, optional) — Show what would change without writing.
• from (string, optional) — Override source CLI root (default: $JSONUI_CLI_PATH or ~/.jsonui-cli/).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Djui_generate_converter

Scaffold a custom component converter from its spec.Parameters

• from_spec (string, optional) — Generate from a single component spec file path.
• all (boolean, optional) — Generate from all component specs in the project.
• container (boolean, optional) — Mark as a container component (accepts child nodes).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Djui_migrate_layouts

Run the CLI's layout migration sweeps for scheduled breaking changes.Parameters

• source_platform (enum, optional) — Platform to copy from: ios | android | web (default: ios).
• dry_run (boolean, optional) — Show what would be copied without executing.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Dread_spec_file

Read a spec file back by path. Used by read-only agents like jsonui-debug.Parameters

• file (string, required) — Filename. e.g. 'login.spec.json' or 'my_card.component.json'.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Dread_layout_file

Read a layout JSON back by path.Parameters

• file (string, required) — Filename. e.g. 'Login.json' or 'Styles/Common.json'.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Dget_platform_mapping

Return the spec-type → platform-type map (FeaturedLink → SwiftUI struct vs TS interface, etc.).Parameters

• category (string, optional) — Mapping category: values, contentMode, textAlign, fontWeight, orientation, gravity, types. Omit for all.

Dget_modifier_order

Return the canonical modifier order for styling attributes (padding, margin, …).Parameters

• platform (enum, optional) — Platform: swift | kotlin | react. Omit for all platforms.

Elist_api_specs

Discover swagger files in `docs/api/` with title / version / schema_count / endpoint_count metadata, plus any parser halts.Parameters

• project_dir (string, optional) — Project directory. Overrides JUI_PROJECT_DIR env.

Elist_api_models

Per-platform inventory of generated DTOs, Domain scaffolds, and orphans (the same set `jui ls api-models` reports).Parameters

• platform (enum, optional) — Platform: ios | android | web. Omit for all platforms.
• project_dir (string, optional) — Project directory. Overrides JUI_PROJECT_DIR env.

Epreview_api_model_sync

Dry-run filter changes — returns `kept_schemas` / `filtered_out` / `skip_domain_matches` / `halts` as JSON without writing files.Parameters

• project_dir (string, optional) — Project directory. Overrides JUI_PROJECT_DIR env.

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.Parameters

• files (string[], required) — Files or directories to validate (e.g. ['tests/screens'] or ['login.test.json']).
• quiet (boolean, optional) — Hide warnings, show only errors.
• verbose (boolean, optional) — Show all files, including valid ones.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Ftest_generate_screen

Scaffold a screen test template for a named screen.Parameters

• name (string, required) — Screen name (e.g. login, home).
• path (string, optional) — Output test file path (default: tests/screens/<name>/<name>.test.json).
• platform (string, optional) — Target platform: ios / ios-swiftui / ios-uikit / android / web / all.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Ftest_generate_flow

Scaffold a flow test template spanning multiple screens.Parameters

• name (string, required) — Flow name (e.g. login, checkout).
• path (string, optional) — Output test file path (default: tests/flows/<name>/<name>.test.json).
• platform (string, optional) — Target platform: ios / ios-swiftui / ios-uikit / android / web / all.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Ftest_generate_description

Scaffold a description JSON for one screen/flow test case.Parameters

• test_type (string, required) — Whether the case belongs to a screen or flow test: screen / flow.
• name (string, required) — Screen/flow name (e.g. login, checkout).
• case_name (string, required) — Test case name (e.g. initial_display, happy_path).
• path (string, optional) — Output file path (default: tests/<type>s/<name>/descriptions/<case_name>.json).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

Ftest_report

Convert results JSON (results.schema.json) into a JUnit XML or HTML report.Parameters

• files (string[], required) — Results JSON files to convert (multiple inputs merge into one report).
• format (string, required) — Report format: junit / html.
• output (string, optional) — Output file path (default: report.xml / report.html).
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

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.)Parameters

• swagger (string[], optional) — Paths to OpenAPI files (repeatable). Defaults to the project mock config if omitted.
• out (string, optional) — Output mock dir (default: mock.mockDir or tests/mocks).
• config_file (string, optional) — Config file (default: jui.config.json).
• check (boolean, optional) — When true, report drift vs swagger and do NOT write (adds --check). Default false.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.

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.Parameters

• screen (string, required) — Screen name in snake_case (resolves <spec_directory>/<screen>.spec.json).
• platform (string, optional) — web (default) / android / ios. android also requires package; ios also requires module.
• package (string, optional) — Kotlin package for the generated sources — required for platform 'android'.
• module (string, optional) — App module name for @testable import — required for platform 'ios'.
• spec (string, optional) — Explicit spec file path (overrides spec_directory resolution).
• out_dir (string, optional) — Output directory for the @generated test + runtime files.
• harness_dir (string, optional) — Project-owned harness directory (skeleton written only when absent).
• mocks_dir (string, optional) — Directory scanned for *.mock.json scenario files.
• project_dir (string, optional) — Project directory (overrides JUI_PROJECT_DIR).

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.Parameters

• platform (string, optional) — Restrict collection to one platform: ios / android / web. Default: all.
• clean (boolean, optional) — Remove the sources after pulling (Android: the device-side tree; web: the local Playwright output dirs). Default false.
• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.
Returns the CLI's JSON output — the absolute paths of every collected file (organized under tests/artifacts/<platform>/<stamp>/, with a latest symlink).

Ftest_artifacts_status

Show the resolved `test.artifacts` config and what has already been collected.Parameters

• project_dir (string, optional) — Project directory; overrides the JUI_PROJECT_DIR env var.
Returns the resolved `test.artifacts` config (dir / ios.xcresult / android.appId / web.testResults / web.screenshotDir, plus the resolved adb path or null) and a listing of what has already been collected.

Keep reading

jsonui-mcp-serverThe overview page this reference details./tools/mcp

AgentsThe clients that call these tools./tools/agents