Skip to content

Commit 083baf0

Browse files
segunadebayosegunadebayo
committed
docs: mcp server
1 parent 3c86c29 commit 083baf0

File tree

7 files changed

+329
-3
lines changed

7 files changed

+329
-3
lines changed

website/content/docs/overview/llms-txt.mdx renamed to website/content/docs/ai/llms-txt.mdx

File renamed without changes.

‎website/content/docs/ai/mcp-server.mdx‎

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
---
2+
title: MCP Server
3+
description: Expose your Panda CSS design system to AI assistants using the Model Context Protocol (MCP).
4+
---
5+
6+
The Panda MCP Server allows AI assistants like Claude, Cursor, VS Code Copilot, Windsurf, and Codex to understand and
7+
work with your project's design system. It provides tools for querying tokens, recipes, patterns, conditions, and more.
8+
9+
## What is MCP?
10+
11+
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard for connecting AI assistants to
12+
external tools and data sources. Panda's MCP server exposes your design system through a set of specialized tools that
13+
AI assistants can use to:
14+
15+
- Look up design tokens and their values
16+
- Understand available component recipes and variants
17+
- Query layout patterns and their properties
18+
- Analyze token and recipe usage across your codebase
19+
20+
## Quick Start
21+
22+
### 1. Initialize MCP Configuration
23+
24+
Run the interactive setup command in your project:
25+
26+
```bash
27+
pnpm panda init-mcp
28+
```
29+
30+
This will prompt you to select which AI clients to configure:
31+
32+
```
33+
◆ Panda MCP Setup
34+
│
35+
◆ Select AI clients to configure:
36+
│ ◻ Claude (.mcp.json)
37+
│ ◻ Cursor (.cursor/mcp.json)
38+
│ ◻ VS Code (.vscode/mcp.json)
39+
│ ◻ Windsurf (.windsurf/mcp.json)
40+
│ ◻ Codex (.codex/mcp.json)
41+
```
42+
43+
### 2. Use with Your AI Assistant
44+
45+
Once configured, your AI assistant will automatically have access to Panda CSS tools. You can ask questions like:
46+
47+
- "What color tokens are available in my design system?"
48+
- "Show me the button recipe variants"
49+
- "Which tokens are unused in my codebase?"
50+
- "What breakpoints are defined?"
51+
52+
## CLI Commands
53+
54+
### init-mcp
55+
56+
Initialize MCP configuration for one or more AI clients.
57+
58+
```bash
59+
# Interactive mode - select clients from a list
60+
pnpm panda init-mcp
61+
62+
# Configure specific clients directly
63+
pnpm panda init-mcp --client claude,cursor
64+
65+
# Specify working directory
66+
pnpm panda init-mcp --cwd ./my-project
67+
```
68+
69+
| Flag | Description |
70+
| ------------------ | ----------------------------------------- |
71+
| `--client <names>` | AI clients to configure (comma-separated) |
72+
| `--cwd <path>` | Current working directory |
73+
74+
### mcp
75+
76+
Start the MCP server manually (usually not needed - clients start it automatically).
77+
78+
```bash
79+
pnpm panda mcp
80+
81+
# With custom config path
82+
pnpm panda mcp --config ./panda.config.ts
83+
84+
# Specify working directory
85+
pnpm panda mcp --cwd ./my-project
86+
```
87+
88+
| Flag | Description |
89+
| --------------------- | ------------------------- |
90+
| `--config, -c <path>` | Path to Panda config file |
91+
| `--cwd <path>` | Current working directory |
92+
93+
## Supported AI Clients
94+
95+
The MCP server supports the following AI assistants:
96+
97+
| Client | Config Path | Description |
98+
| -------- | -------------------- | ------------------------------ |
99+
| Claude | `.mcp.json` | Claude Code and Claude Desktop |
100+
| Cursor | `.cursor/mcp.json` | Cursor IDE |
101+
| VS Code | `.vscode/mcp.json` | VS Code with Copilot |
102+
| Windsurf | `.windsurf/mcp.json` | Windsurf IDE |
103+
| Codex | `.codex/mcp.json` | OpenAI Codex CLI |
104+
105+
## Available Tools
106+
107+
The MCP server exposes these tools to AI assistants:
108+
109+
| Tool | Description | Input |
110+
| ---------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
111+
| `get_tokens` | Get design tokens with values, CSS variables, and usage examples | `category?` - filter by token category |
112+
| `get_semantic_tokens` | Get semantic tokens with conditional values (dark mode, responsive) | `category?` - filter by token category |
113+
| `get_color_palette` | Get the complete color palette | - |
114+
| `get_recipes` | Get component recipes with variants and default values | `name?` - filter by recipe name |
115+
| `get_patterns` | Get layout patterns with properties and usage examples | `name?` - filter by pattern name |
116+
| `get_conditions` | Get all conditions (breakpoints, pseudo-classes, color modes) | - |
117+
| `get_keyframes` | Get keyframe animations defined in the theme | - |
118+
| `get_text_styles` | Get text style compositions for typography | - |
119+
| `get_layer_styles` | Get layer style compositions for visual styling | - |
120+
| `get_animation_styles` | Get animation style compositions | - |
121+
| `get_config` | Get the resolved Panda CSS configuration | - |
122+
| `get_usage_report` | Analyze token/recipe usage across the codebase | `scope?` - `'all'`, `'token'`, `'recipe'` |
123+
124+
The `get_usage_report` tool is particularly useful for auditing your design system, identifying unused tokens/recipes,
125+
and finding missing definitions.
126+
127+
## Generated Configuration
128+
129+
When you run `panda init-mcp`, the following configuration is generated for each selected client:
130+
131+
```json
132+
{
133+
"mcpServers": {
134+
"panda": {
135+
"command": "npx",
136+
"args": ["panda", "mcp"]
137+
}
138+
}
139+
}
140+
```
141+
142+
The server automatically loads your `panda.config.ts` from the current working directory when started.
143+
144+
## Manual Configuration
145+
146+
If you prefer to configure MCP manually, create the appropriate config file for your AI client:
147+
148+
### Claude
149+
150+
Create `.mcp.json` in your project root:
151+
152+
```json
153+
{
154+
"mcpServers": {
155+
"panda": {
156+
"command": "npx",
157+
"args": ["panda", "mcp"]
158+
}
159+
}
160+
}
161+
```
162+
163+
### Cursor
164+
165+
Create `.cursor/mcp.json`:
166+
167+
```json
168+
{
169+
"mcpServers": {
170+
"panda": {
171+
"command": "npx",
172+
"args": ["panda", "mcp"]
173+
}
174+
}
175+
}
176+
```
177+
178+
### VS Code
179+
180+
Create `.vscode/mcp.json`:
181+
182+
```json
183+
{
184+
"servers": {
185+
"panda": {
186+
"command": "npx",
187+
"args": ["panda", "mcp"]
188+
}
189+
}
190+
}
191+
```
192+
193+
### Custom Config Path
194+
195+
If your Panda config is not in the default location, specify it explicitly:
196+
197+
```json
198+
{
199+
"mcpServers": {
200+
"panda": {
201+
"command": "npx",
202+
"args": ["panda", "mcp", "--config", "./path/to/panda.config.ts"]
203+
}
204+
}
205+
}
206+
```
207+
208+
## Example Interactions
209+
210+
Here are some example prompts you can use with AI assistants once MCP is configured:
211+
212+
### Exploring Tokens
213+
214+
> "What spacing tokens are available?"
215+
216+
The AI will use `get_tokens` with `category: "spacing"` to show you all spacing values.
217+
218+
### Understanding Recipes
219+
220+
> "How do I use the button recipe with a destructive variant?"
221+
222+
The AI will use `get_recipes` with `name: "button"` to show variants and usage.
223+
224+
### Finding Unused Tokens
225+
226+
> "Which design tokens are not being used in my codebase?"
227+
228+
The AI will use `get_usage_report` with `scope: "token"` to identify unused tokens.
229+
230+
### Checking Conditions
231+
232+
> "What responsive breakpoints are defined?"
233+
234+
The AI will use `get_conditions` to show all available breakpoints.
235+
236+
## Troubleshooting
237+
238+
### Server Not Starting
239+
240+
If the MCP server fails to start:
241+
242+
1. Ensure Panda CSS is installed: `pnpm add -D @pandacss/dev`
243+
2. Verify you have a valid `panda.config.ts` in your project
244+
3. Check that `npx panda mcp` runs without errors
245+
246+
### Tools Not Available
247+
248+
If tools aren't showing up in your AI assistant:
249+
250+
1. Restart the AI assistant after adding the MCP configuration
251+
2. Verify the config file is in the correct location
252+
3. Check the AI assistant's MCP documentation for any additional setup steps
253+
254+
### Usage Report Empty
255+
256+
If `get_usage_report` returns empty results:
257+
258+
1. Ensure your `include` paths in `panda.config.ts` cover your source files
259+
2. Run `pnpm panda codegen` to ensure the project is properly set up
260+
3. Verify files contain Panda CSS usage (css(), styled(), etc.)

