Lanhu MCP 0.2

简体中文

Lanhu MCP is a local, Unity-only MCP server that converts a Lanhu design page into a validated Packet v1, a Unity Plan v1, and an experimental staged UGUI Prefab YAML snapshot.

What it supports

• Unity 2022.3 LTS and Unity 6 LTS.

• UGUI hierarchy and presentation components: GameObject, RectTransform, CanvasRenderer, Image, Text, masks, layout groups, LayoutElement, Outline, Shadow, and CanvasGroup.

• Conservative best-effort inference for Button, Slider, Toggle, ToggleGroup, InputField, Dropdown, ScrollRect, and Scrollbar.

• Downloaded sprites, deterministic .meta files, a Prefab Source Map, and an ownership manifest.

Semantic inference is not business-logic restoration. Review inferred component bindings in Unity. No C# Unity Editor importer is shipped in 0.2; the current Direct YAML path is best suited to inspectable snapshots, diffs, and pre-generation.

Related MCP server: lanhu-context-mcp

Requirements

• Python 3.10 or newer.

• A Lanhu session Cookie for private projects; some DDS sources may require a separate DDS Cookie.

• A Unity project whose root contains both Assets/ and ProjectSettings/.

• Unity's built-in UGUI package; editable text uses UnityEngine.UI.Text and the built-in Arial font by default.

Install and run

From a source checkout:

python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env
.venv/bin/lanhu-mcp

HTTP mode is loopback-only and listens at http://127.0.0.1:8126/mcp by default. This server has no remote authentication and must not be exposed to the internet.

For a stdio MCP client, point the client at the absolute path to run-stdio.sh. A typical MCP client entry is:

{
  "mcpServers": {
    "lanhu": {
      "command": "/absolute/path/to/lanhu-mcp/run-stdio.sh"
    }
  }
}

Client configuration keys vary by MCP host. The equivalent command is:

MCP_TRANSPORT=stdio /absolute/path/to/lanhu-mcp/.venv/bin/python -m lanhu_mcp

Configuration

Copy .env.example to .env. For an authorized Lanhu browser session, set the complete request Cookie header value; do not commit or share it. DDS_COOKIE is separate and never inherits LANHU_COOKIE.

LANHU_BASE_URL and DDS_BASE_URL are advanced HTTPS-only endpoint overrides. Process environment variables take precedence over .env; restart the MCP process after changing configuration.

The server intentionally clears DATA_DIR/packets and DATA_DIR/assets on startup. A packet_id and its downloaded files are therefore valid only for the current server process; call lanhu_prepare_design again after a restart.

Prepare Unity text

Editable UnityEngine.UI.Text output is enabled by default. During generation, Lanhu MCP scans the target project's Assets/ tree for .ttf/.otf files and matches normalized source names in this order: family + style/weight, then family. The matched font's .meta GUID is written internally as m_Font with fileID 12800000; users do not need to configure GUIDs for normal name-based matching.

Explicit text_font_map_json or UNITY_TEXT_FONT_MAP_* values override automatic matches, and text_font_guid/UNITY_TEXT_FONT_GUID supplies a default. These GUIDs must reference imported .ttf/.otf files, not TMP .asset files. Ambiguous or unmatched names produce warnings; unmatched text falls back to built-in Arial. Set use_text_components=false only when intentionally choosing visual-only rasterized text output.

Quick start workflow

The examples below show MCP tool payloads, not shell commands.

1. List designs

{
  "url": "https://lanhuapp.com/web/#/item/project/product?..."
}

Call lanhu_list_designs, then select a design by exact name, unique partial name, zero-based list index, or the image_id already present in the URL.

2. Prepare and download

Call lanhu_prepare_design:

{
  "url": "https://lanhuapp.com/web/#/item/project/product?...",
  "design": "Home",
  "force_refresh": false
}

Keep the returned packet_id. This step fetches sources, normalizes nodes, downloads assets into the managed cache, validates the Packet, and records partial download failures as warnings.

3. Inspect readiness

Call lanhu_inspect_design before writing Unity files:

{
  "packet_id": "0123456789abcdef0123",
  "view": "summary"
}

Review unity_readiness.status, blockers, review_items, missing assets, and missing font mappings. Use view="unity_plan" to inspect the exact creation/component plan, view="assets" for download state, and view="slices" for Sprite candidates.

