# Gemini Designer MCP

> AI-powered UI design and code generation for your coding assistant

[![npm version](https://badge.fury.io/js/gemini-designer.svg)](https://www.npmjs.com/package/gemini-designer)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An **MCP server** that gives your AI coding assistant **17 tools** for UI design, repo intelligence, and frontend code generation.

## Install

```bash
npx gemini-designer init --local
```

That's it. The CLI will:

1. Detect your MCP clients (Cursor, Gemini CLI, VS Code, Claude, Codex, Windsurf, Zed, Antigravity)
2. Let you choose which to configure
3. Set up Gemini Designer automatically

## Tools

| Tool                          | What it does                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `generate_vibes`              | Design tokens, themes, color palettes                                                 |
| `scaffold_project`            | Plan + scaffold multi-file project structure (React/Next/Vue/SvelteKit/Remix/Angular) |
| `ui_generate`                 | Unified generator that returns a multi-file `FileBundle` (no writing)                 |
| `modify_ui`                   | Edit existing UI code (supports multi-file targets)                                   |
| `generate_component_variants` | Add variants (+ optional Storybook file)                                              |
| `ui_review`                   | Screenshot + target files → patchable `FileBundle`                                    |
| `analyze_tokens`              | Extract tokens from CSS                                                               |
| `sync_design_tokens`          | Convert tokens between CSS/Tailwind/Tokens Studio                                     |
| `detect_ui_stack`             | Auto-detect framework & libraries                                                     |
| `catalog_components`          | Index your components                                                                 |
| `repo_tree`                   | Fast filtered repo file listing                                                       |
| `repo_read_files`             | Read multiple files safely (truncation + sha256)                                      |
| `repo_get_file_meta`          | File metadata (exists/size/mtime + optional sha256)                                   |
| `repo_search`                 | Text search (ripgrep-powered)                                                         |
| `apply_file_bundle`           | Generic writer tool to apply multi-file bundles                                       |
| `validate_project`            | Run allowlisted scripts (lint/typecheck/build) (disabled by default)                  |
| `prompting_guide`             | High-signal prompting templates                                                       |

## Usage

Local mode is free and uses your own Gemini API key:

```bash
npx gemini-designer init --local
```

The server also retains a remote mode for compatible self-hosted gateways. The former hosted Gemini Designer service is currently unavailable and is not required for local use.

## Auto-Detected Clients

The CLI automatically detects and configures these MCP clients:

| Client           | Config Path                             |
| ---------------- | --------------------------------------- |
| **Cursor**       | `~/.cursor/mcp.json`                    |
| **Gemini CLI**   | `~/.gemini/settings.json`               |
| **VS Code**      | `~/.vscode/settings.json`               |
| **Claude Code**  | `~/.claude/mcp.json`                    |
| **OpenAI Codex** | `~/.codex/config.toml`                  |
| **Windsurf**     | `~/.codeium/windsurf/mcp_config.json`   |
| **Zed**          | `~/.config/zed/settings.json`           |
| **Antigravity**  | `~/.gemini/antigravity/mcp_config.json` |

## Docs

Maintainer/agent docs live in this repo under [`docs/`](docs/README.md).

## License

MIT