Skip to main content
Glama
aea91

ArkUIBuilder MCP

by aea91
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ArkUIBuilder MCP

MCP server that gives AI assistants (Claude Code, Claude Desktop, Cursor, …) the ArkUIBuilder catalog of ready-made HarmonyOS ArkUI components.

Instead of writing UI components from scratch, the assistant finds a tested one, has this server copy it into the project, and writes only the call:

You:    Build a fitness page with a step ring and a dark-mode toggle, using ArkUIBuilder widgets.
Claude: search_widgets("progress ring")  → ProgressRingFb({ value: this.value })
        search_widgets("toggle")         → SwitchFb({ on: this.on })
        add_widget(ProgressRingFb, …/pages/Fitness.ets)   ← file + import written by the server
        add_widget(SwitchFb, …/pages/Fitness.ets)
        …writes only the page: @State value, @State on, and the two calls in build()

Because the component code is copied by the server rather than typed by the model, the assistant spends tokens only on the page itself. For example, ColorStudioFb's signature is ~70 tokens; its source is ~1,400.

Tools

Tool

What it does

search_widgets

Search by words, platform (Mobile, Wearable, PC (2in1), My Widgets) and category. No arguments gives an overview. Each result shows the call and required parameters.

get_widget

One widget's details; include_code: true adds its source (only needed to adapt it).

add_widget

Writes <module>/src/main/ets/components/<Name>.ets, adds import { Name } from '…' to target_file, returns the call. Never overwrites a different existing file unless overwrite: true. Reports $r() / $rawfile() resources the module lacks.

It also lists My Widgets saved with the ArkUIBuilder IDE plugin (found automatically in the IDE config folders; set ARKUIBUILDER_MY_WIDGETS to point at a my-widgets.json elsewhere).

Related MCP server: ArkTS Helper MCP

Setup

Requires Node.js 18+.

Claude Code

claude mcp add arkuibuilder -- npx -y arkuibuilder-mcp

Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json) and other MCP clients:

{
  "mcpServers": {
    "arkuibuilder": { "command": "npx", "args": ["-y", "arkuibuilder-mcp"] }
  }
}

From a local checkout, use node /path/to/arkuibuilder-mcp/dist/index.js as the command instead.

Development

npm install
npm test        # builds, then runs parser, importer and stdio end-to-end tests

The component parser is a port of the IDE plugin's ComponentParser.kt; a test checks that both produce the same call for every catalog widget (test/fixtures/plugin-calls.txt). Environment variables:

Variable

Purpose

ARKUIBUILDER_CATALOG_FILE

Read the catalog from a saved getWidgetCatalog response instead of the network

ARKUIBUILDER_MY_WIDGETS

Path of the plugin's my-widgets.json

Available Tools

3 tools
add_widgetAdd an ArkUIBuilder widget to the projectA
Idempotent

Copies a widget's component into /src/main/ets/components/.ets and adds its import to target_file. Returns the call to place in build(). Never overwrites a different existing file unless overwrite is true.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesComponent name, id or title
overwriteNoReplace an existing, different components/<Name>.ets (default false)
target_fileYesAbsolute path of the .ets page that will use it, inside <module>/src/main/ets (may not exist yet)

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare openWorldHint, idempotentHint, and non-destructive; the description goes further by disclosing concrete side effects (file written to a specific path, import injected into target_file) and the overwrite guard, which is exactly the kind of behavior an agent needs to know. It does not cover failure modes or permission requirements, so it falls short of exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core action, followed by the return value and the destructive-behavior caveat. No filler or restated name/title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully states what is returned (the call to place in build()), and annotations cover the safety profile, so an agent has enough to invoke it correctly. The only gap is where the widget component source comes from and what happens on failure, which is minor for a 3-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents name, overwrite, and target_file, making 3 the baseline. The description reinforces overwrite semantics ('Never overwrites a different existing file unless overwrite is true') but adds no format or constraint detail beyond what the schema already gives.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb (copies/adds import) and concrete destination (<module>/src/main/ets/components/<Name>.ets plus target_file), so the operation is unmistakable. It does not name the siblings search_widgets or get_widget, but the add-vs-read distinction is implicit and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent infers this is the tool to call when it has a widget name and wants it wired into a page, and 'Returns the call to place in build()' hints at the workflow step. No explicit when-to-use, when-not-to-use, or alternative (e.g., versus search_widgets/get_widget) is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_widgetGet an ArkUIBuilder widgetA
Read-only