4. Generate the Prefab snapshot

{
  "packet_id": "0123456789abcdef0123",
  "unity_project_path": "/absolute/path/to/UnityProject",
  "overwrite": false,
  "prefab_visual_mode": "layered",
  "use_text_components": true,
  "component_policy": "conservative"
}

The Unity project path must be the project root, not its Assets/ directory.

5. Verify generated files

Generation runs a staged static verification automatically. It also returns prefab_asset_path and source_map_asset_path, which can be checked again with lanhu_verify_unity_prefab:

{
  "unity_project_path": "/absolute/path/to/UnityProject",
  "prefab_asset_path": "Assets/LanhuMCP/Home/Prefabs/01234567_ViewRoot.prefab",
  "source_map_asset_path": "Assets/LanhuMCP/Home/Prefabs/01234567_ViewRoot.design-to-unity.json"
}

pass_with_warnings requires review; it is not the same as production acceptance.

Tool reference

lanhu_list_designs

lanhu_prepare_design

lanhu_inspect_design

lanhu_generate_unity_prefab

lanhu_verify_unity_prefab

Every tool response includes api_version: "0.2" and an envelope status. Expected failures use {code, message, details, retryable}. A successful envelope may still contain a domain result_status, readiness blockers, generation warnings, or verification status pass_with_warnings; inspect those fields before continuing.

Rendering and overwrite policies

Visual modes

• layered is the default editable output. Recognized and downloaded source assets are copied into Sprites/ and bound to layer Image components.

• flattened_reference_overlay uses the whole-design reference image as the visible baseline. It deliberately suppresses normal source-layer visuals while retaining hierarchy, metadata, and transparent interaction overlays. It requires a usable design.reference_asset_ref; if that reference download is missing or failed, do not use this mode.

include_reference=true copies the whole-design reference; it does not control whether normal slices are downloaded or imported.

Component policies

• conservative emits inferred interactive components only when confidence is at least 0.8, no semantic review is required, and all required serialized references are available.

• structure_only emits hierarchy and presentation components without inferred interaction.

Overwrite safety and limitation

Output is built in staging, statically verified, and transactionally committed. overwrite=false rejects collisions. overwrite=true can replace only files listed in the same Packet's ownership manifest; failures restore replaced files, and historical orphans are reported rather than deleted.

Generated output

With the default asset_root, output resembles:

Assets/LanhuMCP/<design-name>/
├── Sprites/
│   ├── <generated images>
│   └── <generated image .meta files>
├── Prefabs/
│   ├── <name>.prefab
│   ├── <name>.prefab.meta
│   ├── <name>.design-to-unity.json
│   └── <name>.design-to-unity.json.meta
└── lanhu-mcp-manifest.json

• The Source Map records source node IDs, Unity fileIDs, assets, component counts, policies, and expected import gates.

• The ownership manifest records the Packet owner and SHA-256 of every generated file; do not delete it if you intend to use overwrite=true later.

Unity acceptance checks

Static status means:

• pass: no static YAML/schema/reference problem was found.

• pass_with_warnings: files are structurally usable but listed bindings or resources require review.

• fail: regenerate or fix the reported files/references before Unity import.

After a static pass or reviewed pass_with_warnings:

1. Open/refresh the project in the matching supported Unity Editor.

2. Confirm the project compiles and the Console has no relevant import errors.

3. Open the Prefab and check for Missing Scripts.

4. Confirm generated textures import as Sprites and the Source Map imports as a TextAsset.

5. Review UGUI Text font appearance and inferred Slider, Toggle, InputField, Dropdown, ScrollRect, Scrollbar, mask, and layout bindings.

6. Capture a Prefab/GameView screenshot and compare it with the Lanhu reference.

Static verification cannot replace these steps.

Troubleshooting

Data contracts and migration

Version 0.2 intentionally does not load or migrate legacy/unversioned Packets or Source Maps. Canonical JSON Schemas live in schemas/ and can be regenerated with:

python -m lanhu_mcp.schema_export schemas

See Security, Architecture, Data contracts, 0.2 migration, Unity support, and the Changelog.

Development

uv sync --extra dev
.venv/bin/ruff check src tests
.venv/bin/mypy src/lanhu_mcp
.venv/bin/pytest

License

MIT