Skip to content

Commit 0d0f63b

Browse files
freemafreema
authored
Merge pull request #3 from freema/update-publish
Update publish
2 parents c888a45 + 675f81e commit 0d0f63b

File tree

3 files changed

+157
-159
lines changed

3 files changed

+157
-159
lines changed

‎DEVELOPMENT.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Development Guide
2+
3+
## Prerequisites
4+
5+
- Node.js 18+
6+
- Network access to Storybook URL
7+
- Chrome/Chromium browser (for Puppeteer)
8+
9+
## Setup
10+
11+
```bash
12+
# Install dependencies
13+
npm install
14+
15+
# Run TypeScript checks
16+
npm run typecheck
17+
18+
# Run linting
19+
npm run lint
20+
21+
# Build for production
22+
npm run build
23+
24+
# Clean build files
25+
npm run clean
26+
```
27+
28+
## Development Commands
29+
30+
```bash
31+
# Start in development mode
32+
npm run dev
33+
34+
# Run with MCP Inspector
35+
npm run inspector:dev
36+
```
37+
38+
## Configuration
39+
40+
### With Claude Desktop
41+
42+
Use the setup script:
43+
```bash
44+
npm run setup
45+
```
46+
47+
Or manually add to your Claude Desktop configuration:
48+
49+
```json
50+
{
51+
"mcpServers": {
52+
"design-system-extractor": {
53+
"command": "node",
54+
"args": ["/path/to/mcp-design-system-extractor/dist/index.js"],
55+
"env": {
56+
"STORYBOOK_URL": "http://localhost:6006"
57+
}
58+
}
59+
}
60+
}
61+
```
62+
63+
### With Claude Code
64+
65+
Add to your `.claude_code_config.json` in the project root:
66+
67+
```json
68+
{
69+
"mcpServers": {
70+
"design-system-extractor": {
71+
"command": "npm",
72+
"args": ["run", "dev"],
73+
"env": {
74+
"STORYBOOK_URL": "http://localhost:6006"
75+
}
76+
}
77+
}
78+
}
79+
```
80+
81+
Or for production build:
82+
83+
```json
84+
{
85+
"mcpServers": {
86+
"design-system-extractor": {
87+
"command": "node",
88+
"args": ["dist/index.js"],
89+
"env": {
90+
"STORYBOOK_URL": "http://localhost:6006"
91+
}
92+
}
93+
}
94+
}
95+
```
96+
97+
## Environment Variables
98+
99+
- `STORYBOOK_URL`: URL of the Storybook instance (default: `http://localhost:6006`)
100+
101+
## Testing
102+
103+
The server connects to Storybook using these endpoints:
104+
- `/index.json` or `/stories.json` - Component metadata
105+
- `/iframe.html?id=component--story` - Rendered components
106+
107+
Verify your Storybook is accessible by visiting these URLs directly in your browser.
108+
109+
## Architecture
110+
111+
Key features:
112+
- **Dynamic Content Support**: Uses Puppeteer with headless Chrome to render JavaScript components
113+
- **Smart Caching**: Caches responses for 5 minutes to improve performance
114+
- **Retry Logic**: Automatically retries failed requests up to 3 times
115+
- **Timeout Protection**: Configurable timeouts for different operations
116+
- **Error Handling**: Comprehensive error categorization and debugging information
117+
118+
## Troubleshooting
119+
120+
### Connection Issues
121+
- Verify Storybook is running (typically on port 6006)
122+
- Check CORS configuration in your Storybook
123+
- Ensure network connectivity to the Storybook URL
124+
- Try accessing endpoints directly in browser
125+
126+
### Component Extraction Issues
127+
- Ensure you're using the exact story ID format: "component-name--story-name"
128+
- Use `get_component_variants` to find valid story IDs
129+
- Check that stories exist and are published in Storybook
130+
131+
### Performance Issues
132+
- Adjust timeout values in `src/utils/timeout-constants.ts`
133+
- Monitor cache hit rates
134+
- Check network latency to Storybook instance

