# @lando-labs/lando-ds-mcp

[![npm version](https://img.shields.io/npm/v/@lando-labs/lando-ds-mcp.svg)](https://www.npmjs.com/package/@lando-labs/lando-ds-mcp)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![CI](https://github.com/lando-labs/lando-ds-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/lando-labs/lando-ds-mcp/actions/workflows/test.yml)
[![Node.js Version](https://img.shields.io/node/v/@lando-labs/lando-ds-mcp.svg)](https://nodejs.org)

**MCP server for the [Lando Labs Design System](https://github.com/lando-labs/lando-ds).** Gives AI agents authoritative introspection and code-generation for 127 React components, 19 utility hooks, 70 brand icons, ~1,500 Lucide icons, six token categories, and multiple theme presets — all sourced from the DS's own emitted metadata (`@lando-labs/lando-ds-meta`), always current with each DS release.

Built on the [Model Context Protocol](https://modelcontextprotocol.io). Works with Claude Code, Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible client.

---

## What it does

Exposes **15 tools** to any MCP-connected AI client:

| Tool | Purpose |
|---|---|
| `list_components` | Enumerate DS components, filter by category / capability / deprecation |
| `get_component` | Generate ready-to-use JSX for a component with props, children, and correct imports |
| `get_component_props` | TypeScript-style props interface for any component |
| `get_component_reference` | Full reference: description + examples + composes + props in one call |
| `get_component_capabilities` | Capability matrix — RSC-safe, polymorphic, forwardRef, deprecated |
| `get_composition_hints` | Which components officially compose with a given one (from meta) |
| `compose_components` | Merge multiple components into one snippet with unified imports |
| `get_design_tokens` | Design tokens (colors, spacing, typography, radius, shadows, motion) in CSS, hex, or both |
| `get_animation_examples` | Curated animation patterns with CSS keyframes and reduced-motion handling |
| `get_theme_presets` | Available theme presets (default `brand-neutral`; opt-in `lando`, `forest`, `midnight`, `rose`, `slate`, `sunset`) |
| `list_icons` | Browse icons: `ds-brand` (~70), `lucide` (full ~1,500-icon catalog; ~80 with rich metadata, the rest by name), or `all` |
| `search_icons` | Semantic search across icon catalogs with confidence-ranked results |
| `list_hooks` | Enumerate DS utility hooks (state, dom, browser, a11y, …), filter by category / RSC safety |
| `get_hook` | Full detail for a single hook — signature, returns, RSC safety, subpath, description |
| `get_ds_metadata` | DS package version, meta schema version, component/token/icon/hook summary |

Every tool reads from `@lando-labs/lando-ds-meta` — the DS's self-describing metadata, shipped as a zero-dependency JSON npm package. When the DS ships new components, deprecates old ones, or renames tokens, the MCP surfaces the change on the next content refresh with zero code changes.

## Install + connect

You need Node.js 18 or later.

### Claude Code

```bash
npm install -g @lando-labs/lando-ds-mcp
claude mcp add lando-ds lando-ds-mcp
```

Or via `~/.claude.json`:

```json
{
  "mcpServers": {
    "lando-ds": {
      "command": "lando-ds-mcp"
    }
  }
}
```

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on Windows/Linux:

```json
{
  "mcpServers": {
    "lando-ds": {
      "command": "npx",
      "args": ["-y", "@lando-labs/lando-ds-mcp"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "lando-ds": {
      "command": "npx",
      "args": ["-y", "@lando-labs/lando-ds-mcp"]
    }
  }
}
```

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "lando-ds": {
      "command": "npx",
      "args": ["-y", "@lando-labs/lando-ds-mcp"]
    }
  }
}
```

### Zed

Zed uses context servers configured via `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "lando-ds": {
      "command": {
        "path": "npx",
        "args": ["-y", "@lando-labs/lando-ds-mcp"]
      }
    }
  }
}
```

### Generic MCP client

The server speaks MCP over stdio. Invoke `lando-ds-mcp` (after `npm install -g`) or `npx @lando-labs/lando-ds-mcp`.

## Verify

After connecting, ask your agent to call `get_ds_metadata`. It should reply with the DS version, component count, and tool summary. If it does, you're wired up.

## What it does not do

- **Not a UI library.** The MCP tells agents about DS components — the actual components live in `@lando-labs/lando-ds` and must be installed in your project separately.
- **Not a code generator standalone.** Runs as an MCP server; needs an MCP client to invoke it.
- **Not a project scanner.** Every tool reads from DS meta; nothing scans your project source. A future release may add DS-adoption auditing tools; not yet.
- **Not Vue/Svelte/Angular compatible.** The DS is React; the MCP's code-generation output is JSX.
- **Not React Native compatible.** The DS is web-only as of v0.57.0.

## How it works

The DS publishes `@lando-labs/lando-ds-meta` — a zero-dependency npm package with `meta.json` (light) and `meta.verbose.json` (with descriptions, examples, and composition hints). The MCP takes a semver dep on it and exposes the data through the 15 tools above. `npm update @lando-labs/lando-ds-meta` is the whole content-refresh workflow.

Because meta is the source of truth, the MCP is a **thin protocol adapter over emitted metadata** — no synthesis of information the DS didn't emit.

## Contributing

Contributions welcome — file an issue or open a PR. Some context up front:

- **Development setup**: `git clone`, then `npm install && npm run build && npm test`. Nothing else — DS meta arrives via npm.
- **Meta compatibility**: MCP consumes DS meta schema `^1.x`. Schema major bumps require an MCP major bump.
- **Testing**: `npm test` uses a custom runner in `src/test.ts`.
- **Version discipline**: version strings live in `package.json`, `src/index.ts`, and `CHANGELOG.md`. The version-sync tests fail CI if these drift.

Issues: [github.com/lando-labs/lando-ds-mcp/issues](https://github.com/lando-labs/lando-ds-mcp/issues)
Security disclosures: see [MAINTAINERS.md](./MAINTAINERS.md#reaching-us).
Maintainers: [MAINTAINERS.md](./MAINTAINERS.md).

## License

Apache License 2.0. See [LICENSE](./LICENSE) for full terms and [NOTICE](./NOTICE) for attribution.

Copyright 2026 Lando Labs.

## Related

- **[@lando-labs/lando-ds](https://github.com/lando-labs/lando-ds)** — The design system itself. React web components; the source of truth the MCP reflects.
- **[@lando-labs/lando-ds-meta](https://www.npmjs.com/package/@lando-labs/lando-ds-meta)** — Zero-dependency JSON metadata subpackage the MCP consumes at runtime. Updating the MCP's DS content is `npm update @lando-labs/lando-ds-meta`.

---

*First published to public npm and public GitHub as `@lando-labs/lando-ds-mcp@4.0.0` on 2026-07-16, alongside `@lando-labs/lando-ds@0.57.0` and `@lando-labs/lando-ds-meta@0.57.0`.*