‎website/content/docs/references/cli.mdx‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -353,3 +353,51 @@ pnpm panda emit-pkg --outdir styled-system
353353
| `--base <path>` | The base directory of the package.json entrypoints | - |
354354
| `--silent` | Whether to suppress all output | [`config.logLevel`](/docs/references/config#log-level) |
355355
| `--cwd <path>` | Current working directory | [`config.cwd`](/docs/references/config#cwd) |
356+
357+
## mcp
358+
359+
Start the MCP (Model Context Protocol) server for AI assistants. This exposes your design system to AI tools like
360+
Claude, Cursor, VS Code Copilot, and more.
361+
362+
```bash
363+
pnpm panda mcp
364+
365+
# With custom config path
366+
pnpm panda mcp --config ./panda.config.ts
367+
368+
# Specify working directory
369+
pnpm panda mcp --cwd ./my-project
370+
```
371+
372+
| Flag | Description | Related |
373+
| --------------------- | ------------------------- | ------------------------------------------- |
374+
| `--config, -c <path>` | Path to Panda config file | [`config`](/docs/references/config.md) |
375+
| `--cwd <path>` | Current working directory | [`config.cwd`](/docs/references/config#cwd) |
376+
377+
> Note: This command is typically started automatically by AI clients. See the [MCP Server guide](/docs/ai/mcp-server)
378+
> for setup instructions.
379+
380+
## init-mcp
381+
382+
Initialize MCP configuration for AI clients. This creates the necessary configuration files for AI assistants to connect
383+
to the Panda MCP server.
384+
385+
```bash
386+
# Interactive mode - select clients from a list
387+
pnpm panda init-mcp
388+
389+
# Configure specific clients
390+
pnpm panda init-mcp --client claude,cursor
391+
392+
# Specify working directory
393+
pnpm panda init-mcp --cwd ./my-project
394+
```
395+
396+
| Flag | Description | Related |
397+
| ------------------ | ----------------------------------------- | ------------------------------------------- |
398+
| `--client <names>` | AI clients to configure (comma-separated) | - |
399+
| `--cwd <path>` | Current working directory | [`config.cwd`](/docs/references/config#cwd) |
400+
401+
Supported clients: `claude`, `cursor`, `vscode`, `windsurf`, `codex`
402+
403+
See the [MCP Server guide](/docs/ai/mcp-server) for detailed usage and available tools.

‎website/next.config.mjs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,11 @@ const config = {
2929
source: '/learn',
3030
destination: 'https://pandamastery.com',
3131
permanent: true
32+
},
33+
{
34+
source: '/docs/overview/llms-txt',
35+
destination: '/docs/ai/llms-txt',
36+
permanent: true
3237
}
3338
]
3439
},

‎website/src/components/docs/sidebar.tsx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ import { Badge } from '@/components/ui/badge'
44
import { docsNavigation, type NavItem } from '@/docs.config'
55
import { ChevronDownIcon, ChevronRightIcon } from '@/icons'
66
import { css } from '@/styled-system/css'
7-
import { Box, Stack } from '@/styled-system/jsx'
7+
import { Box, HStack, Stack } from '@/styled-system/jsx'
88
import Link from 'next/link'
99
import { usePathname } from 'next/navigation'
1010
import { useState } from 'react'
@@ -34,6 +34,7 @@ export function Sidebar({ slug: currentSlug }: Props) {
3434
docsNavigation.items?.map((section: NavItem) => ({
3535
title: section.title,
3636
slug: section.url || '',
37+
tag: section.tag,
3738
children: section.items?.map((item: NavItem) => ({
3839
title: item.title,
3940
slug: item.external ? item.href || '' : `${section.url}/${item.url}`,
@@ -92,7 +93,10 @@ export function Sidebar({ slug: currentSlug }: Props) {
9293
cursor: 'pointer'
9394
})}
9495
>
95-
<span>{section.title}</span>
96+
<HStack>
97+
<span>{section.title}</span>
98+
{section.tag && <Badge variant="solid">{section.tag}</Badge>}
99+
</HStack>
96100
{section.children && (
97101
<Box
98102
as={isExpanded ? ChevronDownIcon : ChevronRightIcon}

‎website/src/components/ui/badge.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { panda } from '@/styled-system/jsx'
33
export const Badge = panda('span', {
44
base: {
55
fontWeight: 'medium',
6+
fontSize: '11px',
67
px: '1',
78
ms: '2',
89
rounded: 'sm'

‎website/src/docs.config.tsx‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,6 @@ export const docsNavigation: NavItem = {
8383
{ title: 'Why Panda?', url: 'why-panda' },
8484
{ title: 'FAQs', url: 'faq' },
8585
{ title: 'Browser Support', url: 'browser-support' },
86-
{ title: 'LLMs.txt', url: 'llms-txt' },
8786
{
8887
title: 'Roadmap',
8988
href: 'https://panda-css.canny.io/',
@@ -96,6 +95,15 @@ export const docsNavigation: NavItem = {
9695
}
9796
]
9897
},
98+
{
99+
title: 'AI for Agents',
100+
url: 'ai',
101+
tag: 'new',
102+
items: [
103+
{ title: 'LLMs.txt', url: 'llms-txt' },
104+
{ title: 'MCP Server', url: 'mcp-server' }
105+
]
106+
},
99107
{
100108
title: 'Installation',
101109
url: 'installation',

0 commit comments

Comments
 (0)