Content
# lanhu-context-mcp
English | [简体中文](./README.md)
[](https://npmjs.com/package/lanhu-context-mcp) [](https://npmjs.com/package/lanhu-context-mcp) [](https://github.com/refinist/lanhu-context-mcp/actions/workflows/unit-test.yml) [](https://codecov.io/github/refinist/lanhu-context-mcp)
✨ Organize LanHu design drafts into context for AI-generated code.
## Features
- 🎨 Support outputting `HTML+CSS` or `HTML+Tailwind`, adaptable to project tech stacks.
- 🖼️ Provide sliced image resources mapping and download commands, reducing manual handling.
- 🧱 Supplement `Design Tokens` and design preview images for further implementation and visual verification.
- 🧭 Include implementation guidelines for downstream AI, specifying priorities, adaptation methods, and constraints.
- ⚙️ Configurable via CLI parameters and environment variables for `Tailwind` output, image slicing, unit scaling, and prompt language.
- 📦 Offer `inline` / `files` output modes: `inline` returns all content directly; `files` packages HTML, image mapping, Design Tokens, and Guide into `context.md` + `preview.png`, and only returns a resource link, avoiding MCP client output token limits.
## Documentation
For comprehensive documentation, visit [lanhu.refineup.com](https://lanhu.refineup.com).
## Quick Start
### Environment Requirements
- Node.js `^20.19.0 || >=22.12.0`
### Design Draft Conversion
- Enable conversion and upload to LanHu.
### Step 1. Prepare Environment Variables
Create a `.env.local` file.
Obtain a valid LanHu login token, refer to [Get LanHu Token](https://lanhu.refineup.com/guide/get-lanhu-token).
```dotenv
LANHU_TOKEN=your_lanhu_token_here
```
### Step 2. Configure MCP
Insert the corresponding MCP configuration for your client into the respective file; if using Qoder, add and paste the configuration on the MCP service page:
Claude Code (`.mcp.json`) / Cursor (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "npx",
"args": ["-y", "lanhu-context-mcp"]
}
}
}
```
TRAE (`.trae/mcp.json`)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "npx",
"args": ["-y", "lanhu-context-mcp", "--cwd", "${workspaceFolder}"]
}
}
}
```
Codex (`.codex/config.toml`)
```toml
[mcp_servers.lanhu-context-mcp]
cwd = "/absolute/path/to/current-project"
command = "npx"
args = ["-y", "lanhu-context-mcp"]
```
Qoder (Global MCP Service)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "npx",
"args": [
"-y",
"lanhu-context-mcp",
"--cwd",
"/absolute/path/to/current-project"
],
"env": {
"LANHU_TOKEN": "your_lanhu_token_here"
}
}
}
}
```
`TRAE` has a design issue: MCP subprocess working directory doesn't point to the current project, causing `.env.local` unreadable and `.lanhu-context-mcp.local/` abnormal writing. So, TRAE configuration must pass `--cwd` parameter; use editor's built-in variable `${workspaceFolder}` to automatically point to the project root.
`Codex` MCP configuration is special, requiring extra `cwd` setting to current project's absolute path. Since this path varies by person, it's not recommended to commit `.codex/config.toml` to Git; instead, exclude it from Git and maintain it locally.
`Qoder` currently only supports global (user-level) MCP configuration, with a working directory typically being `/`, causing permission issues when writing `.lanhu-context-mcp.local/`. So, Qoder configuration must specify `--cwd` (or `env.CWD`) to switch the working directory to the project root and pass `LANHU_TOKEN` via `env`.
`--cwd` doesn't need to be an absolute path; editors with variable replacement (like VSCode) can use built-in variables for team-shared configurations.
**Windows**
If directly using the above `npx` configuration fails on Windows, try the following:
Claude Code (`.mcp.json`) / Cursor (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "cmd",
"args": ["/c", "npx", "-y", "lanhu-context-mcp"]
}
}
}
```
TRAE (`.trae/mcp.json`)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"lanhu-context-mcp",
"--cwd",
"${workspaceFolder}"
]
}
}
}
```
Codex (WSL2)
```toml
[mcp_servers.lanhu-context-mcp]
cwd = "/absolute/path/to/current-project"
command = "npx"
args = ["-y", "lanhu-context-mcp"]
```
Codex (Native)
```toml
[mcp_servers.lanhu-context-mcp]
cwd = "C:\\absolute\\path\\to\\current-project"
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "lanhu-context-mcp"]
[mcp_servers.lanhu-context-mcp.env]
APPDATA = "C:\\Users\\{your-name}\\AppData\\Roaming"
LOCALAPPDATA = "C:\\Users\\{your-name}\\AppData\\Local"
USERPROFILE = "C:\\Users\\{your-name}"
HOME = "C:\\Users\\{your-name}"
SYSTEMROOT = "C:\\Windows"
COMSPEC = "C:\\Windows\\System32\\cmd.exe"
```
Qoder (Global MCP Service)
```json
{
"mcpServers": {
"lanhu-context-mcp": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"lanhu-context-mcp",
"--cwd",
"C:\\absolute\\path\\to\\current-project"
],
"env": {
"LANHU_TOKEN": "your_lanhu_token_here"
}
}
}
}
```
`Codex` native fallback: [openai/codex#2555](https://github.com/openai/codex/issues/2555#issuecomment-3381914894)
### Step 3. Install Lanhu Helper Google Chrome Extension
Install [Lanhu Helper](https://lanhu.refineup.com/ecosystem/lanhu-helper) to directly copy selected layer links or example prompts from LanHu.
### Step 4. Send LanHu Link and Prompt to AI
```text
Please implement based on this LanHu design draft
@https://lanhuapp.com/web/#/item/project/detailDetach?tid={tid}&pid={pid}&project_id={project_id}&image_id={image_id}
```
```text
https://lanhuapp.com/web/#/item/project/detailDetach?tid={tid}&pid={pid}&project_id={project_id}&image_id={image_id}
```
Write your prompt freely, but ensure the LanHu URL is complete and correct for normal tool invocation.
[View richer documentation](https://lanhu.refineup.com/guide/getting-started)
## Ecosystem
[Lanhu Helper](https://lanhu.refineup.com/ecosystem/lanhu-helper) — Companion LanHu Chrome extension to copy selected layer links and example prompts.
## Contributing
Welcome to submit PRs or issues. Here's the process to set up the development environment:
### 1. Install Dependencies
The repository uses pnpm workspace (including `playground` subpackage); run in the root directory:
```sh
pnpm install
```
### 2. Prepare `.env.local`
Copy the example file and fill in credentials without the `.example` suffix:
```sh
cp .env.local.example .env.local
```
Field explanations:
| Field | Required | Purpose |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `LANHU_TOKEN` | Yes | LanHu API token; obtain via [Get LanHu Token](https://lanhu.refineup.com/guide/get-lanhu-token) |
| `LANHU_TEST_URL` | For integration tests | A real, accessible LanHu design draft detail link; integration tests send requests to it. |
### 3. Three-layer Verification Matrix
Different changes suggest running different verification levels:
| Level | Command | When to run | Dependencies |
| -------------- | ------------------------------------------------ | --------------------------------------- | ----------------------------------------- |
| Unit tests | `pnpm test` / `pnpm test:coverage` | Any PR must pass; target coverage 100% | None |
| Integration tests | `pnpm test:integration` and its `:http/:stdio` variants | Service, tool, transport, or protocol layer changes; suggest running | `LANHU_TOKEN` + `LANHU_TEST_URL` |
| End-to-end verification arena | See playground section below | Output format, prompt, or file landing logic changes; manual testing | `LANHU_TOKEN` + Any MCP client |
Subsets of integration tests (e.g., only files mode, only stdio) are in `package.json`'s `test:integration:*` scripts.
### 4. playground — End-to-end Verification Arena (E2E Verification Harness)
`playground/` is a Vue 3 + Vite + Tailwind project to run actual LanHu API, land generated pages in `src/pages/`, and preview via dev server — verifying `get_design_context` chain behavior not covered by unit/integration tests.
Common commands:
```sh
# Start playground dev server
pnpm play
# Clean up previous build (pages in src/pages + assets in src/assets + .lanhu-context-mcp.local directory)
pnpm play:clean
```
Detailed workflow and client configurations see [`playground/README.md`](./playground/README.md).
### 5. Pre-PR Checklist
- [ ] `pnpm typecheck` passes
- [ ] `pnpm test` passes with no coverage decrease (run `pnpm test:coverage` to confirm)
- [ ] `pnpm lint` passes
- [ ] For changes affecting external behavior or output format, run at least one `pnpm test:integration:files` or verify in playground.
## License
[MIT](./LICENSE)
Copyright (c) 2026-present, [REFINIST](https://github.com/refinist)