‎README.md‎

Lines changed: 20 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# MCP Design System Extractor
22

3-
A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. This server connects to a running Storybook instance and extracts HTML, styles, and component metadata directly from the Storybook iframe.
3+
A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. Connects to Storybook instances (including https://storybook.js.org distributions) and extracts HTML, styles, and component metadata.
4+
5+
## Key Dependencies
6+
7+
- **Puppeteer**: Uses headless Chrome for dynamic JavaScript component rendering
8+
- **Chrome/Chromium**: Required for Puppeteer (automatically handled in Docker)
9+
- Works with built Storybook distributions from https://storybook.js.org
410

511
<a href="https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor">
612
<img width="380" height="200" src="https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor/badge" alt="Design System Extractor MCP server" />
@@ -19,107 +25,21 @@ A Model Context Protocol (MCP) server that extracts component information from S
1925
- 🧩 **Composition Examples**: Get examples of how components are combined together
2026
- 📝 **External CSS Analysis**: Fetch and analyze CSS files to extract design tokens and variables
2127

22-
## Installation
23-
24-
```bash
25-
npm install
26-
npm run build
27-
```
28-
29-
## Quick Setup
30-
31-
Use the interactive setup script to configure Claude Desktop:
28+
## Quick Start
3229

3330
```bash
34-
npm run setup
31+
npm install && npm run build
32+
npm run setup # Interactive setup for Claude Desktop
3533
```
3634

37-
This will:
38-
- Build the project if needed
39-
- Let you choose your Storybook URL (local or custom)
40-
- Test the connection
41-
- Configure Claude Desktop automatically
42-
43-
## Manual Configuration
44-
45-
Alternatively, set the Storybook URL via environment variable:
46-
35+
Or set manually:
4736
```bash
4837
export STORYBOOK_URL=http://localhost:6006
4938
```
5039

51-
Default: `http://localhost:6006`
52-
5340
## Usage
5441

55-
### With Claude Desktop
56-
57-
**Recommended:** Use the setup script:
58-
```bash
59-
npm run setup
60-
```
61-
62-
**Manual:** Add to your Claude Desktop configuration:
63-
64-
```json
65-
{
66-
"mcpServers": {
67-
"design-system-extractor": {
68-
"command": "node",
69-
"args": ["/path/to/mcp-design-system-extractor/dist/index.js"],
70-
"env": {
71-
"STORYBOOK_URL": "http://localhost:6006"
72-
}
73-
}
74-
}
75-
}
76-
```
77-
78-
### With Claude Code
79-
80-
For development with Claude Code, add to your `.claude_code_config.json` in the project root:
81-
82-
```json
83-
{
84-
"mcpServers": {
85-
"design-system-extractor": {
86-
"command": "npm",
87-
"args": ["run", "dev"],
88-
"env": {
89-
"STORYBOOK_URL": "http://localhost:6006"
90-
}
91-
}
92-
}
93-
}
94-
```
95-
96-
Or for production build:
97-
98-
```json
99-
{
100-
"mcpServers": {
101-
"design-system-extractor": {
102-
"command": "node",
103-
"args": ["dist/index.js"],
104-
"env": {
105-
"STORYBOOK_URL": "http://localhost:6006"
106-
}
107-
}
108-
}
109-
}
110-
```
111-
112-
Then restart Claude Code to load the MCP server. You can verify it's working by using any of the design system tools in your Claude Code session.
113-
114-
### Development
115-
116-
```bash
117-
# Start in development mode
118-
npm run dev
119-
120-
# Run with MCP Inspector
121-
npm run inspector:dev
122-
```
42+
See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed setup instructions.
12343

12444
## Available Tools
12545

@@ -286,80 +206,25 @@ When using with Claude or other AI assistants:
286206

287207
## How It Works
288208

289-
The server connects to Storybook using these endpoints:
290-
- `/index.json` or `/stories.json` - Component metadata
291-
- `/iframe.html?id=component--story` - Rendered components
292-
293-
Key features:
294-
- **Dynamic Content Support**: Uses happy-dom to execute JavaScript and render dynamic content
295-
- **Smart Caching**: Caches responses for 5 minutes to improve performance
296-
- **Retry Logic**: Automatically retries failed requests up to 3 times
297-
- **Timeout Protection**: 10-second timeout on all network requests
298-
- **Better Error Messages**: Provides helpful suggestions when connections fail
299-
300-
It extracts:
301-
- Component HTML structure (including dynamically rendered content)
302-
- CSS classes and inline styles
303-
- Component props and API documentation
304-
- Component dependencies and relationships
305-
- Design system tokens and theme information
306-
- External CSS files and design tokens from Storybook assets
209+
Connects to Storybook via `/index.json` and `/iframe.html` endpoints. Uses Puppeteer with headless Chrome for dynamic JavaScript rendering. Extracts component HTML, styles, props, dependencies, and design tokens with smart caching and timeout protection.
307210

308211
## Troubleshooting
309212

310-
### Common Issues
311-
312-
**Empty results from list_components or search_components:**
313-
- Ensure your Storybook is running and accessible at the configured URL
314-
- Check that `STORYBOOK_URL` environment variable is set correctly
315-
- Try accessing `/index.json` or `/stories.json` directly in your browser
316-
- Verify your Storybook has stories configured and published
317-
- Check the debug information returned in the tool response
318-
319-
**"Found 0 components" with category filtering:**
320-
- Use `category: "all"` or omit the category parameter to see all components first
321-
- Check available categories from the initial `list_components` call
322-
- Category names are case-sensitive and must match exactly
323-
324-
**Wildcard search not working:**
325-
- Use `query: "*"` (with quotes) to list all components in search_components
326-
- Ensure the query parameter is provided as a string
327-
328-
**Component HTML extraction fails:**
329-
- Ensure you're using the exact story ID format: "component-name--story-name"
330-
- Use `get_component_variants` first to find valid story IDs
331-
- Check that the story exists and is published in Storybook
332-
333-
**Connection issues:**
334-
- Verify Storybook is running (typically on port 6006)
335-
- Check CORS configuration in your Storybook
336-
- Ensure network connectivity to the Storybook URL
337-
- Try a different URL format (with/without trailing slash)
213+
- Ensure Storybook is running and `STORYBOOK_URL` is correct
214+
- Use exact story ID format: "component-name--story-name"
215+
- Try `list_components` first to see available components
216+
- Check `/index.json` endpoint directly in browser
217+
- See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed troubleshooting
338218

339219
## Requirements
340220

341221
- Node.js 18+
222+
- Chrome/Chromium (for Puppeteer)
342223
- Running Storybook instance
343-
- Network access to Storybook URL
344224

345225
## Development
346226

347-
```bash
348-
# Install dependencies
349-
npm install
350-
351-
# Run TypeScript checks
352-
npm run typecheck
353-
354-
# Run linting
355-
npm run lint
356-
357-
# Build for production
358-
npm run build
359-
360-
# Clean build files
361-
npm run clean
362-
```
227+
See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions.
363228

364229
## License
365230

‎package.json‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,15 +70,14 @@
7070
"dist",
7171
"README.md",
7272
"LICENSE",
73-
"examples",
7473
"scripts"
7574
],
7675
"repository": {
7776
"type": "git",
78-
"url": "git+https://github.com/graslt/mcp-design-system-extractor.git"
77+
"url": "git+https://github.com/freema/mcp-design-system-extractor.git"
7978
},
8079
"bugs": {
81-
"url": "https://github.com/graslt/mcp-design-system-extractor/issues"
80+
"url": "https://github.com/freema/mcp-design-system-extractor/issues"
8281
},
83-
"homepage": "https://github.com/graslt/mcp-design-system-extractor#readme"
82+
"homepage": "https://github.com/freema/mcp-design-system-extractor#readme"
8483
}

0 commit comments

Comments
 (0)