# buoy

Gives a coding agent your tokens and component rules, then flags hardcoded colors and off-scale spacing with a line-level fix.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 20
- Author: ahoybuoy
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ahoybuoy/buoy
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/mcp/buoy

## What it does

Your agent never reads the token file, so it writes `#3b82f6` where the project expects `var(--color-primary)`, or sets 17px padding against a scale of fours. Buoy reports that mismatch and hands back the token plus the exact line edit. It runs as an MCP server with four tools: `list_design_tokens`, `find_token_for_value`, `check_ui_against_design_system` and `design_system_context`.

Nothing to configure at the start. `npx ahoybuoy show all` dumps detected components, tokens and drift; `npx ahoybuoy dock` writes `.buoy.yaml` and wires the local pieces. That YAML lists paths for components, tokens and owning teams, and `buoy system map` plus `buoy system impact` read from it. In Claude the package also registers a `PostToolUse` hook: every style file the agent touches gets checked before it continues.

Scans, fixes and the system map work without an account; the hosted PR bot and sync sit behind `buoy ahoy login`. Bring it in early. `buoy rescue` can plan repairs, land reviewed fixes on a branch and produce an evidence report, but the debt it works through is the debt already in the tree.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add buoy -- npx -y @buoy-design/cli
```

### Codex

**Platform CLI**
```bash
codex mcp add buoy -- npx -y @buoy-design/cli
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "buoy": {
            "command": "npx",
            "args": [
                "-y",
                "@buoy-design/cli"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "buoy": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@buoy-design/cli"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add buoy npx -y @buoy-design/cli
```

## When to use it
- replace hardcoded colors with design tokens
- catch padding values outside the spacing scale
- map the design system against unmanaged UI surface
- see who consumes a component before changing it
- run a style check before committing

## Example prompts
- Connect buoy and check `src/components/Button.tsx` for hardcoded colors
- Use buoy to find the token behind `#1a73e8`
- Run `buoy system impact Button` and list the consumers

## Similar
- [Next AI Draw.io](https://affpapa.org/en/nevibecode/mcp/next-ai-drawio.md) — MCP server · ★ 36398
- [tldraw](https://affpapa.org/en/nevibecode/mcp/tldraw.md) — MCP server · ★ 51091
- [Figma-Context-MCP](https://affpapa.org/en/nevibecode/mcp/figma-context-mcp.md) — MCP server · ★ 16062
- [Agent-Native Assets](https://affpapa.org/en/nevibecode/mcp/agent-native-assets.md) — MCP server · ★ 7506
- [Remove AI Watermarks](https://affpapa.org/en/nevibecode/mcp/remove-ai-watermarks.md) — MCP server · ★ 6114
- [Dembrandt](https://affpapa.org/en/nevibecode/mcp/dembrandt.md) — MCP server · ★ 3821

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md