Details of one widget by component name (e.g. ColorStudioFb), id or title. Set include_code only if you need to read or adapt its source; to use it as-is call add_widget instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesComponent name, id or title
include_codeNoInclude the full ArkTS source (default false)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavioral context: include_code pulls the full ArkTS source (a materially heavier payload) and should only be set for read/adapt scenarios.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the identifier forms and ending with the conditional/alternative routing. Every clause carries actionable information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with a read-only annotation and no output schema, the definition covers identity, the payload-cost branch, and the sibling alternative. Only the shape of the returned widget details is left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the identifier formats for name are already documented and the description largely repeats them. include_code's cost/usage intent is a mild addition beyond the schema's (default false) note, keeping this at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (retrieve details) and resource (one widget) with the three accepted identifier forms. It is clearly distinguishable from siblings, and explicitly names add_widget as the alternative path for using a widget as-is.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit conditional for include_code (only when you need to read or adapt the source) and routes the as-is use case to add_widget. It does not mention search_widgets as the discovery alternative, so the guidance is strong but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_widgetsSearch ArkUIBuilder widgetsA
Read-only

Search ready-made HarmonyOS ArkUI components (ArkUIBuilder catalog plus the user's My Widgets). Each result shows the call to write in build() and its required parameters. Call with no arguments for an overview of platforms and categories.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum results (default 15)
queryNoWords to match in name, title, category, tags or description
categoryNoExact category name from the overview
platformNoMobile, Wearable, Light Wearable, PC (2in1) or My Widgets

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower, and the description still adds real behavior: the result format ("the call to write in build() and its required parameters") and the special no-argument overview mode. Pagination and result-count behavior are left to the schema's limit field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the core action front-loaded, then result format, then the empty-query tip. No sentence is redundant and nothing is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool with no required parameters and full schema coverage, the definition covers sources, result shape, and the no-arg path. With no output schema, a brief note on result volume or how filtering composes would have made it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters are already documented with their matching semantics and allowed platform values. The description only adds the zero-argument case, which is not a per-parameter detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search ready-made HarmonyOS ArkUI components") and even names the two underlying catalogs it searches. It does not explicitly distinguish itself from get_widget or add_widget, but the search-vs-retrieve-vs-add split is inferable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete usage mode: "Call with no arguments for an overview of platforms and categories," which tells the agent how to bootstrap discovery before filtering. It stops short of naming when to prefer get_widget or add_widget instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedadd_widget
    • First observedget_widget
    • First observedsearch_widgets
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation4/5

search_widgets (discover), get_widget (inspect source/details), and add_widget (install into module) have distinct actions, and the descriptions explicitly steer between them (e.g. 'to use it as-is call add_widget instead'). There is mild overlap since search results already return the build() call and parameters, making get_widget's unique value narrower, but the boundaries are clearly drawn.

Naming Consistency5/5

All three tools follow a clean verb_noun snake_case pattern: search_widgets, get_widget, add_widget. The convention is predictable and consistent throughout.

Tool Count4/5

Three tools is on the thin side, but the server's scope (search a widget catalog, inspect a widget, install it) is genuinely narrow, so each tool earns its place. A list-categories or remove-widget tool would round it out but the count is reasonable for the purpose.

Completeness4/5

The core lifecycle of discover -> inspect -> install is fully covered, including an overview mode (search with no args) and a copy/install operation. Minor gaps exist (no tool to remove or update an already-installed widget), but these are workarounds an agent can handle manually.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers