Turn Lanhu (蓝湖) design URLs into AI-ready front-end implementation context — a pipeline CLI built for AI agents and shell automation, with an MCP compatibility layer.
lanhu-context takes a lanhuapp.com design detail URL and breaks the "design → code" flow into small, composable commands: parse IDs, fetch metadata, pull the DDS schema, render HTML+CSS (optionally Tailwind v3/v4), extract design tokens, download slice assets, grab the preview image, or assemble everything into one context.md for an AI agent to implement.
- Atomic, pipeable commands —
parse/meta/schema/html/tokens/assets/preview/context, each does one thing; stdout carries data only. - Machine-readable by default —
--jsongives a uniform envelope (ok/data/error/warnings/meta) plus classified exit codes; errors carry{code, severity, message, hint}. - Graded severity — optional stages (tokens, preview) failing degrade with warnings instead of killing the run (
fatal/degraded/notice). - Idempotent outputs — re-runs compare file content and report
written/skipped/overwritten;--forceto override. - Credential tooling —
lanhu auth set/test/listenandlanhu doctorfor token (browser Cookie) management and diagnosis; tokens are never echoed. A companion browser extension and userscript copy the design URL / cookies from Lanhu's own context menu and can push them straight tolanhu auth listen. - MCP compatibility — the standalone
lanhu-context-mcpbin (npm@lanhu-context/mcp) serves the upstreamlanhu-context-mcpget_design_contexttool contract over stdio or streamable HTTP. - Agent skills included — ready-made skills under skills/ teach Claude Code (and other agents) how to drive the CLI and the MCP server.
Pick a scope, then paste the whole paragraph into any AI client that supports this repo (Codex / Claude Code / Cursor / Hermes / Trae / Qoder, etc.) and let it handle both the CLI install and the skill setup.
Global install (CLI available everywhere, skill goes into the user-level/global skills directory, shared by all projects):
Please install lanhu-context globally for me (do NOT clone any source repository):
1. npm i -g @lanhu-context/cli, then run `lanhu doctor` until it exits 0 (use `lanhu auth set` to configure LANHU_TOKEN if credentials fail);
2. Run `npx -y skills add dayepython/lanhu-context -s lanhu-context-cli -g -y` to install the skill globally; if that doesn't apply to you, install the lanhu-context-cli skill into your own global skill/rule directory (e.g. Claude Code ~/.claude/skills, Codex ~/.codex/AGENTS.md);
3. Report back the doctor result and where the skill was installed.
Project-level install (CLI as a devDependency of the current project, skill scoped to this project; the CLI is not on the global PATH, so every command needs a prefix):
Please install lanhu-context inside the current project (do NOT clone any source repository, do NOT install globally):
1. npm i -D @lanhu-context/cli; from then on run every lanhu command with a prefix: `npx lanhu <command>` (or wrap them in package.json scripts and invoke via npm run);
2. Run `npx lanhu doctor` until it exits 0 (use `npx lanhu auth set` to configure LANHU_TOKEN, stored in the project .env.local — make sure it is gitignored);
3. Run `npx -y skills add dayepython/lanhu-context -s lanhu-context-cli -y` to install the skill (project scope is the default); if that doesn't apply to you, install the lanhu-context-cli skill into this project's skill/rule directory (e.g. .claude/skills, .cursor/rules) and note in the skill usage that commands need the `npx lanhu` prefix;
4. Report back the doctor result and where the skill was installed.
Install the CLI and pass the self-check:
npm i -g @lanhu-context/cli
lanhu doctor # self-check env/credentials, exit 0 = readyIf doctor reports a credential problem, configure your Lanhu credential (LANHU_TOKEN is the full browser Cookie header from a logged-in lanhuapp.com session) and re-run it:
lanhu auth set# reads token from stdin, keeps it off the command line
lanhu auth test"$URL"# exit 0 = token worksPrefer one-click login? Install either companion helper:
- Browser extension (best Cookie fidelity — HttpOnly included with zero config): prebuilt zip on the GitHub Releases page, or build from source — see ecosystem/browser-extension/README.md;
- Userscript (when installing an extension isn't an option): with Tampermonkey (or another script manager) in place, one-click install "蓝湖 lanhu-context 助手" from GreasyFork (auto-updates on every release) — see ecosystem/lanhu-monkey/README.md.
Then start the one-shot receiver — via npx this works even before the CLI is installed:
lanhu auth listen
# no global install? log in via npx:
npx -y -p @lanhu-context/cli lanhu auth listenRight-click "发送 cookies 到本机" (send cookies to this machine) on any Lanhu design page before the timeout (120 s by default) — the receiver only accepts requests originating from the extension (chrome-extension:// origin) or the userscript (x-lanhu-bridge marker header), listens on 127.0.0.1 once, and stores the credential with mode 0600.
To teach your agent how to drive the CLI, install the bundled lanhu-context-cli skill with find-skills (project-scoped by default; add -g for a global install and -a <agent> to pick target agents — agents that don't support global installs are skipped with a ✗):
npx -y skills add \
dayepython/lanhu-context \
-s lanhu-context-cli \
-yGenerate implementation context for a design:
lanhu context "https://lanhuapp.com/web/#/item/project/detailDetach?tid=...&pid=...&image_id=..." \
--json --out-dir .lanhu.localThis writes <out-dir>/<design-name>-<imageId8>/{context.md, preview.png} — HTML+CSS code, a slice-asset mapping, design tokens, and an implementation guide. Download slices into your project with:
lanhu assets "$URL" --download -o src/assets/my-page --jsonPrefer atomic commands when you only need part of the pipeline, e.g. lanhu html "$URL" --skip-slices for layout only, or lanhu tokens "$URL" for tokens only.
For MCP clients: run npx -y @lanhu-context/mcp --stdio (bin lanhu-context-mcp, --http also supported) and register it in the client; migration from the upstream lanhu-context-mcp npm package is drop-in — see skills/lanhu-context-mcp/SKILL.md. The matching agent skill installs with npx -y skills add dayepython/lanhu-context -s lanhu-context-mcp -y (add -g for a global install).
| Package | Description |
|---|---|
@lanhu-context/cli | The lanhu / lanhu-context binary: all pipeline commands, auth, doctor, mcp |
@lanhu-context/core | Pure logic: URL parsing, Lanhu API client, schema→HTML, design tokens, context pipeline |
@lanhu-context/mcp | MCP compatibility layer exposing get_design_context on top of core |
Requires Node ^20.19.0 || >=22.12.0 and pnpm 10.
pnpm install
pnpm build # build all packages
pnpm test# vitest
pnpm typecheck
pnpm lint # biomeSee DESIGN.md for the full architecture (pipeline stages, error model, exit codes, config layering).
This project grew out of, and keeps tool-contract compatibility with, refinist/lanhu-context-mcp — huge thanks to its author for the original end-to-end design-to-context pipeline that made this CLI possible. ❤️