Open Design MCP Server

<p align="center"> <img src="docs/screenshots/02-dashboard.png" alt="Open Design MCP Admin Dashboard" width="720"> </p>

<h1 align="center">Open Design MCP Server</h1>

<p align="center"> <strong>Enterprise-grade MCP bridge for <a href="https://opendesign.dev">Open Design</a> — manage AI design agents via the Model Context Protocol.</strong> </p>

<p align="center"> <img src="https://img.shields.io/badge/python-3.12+-blue?logo=python&logoColor=white" alt="Python 3.12+"> <img src="https://img.shields.io/badge/FastAPI-0.115+-009688?logo=fastapi&logoColor=white" alt="FastAPI"> <img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black" alt="React 19"> <img src="https://img.shields.io/badge/MCP-Protocol-purple" alt="MCP Protocol"> <img src="https://img.shields.io/badge/Tailwind_CSS-4.0-38B2AC?logo=tailwindcss&logoColor=white" alt="Tailwind CSS 4"> <img src="https://img.shields.io/badge/License-MIT-green" alt="License MIT"> </p>

<p align="center"> <a href="README_zh-TW.md">繁體中文文件</a> </p>

---

Overview

Open Design MCP Server exposes the Open Design daemon's REST API as 15 MCP tools over the StreamableHttp transport, enabling any MCP-compatible AI client (Claude App, Claude Code, n8n, etc.) to create, iterate, and manage AI-generated design projects.

The package includes a full-featured Admin GUI (React 19 SPA) for monitoring, tool management, token rotation, and live log viewing — all secured with JWT authentication, CORS allowlists, and security headers.

Why This Package?

Challenge	Solution
Open Design daemon only has a REST API — no MCP support	FastMCP server translates 15 REST endpoints into MCP tools
MCP stdio transport isn't network-accessible	Supergateway bridges stdio → StreamableHttp over HTTP
No admin interface for managing MCP tools and tokens	React 19 SPA with Dashboard, Tool Manager, Token Manager
Security for exposed MCP endpoints	JWT auth, CORS allowlist, SSRF protection, security headers, encrypted proxy
Long-running AI agent operations (3-5 min)	SSE streaming parser with configurable timeouts (up to 300s)
Deployment complexity (3 components)	Single Docker image with multi-stage build, K8s-ready

Features

Core Capabilities

• 15 MCP Tools — System info, project CRUD, file access, AI chat (SSE streaming), content discovery
• StreamableHttp Transport — Network-accessible MCP via Supergateway (stdio → HTTP bridge)
• SSE Response Parser — Handles long-running AI agent operations with real-time text streaming
• Configurable Timeouts — 60s for reads, 300s for AI chat operations

Admin GUI

• Dashboard — Real-time health monitoring (daemon, MCP server, proxy status)
• Tool Manager — Enable/disable individual MCP tools without restarting
• Token Manager — Generate, rotate, and manage MCP authentication tokens
• Log Viewer — Live-streaming server logs with severity filtering
• Settings — Connection configuration with SSRF-protected connectivity testing

Security

• JWT Authentication — HS256 tokens with configurable expiry (default 24h)
• CORS Allowlist — Explicit origin allowlist (no wildcards)
• Security Headers — HSTS, X-Frame-Options: DENY, X-Content-Type-Options, Referrer-Policy
• SSRF Protection — Block metadata endpoints (169.254.169.254), loopback, link-local addresses
• Request Size Limit — 1 MB body limit to prevent abuse
• Encrypted MCP Proxy — Token-based URL path for MCP endpoint access
• Secure Cookies — HttpOnly, Secure, SameSite=Strict

Architecture

graph TB
    subgraph External["External AI Clients"]
        Claude["Claude App / Claude Code"]
        N8N["n8n / Custom MCP Client"]
    end

    subgraph CF["Cloudflare Tunnel"]
        CFT["*.woowtech.io"]
    end

    subgraph Pod["K8s Pod: od-mcp"]
        subgraph AdminGUI["Admin GUI — FastAPI :8080"]
            Auth["JWT Auth Middleware"]
            SecHeaders["Security Headers"]
            Proxy["/private_{token}/mcp → Reverse Proxy"]
            SPA["React 19 SPA"]
            API["REST API /api/*"]
        end

        subgraph SG["Supergateway — Node.js :8000"]
            STDIO["stdio → StreamableHttp Bridge"]
        end

        subgraph MCP["MCP Server — FastMCP"]
            Tools["15 MCP Tools"]
        end
    end

    subgraph OD["Open Design Daemon"]
        ODAPI["REST API :7457"]
    end

    Claude --> CFT
    N8N --> CFT
    CFT --> Auth
    Auth --> SecHeaders
    SecHeaders --> Proxy
    Proxy --> STDIO
    STDIO --> Tools
    Tools --> ODAPI
    CFT --> SPA
    SPA --> API

Three-Component Architecture

Component	Technology	Port	Role
MCP Server	Python FastMCP	stdio	15 MCP tools wrapping OD daemon REST API
Supergateway	Node.js	8000	Bridges MCP stdio → StreamableHttp transport
Admin GUI	FastAPI + React 19	8080	Web management console + MCP reverse proxy

Data Flow

AI Client → Cloudflare Tunnel → Admin GUI (:8080)
                                    ├── /private_{token}/mcp → Supergateway (:8000) → MCP Server (stdio) → OD Daemon (:7457)
                                    └── /api/* → REST API (settings, tools, tokens, logs)

MCP Tools (15)

Category A: System Tools (4)

Tool	Description	Parameters
health	Check OD daemon health status and version	—
version	Get detailed daemon version info	—
list_agents	List available AI agent CLIs (Claude, OpenCode, BYOK)	—
list_connectors	List external connectors (GitHub, etc.)	—

Category B: Project Tools (5)

Tool	Description	Parameters
list_projects	List all design projects with status and metadata	—
get_project	Get detailed info about a specific project	project_id
create_project	Create a new project via AI agent (long-running, up to 5 min)	prompt, agent_id
delete_project	Permanently delete a project	project_id
list_project_files	List all files in a project directory	project_id

Category C: File Tools (2)

Tool	Description	Parameters
read_file	Read raw content of a project file	project_id, file_path
get_file_info	Get file metadata (size, MIME type)	project_id, file_path

Category D: AI Chat Tools (2)

Tool	Description	Parameters
send_message	Send follow-up message in a project conversation (long-running)	project_id, prompt, agent_id
list_runs	List all active and completed AI agent runs	—

Category E: Content Tools (2)

Tool	Description	Parameters
list_plugins	List available plugins and templates	—
list_skills	List available design skills and triggers	—

Admin GUI

Login

Secure JWT-based authentication with admin password.

<p align="center"> <img src="docs/screenshots/01-login.png" alt="Login Page" width="720"> </p>

Dashboard

Real-time health monitoring — OD Daemon status, MCP Server status, Proxy status, daemon version, and namespace info.

<p align="center"> <img src="docs/screenshots/02-dashboard.png" alt="Dashboard" width="720"> </p>

Tool Manager

Enable or disable individual MCP tools. View tool categories, parameters, and descriptions.

<p align="center"> <img src="docs/screenshots/03-tools.png" alt="Tool Manager" width="720"> </p>

Token Manager

Generate and rotate MCP authentication tokens. View token history and connection URLs.

<p align="center"> <img src="docs/screenshots/04-tokens.png" alt="Token Manager" width="720"> </p>

Log Viewer

Live-streaming server logs with auto-scroll and severity filtering.

<p align="center"> <img src="docs/screenshots/05-logs.png" alt="Log Viewer" width="720"> </p>

Settings

Connection configuration, MCP server process management, and SSRF-protected connectivity testing.

<p align="center"> <img src="docs/screenshots/06-settings.png" alt="Settings" width="720"> </p>

Quick Start

Docker

# Build
docker build -t od-mcp-server:latest .

# Run
docker run -d \
  -p 8080:8080 \
  -p 8000:8000 \
  -e OD_API_BASE=http://your-od-daemon:7457 \
  -e JWT_SECRET=your-secret-key \
  -v od-mcp-data:/data \
  od-mcp-server:latest

Kubernetes (K3s)

# Apply manifests
kubectl apply -f k8s-manifests/

# Verify
kubectl get pods -n open-design
kubectl logs -n open-design deployment/od-mcp -c admin-gui

MCP Client Configuration

Connect any MCP client using the StreamableHttp endpoint:

{
  "mcpServers": {
    "open-design": {
      "url": "https://your-domain.com/private_{YOUR_TOKEN}/mcp",
      "transport": "streamable-http"
    }
  }
}

Tech Stack

Backend (Python)

Package	Version	Purpose
FastAPI	0.115+	Admin GUI REST API framework
Uvicorn	0.34+	ASGI server
httpx	0.28+	HTTP client for OD daemon communication
Pydantic	2.10+	Data validation and serialization
PyJWT	2.10+	JWT authentication
SSE-Starlette	2.2+	Server-Sent Events support
mcp[server]	1.1+	MCP protocol SDK (FastMCP)
PyYAML	6.0+	Configuration file parsing
aiofiles	24.1+	Async file I/O

Frontend (JavaScript)

Package	Version	Purpose
React	19.0	UI framework
React Router	7.0	Client-side routing
TanStack React Query	5.60	Server state management
Lucide React	0.460	Icon library
Tailwind CSS	4.0	Utility-first CSS framework
Vite	6.0	Build tool and dev server

Infrastructure

Component	Purpose
Supergateway	stdio → StreamableHttp MCP transport bridge
Docker (multi-stage)	Node 22 (frontend build) → Python 3.12-slim (runtime)
K3s / Kubernetes	Container orchestration
Cloudflare Tunnel	Secure external access with TLS termination

Project Structure

.
├── od_mcp_server.py          # MCP server — 15 tools (FastMCP, stdio)
├── od_mcp_admin/             # Admin GUI app (FastAPI entry point)
│   └── routers/
│       └── config.py         # OD-specific connection config router
├── mcp_admin_core/           # Shared admin framework
│   ├── app.py                # FastAPI app factory + security middleware
│   ├── auth/
│   │   └── middleware.py     # JWT auth middleware + login router
│   ├── config.py             # JSON config store
│   ├── process.py            # MCP server process manager
│   ├── proxy.py              # MCP reverse proxy
│   └── routers/
│       └── settings.py       # Full config management API
├── frontend/                 # React 19 SPA (Vite + Tailwind CSS 4)
│   ├── src/
│   │   ├── pages/            # Dashboard, Tools, Tokens, Logs, Settings
│   │   └── components/       # Shared UI components
│   └── package.json
├── k8s-manifests/            # Kubernetes deployment manifests
├── Dockerfile                # Multi-stage build (Node 22 + Python 3.12)
├── entrypoint.sh             # Container startup script
└── pyproject.toml            # Python project configuration

Security

• Authentication: JWT (HS256) with configurable expiry, secure cookie storage
• Transport: All traffic encrypted via Cloudflare Tunnel (TLS 1.3)
• CORS: Explicit origin allowlist — no wildcard *
• Headers: HSTS, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy
• SSRF Protection: Blocks requests to cloud metadata endpoints, loopback, and link-local addresses
• Request Limits: 1 MB body size limit
• Token Security: MCP tokens masked in API responses, rotation with history tracking
• API Surface: Swagger/OpenAPI docs disabled in production

License

MIT License. See LICENSE for details.

---

<p align="center"> Built by <a href="https://github.com/WOOWTECH">WOOWTECH</a> </p>