npm package: @gravity-ai/mcp-server
Description: MCP Server for Gravity Design System - Install and use Gravity components via AI assistants
Author: Gravity
Latest version: 1.0.1

# Gravity MCP Server

**Model Context Protocol server for the Gravity Design System.**

Let AI assistants install and use Gravity components in any project with a single command.

---

## Quick Start

### 1. Install globally

```bash
npm install -g @gravity-ai/mcp-server
```

### 2. Add to your AI assistant

#### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gravity": {
      "command": "gravity-mcp"
    }
  }
}
```

Then restart Cursor.

#### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "gravity": {
      "command": "gravity-mcp"
    }
  }
}
```

Then restart Claude Desktop.

### 3. Use it!

In your AI assistant, say:

> "Use the Gravity design system to redesign this project's frontend"

or

> "Install Gravity and update this button to use the design system"

---

## What It Does

The MCP server provides three types of capabilities:

### 🔧 Tools (Actions)

| Tool | Description |
|------|-------------|
| `gravity_install` | Installs all 50 components, design tokens, and utilities |
| `gravity_verify` | Verifies installation succeeded and reports missing files |
| `gravity_diagnose` | Scans for common issues (CSS conflicts, wrong imports, etc.) |
| `gravity_list_components` | Lists all available components |
| `gravity_get_component` | Gets the full source code for a specific component |
| `gravity_check_project` | Analyzes project structure for optimal installation |

### 📚 Resources (Documentation)

| Resource | Content |
|----------|---------|
| `gravity://getting-started` | READ FIRST — Workflows for new and existing projects |
| `gravity://components` | Complete component catalog with props and examples |
| `gravity://tokens` | All design tokens (colors, spacing, typography, shadows) |
| `gravity://guidelines` | Brand guidelines, patterns, and anti-patterns |
| `gravity://icons` | Approved icon set (61 Lucide icons) |

### 💬 Prompts (Workflows)

| Prompt | Description |
|--------|-------------|
| `gravity_new_project` | Workflow for building a new project from scratch |
| `gravity_redesign` | Step-by-step workflow to migrate an existing frontend |

---

## Example Conversations

### Install Gravity in a new project

**You:** "Set up this new Next.js project with the Gravity design system"

**AI:** *Uses `gravity_check_project` to detect structure, then `gravity_install` to add all components*

### Redesign existing frontend

**You:** "Use MCP to redesign the frontend to use Gravity design system"

**AI:** *Uses `gravity_redesign` prompt which guides through:*
1. Installing components
2. Discovering existing UI
3. Mapping components
4. Migrating files in batches

### Get a specific component

**You:** "Show me how to use the StatCard component from Gravity"

**AI:** *Uses `gravity_get_component` to fetch source, then `gravity://components` resource for documentation*

---

## Manual Installation

If you prefer not to use the global install:

```bash
# Clone the repo
git clone https://github.com/Try-Gravity/design-system3.git
cd design-system3/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Configure your AI assistant to use the local path
```

Then in your MCP config:

```json
{
  "mcpServers": {
    "gravity": {
      "command": "node",
      "args": ["/absolute/path/to/design-system3/packages/mcp-server/dist/index.js"]
    }
  }
}
```

---

## What Gets Installed

When you run `gravity_install`, the tool:

1. **Copies 50 UI components** to `src/components/ui/` (or detected location)
   - Button, Card, Input, Badge, Dialog, Table, Toast, and 40+ more
   
2. **Adds the `cn()` utility** to `src/lib/utils.ts`
   - Merges Tailwind classes intelligently
   
3. **Merges design tokens** into your global CSS
   - Colors, spacing, typography, shadows, motion
   - Full dark mode support
   
4. **Updates `package.json`** with required dependencies
   - Radix UI primitives
   - CVA, clsx, tailwind-merge
   - Lucide icons
   
5. **Optionally copies logo assets** to `public/logos/`

---

## Requirements

- Node.js 18+
- A React project (Next.js, Vite, CRA, etc.)
- Tailwind CSS configured

---

## Troubleshooting

### "gravity-mcp not found"

Make sure the global npm bin is in your PATH:

```bash
npm config get prefix
# Add {prefix}/bin to your PATH
```

### MCP server not connecting

1. Check your config file syntax (JSON)
2. Restart your AI assistant
3. Look for errors in the assistant's console/logs

### Components not styling correctly

1. Ensure Tailwind is configured
2. Check that `globals.css` is imported in your layout
3. Verify `content` paths in `tailwind.config.js` include component directory

---

## License

MIT

---

**Gravity Design System** — *Quiet authority. Calm intelligence. Infrastructure for AI.*