Skip to content

Commit 17058d1

Browse files
GeneralJerelGeneralJerel
committed
feat: Add standalone OpenGenerativeUI MCP Server
- Fully self-contained MCP server package (open-generative-ui-mcp) - Exposes design system, skills, and renderer as MCP capabilities - Includes three MCP tools/resources/prompts for generative UI - Production-ready with Docker, configuration, and documentation - Can be deployed independently without demo app dependency - Complete README with deployment guides and API reference
1 parent 1fde890 commit 17058d1

16 files changed

+2384
-105
lines changed

‎apps/mcp/.dockerignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
node_modules/
2+
npm-debug.log
3+
.git
4+
.gitignore
5+
README.md
6+
.env.example
7+
.DS_Store
8+
dist/
9+
.turbo/

‎apps/mcp/.env.example‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Server Configuration
2+
MCP_PORT=3100
3+
NODE_ENV=development
4+
5+
# CORS (comma-separated origins, default: * for development)
6+
ALLOWED_ORIGINS=*
7+
8+
# Skills directory (default: ./skills relative to package root)
9+
SKILLS_DIR=./skills
10+
11+
# Logging
12+
LOG_LEVEL=info

‎apps/mcp/.gitignore‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
node_modules/
2+
dist/
3+
.env
4+
.env.local
5+
*.log
6+
npm-debug.log*
7+
yarn-debug.log*
8+
yarn-error.log*
9+
.DS_Store
10+
.turbo/
11+
.venv/
12+
pnpm-lock.yaml

‎apps/mcp/Dockerfile‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Multi-stage build for production
2+
FROM node:20-alpine AS builder
3+
4+
WORKDIR /app
5+
6+
# Install build dependencies
7+
RUN apk add --no-cache python3 make g++
8+
9+
# Copy package files
10+
COPY package.json pnpm-lock.yaml ./
11+
12+
# Install pnpm
13+
RUN npm install -g pnpm@9
14+
15+
# Install dependencies
16+
RUN pnpm install --prod --frozen-lockfile
17+
18+
# Copy source
19+
COPY tsconfig.json ./
20+
COPY src ./src
21+
COPY skills ./skills
22+
23+
# Build
24+
RUN pnpm build
25+
26+
# Production image
27+
FROM node:20-alpine
28+
29+
WORKDIR /app
30+
31+
# Install dumb-init for proper signal handling
32+
RUN apk add --no-cache dumb-init
33+
34+
# Copy built application from builder
35+
COPY --from=builder /app/dist ./dist
36+
COPY --from=builder /app/skills ./skills
37+
COPY --from=builder /app/node_modules ./node_modules
38+
COPY package.json ./
39+
40+
# Non-root user
41+
RUN addgroup -g 1001 -S nodejs && \
42+
adduser -S nodejs -u 1001
43+
44+
USER nodejs
45+
46+
# Health check
47+
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
48+
CMD wget --no-verbose --tries=1 --spider http://localhost:${MCP_PORT:-3100}/health || exit 1
49+
50+
EXPOSE 3100
51+
52+
ENTRYPOINT ["/sbin/dumb-init", "--"]
53+
CMD ["node", "dist/index.js"]

‎apps/mcp/README.md‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# OpenGenerativeUI MCP Server
2+
3+
A standalone, independently deployable [Model Context Protocol](https://modelcontextprotocol.io) server that exposes OpenGenerativeUI's design system, skills, and document renderer to any MCP-compatible client.
4+
5+
## Features
6+
7+
- **Design System Tool** — `assemble_document` wraps HTML fragments with OpenGenerativeUI's complete CSS design system and bridge JavaScript
8+
- **Skill Resources** — Browse and read skill instruction documents via `skills://list` and `skills://{name}`
9+
- **Prompt Templates** — Pre-composed prompts for common visualization tasks: `create_widget`, `create_svg_diagram`, `create_visualization`
10+
- **Standalone** — No dependencies on other packages; can be deployed independently
11+
- **Configurable** — Environment variables for port, CORS origins, skills directory, and logging
12+
13+
## Quick Start
14+
15+
### Prerequisites
16+
- Node.js >= 18
17+
- pnpm or npm
18+
19+
### Installation
20+
21+
```bash
22+
# Navigate to the MCP package
23+
cd apps/mcp
24+
25+
# Install dependencies
26+
pnpm install
27+
28+
# Start the development server
29+
pnpm dev
30+
# → MCP server running on http://localhost:3100/mcp
31+
32+
# Health check
33+
curl http://localhost:3100/health
34+
# → {"status":"ok"}
35+
```
36+
37+
### Build for Production
38+
39+
```bash
40+
pnpm build
41+
pnpm start
42+
```
43+
44+
## Configuration
45+
46+
Create a `.env` file in the package root (copy from `.env.example`):
47+
48+
```bash
49+
# Server port (default: 3100)
50+
MCP_PORT=3100
51+
52+
# CORS origins, comma-separated (default: * for development)
53+
ALLOWED_ORIGINS=*
54+
55+
# Skills directory path (default: ./skills)
56+
SKILLS_DIR=./skills
57+
58+
# Log level (default: info)
59+
LOG_LEVEL=info
60+
```
61+
62+
## Usage
63+
64+
### From Claude Code
65+
66+
Add to `.mcp.json`:
67+
68+
```json
69+
{
70+
"openGenerativeUI": {
71+
"url": "http://localhost:3100/mcp"
72+
}
73+
}
74+
```
75+
76+
Then use the available tools and resources in Claude conversations.
77+
78+
### From Any MCP Client
79+
80+
Connect via HTTP MCP transport to `http://localhost:3100/mcp`.
81+
82+
## API Reference
83+
84+
### Tool: `assemble_document`
85+
86+
Wraps an HTML fragment with the complete OpenGenerativeUI design system.
87+
88+
**Input:**
89+
```typescript
90+
{
91+
title: string; // Short title, e.g., "Binary Search Visualization"
92+
description: string; // One-sentence explanation
93+
html: string; // Self-contained HTML fragment (inline <style> and <script> OK)
94+
}
95+
```
96+
97+
**Output:**
98+
```typescript
99+
{
100+
content: [{
101+
type: "text",
102+
text: string // Complete HTML document, ready to render in iframe
103+
}]
104+
}
105+
```
106+
107+
**Example:**
108+
```javascript
109+
const result = await client.callTool("assemble_document", {
110+
title: "Interactive Algorithm Visualizer",
111+
description: "Step-by-step visualization of the quicksort algorithm",
112+
html: `
113+
<div id="viz">
114+
<p>Click to start visualization</p>
115+
<script>
116+
// Your visualization code here
117+
</script>
118+
</div>
119+
`
120+
});
121+
122+
// result.content[0].text is a complete HTML document
123+
// Render in: <iframe sandbox="allow-scripts allow-same-origin" srcdoc={result.content[0].text} />
124+
```
125+
126+
### Resource: `skills://list`
127+
128+
Returns a JSON array of available skill names.
129+
130+
**Example:**
131+
```bash
132+
curl -X POST http://localhost:3100/mcp \
133+
-H "Content-Type: application/json" \
134+
-d '{
135+
"jsonrpc": "2.0",
136+
"id": 1,
137+
"method": "resources/read",
138+
"params": { "uri": "skills://list" }
139+
}'
140+
```
141+
142+
### Resource: `skills://{name}`
143+
144+
Retrieve the full text content of a specific skill.
145+
146+
Available skills:
147+
- `master-agent-playbook` — When and how to create interactive HTML widgets
148+
- `svg-diagram-skill` — SVG diagram templates and patterns
149+
- `agent-skills-vol2` — Advanced visualizations, dashboards, simulations
150+
151+
**Example:**
152+
```bash
153+
curl -X POST http://localhost:3100/mcp \
154+
-H "Content-Type: application/json" \
155+
-d '{
156+
"jsonrpc": "2.0",
157+
"id": 1,
158+
"method": "resources/read",
159+
"params": { "uri": "skills://master-agent-playbook" }
160+
}'
161+
```
162+
163+
### Prompts
164+
165+
#### `create_widget`
166+
Instructions for creating interactive HTML widgets.
167+
168+
#### `create_svg_diagram`
169+
Instructions for creating inline SVG diagrams with canonical templates.
170+
171+
#### `create_visualization`
172+
Advanced visualization instructions: dashboards, simulations, UI mockups.
173+
174+
## Deployment
175+
176+
### Docker
177+
178+
```bash
179+
# Build image
180+
docker build -t open-generative-ui-mcp .
181+
182+
# Run container
183+
docker run -p 3100:3100 open-generative-ui-mcp
184+
185+
# With custom port and CORS
186+
docker run \
187+
-p 3100:3100 \
188+
-e MCP_PORT=3100 \
189+
-e ALLOWED_ORIGINS="http://localhost:3000,https://myapp.com" \
190+
open-generative-ui-mcp
191+
```
192+
193+
### Node.js
194+
195+
```bash
196+
# Install globally or locally
197+
npm install -g open-generative-ui-mcp
198+
199+
# Run
200+
MCP_PORT=3100 ALLOWED_ORIGINS="*" open-generative-ui-mcp
201+
202+
# Or with node
203+
node dist/index.js
204+
```
205+
206+
### Cloud Deployment
207+
208+
The server is a standard Node.js application and can be deployed to:
209+
- **Heroku**: `Procfile: web: node dist/index.js`
210+
- **Railway**: Connect the repo, select Node.js, set `start` script
211+
- **Vercel**: Use serverless function (requires adapter)
212+
- **AWS Lambda**: Package with Node.js runtime
213+
- **Google Cloud Run**: Use Dockerfile
214+
215+
## Development
216+
217+
### Project Structure
218+
219+
```
220+
apps/mcp/
221+
├── package.json # Standalone package definition
222+
├── tsconfig.json # TypeScript config
223+
├── .env.example # Configuration template
224+
├── Dockerfile # Container definition
225+
├── skills/ # Skill instruction files (copied from source)
226+
└── src/
227+
├── index.ts # Hono HTTP server entry point
228+
├── server.ts # MCP server construction
229+
├── skills.ts # Skill file loader
230+
└── renderer.ts # Design system CSS + assembleDocument
231+
```
232+
233+
### Extending Skills
234+
235+
Add new skill files to `skills/` directory as `.txt` files. They'll automatically be available as resources and can be used in prompts.
236+
237+
### Modifying the Design System
238+
239+
Edit `src/renderer.ts` to update:
240+
- `THEME_CSS` — Theme colors and variables
241+
- `SVG_CLASSES_CSS` — Pre-built SVG helper classes
242+
- `FORM_STYLES_CSS` — Form element styling
243+
- `BRIDGE_JS` — Communication bridge between iframe and parent
244+
245+
## License
246+
247+
MIT
248+
249+
## Support
250+
251+
For issues, feature requests, or questions, visit the [OpenGenerativeUI repository](https://github.com/CopilotKit/OpenGenerativeUI).
252+
253+
## Contributing
254+
255+
This is a standalone deployment package. To contribute improvements:
256+
257+
1. Fork the main [OpenGenerativeUI repository](https://github.com/CopilotKit/OpenGenerativeUI)
258+
2. Make changes to `apps/mcp/` (or the source files it's forked from)
259+
3. Submit a pull request
260+
261+
When updating skills or the design system in the main repo, the MCP package should be updated accordingly.

‎apps/mcp/package.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "open-generative-ui-mcp",
3+
"version": "0.1.0",
4+
"description": "Standalone MCP server for OpenGenerativeUI design system and skills",
5+
"type": "module",
6+
"main": "dist/index.js",
7+
"scripts": {
8+
"dev": "tsx watch src/index.ts",
9+
"build": "tsc",
10+
"start": "node dist/index.js",
11+
"lint": "tsc --noEmit"
12+
},
13+
"keywords": ["mcp", "model-context-protocol", "generative-ui", "design-system"],
14+
"author": "CopilotKit",
15+
"license": "MIT",
16+
"dependencies": {
17+
"@hono/node-server": "^1",
18+
"@modelcontextprotocol/sdk": "^1.25.3",
19+
"hono": "^4",
20+
"zod": "^3.23"
21+
},
22+
"devDependencies": {
23+
"@types/node": "^20",
24+
"tsx": "^4",
25+
"typescript": "^5"
26+
},
27+
"engines": {
28+
"node": ">=18"
29+
}
30+
}

0 commit comments

Comments
 (0)